数据迁移避坑清单：从旧库到新库

迁移这件事，真正难的不是把数据搬过去，而是搬完之后能证明它没变。下面按「先摸清、再演练、后切换」的顺序拆解常见坑。

一、摸清家底：字段和关系比行数更重要

迁移前第一件事是盘点，而不是导出。要盘点的是：每张表的字段类型与长度、允许为空与否、唯一约束、外键关系、枚举值的取值范围。高频坑在于旧系统里长期积累的「脏数据」——同一含义多种写法、日期格式不统一、被截断的超长文本、指向已删除记录的外键。这些问题在旧库里不报错，迁到新库加了约束就会集体失败。做法是先在旧库跑一轮探查：统计每个字段的空值率、最大长度、取值分布，把异常值单独导出成问题清单，逐条决定是清洗、映射还是丢弃。丢弃必须有记录，否则日后对账无从追溯。

二、映射与演练：把转换规则写成可复跑的脚本

字段映射不要靠手工对照，要写成配置文件或脚本，让「旧字段→新字段→转换规则」三者一一对应且可版本管理。常见坑包括：枚举值映射漏项，未知值落成空；时区与编码没统一，时间整体偏移；自增主键直接沿用导致冲突；富文本里的内嵌资源路径失效。演练阶段建议至少完整跑两遍全量迁移，比较两次结果的记录数与关键字段校验和是否一致。同时准备一份抽样核对表，随机抽取若干记录，逐字段人工比对旧新两边的值。演练中发现的问题要回写到映射规则里，而不是临时手工修补。

三、切换与回退：留好退路再动手

正式切换前必须确认三件事：旧库在切换窗口内停止写入、增量数据有补偿方案、回退路径经过验证。常见事故是切换后发现新库写入异常，而旧库已经被新数据污染，回退变成二次迁移。稳妥做法是设定只读窗口，先做一次全量加增量的追赶，确认延迟归零后再切流量；切换后保留旧库只读一段时间，作为对账依据。对账不要只看总数，要按业务维度分组比对，比如按状态、按时间区间分别核对条数，差异才容易被定位。

四、迁移后的验收要点

验收阶段关注四类信号：约束是否全部生效、关联查询是否返回预期结果、关键业务动作能否在新库完整走通、报表口径是否与旧系统一致。任何一项对不上，都先暂停清理旧数据。

功能与适用场景：适用于把内容、用户、订单等结构化数据从旧系统迁往新系统的场景，也适合作为迁移项目的过程管理模板。

使用步骤：盘点字段与脏数据，编写映射脚本，全量演练两遍并抽样比对，设只读窗口切换，按维度对账后清理旧库。

注意事项：脏数据处置必须留痕；映射规则纳入版本管理；回退方案要在切换前实际演练一次，而不是纸面确认。