مطالعه موردی: سیستم یکپارچه فروش و حسابداری — از همگامسازی دورهای به رویدادمحور
اتصال فروشگاه و سیستم حسابداری راهکاران با اسکریپت Python و گردش کار خودکار، برای حذف خطای ثبت دستی…
چند نکته عملی درباره لاگ، خطا، retry و مستندسازی در اتصال سیستمها.

چند نکته عملی درباره لاگ، خطا، retry و مستندسازی در اتصال سیستمها.
اتصال دو سیستم از طریق API معمولاً در محیط تست بهراحتی کار میکند. مشکل واقعی وقتی شروع میشود که این اتصال وارد محیط واقعی (production) میشود: شبکه قطع میشود، سرور مقصد کند جواب میدهد، یا فرمت دادهی برگشتی بدون اطلاع تغییر میکند. اگر از اول برای این حالتها آماده نشده باشی، یک اتصال ساده میتواند تبدیل به بزرگترین منبع باگ پروژه شود.
لاگ کردن فقط «موفق بود / نبود» کافی نیست. برای هر درخواست باید حداقل اینها ثبت شود: زمان دقیق، endpoint و پارامترهای ارسالی (بدون دادهی حساس)، کد وضعیت پاسخ، و در صورت خطا، متن کامل پیام خطا. بدون این سطح از لاگ، وقتی مشکلی گزارش میشود، باید حدس بزنی چه اتفاقی افتاده بهجای اینکه دقیقاً ببینی.
تلاش مجدد خودکار (retry) لازم است چون خیلی از خطاها موقتیاند (timeout، rate limit). اما retry بیقاعده هم خطرناک است: اگر یک درخواست ثبت سفارش بدون بررسی وضعیت قبلی دوباره ارسال شود، ممکن است سفارش دوبار ثبت شود. قاعدهی درست: retry فقط برای خطاهای شبکه/سرور (5xx، timeout)، نه برای خطاهای منطقی (4xx)؛ و همیشه idempotency در طرف دریافتکننده در نظر گرفته شود، یعنی سیستم مقصد بتواند تشخیص دهد این یک درخواست تکراری است.
وقتی یک اتصال API را میسازی، ثبت این موارد در یک فایل ساده (حتی یک صفحهی داخلی) وقت آینده را نجات میدهد: کدام endpointها استفاده میشوند و چرا، چه فیلدهایی اجباریاند، محدودیتهای نرخ درخواست (rate limit)، و رفتار سیستم در صورت خطا. شش ماه بعد که یک باگ گزارش میشود یا باید همان اتصال را برای پروژهی دیگری تکرار کنی، این مستندات فرق بین نیم ساعت رفع مشکل و یک روز کامل حدس زدن است.