Іске қосу кезінде API интеграциясының бес сыни қатесі

Қате № 1. Теңсіздік пен ретрайлардың «дауылы» жоқ

Симптомдары: тапсырыстар/төлемдер дублі, сомалар айырмашылығы, даулы қайтарымдар, DLQ тәуекелдері өсуде.

Түбірі: сұрау/вебхуктарды қайта жеткізу және желілік флаппи - қалыпты. Егер «құру/есептен шығару» операциясы ұқсас болмаса, ретралар залалды көбейтеді.

Қалай дұрыс

Idempotency-Key/' operation _ id 'барлық қауіпсіз емес әдістерге (POST/PATCH).

'operation _ id' бойынша ДҚ-дағы бірегей индекс. Қайталау - бұрынғы нәтижені қайтарыңыз.

Вебхактар Inbox-кесте арқылы (dedupe 'event _ id + signature'). Шығыс оқиғалар - Outbox.

Ретра: ең көп дегенде 1-2 рет, экспонент + джиттер, тек қауіпсіз операциялар үшін.

HTTP-конвенция (мысал):

http
POST /v1/payments
Idempotency-Key: ik_f35a2
Content-Type: application/json

{"amount": 5000, "currency": "EUR", "source": "card_..."}

SQL қорғанысы (жеңілдетілген):

sql
ALTER TABLE payments ADD CONSTRAINT uniq_op UNIQUE (operation_id);

Джиттермен ретраи (псевдокод):

python for i in range(2):
try: return call_api(payload, timeout=0. 6)
except Timeout:
sleep(0. 05 2i + random. uniform(0, 0. 05))
raise UpstreamUnavailable

Чек парағы:

Барлық «ақшалай/жасаушы» логикада 'operation _ id' және uniq-индексі бар.
Кіріс веб-хаттар тек іспеттес воркері бар Inbox арқылы.
Клиенттік SDK Idempotency-Key автоматты түрде қояды.

Қате № 2. SLO-ға қарсы тайм-ауттар/ретраилер: тәуелділіктің «қызып кетуі»

Белгілері: p95 кенеттен жүзіп кетеді, кезектер өседі, circuit breaker «шағылыстырады».

Түбірі: жауаптың жалпы SLO - 400-600 мс, ал сыртқы API-ге тайм-ауттар - 1-2 с, және тағы да ретра × 3. Сіз мүмкіндігіңізден ұзақ істейсіз және тәуелділікті қайталап шабуылдаасыз.

Қалай дұрыс

Budget-тайминг: егер SLO 400 мс, upstream-тайм-аут: 250-300 мс; сұраудың жалпы тайм-ауты ≤ SLO.

Limits/Backpressure: әр тәуелділікке шақыру үшін семафорлар/worker-pool. Толып кетті → 429/503 бірден.

Circuit breaker: 'open' тайм-аутта/5хх, 'half-open' дозаланған.

Admission control: параллелизмді шектеңіз (ағынға, endpoint/PSP).

Мысал (Go):

go sem: = make (chan struct {}, 64 )//PSP func callPSP (ctx context. Context, req Req) (Res, error) {
select {
case sem <- struct{}{}:
defer func(){ <-sem }()
c, cancel:= context. WithTimeout(ctx, 300time. Millisecond)
defer cancel()
return psp. Do(c, req)
default:
return Res {}, ErrBusy//шексіз кезек орнына дереу бас тарту
}
}

Чек парағы:

Тайм-ауттар SLO-дан қысқа; ≤ 2 ретраялары; джиттер бар.
Сыртқы API-ге арналған пулдар/семафорлар; circuit breaker өлшемдерімен.
«busy» маршруттарында қосылымдарды ұстап тұру емес, 429/Retry-After қайтарамыз.

Қате № 3. Қауіпсіздік әлсіз: вебхук қолтаңбалары, құпиялар, TLS

Симптомдары: «бөтен» вебхактар, кодтағы/логтағы құпиялар, MITM-тәуекелдер.

