🧩 چرا «Idempotency» یکی از مهمترین مفاهیم برنامهنویسی است؟
این مفهوم تقریباً در تمام سیستمهای حرفهای وجود دارد، اما بسیاری از برنامهنویسان تا زمانی که با باگهای واقعی روبهرو نشوند، به آن توجه نمیکنند.
مثال ساده
فرض کنید کاربر روی دکمه پرداخت دوبار کلیک کند.
اگر سیستم شما Idempotent نباشد:
کلیک اول → پرداخت انجام شد ✅
کلیک دوم → دوباره پرداخت شد ❌
اما اگر Idempotent باشد:
کلیک اول → پرداخت انجام شد ✅
کلیک دوم → همان نتیجه قبلی برگردانده میشود ✅
در نتیجه فقط یک پرداخت ثبت میشود.
این مفهوم کجاها استفاده میشود؟
- REST API
- پرداخت آنلاین
- ارسال ایمیل
- صفها (RabbitMQ، Kafka)
- Webhookها
- Microserviceها
- Retry مکانیزمها
- Odoo RPC و Controllerها
چرا مهم است؟
در دنیای واقعی همیشه خطا وجود دارد:
- اینترنت قطع میشود.
- کاربر Refresh میکند.
- مرورگر دوباره درخواست میفرستد.
- سرور Timeout میدهد.
- Load Balancer درخواست را تکرار میکند.
اگر برنامه Idempotent نباشد، ممکن است:
- دو سفارش ثبت شود.
- دو فاکتور ایجاد شود.
- دو ایمیل ارسال شود.
- موجودی کالا اشتباه شود.
مثال HTTP
GET /users/1
هر چند بار اجرا شود نتیجه یکسان است.
اما
POST /orders
اگر دوبار اجرا شود ممکن است دو سفارش ساخته شود.
برای همین معمولاً از
Idempotency-Key
استفاده میکنند.
عالی. این موضوع یکی از مفاهیمی است که تفاوت یک برنامهنویس مبتدی با یک برنامهنویس باتجربه را نشان میدهد.
Idempotency چیست؟
تعریف رسمی:
اگر یک عملیات را یک بار یا صد بار اجرا کنیم، نتیجه نهایی یکسان باشد، آن عملیات Idempotent است.
به نتیجه نهایی دقت کنید، نه تعداد دفعات اجرای کد.
مثال اول: کلید برق 💡
فرض کنید چراغ خاموش است.
اگر کلیدی داشته باشیم که فقط دستور خاموش کن را اجرا کند:
خاموش کن
خاموش کن
خاموش کن
خاموش کن
نتیجه همیشه:
چراغ خاموش است.
این عملیات Idempotent است.
اما اگر عملیات تغییر وضعیت (Toggle) باشد:
Toggle
بار اول
خاموش → روشن
بار دوم
روشن → خاموش
بار سوم
خاموش → روشن
هر بار نتیجه عوض میشود.
پس Toggle Idempotent نیست.
مثال دوم: دیتابیس
فرض کنید جدول کاربران داریم.
Users
ID Name Active
------------------
1 Ali false
کد زیر را اجرا میکنیم:
user.active = True
save(user)
اگر ده بار اجرا شود:
false
↓
true
و دوباره:
true
↓
true
باز هم:
true
↓
true
نتیجه نهایی تغییر نمیکند.
این عملیات Idempotent است.
اما این کد را ببینید:
user.balance += 100
اگر یک بار اجرا شود:
100
دو بار:
200
سه بار:
300
پس Idempotent نیست.
مثال سوم: حذف فایل
فرض کنید فایلی داریم.
report.pdf
کد:
delete(report.pdf)
بار اول
فایل حذف شد.
بار دوم
فایل وجود ندارد.
نتیجه نهایی همچنان:
فایل وجود ندارد.
پس از دید نتیجه نهایی، حذف فایل معمولاً Idempotent در نظر گرفته میشود (اگر نبود فایل بهعنوان وضعیت نهایی قابل قبول باشد).
HTTP دقیقاً بر همین اساس طراحی شده است.
بیایید متدهای HTTP را بررسی کنیم.
GET
GET /users/10
ده بار ارسال کنیم:
User:
Ali
هیچ چیز تغییر نمیکند.
پس:
✅ Idempotent
PUT
PUT /users/10
{
"name":"Ali"
}
بار اول:
Ali
بار دوم:
Ali
بار صدم:
Ali
باز هم همان نتیجه.
پس:
✅ Idempotent
DELETE
DELETE /users/10
بار اول:
کاربر حذف شد.
بار دوم:
قبلاً حذف شده.
نتیجه نهایی:
کاربر وجود ندارد.
باز هم یکسان است.
پس:
✅ Idempotent
POST
POST /orders
هر بار:
Order #1001
دوباره:
Order #1002
دوباره:
Order #1003
هر بار یک سفارش جدید ساخته میشود.
پس:
❌ Idempotent نیست.
جدول خلاصه
| Method | Idempotent |
|---|---|
| GET | ✅ |
| PUT | ✅ |
| DELETE | ✅ |
| POST | ❌ |
| PATCH | بستگی به نوع تغییر دارد |
مشکل واقعی دنیا
فرض کنید کاربر روی دکمه پرداخت کلیک میکند.
Client
│
│ POST /pay
▼
Server
سرور پرداخت را انجام میدهد.
پرداخت موفق شد
اما درست همان لحظه اینترنت قطع میشود.
Client ❌ پاسخ را دریافت نکرد.
کاربر فکر میکند پرداخت انجام نشده است.
دوباره دکمه را میزند.
POST /pay
اگر سیستم شما Idempotent نباشد:
پرداخت اول ✅
پرداخت دوم ✅
نتیجه:
دو بار پول کم شد.
این یکی از رایجترین باگهای سیستمهای مالی است.
راهحل: Idempotency Key
به هر درخواست یک شناسه یکتا اختصاص میدهیم.
POST /pay
Idempotency-Key:
A8F1-92B0-XY55
سرور این شناسه را ذخیره میکند.
Key
A8F1-92B0-XY55
اگر همان درخواست دوباره برسد:
همان Key
سرور میگوید:
من این درخواست را قبلاً پردازش کردهام.
و همان پاسخ قبلی را برمیگرداند، بدون اینکه دوباره پرداخت انجام شود.
یک مثال از Odoo
فرض کنید در یک Controller سفارش ایجاد میکنید:
@http.route("/api/order", type="json", auth="public")
def create_order(self):
request.env["sale.order"].create({
"partner_id": 10
})
اگر کلاینت به دلیل Timeout همین درخواست را دوباره ارسال کند:
Sale Order 1
Sale Order 2
دو سفارش ساخته میشود.
اما اگر قبل از ایجاد سفارش، یک Idempotency-Key را بررسی و ذخیره کنید، میتوانید تشخیص دهید که این درخواست قبلاً پردازش شده است و از ایجاد سفارش تکراری جلوگیری کنید.
نکته مهم
Idempotency به این معنا نیست که کد فقط یک بار اجرا میشود.
ممکن است همان کد ۱۰ بار اجرا شود، اما طراحی سیستم باید به گونهای باشد که اثر نهایی فقط یک بار اعمال شود.
این تفاوت ظریف، اساس طراحی بسیاری از APIهای قابل اعتماد، سیستمهای پرداخت و معماریهای توزیعشده است.
در ادامه میتوانیم وارد بخش پیشرفتهتر شویم و ببینیم Stripe، PayPal و سیستمهای بانکی چگونه Idempotency-Key را در عمل پیادهسازی میکنند و حتی یک نمونه واقعی را در Odoo یا Python پیادهسازی کنیم.

دیدگاهتان را بنویسید