اجرای دوبارهٔ کار شکست‌خورده، بدون ثبت هزینهٔ تکراری با SQLite

با یک کلید ثابت برای هر درخواست و یک تراکنش اتمیک، اجرای دوباره را به بازگرداندن همان نتیجه تبدیل کنید. این نمونه برای ثبت اعتبار و هزینه در SQLite است، نه تضمین جلوگیری از برداشت تکراری در یک درگاه خارجی.

برای نرگس، توسعه‌دهندهٔ بک‌اند یک سرویس اعتبار داخلی، راه جلوگیری از کسر دوبارهٔ اعتبار این است: «شناسهٔ درخواست، تغییر اعتبار و نتیجهٔ قابل بازگرداندن» را در یک تراکنش ذخیره کند. اگر worker بعد از ثبت نهایی ولی پیش از پاسخ‌دادن قطع شد، اجرای دوباره باید همان رسید قبلی را بخواند، نه اینکه دوباره اعتبار کم کند. نمونهٔ زیر همین رفتار را با Python و SQLite قابل آزمایش می‌کند.

مرز مسئله: تکرار اجرا مجاز است، تکرار اثر نه

فرض کنید درخواست job-42 باید ۳۰ واحد از اعتبار ۱۰۰ واحدی یک حساب کم کند. قطع اتصال نشان نمی‌دهد که درخواست شکست خورده است؛ ممکن است تغییر ثبت شده باشد و فقط پاسخ به دست فراخوان نرسیده باشد. بنابراین تکرار کورکورانه می‌تواند اعتبار را به ۴۰ برساند، در حالی که نتیجهٔ درست ۷۰ است. کلید idempotency این ابهام را با نسبت‌دادن همهٔ تلاش‌های همان عملیات به یک شناسه حل می‌کند.

کلید را پیش از اولین ارسال تولید و همراه خود کار نگهداری کنید؛ ساختن UUID تازه در هر تلاش، این قرارداد را می‌شکند. علاوه بر کلید، ورودی مؤثر را هم ذخیره می‌کنیم: همان کلید با مبلغ متفاوت باید خطا بدهد، نه اینکه رسید یک عملیات دیگر را بی‌سروصدا برگرداند. در سرویس چندمستاجری، شناسهٔ مستأجر و حساب نیز باید بخشی از دامنهٔ کلید و تطبیق ورودی باشند؛ این مثال عمداً فقط یک حساب دارد.

نمونهٔ اجرایی: اثر و رسید در یک تراکنش

کد را در retry_demo.py ذخیره کنید. فقط کتابخانهٔ استاندارد Python لازم است. پایگاه داده در یک پوشهٔ موقت ساخته می‌شود تا هر اجرای آزمایش مستقل باشد. BEGIN IMMEDIATE پیش از خواندن رسید، تراکنش نوشتن را آغاز می‌کند؛ در نتیجه دو نویسنده نمی‌توانند هم‌زمان نبودن همان رسید را ببینند و هر دو اعتبار کم کنند. کلید اصلی جدول رسید نیز یکتایی شناسه را در خود پایگاه داده اعمال می‌کند.

```python
import json
import sqlite3
import tempfile
from pathlib import Path


def charge(db, key, amount, fail_before_commit=False):
if type(amount) is not int or amount <= 0:
raise ValueError('amount must be a positive integer')
db.execute('BEGIN IMMEDIATE')
try:
row = db.execute(
'SELECT amount, result FROM receipts WHERE request_key = ?',
(key,),
).fetchone()
if row is not None:
if row[0] != amount:
raise ValueError('same key, different amount')
result = json.loads(row[1])
else:
changed = db.execute(
'UPDATE account SET balance = balance - ? '
'WHERE id = 1 AND balance >= ?',
(amount, amount),
).rowcount
if changed != 1:
raise ValueError('insufficient balance')
balance = db.execute(
'SELECT balance FROM account WHERE id = 1'
).fetchone()[0]
result = {'request_key': key, 'charged': amount, 'balance': balance}
db.execute(
'INSERT INTO receipts(request_key, amount, result) VALUES (?, ?, ?)',
(key, amount, json.dumps(result, sort_keys=True)),
)
if fail_before_commit:
raise RuntimeError('simulated failure before commit')
db.execute('COMMIT')
return result
except BaseException:
if db.in_transaction:
db.execute('ROLLBACK')
raise


def main():
with tempfile.TemporaryDirectory() as folder:
db = sqlite3.connect(str(Path(folder) / 'demo.db'), isolation_level=None)
try:
db.executescript('''
CREATE TABLE account (
id INTEGER PRIMARY KEY,
balance INTEGER NOT NULL CHECK(balance >= 0)
);
INSERT INTO account VALUES (1, 100);
CREATE TABLE receipts (
request_key TEXT PRIMARY KEY NOT NULL,
amount INTEGER NOT NULL,
result TEXT NOT NULL
);
''')
try:
charge(db, 'job-42', 30, fail_before_commit=True)
except RuntimeError:
print('before-commit failure: rolled back')
balance = db.execute('SELECT balance FROM account').fetchone()[0]
print('balance after failure:', balance)

# Commit succeeds, but pretend the caller loses this response.
charge(db, 'job-42', 30)
print('after-commit response: lost')
result = charge(db, 'job-42', 30)
print('retry result:', json.dumps(result, sort_keys=True))
print('receipts:', db.execute('SELECT COUNT(*) FROM receipts').fetchone()[0])
try:
charge(db, 'job-42', 40)
except ValueError as error:
print('conflict:', error)
finally:
db.close()


if __name__ == '__main__':
main()
```

