通過API同步數據

1）為什麼需要同步，目標是什麼

域一致性：配置文件，錢包，目錄，限制，KYC。
減少滯後：關鍵流程（付款、獎金）幾乎是實時。
可持續性：我們經歷網絡/提供商中斷而不會丟失事件。
經濟學：通過三角洲和批處理最大限度地減少egress/CPU。

成功度量標準：源和消費者之間的lag （s）, freshness,復制比例,沖突百分比,GB/辛卡小時成本。

2）同步模型

2.1 Pull (polling)

客戶端請求更改間隔。

優點：簡單,負載控制。
缺點：脫落，「空白」民意調查，高變化率跳過的風險。
改進：If-Modified-Since，Etag/If-None-Match，change_token。

2.2 Push (webhooks/events)

消息來源向收件人大放異彩。

優點：近乎實時，民調節省。
缺點：需要使用轉發、重復數據消除、安全（簽名,mTLS）交付。
要求：等效的consumers，指數反向，重播。

2.3 CDC/流媒體（更改數據捕獲）

從事務日誌或事件日誌中捕獲更改（Kafka, Debezium）。

優點：完整性，順序，規模。
缺點：復雜性,需要控制操作類型（insert/update/delete/tombstone）。

2.4混合動力車

Webhooks作為「觸發器」，polling作為fallback和reconciliation。

3）增量三角洲

3.1 Watermark（時間戳）

客戶端存儲「last_seen_ts」並請求「updated_at> watermark」。

風險：時鐘漂移-使用UTC和NTP；在ID+版本上取一個重叠窗口（overlap） 1-2 min和dedup。

3.2 Change Token / Cursor

穩定序列令牌：'？cursor=eyJvZmZzZXQiOjEwMDB 9'。

優點：對順序變化的抵抗力，規模。
要求：可持續光標，TTL和安全重播。

3.3個編號的offset（自動增量）

`id > last_id`.簡單但破裂時，硬化和「漏洞」序列。

4）大樣本的分位

Keyset/cursor（最好）：'?after=cursor&limit=1000'-更改時穩定。
Offset/limit-簡單但昂貴且容易發生變化。
始終指定stable sort key（例如,'（updated_at, id）'）。

json
{
"items": [ { "id": "u_1", "updated_at": "2025-11-03T16:59:10Z" } ],
"next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0xMS0wM1QxNjo1OToxMFoifQ==",
"has_more": true
}

5）更改語義： upsert, merge, delete

5.1 Upsert/merge

「PUT/resource/{id}-完全替換」。
「PATCH/resource/{id}-部分更新（merge補丁驗證）」。
所有write的「Idempotency-Key」相似性。

5.2個刪除

軟刪除（字段「deleted=true」，「deleted_at」）-保存歷史；辛克放棄了墓碑。
硬刪除-在消失之前放棄事件「刪除」。

json
{ "id":"u_1", "event":"deleted", "deleted_at":"2025-11-03T17:00:00Z" }

6）版本控制和競爭

6.1 ETag/If-Match（樂觀鎖定）

讀取返回'ETag： 'v123'。
使用「If-Match」進行更新：「v123」是針對「丟失的更新」的保護。
沖突是409與'error_code：'CONFLICT_VERSION"'的沖突。

6.2記錄的復習

「version」/「updated_at」字段-計算三角洲和重復數據消除。

6.3沖突

策略：最後寫勝,服務器勝,merge-strategy跨字段（例如,加和→、標誌→源優先級）。

7）訂購和重復數據消除

7.1交貨順序

保障措施：加上實際可持續性→事實上的標準。
對於關鍵的現金流-通過一站式商店的異常效果。

7.2個冪等鍵

域組成：'source_id'event_type' sequence'。
TTL存儲24-72小時（或在SLA下更長）。

7.3重復數據消除

將最後應用的version/seq保留在接收器上；丟棄舊的。

8）重播,taymouts, backoff

Retriable： 5 x/429/408/taymauts；Non-retriable: 400/401/403/404/409/422/410/412.

指數backoff+jitter： 1s, 2s, 4s……高達30-60秒。
Retry-After尊重429/503。
客戶端taymauts：連接3-5 c，通用請求10-30 c；總嘗試限制3-6。

9）滯後控制和SLA

9.1 SLI/SLO

SLI Lag： 「occurred_at」和「應用於消費者」之間的中位數/p95 lag。