Түбір: қолтаңбаны/жаңаруды тексеру жоқ, құпиялар env файлдарында, ескі TLS және әлсіз тақырыптарда тұрады.

Қалай дұрыс

Вебхуктардың қолтаңбасы HMAC-SHA256 + 'X-Timestamp' (терезе ≤ 5-10 мин), қолтаңбаны қатаң салыстыру.

сыни интеграциялар немесе IP allow-list үшін mTLS.

Vault/Cloud KMS арқылы құпияларды ротациялау; құқықтардың минимумы; шегерім аудиті.

TLS 1. 2/1. 3 only, HSTS, дұрыс CORS (көздердің тар тізімі).

Қолтаңбаны тексеру (Python):

python def verify(sig_hdr, ts_hdr, body, secret):
if abs(time. time() - int(ts_hdr)) > 600: raise Expired()
calc = hmac. new(secret, (ts_hdr + "." + body). encode(), hashlib. sha256). hexdigest()
if not hmac. compare_digest(calc, sig_hdr): raise BadSig()

Чек парағы:

Барлық веб-хаттар қол қойылған және тексеріледі; жаңалық терезесі шектеулі.
KMS/Vault құпиялары, ротация және аудит бар.
TLS/HSTS қосылған; CORS нүктелі; IP/mTLS орынды.

Қате № 4. Дрифт-келісімшарт: «өз өмірімен өмір сүрді» схемасы

Симптомдары: прод «клиенттердің бір бөлігіне ғана» түсті, логтарда 500/422, SDK және API әртүрлі нұсқалары дауласады.

Түбір: келісімшарттардың қатаң сипаттамасы жоқ, кері үйлеспейтін өзгерістер, «тыныш» өрістер, бірдей атаулардың мағынасы әртүрлі.

Қалай дұрыс

Бірінші келісім-шарт: OpenAPI/AsyncAPI + серверлерді/клиенттерді генерациялау; оқиғалар үшін - Euro/Protobuf + Schema Registry.

Нұсқалау: 'v1 → v2' (URI/хедер), deprecation-жоспар, grace-кезең.

Backward-compat: шағын релиздерде тек additive өзгерістер; v-bumpсіз өшіруге/қайта атауға тыйым салу.

Келісімшарттық тесттер: Pact/Buf - провайдер/консумер CI тексеріледі.

Мысалдар:

yaml
OpenAPI: amount_minor шағын бірліктеріндегі нақты сома түрі:
type: integer minimum: 0 description: Валютаның ең аз бірліктеріндегі сома (бүтін)

Чек парағы:

Келісімшарттар git-те сақталады, CI сәйкессіздік кезінде валидациялайды/бұзады.
Оқиғалар үшін схемалар тіркелгілері, «back/forward» сыйысымдылығы.
Өзгерістердің док-беті, деприкация күндері, серіктестер үшін тестілеу стенді.

Қате № 5. «Соқыр» іске қосу: метриктер/логтар/трейлерлер және құмсалғыштар жоқ

Симптомдары: «ештеңе көрінбейді», қолдауды тоқтатады, дебаг - қолмен тамақта.

Тамыры: бақылаушылық қосылмаған, синтетика жоқ, құмсалғышты «сөзбен» қамырлаған.

Қалай дұрыс

RED/USE-метриктер: rate/error/latency әрбір endpoint, бағыттар/әдістер бойынша.

Корреляция: 'trace _ id' барлық логтар мен жауаптарда; сұрауды байланыстырып, вебхук.

Синтетика: health-сынамалар (login/deposit-құм), вебхуктар үшін SLA-мониторинг T + 60.

Құмсалғыш/стейдж: толық оқшауланған кілттер/домендер, жалған PSP, жазбалар «есептерге кірмейді».

trace идентификаторы бар жауап:

http
HTTP/1. 1 202 Accepted
Trace-Id: 7f2b3d8e9c1a4
Location: /v1/ops/req_42/status

Чек парағы:

