大规模数据迁移，接口怎样设计才少返工
大规模迁移最怕的不是某一批失败，而是失败后说不清哪些数据已写入、哪些需要重放。接口设计要先定义数据范围、幂等键、状态存储和错误处置；规模变大只会放大这些基础问题。
一个可恢复的迁移契约
范围切分可按主键或可排序的稳定键完成，但要明确边界是开区间还是闭区间、遇到删除与并发写入时的快照语义，以及重复读取是否安全。OFFSET很少适合作为并发迁移的进度标记，因为结果集会变化。
目标端写入需要有业务可解释的幂等键或版本条件。单纯把操作叫作 Upsert 并不能解决冲突：应定义相同键的覆盖规则、版本比较和重放后预期结果。只有目标端确认后，协调器才提交对应范围的状态。
错误不要只分“成功与失败”
网络超时、限流等临时错误可在有限次数内重试，重试间隔与总时限应可配置。Schema 不匹配、约束错误和无法解析的数据需要隔离，并附带范围标识、错误类别和最少必要的脱敏样本。隔离记录不是自动跳过的理由；迁移验收要统计并处理它们。
传输格式的选择同样服务于可恢复性。二进制批次、Arrow 或 Protobuf 在合适场景能减少编码开销，但要兼顾跨版本兼容、背压和内存上限，不必为了“零拷贝”牺牲诊断能力。
验收应覆盖重放
在正式迁移前，用抽样校验、范围校验和业务校验分别验证完整性。演练中主动中断 worker、重复投递批次、让目标端短暂不可用，确认状态能恢复且重复写入满足契约。迁移能否返工，取决于这套证据，不取决于一次跑完。
