异构数据同步平台：系统级交付完整复盘

生态店铺 GMV 清洗迁移证明方法论能处理一条复杂业务链路，这个项目证明它能处理系统级交付。放大的规律总结在实证章，本页是完整过程。

一、项目概况

一个类 CloudCanal 的异构数据同步平台：支持 MySQL、SQL Server、PostgreSQL、Doris 之间的数据同步，覆盖实时（CDC）与批量两种模式，下游对接 Doris 数仓的 ODS/DWD/DWS/ADS 分层。

核心能力：CDC 实时同步、批量同步、字段映射与类型转换、数据清洗、断点续传、失败重试、脏数据记录与重放、监控告警；演进方向为 NL2SQL、指标预测、运维诊断 Agent。

我的角色：架构师和编排者——定义同步语义、拆解系统分层、组织上下文、分配 Agent 工作单、验证语义不变量。业务代码由 AI 在边界内生成，我不手写业务代码；这既是效率选择，也是对本站方法论的实证。

二、需求体检：把"做个同步平台"变成语义清单

原始需求只有一句"做一个数据同步平台，支持多种数据库之间同步"。按八维体检扫描后，掉出的核心问题：实时还是批量？断点怎么续？失败怎么恢复？重复消费怎么幂等？源端 DDL 变化怎么办？脏数据怎么处理？多数据源差异怎么抽象？监控指标是什么？

澄清结果：

维度	规格
同步模式	CDC + 批量都支持，可组合（全量初始化 + 增量接续）
一致性	任务级最终一致，交付语义为至少一次（at-least-once），由目标端幂等消化重复
幂等	目标端写入支持重复消费不重复落库
断点续传	CDC 位点与批量游标持久化，重启从断点继续
失败处理	分级：临时失败重试、脏数据跳过入表、任务级失败告警人工介入
数据源差异	SourceConnector / SinkConnector 双向抽象
观测	任务状态、吞吐、延迟、失败数、最后位点
验收	正常、断点恢复、重复消费、失败重试、脏数据、大表批量

注意"至少一次 + 目标端幂等"这一条：交付语义是整个系统最重要的一个结构决策——精确一次（exactly-once）在异构多端场景的实现成本极高，而"至少一次 + 幂等消化"能以低得多的复杂度达到等价的业务效果。这是典型的"AI 无法替你做的取舍"：它是成本判断，不是技术推断。

三、系统级规格：五条语义不变量

按规格层级化的原则，系统级只锁跨模块恒成立的性质：

- 可恢复：任何任务中断后，SHALL 从持久化位点继续，不重跑全量
- 幂等：同一变更事件重复消费，目标端 SHALL 不产生重复数据
- 隔离：单任务失败 SHALL 不影响其他任务；脏数据 SHALL 不阻断任务
- 可观测：吞吐、延迟、失败数、位点 SHALL 随时可查
- 不静默：任何失败 SHALL 留下可追踪、可补偿的记录

每个模块的规格、每张工作单的验收标准，都从这五条推导；后面的故障注入验证也逐条对着它们打。

四、架构分层与三个关键结构决策

数据源接入层 → 任务编排层 → 转换清洗层 → 目标端写入层
                    ↓
        元数据与状态管理层 ← 监控告警层

分层本身常规，值得复盘的是三个结构决策——每个都是按不可逆性排序后由人拍板、记入 ADR 的：

① Connector 双向抽象：隔离"数据源差异"这个易变决策。 MySQL 走 binlog、SQL Server 走 CDC 表、PostgreSQL 走逻辑复制，三者的增量语义、类型系统、分页方式全不一样；Doris 作为目标端的写入模型又与关系库完全不同。按 Parnas 信息隐藏原则（见架构边界），"每种数据源怎么读怎么写"就是那个该被藏起来的易变决策——SourceConnector 统一产出标准化变更事件，SinkConnector 统一消费，中间所有层只认标准事件。后来每接入一种新数据源，改动都被约束在一个 Connector 实现里，这是抽象兑现价值的时刻。

② 位点先行、写入其后：用提交顺序换崩溃安全。 断点续传的核心陷阱是位点提交与数据写入的顺序：先提交位点再写入，崩溃时丢数据；先写入再提交位点，崩溃时重复消费。选择后者——宁可重复，不可丢失——重复由不变量第二条（目标端幂等）消化。这个决策把"可恢复"和"幂等"两条不变量咬合成一个自洽的整体：幂等不是锦上添花，而是崩溃安全的前提。

③ 脏数据旁路：错误记录表 + 人工重放。 坏数据（类型溢出、约束冲突、编码问题）不阻断任务，进入错误记录表，携带原始数据与失败原因，支持人工修正后重放。对应不变量第三、五条：隔离 + 不静默。日志不是恢复机制——只有落进状态表的失败才是可补偿的失败。