RED/USE өлшемдері, дашбордтар, алерталар (симптомдар + себептер).
end-to-end трейдерлері; JSON логтары, PII жоқ, с 'trace _ id'.
Негізгі өңірлерден синтетика; құмсалғыш міндетті, кілттер әр түрлі.

Прелаунч-жоспар (T-7 → T-0)

T-7 күн:

Соңғы келісімшарт-сканер: үйлеспейтін өзгерістер жоқ па; freeze схемалары.
Құпиялар/сертификаттар: айналымын, қолжетімділігін, KMS саясатын тексеріңіз.
Синтетика 24 × 7, алерталар on-call байланған.

T-3 күн:

Жүктемелі шағын жүгіру (burst 2-5 мин): р95/пулы/жасыл аймақтағы кезек.
DRY-RUN вебхук (қайталаулар, 5xx, джиттер), DLQ тексеру.
Серіктестер «Телефон кітабы»: L1/L2 контактілер, war-room арнасы.

T-0:

Канареялық трафик 5% → 25% → 50% SLO-гейтпен; дайын rollback.
Қатер шегінде kill-switch/feature-flags қосылған.
War-room белсенді, күй үлгілері дайын.

Роллбэк-жоспар (егер бірдеңе дұрыс болмаса)

1. Трафикті алдыңғы тұрақты нұсқаға/маршрутқа алып тастау.

2. Даулы өзгерістерді фичефлагпен өшіру.

3. Кезекті/пулды тұрақтандыру, «дауыл» кезінде ретрацияны тоқтату.

4. Пост-инцидент: таймлайн, түбірлерді, міндеттерді жинау (фикс-форвард/келісімшарт фикстері).

Іске қосуға өзін-өзі тексеру кестесі (қысқа)

Блок	Сұрақ	Иә/Жоқ
Теңсіздік	Барлық «жасаушы» әдістерде Idempotency-Key/' operation _ id 'және uniq-индексі бар ма?
Ретрайлер/тайм-ауттар	Тайм-ауттар SLO-дан қысқа; ≤ 2 ретраялары; джиттер қосылды ма?
Қауіпсіздік	Вебхактар қол қойылған, жаңалық терезесі ≤ 10 мин, KMS құпиялары?
Келісімшарттар	OpenAPI/AsyncAPI тіркелген, CI сыйыспаушылықты ұстап отыр ма?
Бақылау мүмкіндігі	RED/USE, трейстер, синтетика T + 60, құмсалғыш оқшауланған ба?
Роллбэк	Кері қайтару/kill-switch түймешігі, коммуникация жоспары бар ма?

Жиі қойылатын «егер...»

... провайдер Idempotency-Key қызметін қолдамайды ма?

'hash (body)' + 'partner _ request _ id' сақтаңыз және өзіңіздің ұқсастығыңызды енгізіңіз.

... вебхактар кейде жауаптың алдында келеді ме?

'operation _ id' бойынша тігіңіз және «unknown → reconcile» мәртебесін уақытша сақтаңыз; мерзімдік reconciler айырмашылықтарды жабады.

... ескі клиенттер мен жаңа клиенттерді қолдау керек пе?

endpoint '('/v1' және '/v2 ') түрлендіріңіз ,/URI тақырыбы бойынша бағыттаңыз, кемінде N ай бойы backward үйлесімділігін сақтаңыз.

Түйіндеме

Интеграцияның сәтсіздігі әрқашан бірдей: демпотенттік жоқ, тайм-ауттар мен ретрайлер дұрыс емес, веб-хуктардың қолтаңбасы әлсіз, келісімшарттардың дрейфі және көрінудің жоқтығы. Келісімшарттарды алдын ала белгілеңіз, бақылауды қосыңыз, лимиттерді/бекпрешерді белгілеңіз, барлық сыртқы өзара іс-қимылдарға қол қойыңыз және синтетиканы іске қосыңыз. Сонда серіктестер сәтсіздікке ұшыраса да, сіздің шығарылымыңыз басқарылатын болады - ретрада жоғалған ақшасыз және бүкіл командада ұйқысыз түнсіз.