پنج خطای مهم ادغام API در هنگام راه اندازی

خطای شمارۀ 1. بدون idempotence و «طوفان» عقب نشینی

علائم: سفارشات/پرداخت های تکراری، اختلاف در مقادیر، بازده های متضاد، هشدارهای DLQ در حال رشد هستند.

ریشه: تحویل مکرر درخواست ها/وب سایت ها و فلاپی های شبکه طبیعی است. اگر عملیات «create/write off» بی فایده نباشد، آسیب را چند برابر می کند.

چگونه به

Idempotency-Key/' operation _ id 'به تمام روش های ناامن (POST/PATCH).

شاخص منحصر به فرد در پایگاه داده برای 'operation _ id'. Replay: نتیجه قبلی را برمیگرداند.

وبوکها از طریق جدول صندوق ورودی (dedupe توسط «event _ id + signature»). رویدادهای خروجی - جعبه خروجی.

Retrai: حداکثر 1-2 بار، نمایشگر + لرزش، فقط برای عملیات ایمن.

قرارداد HTTP (مثال):

وب سایت
پست/v1/پرداخت
Idempotency-کلید: ik_f35a2
نوع محتوا: کاربرد/json

{"مقدار": 5000، "ارز": "EUR"، "منبع": "card_..."}

حفاظت SQL (ساده شده):

SQL
پرداخت جدول را تغییر دهید اضافه کردن محدودیت uniq_op منحصر به فرد (operation_id) ؛

Retray با لرزش (شبه کد):

پایتون برای من در محدوده (2):
سعی کنید: call_api بازگشت (payload, timeout = 0. 6)
به جز اتمام وقت:
خواب (0) 05 2i + تصادفی. یونیفرم (0, 0. 05))
بالا بردن UpstreamUnavailable

چک لیست:

تمام منطق «پولی/ایجاد» دارای «operation _ id» و شاخص uniq است.
وب سایت های ورودی تنها از طریق صندوق ورودی با کارمند idempotent.
SDK مشتری به طور خودکار کلید Idempotency را تنظیم می کند.

خطای شماره 2 زمان/بازپرداخت در مقابل SLO: وابستگی بیش از حد

علائم: p95 به طور ناگهانی شناور دور، صف رشد می کنند، قطع کننده مدار «bangs».

ریشه: SLO کل پاسخ 400-600 میلی ثانیه است، و زمان بندی برای API های خارجی 1-2 ثانیه است، و حتی × 3 را بازبینی می کند. شما بیشتر از آنچه می توانید انجام دهید و اعتیاد را با تکرار طوفان می کنید.

چگونه به

زمان بندی بودجه: اگر SLO 400 میلی ثانیه باشد، زمان بالادست: 250-300 میلی ثانیه ؛ مدت زمان کل درخواست ≤ SLO.

محدودیت/فشار پشتی: سمافور/کارگر استخر برای تماس به هر وابستگی. شلوغ → 429/503 در یک بار.

قطع کننده مدار: 'باز' با timeouts/5xx، 'نیمه باز' دوز.

کنترل پذیرش: محدود کردن همزمانی (در هر موضوع، در هر نقطه پایانی/PSP).

مثال (برو):

go sem: = make (chan struct {}, 64 )//حد رقابت به PSP func callPSP (ctx context. متن، req req) (تحقیق، خطا) {
انتخاب کنید {
مورد sem <- ساختار {}:
به تعویق انداختن func () {<-sem} ()
c، لغو: = زمینه. WithTimeout (ctx، 300 زمان. میلی ثانیه)
تعویق لغو ()
بازگشت PSP انجام دهید (c، req)
پیش فرض:
بازگشت Res {}، ErrBusy//شکست فوری به جای صف بی پایان
}
}

چک لیست:

وقفه ها کوتاه تر از SLO هستند ؛ retrai ≤ 2 ؛ اينجا جيتر هست.
استخر/semaphores به API های خارجی ؛ قطع کننده مدار با متریک.
در مسیرهای شلوغ، ما به 429/Retry-After باز می گردیم، نه ارتباطات را حفظ می کنیم.

خطای شماره 3 امنیت ضعیف: امضاهای Webhook، اسرار، TLS

