Sincronizarea datelor prin API
1) De ce este necesară sincronizarea și care sunt obiectivele
Consistența domeniului: profil, portofel, directoare, limite, KYC.
Scăderea decalajelor: aproape în timp real pentru procese critice (plăți, bonusuri).
Reziliență: se confruntă cu întreruperi de rețea/furnizor fără pierderi de evenimente.
Economie: Minimizați ieșirea/procesorul prin delte și ambalare.
Valori de succes: decalaj între sursă și consumator, prospețime, proporția de duplicate, procentul de conflicte, costul de GB/oră de albastru.
2) Modele de sincronizare
2. 1 Tragere (votare)
Clientul solicită modificări la intervale de timp.
Pro: simplitate, controlul sarcinii.
Contra: decalaj, sondaje „goale”, risc de a sări peste o rată ridicată de schimbare.
Îmbunătățiri: Dacă-modificat-deoarece, Etag/If-None-Match, change_token.
2. 2 Împingere (webhooks/evenimente)
Sursa fluffs evenimentele la destinatar.
Pro: aproape în timp real, economie de sondaj.
Contra: aveți nevoie de livrare cu retraverse, deduplicare, securitate (semnătură, mTLS).
Cerințe: consumatori idempotenți, backoff exponențial, reluare.
2. 3 CDC/Streaming (modificarea capturii de date)
Instantaneu al modificărilor din jurnalul de tranzacții/eveniment (Kafka, Debezium).
Argumente pro: exhaustivitate, ordine, scară.
Contra: complexitate, aveți nevoie de control asupra tipurilor de operațiuni (inserați/actualizați/ștergeți/piatra funerară).
2. 4 Hibrid
Webhooks ca un „declanșator”, sondare ca o rezervă și pentru reconciliere.
3) Delte incrementale
3. 1 Filigran (marcaj de timp)
Clientul stochează 'last _ seen _ ts' și solicită' updated _ at> filigran '.
Riscuri: drift oră - utilizare UTC și NTP; ia fereastra de suprapunere pentru 1-2 min și dedup de ID + versiune.
3. 2 Schimbă Token/Cursor
Token secvență stabilă: "? cursor = eyJvZmZzZXQiOjEwMDB9 '.
Pro: reziliență la schimbarea ordinii, scară.
Cerințe: cursoare non-epuizate, TTL și reluarea în condiții de siguranță.
3. 3 Decalaje numerotate (increment automat)
'id> last_id'. Simplu, dar se descompune atunci când sharding și „găuri” în secvența.
4) Paginare eșantion mare
Keyset/cursor (preferat): '? after = cursor & limit = 1000 '- stabil cu modificări.
Offset/limită - simplu, dar scump și supus schimburilor.
Specificați întotdeauna o cheie de sortare stabilă (de exemplu, „(updated_at, id)”).
json
{
"items": [ { "id": "u_1", "updated_at": "2025-11-03T16:59:10Z" } ],
"next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0xMS0wM1QxNjo1OToxMFoifQ==",
"has_more": true
}5) Schimbarea semanticii: upsert, fuzionare, ștergere
5. 1 Upsert/îmbinare
„PUT/resource/{ id}” este un înlocuitor complet.
'PATCH/resource/{ id}' - actualizare parțială (îmbinare patch-uri cu validare).
Idempotența prin „Idempotency-Key” pentru toți scrieți.
5. 2 Deletions
Soft delete (câmp 'șters = adevărat', 'șters _ la') - salvați istoricul; chiuveta dă piatră funerară.
Ștergeți greu - dați evenimentul 'deleted' înainte de a dispărea.
json
{ "id":"u_1", "event":"deleted", "deleted_at":"2025-11-03T17:00:00Z" }6) Controlul versiunii și concurența
6. 1 ETag/If-Match (încuietori optimiste)
Citiți returnările „ETag:” v123 „”.
Actualizare din „If-Match:” v123 „” - protecție împotriva „actualizărilor pierdute”.
În caz de conflict - 409 Conflict cu 'error _ code: "CONFLICT_VERSION"'.
6. 2 Versionarea înregistrărilor
Câmp 'versiune '/' actualizat _ at' - în calculul delta și eliminarea duplicatelor.
6. 3 Conflicte
Politici: last-write-wins, server-wins, unge-strategy by fields (de exemplu, sume → aditivi, steaguri → prioritate sursă).
7) Comandarea și eliminarea duplicatelor
7. 1 Procedura de livrare
Garanții: cel puțin o dată plus idempotență → standard de facto.
Pentru fluxurile critice de numerar - efecte exact o dată prin magazinul de idempotență.
7. 2 Chei de idempotence
Compoziția câmpurilor de domeniu: 'source _ id' event _ type' sequence '.
Depozitare TTL 24-72 ore (sau mai mult în SLA).
7. 3 Eliminarea duplicatelor
Salvați ultima versiune/seq aplicată receptorului; picătură cele mai în vârstă.
8) Repetiții, timeout-uri, backoff
Retriable: 5xx/429/408/timeout; Nerecuperabil: 400/401/403/404/ 409/422/410/412.
Backoff exponențial + jitter: 1s, 2s, 4s... la 30-60 de ani.
Retry-După respect pentru 429/503.
Timeout client: conexiune 3-5s, cerere generală 10-30; limita totală a încercărilor 3-6.
9) Lags și controlul SLA
9. 1 SLI/SLO
Lag SLI: lag median/p95 între 'happened _ at' și' aplicat în consumator ".
SLO: de exemplu, "p95 lag ≤ 60s (28d)", "ponderea evenimentelor pierdute = 0", "cota duplicatelor ≤ 0. 01%».
Eroare buget: cheltui pe versiuni/experimente.
9. 2 Măsurători
'sync _ lag _ seconds',' events _ received _ total ',' events _ applied _ total ',' duplicates _ total ',' conflicts _ total ',' retries _ total ',' backlog _ size ',' cursor _ advance _ rate '.
10) Reconciliere și rambursare
Reconcilieri zi/oră: totaluri/hash-uri ferestre.
API de reconciliere: 'GET/reconciliere? de la =... & to =... "returnează sumele de control și variațiile.
Backfill: reîncărcare sigură a datelor istorice în loturi cu un cursor, fără o sursă DDOS; respectă limitele.
11) Scheme și exemple
11. 1 Evenimente Webhook (semnat)
json
{
"event": "user. updated",
"id": "evt_01HX",
"occurred_at": "2025-11-03T18:00:05Z",
"sequence": 123456,
"data": { "id": "u_1", "email": "a@b. com", "updated_at": "2025-11-03T18:00:02Z" }
}- 'X-Signature: sha256 =
' - "X-Event-Id: evt_01HX'
- 'X-Retry: 0
11. 2 Eșantionare incrementală (sondaj)
"GET/v1/users? updated_after=2025-11-03T17: 58:00Z&cursor=...&limit=1000'
11. 3 Upsert idempotent
POST /v1/users
Idempotency-Key: upsert-u_1-20251103T1800Z
{ "id":"u_1","email":"a@b. com","version":124 }
→ 201/200 (stable)12) Siguranță și conformitate
Auth: OAuth2 scopes/JWT; pentru canale de legătură - mTLS la cerere.
Subtitrări: Titluri HMAC pentru cărți web, secrete rotative.
Minimizarea PII, mascarea în jurnale; GDPR/DSAR Încărcați/Ștergeți.
RBAC/ABAC: acces chiriaș/organizație, cote stricte.
13) Observabilitate și jurnale
Лейблы: 'env', 'service', 'chiriaş', 'sursă', 'cursor', 'seq', 'event _ type'.
Corelație: "trace _ id' de la intrare se → aplica jurnalelor și urmelor.
Tablouri de bord: decalaj, restanțe, viteza cursorului, erori de tip, 429/5xx, cost (ieșire/min).
14) FinOps: costul de sincronizare
Lot (mărimea lotului 100-1000) + compresie (gzip/br).
Caching și ETag pentru pagini neschimbate.
Sarcini utile subțiri: numai câmpuri schimbate, un link către o resursă completă la cerere.
Limitele de concurență și „ferestre de noapte” pentru rambursare.
15) Testarea și calitatea
15. 1 Contracte și cazuri negative
Validați schemele JSON, câmpurile necesare, stabilitatea „error _ code”.
Teste: out-of-order, duplicate, sărind peste evenimente, conflict versiune, 429/5xx.
15. 2 Haos/jocuri
Injecții: întârzieri de rețea, scădere 10-30% din evenimente, reordonare.
Criterii: ordine/integritate menținută? Fără pierderi? decalaj în cadrul SLO?
16) Lista de verificare a implementării
- Modelul selectat (push/pull/hybrid) și sursa adevărului.
- Delte incrementale: filigran sau cursor/token.
- Paginare: cursor/keyset cu grad stabil.
- Idempotency-store, chei și TTL; dedup by '(id, versiune/seq)'.
- ETag/If-Match și politica de conflict (LWW/server-wins/fuzionare).
- Retry/backoff/jitter, respect 'Retry-After'.
- Metrics lag/restlog/duplicate/conflicte, tablouri de bord și alerte.
- Reconciliere API + reconcilieri zilnice.
- Securitate: OAuth2/JWT, semnături webhook, mTLS, politici PII.
- FinOps: lot + compresie, limite de concurență, cote de ieșire.
- Suită de testare: reorder, duplicate, întreruperi, backfill.
17) Planul de implementare (3 iterații)
1. MVP (1-2 săptămâni):
Paginare cursor, delte filigran, upsert idempotent, decalaj/restanțe de bază, încercați din nou + metrici backoff.
2. Scala (2-3 săptămâni):
Webhooks ca declanșator + sondare de opinie-rezervă, semnături HMAC, reconciliere, ETag/If-Match, tablouri de bord și arde alerte de lag.
3. Pro (3-4 săptămâni):
CDC/streaming (Kafka/Debezium) pentru domenii fierbinți, auto-backfill, scripturi DR, optimizare FinOps (lot/brotley), SLA pentru întârziere și raportare.
18) Mini-Întrebări frecvente
Ce să alegeți: filigran sau cursor?
Cursor/keyset este mai rezistent la reorder și scară; filigran este mai ușor de început, dar se adaugă suprapunere și deadup.
Este nevoie de exact-o dată?
În general, scump. Practică - cel puțin o dată + idempotență; exact o dată - numai pentru efectele monetare.
Cum de a minimiza conflictele?
Utilizați ETag/If-Match, proiectați îmbinarea prin câmpuri, evitați efectele secundare „ascunse”.
Total
Sincronizarea fiabilă este delta incrementală + paginarea corectă + controlul idempotenței și al versiunii, îmbunătățită prin observabilitate, paiete și transport economic. Alegeți modelul potrivit (push/pull/CDC), fixați SLO pe decalaj, implementați politici de conflict și teste de scenariu murdare - iar schimbul de date devine previzibil, durabil și rentabil.