ورودی آزمایش، حسابی با اعتبار ۱۰۰ و درخواست job-42 با مبلغ ۳۰ است. بار اول عمداً پیش از commit خطا می‌سازیم؛ بار دوم commit موفق را با پاسخ گم‌شده شبیه‌سازی می‌کنیم؛ بار سوم همان درخواست را دوباره می‌فرستیم. دستور اجرا و خروجی مورد انتظار زیر است. این آزمایش منطق rollback و بازیابی رسید را نشان می‌دهد، نه تست قطع برق یا خرابی دیسک.

```bash
python3 retry_demo.py
```

```other
before-commit failure: rolled back
balance after failure: 100
after-commit response: lost
retry result: {"balance": 70, "charged": 30, "request_key": "job-42"}
receipts: 1
conflict: same key, different amount
```

چرا کار می‌کند و کجا می‌شکند؟

اصل مهم، حذف فاصلهٔ میان اثر و ثبت رسید است. اگر ابتدا اعتبار را در یک تراکنش کم کنید و سپس رسید را جداگانه بنویسید، قطع‌شدن میان این دو مرحله دوباره هزینه می‌سازد. در این نمونه، شکست پیش از commit هر دو تغییر را برمی‌گرداند و موفقیت commit هر دو را ثبت می‌کند. رسید هم نتیجهٔ همان لحظه را نگه می‌دارد؛ اگر بعداً اعتبار حساب تغییر کند، تکرار job-42 همچنان نتیجهٔ قبلی را برمی‌گرداند، نه وضعیت جاری حساب.

بهای این سادگی، نگهداری رسید و محدودکردن هم‌زمانی نوشتن است. طبق مستندات SQLite، فقط یک تراکنش نوشتن هم‌زمان وجود دارد؛ BEGIN IMMEDIATE ممکن است با قفل نویسندهٔ دیگر روبه‌رو شود. در سرویس واقعی، خطای موقت قفل را با تعداد تلاش محدود و تأخیر افزایشی مدیریت کنید، اما خطای «همان کلید با مبلغ متفاوت» را تکرار نکنید. رسیدها را هم زودتر از پایان بازهٔ مجاز retry حذف نکنید؛ پس از حذف رسید، همان کلید دوباره اثر خواهد گذاشت.

این راه برای برداشت از درگاه خارجی به‌تنهایی غلط است: rollback محلی نمی‌تواند برداشت انجام‌شده در شبکه را برگرداند. اگر ارائه‌دهنده مانند Stripe کلید idempotency می‌پذیرد، برای همان عملیات کلید ثابت را به آن هم بدهید و محدودیت نگهداری و قواعد تکرار آن ارائه‌دهنده را رعایت کنید. برای ارسال پیام، الگوی outbox می‌تواند ثبت قصد ارسال را با تغییر محلی اتمیک کند، اما ارسال مجدد هنوز ممکن است و مصرف‌کننده باید تکرار را تحمل کند. انتخاب تعیین‌کننده این است: اثر در همان پایگاه داده است یا بیرون از آن؛ نه اینکه چند بار دستور retry را اجرا می‌کنید.

منابع

SQLite — Transactions
https://www.sqlite.org/lang_transaction.html
مرجع رفتار تراکنش‌ها، BEGIN IMMEDIATE و محدودیت نویسندهٔ هم‌زمان.

Python — sqlite3: DB-API interface for SQLite databases
https://docs.python.org/3/library/sqlite3.html
مرجع اتصال، اجرای SQL، پارامترهای پرس‌وجو و کنترل تراکنش در ماژول استاندارد Python.

Stripe API — Idempotent requests
https://docs.stripe.com/api/idempotent_requests
نمونهٔ رسمی قرارداد idempotency برای یک اثر خارجی، شامل تطبیق پارامترها و قواعد نگهداری کلید.

No comments yet