Idempotency چیست؟

🧩 چرا «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 نیست.


جدول خلاصه

MethodIdempotent
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 پیاده‌سازی کنیم.

دیدگاه‌ها

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

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *