اگر شبکه قطع شود و ایجنت دوباره یک کار را بفرستد، نباید ثبت سفارش یا درخواست دو بار انجام شود. کلید idempotency یک شناسه برای همان اقدام منطقی است. کلید تازه در هر retry این هدف را خراب می‌کند؛ از طرف دیگر، استفاده دوباره از یک کلید برای دو اقدام متفاوت هم خطاست.
روش اجرا و تصمیم‌گیری
کلید را در سمت معتبر برنامه هنگام ایجاد قصد انجام کار بسازید و تا پایان آن کار نگه دارید. داده شخصی مانند شماره تلفن را مستقیم در کلید قرار ندهید. کلید باید به کاربر، نوع عملیات و اثر موردنظر متصل باشد و زمان نگهداری آن با قرارداد سرویس سازگار باشد.
در مقصد، پذیرش کلید و ثبت اثر باید هماهنگ باشند تا دو درخواست هم‌زمان هر دو اجرا نشوند. وضعیت در حال انجام، موفق و ناموفق را صریح نگه دارید. رفتار خطا و تلاش هم‌زمان بسته به ارائه‌دهنده فرق دارد؛ مثال Stripe یک قرارداد خاص است، نه قانون خودکار همه APIها.
پارامترهای اقدام را هم مقایسه کنید. اگر همان کلید با مبلغ، گیرنده یا زمان تازه آمد، نباید نتیجه قبلی بی‌توضیح برگردد یا اقدام تازه مخفیانه اجرا شود. کار جدید با تأیید تازه و شناسه مستقل ساخته شود. گزارش نتیجه باید مشخص کند اثر تازه ایجاد شده یا نتیجه قبلی بازیابی شده است.
نمونهٔ ساختگی و قابل تکرار
دو درخواست ساختگی با کلید یکسان برای ایجاد یک پرونده بی‌اثر می‌رسند. درخواست اول رکورد نمونه را می‌سازد؛ دومی همان نتیجه را دریافت می‌کند و شمار رکوردها یک می‌ماند. در آزمایش بعد، کلید همان است اما موضوع پرونده تغییر کرده؛ برنامه ناسازگاری پارامتر را رد می‌کند. این آزمون را هم‌زمان نیز اجرا کنید، چون آزمون پشت‌سرهم ممکن است خطای رقابت را آشکار نکند. هیچ تماس، پرداخت یا ثبت مشتری واقعی برای این آزمایش لازم نیست.
محدودیت‌ها و خطاهای رایج
این کلید جای مجوز، اعتبارسنجی یا قفل کسب‌وکار را نمی‌گیرد. پاک‌شدن سابقه کلید ممکن است رفتار تکرار را عوض کند. مدت نگهداری و وضعیت درخواست نیمه‌کاره را از مستندات مقصد بخوانید و به صورت بخشی از قرارداد اتصال ثبت کنید.
کنترل پیش از استفاده
| کنترل | معیار پذیرش |
|---|---|
| هویت کار | تمام retryهای همان اقدام کلید ثابت داشته باشند. |
| رقابت | دو درخواست هم‌زمان فقط یک اثر ایجاد کنند. |
| تغییر ورودی | کلید تکراری با پارامتر متفاوت خطای روشن بدهد. |
کاربرگ همراه
کاربرگ تلاش‌ها را به یک قصد مشترک وصل می‌کند. برای سنجش، تعداد اثرهای مقصد را بشمارید نه فقط پاسخ موفق HTTP. یک پاسخ موفق تکراری می‌تواند کاملاً درست باشد، اگر هیچ اثر تازه‌ای ایجاد نکرده باشد.
دریافت کاربرگ CSV این راهنما — داده‌های داخل فایل نمونهٔ ساختگی‌اند. نسخهٔ اصلی را نگه دارید و برای آزمون خودتان یک کپی بسازید.
منبع و ادامهٔ کار
Stripe: درخواست‌های تکرارپذیر امن. تاریخ بررسی منابع: ۱ نوامبر ۲۰۲۶.
اگر کاربرد شما پاسخ‌گویی به مشتری است، مسیر مرتبط اپرا را ببینید و مسئله و محدودیت‌های همین کاربرگ را برای بررسی در دمو همراه داشته باشید.