工具链同步任务在网络抖动、接口限流或服务重启时失败很常见，重跑时既要避免重复写入，又要防止漏掉数据。本文按“划分同步单元—幂等写入—断点续传—重试配合—角色分工—示例—上线检查”的顺序，给出可落地的设计步骤、字段表与检查清单，适用于 GitLab、SVN 等源系统的数据同步场景。
要点总览（TL;DR）
- 先把同步任务拆成可重放的单元：增量窗口定位拉取范围、批次划定事务边界、单条记录按稳定业务键判重，游标只负责定位，业务键负责去重。
- 幂等写入分两条路径：插入靠业务键唯一约束或去重表，更新靠版本号或更新时间比较，旧数据晚到也不会覆盖新数据，重复执行返回明确状态并记入日志。
- 断点续传的关键是断点信息与业务数据同事务提交，批次状态按待处理、处理中、已确认、失败流转，恢复时只从最后一个已确认批次的游标继续。
- 重试只重放未确认批次：网络超时、限流等可重试错误用指数退避并设上限，参数错误、权限不足不重试，超限后告警转人工。
- 上线前用重复执行、中断恢复、乱序写入、告警可观测四类用例逐项验证，每项留证据并指定负责人。
先定同步单元：幂等和断点续传的共同基础
幂等和断点续传解决的是两个不同问题：幂等保证同一条数据重复写入不出错，断点续传保证失败后从正确位置继续。两者要共用一套标识体系，否则写入端判重和任务端定位进度会对不上。第一步是把同步任务拆成可重放的单元，并为每个单元确定稳定业务键。
同步单元通常有三个粒度，选择取决于数据量和失败影响范围：
- 单条记录：一条议题、一次提交、一个文件版本。粒度最细，重放代价小，适合记录级写入。
- 批次：一次拉取的若干条记录组成一个批次，批次内整体提交或整体回滚。适合需要事务一致性的场景。
- 增量窗口：按时间区间（如每小时、每天）切分拉取范围。适合源系统只提供时间过滤接口的情况。
实际设计中常见组合是“增量窗口内分批、批次内逐条判重”：窗口负责定位拉取范围，批次负责事务边界，单条记录负责幂等判重。
业务键的选取要满足两个条件：源系统内唯一、在记录生命周期内不变。常见来源包括源系统的全局唯一 ID、提交哈希、文件路径加版本号。更新时间戳可以作为辅助字段，不适合单独作为业务键，因为同一秒内的多条记录可能冲突，且时间戳可能被源系统修正。
业务键与游标职责分离：游标回答“从哪里继续拉”，业务键回答“这条数据是否已写过”。游标可以变化（如时间戳推进），业务键必须稳定。把两者混用，例如用游标值当去重键，会在边界重叠时产生误判。
GitLab 议题可提供议题 IID（项目内编号）、全局 ID、创建时间、更新时间；提交可提供 commit SHA；SVN 可提供修订号（revision）、文件路径和提交时间。选取时优先用不可变的标识，时间字段只用于增量过滤。
| 字段 | 来源 | 是否唯一 | 是否可变 | 用途 |
|---|---|---|---|---|
| issue_id（全局ID） | GitLab 议题接口 | 是 | 否 | 业务键 |
| issue_iid | GitLab 议题接口 | 项目内唯一 | 否 | 业务键（限定项目范围） |
| commit_sha | GitLab 提交接口 | 是 | 否 | 业务键 |
| revision | SVN 日志 | 仓库内递增 | 否 | 业务键或游标 |
| updated_at | 各源系统 | 否 | 可能被修正 | 增量过滤、版本比较 |
| last_sync_cursor | 任务侧维护 | — | 是 | 游标，仅用于定位 |
幂等写入的实现步骤
幂等写入的目标是：同一业务键的数据无论写入多少次，最终结果一致，且不产生重复记录。实现分两条路径——插入和更新，各自有对应的判重方式。
插入路径依赖唯一约束。在目标表上对业务键建立唯一索引，写入时使用“存在则跳过、不存在则插入”的语义。数据库层面可用唯一约束加冲突忽略，或在应用层先查询再插入。前者更可靠，因为并发写入时查询与插入之间存在竞态窗口。如果目标系统不支持唯一约束，则建立独立的去重表，字段包括业务键、来源系统、首次写入时间、最后写入时间、写入状态。
更新路径依赖版本比较。源记录携带版本号或更新时间，写入前比较目标记录的版本：源版本更新则覆盖，否则跳过。这样即使旧批次延迟到达，也不会覆盖新数据。版本号优先于时间戳，因为时间戳可能因时钟偏差或源系统修正而不可靠。
重复执行时的返回结果要明确区分三种状态：新写入、已存在跳过、版本较旧跳过。三种状态都记入同步日志，日志字段包括业务键、批次号、执行时间、结果状态、耗时。这样排查“为什么这条没同步”时有据可查。
一次完整的幂等写入可以按以下输入、动作、输出描述：
- 输入：同步记录（含业务键、版本字段、数据内容）、来源系统标识。
- 动作：按业务键查询目标记录；不存在则插入；存在则比较版本，决定覆盖或跳过。
- 输出：写入结果状态（新增/更新/跳过）、目标记录 ID、日志条目。
- 完成标志：该批次内所有记录都返回了明确状态，且无未处理异常。
| 去重表字段 | 类型说明 | 作用 |
|---|---|---|
| biz_key | 字符串，唯一索引 | 业务键，判重依据 |
| source_system | 字符串 | 区分来源，避免多源冲突 |
| version | 整数或时间戳 | 版本比较 |
| first_written_at | 时间 | 首次写入时间 |
| last_written_at | 时间 | 最近写入时间 |
| write_status | 枚举 | 新增/更新/跳过 |
断点续传：游标、批次状态与恢复流程
断点续传要解决的是“失败后从哪里继续”，核心是让进度记录和业务数据保持一致。如果进度先提交、数据后写入，失败时会出现漏同步；如果数据先写入、进度后提交，失败时会重复拉取同一段数据——后者可以靠幂等兜住，前者不能。因此断点信息应与业务数据在同一事务中提交。
游标类型按源系统能力选择：
- 时间戳游标：适合提供 updated_at 过滤的接口，如 GitLab 议题列表。注意边界重叠，拉取时用“大于等于上次游标”而非“大于”，靠业务键去重消化重叠部分。
- 自增 ID 游标：适合单调递增的记录 ID，定位精确，但要求源系统 ID 不回退。
- 提交哈希或修订号游标：适合代码类数据，如 GitLab 提交 SHA、SVN revision，天然有序且不可变。
批次状态机建议四个状态：待处理、处理中、已确认、失败。状态迁移规则是：批次创建后为待处理；开始拉取置为处理中；数据写入并断点提交成功后置为已确认；异常时置为失败并记录错误信息。只有已确认批次的游标才能作为下次恢复的起点。
恢复流程按以下步骤执行：
- 读取最后一个已确认批次的游标作为起点。
- 检查是否存在处理中或失败的批次，若有，先确认其数据是否已部分写入。
- 从起点重新拉取，允许与上次范围有重叠，重叠部分由业务键判重消化。
- 新批次写入数据的同时更新游标，两者在同一事务提交。
- 批次置为已确认，记录完成时间与记录条数。
完成标志是：新批次状态为已确认，游标已推进，且该批次记录数与源端统计一致。
| 批次状态表字段 | 说明 |
|---|---|
| batch_id | 批次唯一标识 |
| source_system | 来源系统 |
| cursor_start / cursor_end | 本批次拉取范围 |
| status | 待处理/处理中/已确认/失败 |
| record_count | 本批次记录数 |
| error_message | 失败原因 |
| started_at / confirmed_at | 开始与确认时间 |
失败重试策略与重复执行安全
重试的前提是分清哪些错误值得重试。网络超时、连接中断、接口限流、源系统临时不可用属于可重试错误，等待后重放有较大概率成功。参数错误、权限不足、业务键缺失、数据格式不合法属于不可重试错误，重试只会重复失败，应直接标记失败并告警。
退避方式建议指数退避，例如首次间隔 30 秒，之后每次翻倍，设上限如 10 分钟。重试上限按任务重要性设定，常见 3 到 5 次。超过上限后不再自动重试，转为告警并等待人工介入。
重试与断点续传的配合原则是：只重放未确认批次。已确认批次的数据已经落库且游标已推进，重放只会产生无意义的判重开销。失败批次重试时，从该批次的起始游标重新拉取，而不是从任务最开始重跑。
需要人工介入的条件包括：同一批次连续失败超过上限、失败原因为不可重试错误、断点状态与实际数据不一致、去重表出现业务键冲突但版本无法比较。这些情况应触发告警，告警内容包含批次号、错误类型、最后游标和影响范围。
| 错误类型 | 重试次数 | 间隔策略 | 处理人 |
|---|---|---|---|
| 网络超时、连接中断 | 5 | 指数退避，30秒起，上限10分钟 | 自动重试，超限告警集成开发 |
| 接口限流 | 5 | 指数退避，尊重源系统 Retry-After | 自动重试，超限告警集成开发 |
| 源系统临时不可用 | 3 | 固定5分钟 | 自动重试，超限告警运维 |
| 参数错误、数据格式错误 | 0 | 不重试 | 告警集成开发 |
| 权限不足 | 0 | 不重试 | 告警运维与集成开发 |
角色分工与交付物
方案落地需要集成开发、测试、运维三方各司其职，交付物要能互相衔接：开发交付的字段定义是测试用例的输入，测试验证过的状态机是运维监控的依据。
| 角色 | 职责 | 交付物 |
|---|---|---|
| 集成开发 | 划分同步单元，定义业务键与游标，实现幂等写入与批次状态机 | 同步单元与业务键定义表、去重表设计、批次状态表、重试参数配置 |
| 测试 | 设计重复执行、中断恢复、乱序写入的验证用例并执行 | 测试用例集、验证记录、缺陷清单 |
| 运维 | 监控批次状态、重试次数与告警，处理超限失败 | 监控看板配置、告警规则、故障处理记录 |
在同步任务本身的管理上，可以把批次状态、失败原因和重试记录作为工作项跟踪。ONES 提供 API 接口用于与企业系统集成，并支持对接 GitLab 等第三方应用，团队可以把同步任务的异常处理纳入统一的工作项流程，让告警、责任人和处理状态在同一处可见。具体的接口能力与同步机制以实际集成方案和官方文档为准。
示例：GitLab 议题同步的幂等与续传设计
假设需要把 GitLab 项目议题同步到内部系统，按前述规则组合落地如下。
业务键与游标选择：业务键用议题全局 ID，保证跨项目唯一且不变；游标用议题的 updated_at 时间戳，因为议题列表接口支持按更新时间过滤。版本比较用 updated_at，源端更新时间晚于目标记录则覆盖。
批次处理：每次同步按时间窗口拉取，例如从上次游标到当前时间，窗口内按分页拉取，每页作为一个批次。批次开始时写入批次记录，状态置为处理中；逐条按全局 ID 判重写入；本页数据与游标在同一事务提交；成功后批次置为已确认。
重复执行：同一批次重跑时，已写入的议题因全局 ID 已存在而被跳过，返回“已存在跳过”状态；源端有更新的议题因 updated_at 较新而被覆盖，返回“更新”状态。两种情况都不产生重复记录。
中断恢复：同步进行到第 3 页时服务重启，第 3 页批次停留在处理中。恢复时读取最后一个已确认批次（第 2 页）的游标作为起点，重新拉取第 3 页范围。第 3 页中已写入的部分被判重跳过，未写入的部分正常插入，完成后游标推进到第 3 页末尾。
结果核对：同步结束后比对源端议题总数与目标端记录数，核对本批次记录数与源端分页统计，检查日志中新增、更新、跳过的数量之和是否等于拉取条数。差异超过阈值时告警。
完成检查：上线前要验证的项
上线前用以下清单逐项验证，每项都要有可核对的证据和负责人，未通过的项目作为上线阻断项处理。
| 检查项 | 验证方法 | 证据 | 负责人 |
|---|---|---|---|
| 重复执行同一批次不产生重复记录 | 对同一批次连续执行两次，比对目标表记录数 | 两次执行前后记录数一致，日志显示跳过状态 | 测试 |
| 中断后从断点恢复且无漏同步 | 执行中强制中断，恢复后比对源端与目标端全量数据 | 数据比对报告无缺失记录 | 测试 |
| 旧数据不覆盖新数据 | 构造旧版本记录晚于新版本到达的场景 | 目标记录保持新版本，日志显示版本较旧跳过 | 测试 |
| 重试次数与告警可观测 | 模拟可重试错误与不可重试错误 | 监控看板显示重试次数，超限触发告警 | 运维 |
| 断点与业务数据一致 | 在事务提交前后分别制造失败 | 无“游标已推进但数据未写入”的情况 | 集成开发 |
| 业务键唯一约束生效 | 并发写入同一业务键 | 仅一条记录落库，其余返回冲突或跳过 | 集成开发 |
清单全部通过后，方案具备上线条件。上线后仍需持续观察批次失败率和重试分布，出现异常集中时回查业务键选取与游标边界是否合理。
常见问题
源系统只提供更新时间过滤接口，时间戳游标怎么避免漏数据和重复拉取？
时间戳游标的边界处理是重点。拉取时用“大于等于上次游标”而不是“大于”，把边界那一秒或那一毫秒的记录重新纳入范围，重叠部分交给业务键判重消化。这样即使有记录在边界时刻写入、或源系统时间戳精度不足，也不会漏掉。
如果源系统时间戳可能被修正（例如议题被重新编辑导致 updated_at 回退），单靠时间戳会漏数据。此时可以叠加一个兜底机制：定期按业务键做一次全量或较大窗口的核对，发现目标端缺失的记录补写。核对频率按数据量和业务容忍度设定，不必每次同步都做。
断点信息和业务数据不在同一事务里提交，会出现什么问题？
两种提交顺序对应两类故障。先提交断点、后写数据：中途失败时游标已推进，但数据没落库，恢复后从新游标继续，这段数据就漏了，而且幂等机制救不回来，因为它只防重复不防缺失。先写数据、后提交断点：失败时游标没推进，恢复后会重新拉取同一段，产生重复写入，这种情况可以靠业务键判重兜住。
所以设计上宁可接受重复拉取，也要保证断点不超前于数据。如果目标库和断点表在同一个数据库，用本地事务包住两者最直接；如果跨库，可以先把批次状态置为处理中并记录起始游标，数据写入完成后再单独确认，恢复时以“已确认”状态为准，未确认批次一律重放。
同步过程中源端数据被修改，重放旧批次会不会把新数据覆盖掉？
这正是更新路径要做版本比较的原因。写入前比较源记录与目标记录的版本号或更新时间，源版本不新于目标版本就跳过，并记录“版本较旧跳过”状态。这样旧批次延迟到达时不会覆盖新数据。
版本号优先于时间戳。时间戳受时钟偏差、源系统批量修正影响，可能出现新数据时间戳反而更早的情况；版本号由源系统单调递增维护时更可靠。如果源系统两者都不提供，可以退而用内容哈希比较：内容一致则跳过，不一致则按“后写入为准”并记录变更，同时把这类记录纳入人工抽查范围。
重试次数用完了还是失败，运维应该怎么接手？
超限告警应包含批次号、错误类型、最后游标、影响记录数和已重试次数，运维拿到告警后先判断错误性质。可重试错误超限，通常是源系统持续不可用或限流窗口较长，确认源端恢复后手动触发该批次重放即可，重放从批次起始游标开始，已写入部分会被判重跳过。
不可重试错误（参数错误、权限不足、数据格式不合法）重试没有意义，应转给集成开发修正配置或数据后重跑。如果断点状态与实际数据不一致，例如批次显示已确认但目标端查不到对应记录，先冻结该同步任务，核对最后一个已确认批次的数据完整性，再决定从哪个游标重建，不要直接在原状态上继续推进。
用 ONES 承载同步任务的异常跟踪，能覆盖到什么程度？
ONES 提供 API 接口用于与企业系统集成，并支持对接 GitLab 等第三方应用，团队可以把同步批次、失败原因、重试记录作为工作项纳入统一流程，让告警、责任人和处理状态在同一处可见。这解决的是异常处理过程的可见与流转问题。
同步任务内部的重试、幂等判重与断点续传机制，仍需要在集成侧按本文的设计实现。ONES 侧具体接口的调用限制、增量拉取方式与同步机制，以实际集成方案和官方文档为准，上线前建议用真实数据做一次中断恢复验证。
