→ سیستم‌نامه

API Integration بدون مستندسازی چرا دردسر می‌شود

چند نکته عملی درباره لاگ، خطا، retry و مستندسازی در اتصال سیستم‌ها.

2 دقیقه مطالعهآخرین بروزرسانی: سپتامبر 8, 2026

چند نکته عملی درباره لاگ، خطا، retry و مستندسازی در اتصال سیستم‌ها.

مسئله از کجا شروع می‌شود؟

اتصال دو سیستم از طریق API معمولاً در محیط تست به‌راحتی کار می‌کند. مشکل واقعی وقتی شروع می‌شود که این اتصال وارد محیط واقعی (production) می‌شود: شبکه قطع می‌شود، سرور مقصد کند جواب می‌دهد، یا فرمت داده‌ی برگشتی بدون اطلاع تغییر می‌کند. اگر از اول برای این حالت‌ها آماده نشده باشی، یک اتصال ساده می‌تواند تبدیل به بزرگ‌ترین منبع باگ پروژه شود.

لاگ‌گیری که واقعاً به درد می‌خورد

لاگ کردن فقط «موفق بود / نبود» کافی نیست. برای هر درخواست باید حداقل این‌ها ثبت شود: زمان دقیق، endpoint و پارامترهای ارسالی (بدون داده‌ی حساس)، کد وضعیت پاسخ، و در صورت خطا، متن کامل پیام خطا. بدون این سطح از لاگ، وقتی مشکلی گزارش می‌شود، باید حدس بزنی چه اتفاقی افتاده به‌جای اینکه دقیقاً ببینی.

Retry، اما هوشمند

تلاش مجدد خودکار (retry) لازم است چون خیلی از خطاها موقتی‌اند (timeout، rate limit). اما retry بی‌قاعده هم خطرناک است: اگر یک درخواست ثبت سفارش بدون بررسی وضعیت قبلی دوباره ارسال شود، ممکن است سفارش دوبار ثبت شود. قاعده‌ی درست: retry فقط برای خطاهای شبکه/سرور (5xx، timeout)، نه برای خطاهای منطقی (4xx)؛ و همیشه idempotency در طرف دریافت‌کننده در نظر گرفته شود، یعنی سیستم مقصد بتواند تشخیص دهد این یک درخواست تکراری است.

مستندسازی، همان چیزی که همیشه عقب می‌افتد

وقتی یک اتصال API را می‌سازی، ثبت این موارد در یک فایل ساده (حتی یک صفحه‌ی داخلی) وقت آینده را نجات می‌دهد: کدام endpoint‌ها استفاده می‌شوند و چرا، چه فیلدهایی اجباری‌اند، محدودیت‌های نرخ درخواست (rate limit)، و رفتار سیستم در صورت خطا. شش ماه بعد که یک باگ گزارش می‌شود یا باید همان اتصال را برای پروژه‌ی دیگری تکرار کنی، این مستندات فرق بین نیم ساعت رفع مشکل و یک روز کامل حدس زدن است.

SOS سایتت خوابیده؟