NoSQL 与搜索 / 系统课时
实施 Schema 版本化与在线迁移
实施 Schema 版本化与在线迁移
在线 Schema 迁移的目标不是“尽快把旧文档改完”,而是让新旧格式在一段时间内同时可用。本课用 schemaVersion、兼容读写、后台回填和最终收口组成迁移链路,避免一次性停机重写整个集合。
学习目标
- 能用
schemaVersion明确区分文档结构版本 - 能设计兼容读写与后台回填的迁移顺序
- 能验证旧版数据清零后再安全移除兼容代码
先定义版本边界
假设旧版用户文档把城市直接存为 city,新版要改成 address.city。不要仅靠“字段是否存在”猜版本,而应给新写入的数据显式记录 schemaVersion: 2。这样读取、回填和审计都能基于稳定条件判断。
迁移期间通常采用“先兼容、再回填、最后收口”的顺序:先发布能读 v1/v2 的代码,再让新写入进入 v2,随后后台批量回填 v1,确认没有旧文档后才删除旧字段与兼容分支。

让应用先兼容新旧格式
下面是 TypeScript 片段示例,假设数据库访问层已经得到一个用户文档。读取函数同时接受 v1 和 v2;写入函数在兼容窗口内写入 v2 字段,并保留旧 city 字段,方便旧版本应用尚未完全下线时继续工作。
type UserDoc = {
_id: string;
schemaVersion?: 1 | 2;
city?: string;
address?: { city: string };
};
function readCity(user: UserDoc): string | undefined {
if (user.schemaVersion === 2) {
return user.address?.city;
}
return user.city;
}
function buildCityUpdate(city: string) {
return {
$set: {
schemaVersion: 2,
"address.city": city,
city
}
};
}这是片段示例,依赖你的 MongoDB Repository 或 Driver 调用上下文。其生效行为是:新版本读取两种结构,新版本写入时以 v2 为主,同时暂时维持旧字段;旧应用全部下线后才能停止这段双写。
分批回填旧文档
后台回填要做到可重复执行。下面的 mongosh 示例只处理仍为 v1 或没有版本号、且存在 city 的文档;更新使用管道把旧值复制到新结构,再标记为 v2。
db.users.updateMany(
{
$or: [
{ schemaVersion: 1 },
{ schemaVersion: { $exists: false } }
],
city: { $exists: true }
},
[
{
$set: {
schemaVersion: 2,
address: {
$mergeObjects: [
{ $ifNull: ["$address", {}] },
{ city: "$city" }
]
}
}
}
]
)
db.users.countDocuments({
$or: [
{ schemaVersion: 1 },
{ schemaVersion: { $exists: false } }
]
})预期输出
0updateMany() 本身还会返回匹配数与修改数,具体数值取决于当前数据量;这里真正的验收条件是第二条查询返回 0。生产环境应按 _id 范围或时间窗口分批执行,而不是一次更新数百万文档。
用监控决定何时收口
不要在“回填脚本跑完”这一刻立即删除兼容逻辑。至少要同时检查 v1 剩余数量、读取旧分支命中次数、写入错误率以及回填失败记录。只有 v1 数量持续为 0,旧应用已经下线,并经过约定的观察窗口,才进入收口。
收口时先停止双写旧 city,保持读取兼容一小段时间;确认没有旧字段依赖后,再删除旧读取分支,并通过第二次后台清理移除冗余 city 字段。这种两阶段删除比“一次发布同时删读、删写、删数据”更容易回滚,也更容易定位问题。