Ишке киргизүүдө беш маанилүү API интеграциялык каталар

Ката № 1. Эч кандай демпотенттик жана "бороон" retrais

Симптомдору: эки буйрутмалар/төлөмдөр, суммалардын айырмачылыгы, талаштуу кайтарымдар, DLQ алерттери өсүүдө.

Root: суроо-талаптарды/Webhook кайра жеткирүү жана тармак Flap - нормалдуу. Эгерде "түзүү/эсептен чыгаруу" операциясы демпотенттик болбосо, ретрайлер зыянды көбөйтөт.

Кантип туура

Idempotency-Key/' operation _ id 'бардык кооптуу ыкмаларга (POST/PATCH).

DB боюнча уникалдуу индекси 'operation _ id'. Кайталоо - мурунку жыйынтыкты кайтарыңыз.

Inbox жадыбалы аркылуу Webhucks (dedupe 'event _ id + signature'). Чыгыш окуялар - Outbox.

Retrais: максималдуу 1-2 жолу, экспонент + життер, коопсуз иш үчүн гана.

HTTP-Convention (мисал):

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-индекси бар.
Кирген Webhucks гана демпотент Worker менен Inbox аркылуу.
Кардар SDK жазуусу Idempotency-Key койду.

Ката № 2. SLO каршы убакыт/Retray: "ысып" көз карандылык

Белгилери: p95 күтүлбөгөн жерден сүзүп, кезек өсүп, circuit breaker "чайкап".

Тамыры: жооп жалпы SLO - 400-600 мс, ал эми тышкы API үчүн тайм-ауттар - 1-2 с, ал тургай, retrais × 3. Сиз мүмкүн болушунча көп кылып, кайра көз карандылыкты басып.

Кантип туура

Budget-тайм: SLO 400 мс болсо, upstream-тайм-аут: 250-300 мс; жалпы убакыт суроо ≤ SLO.

Limits/Backpressure: семафор/worker-pool ар бир көз карандылыкка чалуулар. толуп → 429/503 дароо.

Circuit breaker: тайм-ауттарда 'open '/5xx,' 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. Начар коопсуздук: кол Webhook, сырлар, TLS

Белгилери: "чоочун" Webhuke өтүп, код/Логдо сырлар, MITM-тобокелдиктер.

Тамыры: эч кандай кол тамга/сергектик текшерүү, сырлар env-файлдарда жашайт, эски TLS жана алсыз аталыштар.

Кантип туура

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

mTLS критикалык интеграция же IP allow-list үчүн.

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()

Чек тизмеси:

Бардык Webhucks кол коюлган жана текшерилет; терезе сергектик чектелген.
KMS/Vault сырлары, айлануу жана аудит бар.
TLS/HSTS кирет; CORS чекити; ылайыктуу IP/mTLS.

Ката № 4. Drift-контракт: схемасы "өз өмүрүн жашап"

Симптомдору: "кардарлардын бир бөлүгү гана", 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" шайкештиги.
Doc-бет өзгөртүү, деприкация датасы, өнөктөштөр үчүн сыноо стенд.

Ката № 5. "Сокур" ишке киргизүү: эч кандай метриктер/Логи/соода жана Sandbox

Белгилери: "эч нерсе көрүнбөйт", колдоо толуп, дебаг - тамак-ашта колу менен.

тамыры: байкоо камтылган эмес, эч кандай синтетика, кум "сөз" сыналган.

Кантип туура

RED/USE-метрика: маршруттар/ыкмалар боюнча ар бир endpoint боюнча rate/error/latency.

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

Синтетика: ден соолук үлгүлөрү (login/deposit-кум), SLA мониторинг T + 60 үчүн Webhook.

Sandbox/Stage: толугу менен изоляцияланган ачкычтар/домендер, жасалма PSP, жазуулар "отчетторго кирбейт".

trace ID менен жооп:

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

Чек тизмеси:

RED/USE Metrics, Dashboard, Алерт (симптомдору + себептери).
end-to-end соода; JSON Логи, PII жок, с 'trace _ id'.
негизги аймактардан синтетика; керек, ачкычтар ар кандай.

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

T-7 күн:

Акыркы контракт-сканер: шайкеш келбеген өзгөрүүлөр бар; freeze схемалар.
Сырлар/күбөлүктөр: айлануу текшерүү, кирүү, KMS саясаты.
Синтетика 24 × 7, аллергия on-call менен байланышкан.

T-3 күн:

Жүктөө мини-чуркоо (burst 2-5 мин): p95/жашыл зонада пулдар/кезек.
DRY-RUN Webhook (кайталоо, 5xx, Jitler), DLQ текшерүү.
"Телефон китеби" өнөктөштөр: L1/L2 байланыштар, war-room канал.

T-0:

Канар трафик 5% → 25% → 50% SLO гейт; даяр rollback.
Тобокелдик phichs боюнча kill-switch/feature-flags кирет.
War-room активдүү, статус-шаблондор даярдалган.

Rollback планы (бир нерсе туура эмес болсо)

1. Мурунку туруктуу версия/маршрут үчүн трафикти алып салуу.

2. Ficheflagom талаштуу өзгөрүүлөрдү өчүрүү.

3. кезектерди/пулдарды турукташтыруу, "бороон-чапкын" учурунда ретрацияны токтотуу.

4. Пост-инцидент: таймлайн, тамыр, милдеттерди чогултуу (фикс-форвард/контракт фикстери).

Өзүн-өзү текшерүү жадыбалы (кыска)

Блок	Суроо	Ооба/Жок
Демпотенттик	Бардык "түзүү" ыкмалары Idempotency-Key/' operation _ id 'жана uniq-индекси бар?
Ретраи/тайм-ауттор	Убакыттын өтүшү SLO кыска; ретраиялар ≤ 2; Життер күйгүзүлгөнбү?
Коопсуздук	Вебхактар кол коюлган, жаңылык терезе ≤ 10 мин, KMS сырлар?
Келишимдер	OpenAPI/AsyncAPI белгиленген, CI туура эмес кармап?
Байкоо	RED/USE, соода, синтетикалык T + 60, Sandbox өзүнчө?
Роллбэк	Артка/kill-switch баскычы бар, байланыш планы?

Көп учурда "эмне кылуу керек, эгер..."

... провайдер Idempotency-Key колдобойбу?

'hash (body)' + 'partner _ request _ id' сактаңыз жана сиздин демпотенттүүлүгүңүздү киргизиңиз.

... Webhook кээде "эрте" жооп келет?

'operation _ id' аркылуу тигүү жана убактылуу "unknown → reconcile" статусу; мезгил-мезгили менен reconciler айырмачылыктарды жабат.

... эски кардарларды жана жаңы кардарларды колдоо керекпи?

endpoint's version ('/v1 'и '/v2'), аталышы/URI боюнча багыттоо, жок дегенде N ай backward шайкештикти сактап.

Резюме

Интеграциялардын ийгиликсиздиктери дээрлик ар дайым бир эле нерсе жөнүндө: эч кандай демпотенттүүлүк, туура эмес тайм-ауттар жана ретрациялар, вебхуктардын начар кол тамгасы, келишимдердин дрейфтери жана көрүнбөө. Алдын ала келишимдерди бекитүү, байкоо киргизип, чектөөлөрдү/бекпрешерди коюп, бардык тышкы өз ара аракеттенүүгө кол коюп, синтетиканы ишке киргизүү. Ошондо да өнөктөштөр ийгиликсиз болсо да, сиздин релизиңиз башкарылуучу бойдон калат - ретрада жоголгон акчасыз жана бүт командада уйкусуз түн жок.