五、上下文组织

五条不变量与三个 ADR 进入常驻规则与决策记忆层（四层架构）：

【常驻规则】
- Connector 之间只通过标准事件接口交互，禁止跨层直连数据源
- 同步状态必须可恢复；位点提交顺序：先写入，后提位点
- 目标端写入必须幂等；失败必须落表，禁止只打日志
- 大表禁止一次性加载，一律游标分页

【决策记忆（ADR 摘要）】
- 交付语义：至少一次 + 目标端幂等（否掉 exactly-once：多端异构下成本不可控）
- 位点持久化于任务状态表，重启后从位点继续
- 脏数据入错误记录表，允许人工修正后重放

这些规则常驻后，后续每个 Agent 的每张工作单都自动继承同一套事实——系统级交付里，这是防止"N 个任务做出 N 组假设"的关键。

六、Agent 执行：七类工作单

人担任编排者（orchestrator-workers 模式），按分层切工作单，层间靠已冻结的事件接口与任务模型并行：

工作单	交付物	依赖
Connector 抽象	Source/Sink 接口与标准事件模型	无（最先冻结）
任务模型	Job / Task / Checkpoint / ErrorRecord	无（最先冻结）
批量同步	游标分页读取、批量写入	前两者定稿
CDC 同步	位点消费、事件转换、断点续传	前两者定稿
清洗规则	字段映射、类型转换、过滤	事件模型定稿
监控告警	吞吐、延迟、失败数、任务状态指标	任务模型定稿
测试回归	不变量场景全覆盖	各实现单交付后

每张工作单遵循标准八字段：独立上下文、显式禁区（如"CDC 单禁止触碰批量代码"）、验收对应不变量、统一格式汇报。实现、测试、review 分角色，review 用干净上下文只看规格与 diff。

七、验证：对着不变量做故障注入

系统级验证的重心不是用例通过，而是不变量注入——主动制造故障，验证五条不变量扛不扛得住：

注入手段	验证的不变量
同步中途 kill 任务进程，重启	可恢复：从位点继续，不重跑、不丢失
重放同一批变更事件	幂等：目标端无重复数据
混入类型溢出/约束冲突的坏数据	隔离 + 不静默：入错误表，任务不断，可重放
目标端临时不可用后恢复	失败分级：重试成功，无数据丢失
灌大表全量同步	游标分页：内存平稳，不 OOM
拔掉监控看板做一次故障演练	可观测：仅凭指标能定位到任务和位点

这套注入清单直接从不变量推导——规格写成不变量的收益在这里兑现：验证方案不需要重新设计，照着规格打就行。

八、踩坑记录

真实踩过、且都指向工程语义而非语法的坑：

• 任务拆得太大：早期一张工作单覆盖整条同步链路，AI 生成大量互相耦合的代码，返工重拆——INVEST 的“小”在系统尺度上不是建议是纪律；
• 只关注同步成功，忽略断点恢复：demo 跑通极易，位点语义想清楚很难；这个坑直接催生了“位点先行”的 ADR；
• 重复消费没幂等：CDC 重复投递是常态不是异常，幂等必须是目标端的默认属性；
• 数据源差异渗漏进业务：类型映射一度散落在清洗逻辑里，靠边界 review 拉回 Connector——渗漏初期毫无痛感，是最危险的一类腐烂；
• 失败只打日志：日志无法驱动补偿，返工把失败全部落表；
• 监控后补：指标口径各模块不一致，返工统一——这也是“可观测”最终升格为系统级不变量的原因。

九、如果重来，会改三件事

复盘不该只有成绩单：

1. DDL 变更策略应该进第一版规格——源端加字段、改类型的处理被推迟到演进项，实际它是生产环境最早遇到的问题之一；
2. 监控指标应该在任务模型定稿时同步定稿，而不是作为独立工作单后置——可观测性是横切关注点，后置必然口径分裂；
3. Connector 接口应该配契约测试（consumer-driven contract）：每个新 Connector 实现自动跑一套标准语义测试，而不是依赖 review 把关——把边界从"人盯"升级为"机器强制"可以更早发生。

十、这个项目证明了什么

• AI 可以承担系统级交付中绝大部分实现工作——前提是每个任务都被钉在边界内、验收都可执行；
• 系统能不能交付，取决于人定义的东西：交付语义的取舍、五条不变量、三个结构决策、七类工作单的边界；
• 需求体检、规格、上下文、编排、验证这套闭环，能从接口级原样放大到系统级——放大的规律见实证章。

它不是“AI 写了一个项目”，而是我组织 AI 交付了一个系统。

---

相关阅读

• 实证：方法论如何从接口放大到系统——本案例的方法论提炼
• 生态店铺 GMV 清洗迁移案例——同一套方法的接口级演练
• 面试表达——这个项目在面试中的讲法