علائم: «افراد دیگر» webhooks عبور، اسرار در کد/ورود به سیستم، خطرات MITM.

ریشه: بدون چک امضا/طراوت، اسرار در فایل های ENV، TLS قدیمی و هدر ضعیف زندگی می کنند.

چگونه به

امضای webhooks HMAC-SHA256 + 'X-Timestamp' (پنجره ≤ 5-10 دقیقه)، مقایسه دقیق امضا.

mTLS برای یکپارچگی بحرانی یا لیست مجاز IP.

چرخش اسرار از طریق Vault/Cloud KMS ؛ حداقل حقوق ؛ حسابرسی تفریق.

TLS 1. 2/1. فقط 3، HSTS، CORS صحیح (لیست منبع باریک).

تأیید امضا (پایتون):

python def verify (sig_hdr, ts_hdr, body, secret):
اگر ABS (زمان. time () - int (ts_hdr))> 600: بالا بردن منقضی شده ()
کالک = هماک جدید (راز، (ts_hdr + «.» + بدن). encode (), hashlib. sha256) شش ضلعی ()
اگر نه HMAC. compare_digest (کالک، sig_hdr): افزایش BadSig ()

چک لیست:

تمام وب سایت ها امضا شده و تایید شده اند ؛ پنجره تازه محدود است.
اسرار در KMS/Vault، چرخش و حسابرسی وجود دارد.
TLS/HSTS را فعال کنید ؛ نقطه CORS ؛ IP/mTLS در صورت لزوم

خطای شماره 4 رانش قرارداد: طرح «زندگی خود را زندگی کرد»

علائم: PROD سقوط «تنها در برخی از مشتریان»، 500/422 در سیاهههای مربوط، نسخه های مختلف از SDK و API استدلال می کنند.

ریشه: هیچ توصیف دقیقی از قراردادها، تغییرات ناسازگار گذشته، زمینه های «آرام»، معانی مختلف برای نام های مشابه وجود ندارد.

چگونه به

قرارداد اول: OpenAPI/AsyncAPI + تولید سرور/مشتری ؛ برای رویدادها - Avro/Protobuf + Schema Registry.

نسخه بندی: 'v1 → v2' (URI/header)، انحراف طرح، گریس دوره.

کامپات عقب: تنها تغییرات افزودنی در نسخه های جزئی ؛ بدون v-bump نمی توان حذف/تغییر نام داد.

تست های قرارداد: Pact/Buf - ارائه دهنده/مصرف کننده در CI آزمایش می شود.

مثال ها:

یامل
OpenAPI: نوع مشخصی از مبلغ در واحدهای amount_minor جزئی:
نوع: حداقل عدد صحیح: 0 شرح: مجموع در حداقل واحد ارز (عدد صحیح)

چک لیست:

قراردادها در git ذخیره می شوند، CI اگر ناسازگار باشد، معتبر/خراب می شود.
Schema برای رویدادها، سازگاری «عقب/جلو» ثبت می شود.
صفحه docking تغییرات، تاریخ تخریب، نیمکت آزمون برای شرکا.

خطای شماره 5 «کور» راه اندازی: هیچ متریک/سیاهههای مربوط/مسیرهای پیاده روی و sandbox

علائم: «هیچ چیز قابل مشاهده است»، پشتیبانی پر می کند، debag - دست در prod.

ریشه: مشاهده پذیری گنجانده نشده است، هیچ مصنوعی وجود ندارد، sandbox «در کلمات» آزمایش شد.

چگونه به

معیارهای RED/USE: نرخ/خطا/تاخیر در هر نقطه پایانی، توسط مسیر/روش.

همبستگی: 'trace _ id' در تمام سیاههها و پاسخها ؛ بسته بندی zapros↔vebkhuk

Synthetics: آزمایشات بهداشتی (شن و ماسه ورود/سپرده)، نظارت SLA T + 60 برای webhooks.

Sandbox/stage: کلیدها/دامنههای کاملاً مجزا، PSPهای ساختگی، ورودیها «در گزارشها گنجانده نشدهاند».

پاسخ با شناسه ردیابی:

وب سایت
HTTP/1 است. 1 202 پذیرفته شده است
ردیابی شناسه: 7f2b3d8e9c1a4
محل سکونت :/ v1/ops/req_42/status

