通过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固定为滞后，实施冲突策略和"肮脏"情景测试-并且您的数据共享将变得可预测，可持续且经济。