Açylanda API integrasiýasynyň bäş sany möhüm ýalňyşlygy

№ 1 ýalňyşlyk. Yhlas ýok we retraýlaryň "tupany"

Alamatlary: sargytlary/tölegleri goşmak, pul tapawudy, jedelli yzyna gaýtaryşlar, DLQ alertleri artýar.

Kök: Soraglary/webhuklary gaýtadan eltip bermek we tor flappileri - adaty. Eger "döretmek/ýazmak" operasiýasy indempotent bolmasa, retralar zyýany köpeldýärler.

Dogry

Idempotency-Key/' operation _ id 'ähli howply usullar üçin (POST/PATCH).

"operation _ id" DB-de özboluşly indeks. Gaýtalamak - öňki netijäni yzyna gaýtaryň.

Inbox-tablisanyň üsti bilen webhuklar (dedupe 'event _ id + signature'). Gidýän wakalar - Outbox.

Retraýlar: iň köp 1-2 gezek, eksponent + jitter, diňe howpsuz amallar üçin.

HTTP-konwensiýasy (mysal):

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

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

SQL-gorag (ýönekeýleşdirilen):

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

Jitter bilen retrailer:

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

Çek sanawy:

Ähli "pul/dörediji" logikanyň 'operation _ id' we unik-indeksi bar.
Gelen webhoklar diňe idempotent worker bilen Inbox arkaly.
Müşderi SDK awtomatiki usulda Idempotency-Key goýýar.

№ 2 ýalňyşlyk. SLO garşy wagt/retra: endikleriň "aşa gyzmagy"

Alamatlary: p95 birden ýüzüp gidýär, nobatlar köpelýär, circuit breaker "sarsýar".

Kök: jogabyň umumy SLO - 400-600 ms, daşary API-e taým-autlar - 1-2 s, hatda retralar × 3. Mümkin boldugyça uzaga çekýärsiňiz we endikleriňizi gaýtalaýarsyňyz.

Dogry

Budget-taýming: SLO 400 ms, upstream-taým-aut: 250-300 ms; Soragyň umumy wagty ≤ SLO.

Limits/Backpressure: semaforlar/worker-pool her bir garaşlylyga çagyryşlara. Birbada dolduryldy → 429/503.

Circuit breaker: time-autlarda 'open '/5xx,' half-open 'dozasy.

Admission control: paralelligi çäklendiriň (akym, endpoint/PSP).

Mysal (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//tükeniksiz nobatyň ýerine derrew ýüz öwürmek
}
}

Çek sanawy:

Wagt autlary SLO-dan gysga; retralar ≤ 2; jitler bar.
Daşarky API-lere howuzlar/semaforlar; metrler bilen circuit breaker.
"busy" ugurlarda baglanyşyklary saklamak däl-de, 429/Retry-After yzyna gaýtarýarys.

№ 3 ýalňyşlyk. Gowşak howpsuzlyk: webhook gollary, syrlar, TLS

Alamatlary: "nätanyş" webhuklar geçýär, kodda/ýazgyda syrlar, MITM-töwekgelçilikler.

Kök: gol/täzelik barlagy ýok, syrlar env faýllarda, köne TLS we gowşak sözbaşylarda ýaşaýar.

Dogry

Webhuklaryň goly HMAC-SHA256 'X-Timestamp' (penjire ≤ 5-10 minut), goluň berk deňeşdirilmegi.

Möhüm integrasiýa üçin mTLS ýa-da IP allow-list.

Vault/Cloud KMS arkaly syrlary aýlamak; iň az hukuk; aýyrma barlagy.

TLS 1. 2/1. 3 only, HSTS, dogry CORS (çeşmeleriň dar sanawy).

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

Çek sanawy:

Webhuklaryň hemmesi gol çekilýär we barlanýar; täzelik penjiresi çäklidir.
KMS/Vault-da syrlar, aýlanyş we audit bar.
TLS/HSTS goşuldy; Nokat CORS; IP/mTLS ýerlikli.

№ 4 ýalňyşlyk. Drift-şertnama: "öz durmuşynda ýaşady" shemasy

Alamatlary: "diňe müşderileriň bir bölegine" düşdi, 500/422, SDK we API-iň dürli görnüşleri jedel edýär.

Kök: şertnamalaryň berk beýany ýok, ters gabat gelmeýän üýtgeşmeler, "asuda" meýdanlar, birmeňzeş atlaryň dürli manylary.

Dogry

Birinji şertnama: OpenAPI/AsyncAPI + serwerleri/müşderileri döretmek; wakalar üçin - Euro/Protobuf + Schema Registry.

Wersiýa: 'v1 → v2' (URI/heder), deprecation-plan, grace-döwür.

Backward-compat: diňe minor relizlerdäki additive üýtgeşmeler; v-bump bolmazdan aýyrmak/adyny üýtgetmek gadaganlygy.

Şertnama synaglary: Pact/Buf - üpjün ediji/konsumer CI-de barlanýar.

Mysal üçin:

yaml
OpenAPI: minor birliklerdäki jemi amount_minor:
type: integer minimum: 0 description: Iň az walýuta birliklerindäki mukdar (tutuş)

Çek sanawy:

Şertnamalar git-de saklanylýar, CI gabat gelmeýän ýagdaýynda tassyklaýar/bozýar.
Wakalar üçin shema registrleri, "back/forward" gabat gelýär.
Üýtgeşmeler sahypasy, deprikasiýa senesi, hyzmatdaşlar üçin synag stendi.

№ 5 ýalňyşlyk. "Kör" başlangyç: metrikler/loglar/treyslar we sandyk gutusy ýok

Alamatlary: "hiç zat görünmeýär", goldawy doldurýar, debag - elleri bilen naharda.

Kök: gözegçilik edilmedi, sintetika ýok, sandyk gutusy "sözde" synagdan geçirildi.

Dogry

RED/USE-metrikler: rate/error/latency her endpoint-de, marşrutlar/usullar boýunça.

Baglanyşyk: 'trace _ id' ähli bloglarda we jogaplarda; Bir topar sorag- vebhuk.

Sintetika: saglyk synaglary (login/deposit-gum), webhuklar üçin SLA-monitoring T + 60.

Sandbox/Stage: doly izolirlenen açarlar/domenler, toslama PSP, ýazgylar "hasabatlara girmeýär".

Trace identifikatorly jogap:

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

Çek sanawy:

RED/USE metrikleri, daşbordlar, aladalar (alamatlar + sebäpler).
End-to-end söwdalary; JSON logleri, PII-siz, 'trace _ id'.
Esasy sebitlerden sintetika; guty hökmanydyr, açarlar dürli.

Prelaunch meýilnamasy (T-7 → T-0)

T-7 gün:

Jemleýji kontrakt-skan: gabat gelmeýän üýtgeşmeleriň ýokdugy; freeze shemalary.
Syrlar/şahadatnamalar: aýlanyş, elýeterlilik, KMS syýasatlaryny barlaň.
Sintetika 24 × 7, alertler on-call-a daňylýar.

T-3 gün:

Ýük mini-geçişi (burst 2-5 minut): p95/howuzlar/ýaşyl zolakda nobatlar.
DRY-RUN webhook (gaýtalamak, 5xx, jitter), DLQ barlagy.
Hyzmatdaşlaryň "Telefon kitaby": L1/L2 aragatnaşyklar, war-room kanaly.

T-0:

Kanar traffigi 5% → 25% → 50% SLO geýtleri boýunça; rollback taýýar.
Töwekgelçilikli şekillerde öldürmek-switch/feature-flags goşuldy.
War-room işjeňdir, status şablonlary taýýarlandy.

Rollbek meýilnamasy (bir zat nädogry bolsa)

1. Traffigi öňki durnukly wersiýasyna/ugruna aýyryň.

2. Jedelli üýtgeşmeleri fiçeflag bilen öçürmek

3. Nobatlary/howuzlary durnuklaşdyrmak, "tupan" wagtynda retralary duruzmak.

4. Post-waka: taýmline, kökleri, wezipeleri ýygnamak (fix-forward/kontrakt fixleri).

Öz-özüňi barlamak üçin tablisa (gysga)

Blok	Sorag	Hawa/Ýok
Idempotentlik	"Dörediji" usullaryň hemmesinde Idempotency-Key/' operation _ id 'we unik-indeks barmy?
Retrailer/Wagt-autlar	Wagt autlary SLO-dan gysga; retralar ≤ 2; Jitler açykmy?
Howpsuzlyk	Webhuklar gol çekilýärmi, täzelik penjiresi ≤ 10 min, KMS-de syrlar?
Şertnamalar	OpenAPI/AsyncAPI hasaba alyndy, CI gabat gelmeýänligi tutýarmy?
Syn ediliş	RED/USE, söwda, sintetika T + 60, sandyk gutusy izolirlenen?
Rollback	Aragatnaşyk meýilnamasy/öldürmek-switch düwmesi barmy?

Köplenç "näme etmeli, eger..."

... üpjün ediji Idempotency-Key-i goldamaýarmy?

'hash (body)' + 'partner _ request _ id' -ni saklaň we idempotentligiňizi giriziň.

... webhuklar käwagt jogapdan "öň" gelýär?

'operation _ id' bilen tikiň we "unknown → reconcile" statusyny wagtlaýyn saklaň; wagtal-wagtal reconciler tapawudy ýapar.

... köne müşderileri we täze müşderileri goldamaly?

Endpoint 'leriňizi ('/v1' и '/v2 ') wersiýalaň ,/URI sözbaşy boýunça ugrukdyryň, iň az N aýlap saklaň.

Jemleme

Integrasiýalardaky şowsuzlyklar hemişe diýen ýaly birmeňzeş: idempotentlik ýok, nädogry wagt we retralar, webhuklaryň gowşak goly, şertnamalaryň süýşmegi we görünmezlik. Şertnamalary öňünden belläň, gözegçiligi açyň, çäkleri/bekpreşeri goýuň, ähli daşarky özara gatnaşyklara gol çekiň we sintetikany işe giriziň. Şonda, hyzmatdaşlaryňyzda şowsuzlyklar ýüze çyksa-da, goýberişiňiz dolandyrylyp bilinmez - retrada ýitirilen pul bolmazdan we tutuş toparyň ukusyz gijesi bolmazdan.