چک لیست:

قرمز/استفاده از معیارهای، داشبورد، هشدار (علائم + علل).
پایان به پایان مسیرهای پیاده روی ؛ JSON سیاهههای مربوط، بدون PII، با 'trace _ id'.
مصنوعی از مناطق کلیدی ؛ sandbox مورد نیاز است، کلید های مختلف.

طرح مقدماتی (T-7 → T-0)

روزهای T-7:

اسکن قرارداد نهایی: آیا تغییرات ناسازگار وجود دارد ؛ طرح های یخ زده
اسرار/گواهینامه ها: چرخش، دسترسی، سیاست های KMS را بررسی کنید.
مصنوعی 24 × 7، هشدار به تماس گره خورده است.

T-3 روز:

بارگیری مینی اجرا (پشت سر هم 2-5 دقیقه): p95/استخر/صف در منطقه سبز.
DRY-RUN webhooks (تکرار، 5xx، jitter)، بررسی DLQ.
«دفترچه تلفن» شرکا: مخاطبین L1/L2، کانال اتاق جنگ.

T-0:

ترافیک کانال 5٪ → 25٪ → 50٪ برای دروازه های SLO ؛ آماده برگشت.
Kill-switch/feature-flags در ویژگی های خطرناک گنجانده شده است.
اتاق جنگ فعال است، قالب وضعیت آماده شده است.

طرح بازگشت (اگر چیزی اشتباه رفت)

1. انتشار ترافیک به نسخه پایدار/مسیر قبلی.

2. غیرفعال کردن تغییرات بحثبرانگیز phicheflag.

3. تثبیت صف/استخر، توقف عقب نشینی در طوفان.

4. پس از حادثه: جمع آوری جدول زمانی، ریشه ها، وظایف (ثابت/قرارداد ثابت).

جدول خودآزمایی را شروع کنید (کوتاه)

مسدود کردن	پرسش و پاسخ	آره، نه
ایده پردازی	آیا تمام متدهای «creating» یک Idempotency-Key/' operation _ id 'و یک شاخص uniq دارند ؟
بازپرداخت/زمان بندی	تایم اوت ها کوتاه تر از SLO هستند. ≤2 retrai ؛ جيتر روشن بود ؟
امنیت و ایمنی	وب سایت امضا شده، پنجره طراوت ≤10 دقیقه، اسرار در KMS ؟
قرارداد ها	OpenAPI/AsyncAPI ثابت است، CI ناسازگاری را جلب می کند ؟
قابل مشاهده بودن	قرمز/استفاده، مسیرهای پیاده روی، مصنوعی T + 60، sandbox جدا شده است ؟
برگشت به عقب	آیا دکمه برگشت/kill-switch، برنامه ارتباطی وجود دارد ؟

اغلب پرسیده می شود «چه می شود اگر»...

... آیا ارائه دهنده از Idempotency-Key پشتیبانی نمی کند ؟

«هش (بدنه)» + «partner _ request _ id» را ذخیره کنید و idemotency خود را وارد کنید.

... گاهی اوقات وب سایت ها «قبل» پاسخ می دهند ؟

دوختن در 'operation _ id' و به طور موقت حفظ وضعیت «unknown» → آشتی دادن ؛ آشتی دوره ای اختلافات را می بندد.

... نیاز به حمایت از مشتریان قدیمی و جدید ؟

نسخه نقاط پایانی ('/v1 'و '/v2')، مسیر توسط هدر/URI، حداقل N ماه سازگاری عقب را حفظ کنید.

خلاصه رزومه

شکست ادغام تقریبا همیشه در مورد همان چیزی است: هیچ idempointency، زمان اشتباه و عقب نشینی، امضای ضعیف از webhooks، رانش قرارداد و عدم دید. ثابت قرارداد در پیشبرد، فعال کردن مشاهده، محدودیت محل/backprescher، ثبت نام تمام فعل و انفعالات خارجی و اجرای مصنوعی. سپس، حتی در صورت شکست شرکا، آزادی شما قابل کنترل خواهد بود - بدون از دست دادن پول در retras، و بدون یک شب بی خوابی برای کل تیم.