SLO： 例如"p95 lag ≤ 60 s（28d）"，"丟失事件的比例=0"，"重復的比例≤ 0。01%».

錯誤預算：用於發行版/實驗。

9.2個指標

`sync_lag_seconds`, `events_received_total`, `events_applied_total`, `duplicates_total`, `conflicts_total`, `retries_total`, `backlog_size`, `cursor_advance_rate`.

10）恢復（和解）和backfill

白天/小時對賬：窗口總數/哈希。
API： 'GET/reconciliation?from=.&to=.'返回校驗和和差異。
Backfill：安全地將歷史數據與光標捆綁在一起，而沒有DDOS源；遵守限制。

11）圖和示例

11.1 Webhook活動（簽名）

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..N`

11.2增量采樣（polling）

`GET /v1/users?updated_after=2025-11-03T17:58:00Z&cursor=...&limit=1000`

11.3 Idempotent upsert

POST /v1/users
Idempotency-Key: upsert-u_1-20251103T1800Z
{ "id":"u_1","email":"a@b. com","version":124 }
→ 201/200 (stable)

12）安全和合規性

Auth: OAuth2 scopes/JWT;sink通道-mTLS按需。
標題：HMAC的webhooks標題，秘密輪換。
PII最小化，在日誌中掩蓋；GDPR/DSAR：卸載/卸載。
RBAC/ABAC：通過tenant/組織訪問，嚴格的配額。

13）可觀察性和記錄

Лейблы: `env`, `service`, `tenant`, `source`, `cursor`, `seq`, `event_type`.

相關性：「trace_id」來自登錄→應用到日誌和跟蹤中。
Dashbords：lag，backlog，光標速度，類型錯誤，429/5xx，成本（egress/min）。

14） FinOps： 同步成本

批處理（batch size 100-1000）+壓縮（gzip/br）。
未更改頁面的緩存和ETag。
精細的付費：僅更改字段,按需鏈接到完整資源。
並發限制和backfill的「夜間窗口」。

15）測試和質量

15.1合同和負面案例

驗證JSON方案、必填字段、「error_code」穩定性。
測試：出局，復制，跳過事件，版本沖突，429/5xx。

15.2混亂/遊戲

註射：網絡延遲,drop 10-30%的事件,reorder。

標準： 保持順序/完整性？沒有損失？SLO內的差?

16）實施支票

• 選擇了模型（push/pull/hybrid）和真相來源。
• 增量三角洲：watermark或cursor/token。
• 分割：具有穩定品種的cursor/keyset。
• Idempotency商店，鑰匙和TTL；「（id, version/seq）」。
• ETag/If-Match和沖突政策（LWW/server-wins/merge）。
• Retry/backoff/jitter，尊重「Retry-After」。
• lag/backlog/duplicates/conflicts，dashbords和alertes度量。
• Reconciliation API+每日對賬。
• 安全：OAuth2/JWT，webhook簽名，mTLS，PII策略。
• FinOps： batch+compression,並發限制,egress配額。
• 測試套件：reorder, duplicates, outages, backfill.

17）實施計劃（3次叠代）

1.MVP（1-2周）：

Cursor分割，watermark三角洲，等效的upsert，基本的lag/backlog度量，retry+backoff。

2.量表（2-3周）：

Webhooks作為觸發器+polling-fallback，HMAC簽名，reconciliation，ETag/If-Match，dashbords和burn-alerta。

3.Pro （3-4周）：

CDC/流媒體（Kafka/Debezium），用於熱域，自動回流，DR腳本，FinOps優化（batch/brotley），SLA和報告。

18）迷你常見問題

選擇什麼： watermark或cursor?

Cursor/keyset對越野者和規模具有抵抗力；watermark更容易啟動，但添加超重和後坐力。

是否需要exactly-once？
一般來說，價格昂貴。實踐是at-least-once+等效性；exactly-once-僅用於貨幣效應。

如何盡量減少沖突？
使用ETag/If-Match,在田間設計混合物,避免「隱藏」副作用。

底線

可靠的同步是增量增量Delta+正確的分區+等效性和版本控制，可觀察性，對等性和經濟運輸性得到了增強。選擇合適的模型（push/pull/CDC），將SLO固定為滯後，實施沖突策略和「骯臟」情景測試-並且您的數據共享將變得可預測，可持續且經濟。