MongoDB本身不提供模型兼容性抽象层，Stable API仅保障命令行为稳定性，字段增删、类型变更等模型级兼容由驱动或框架（如Laravel-MongoDB的HasSchemaVersion）实现。
直接说结论：MongoDB 本身不提供“模型兼容性”抽象层，API Versioning（Stable API）只约束服务器端命令行为的稳定性，不负责字段增删、类型变更、序列化格式等传统意义上的“模型兼容”。真正处理模型级兼容的，是驱动层或应用框架（如 Laravel-MongoDB 的 HasSchemaVersion），不是 MongoDB Server。
Stable API 不等于模型版本控制
Stable API 是 MongoDB Server 5.0+ 引入的协议级兼容机制，它只锁定一组官方支持的命令及其参数语义（比如 find、updateOne、聚合阶段的行为），确保即使升级到 7.0，version: "1" 下的 $lookup 仍按 5.0 的规则执行。但它完全不管你的文档里有没有 galaxy 字段、price 是 number 还是 string、或者旧客户端是否能解析新字段。
常见误解场景：
- 你用 PyMongo 4.0 连接 MongoDB 6.0，并启用
server_api={"version": "1"}→ 命令语法和错误码稳定，但若服务端返回了新字段，老客户端照样能收到，只是可能忽略或报错（取决于驱动反序列化逻辑） - 你在 Node.js 应用中把
user.status从 string 改成 enum，同时保留旧数据 →Stable API不会帮你做字段映射或默认值填充
Laravel-MongoDB 的 HasSchemaVersion 才管模型迁移
如果你用的是 Laravel + laravel-mongodb，那真正的模型兼容落地靠的是 HasSchemaVersion trait，它在 ORM 层拦截读写，实现字段演进：
- 文档存一个
schema_version: 1字段，记录该文档诞生时的模型版本 - 每次
retrieved事件触发时，对比文档版本与当前SCHEMA_VERSION常量，自动调用migrateSchema() - 迁移函数里可以补默认值、重命名字段、转换类型，例如：
$this->galaxy = $this->getAttribute('galaxy') ?? 'Milky Way';
注意：这个机制只在 Eloquent 模型实例化时生效；裸用 MongoDB\Collection::find() 不走这套逻辑，字段兼容得自己 handle。
驱动层兼容的关键其实是 BSON 和 wire protocol
不同版本客户端能否“互通”，底层看三件事：
-
BSON版本：MongoDB 驱动通过 BSON 库序列化/反序列化文档。BSON 1.1（2014）起已稳定，新版驱动通常向下兼容旧 BSON 格式，但反过来不一定（比如用 7.0 驱动写入的Decimal128，3.4 驱动可能无法解析） - wire protocol 版本：驱动协商使用哪个协议版本通信（如 OP_MSG）。MongoDB Server 会拒绝不支持的协议请求，错误类似
"Unsupported wire protocol version" - 功能开关：比如事务（
startTransaction）在 4.0+ Server 才可用，老驱动即使发了请求，Server 也会返回"Transaction numbers are only allowed on a replica set member or mongos"
所以，所谓“客户端版本兼容”，本质是驱动版本与 Server 版本在 BSON、wire protocol、feature support 三个维度对齐。查官方兼容矩阵比猜更可靠 —— 例如 PyMongo 4.8 明确要求 MongoDB ≥ 4.2。
跨版本模型兼容必须分层设计
没有银弹。真要支撑多版本客户端共存，得组合几层策略：
- 协议层：用
Stable API锁定命令行为，避免因 Server 升级导致查询语义突变（比如$facet在不同版本返回结构不同） - 数据层：用
featureCompatibilityVersion (FCV)控制 Server 是否启用新存储格式或索引特性，避免旧驱动写入后新驱动读失败 - 应用层：在 ORM 或 service 层做字段适配（如 Laravel 的
HasSchemaVersion、Express 中间件做 response transform） - 传输层：API 网关统一做字段裁剪或别名映射（比如把
v2_user_id映射为id给 v1 客户端）
最容易被忽略的一点：Stable API 的 strict: true 选项会让 Server 直接拒掉非白名单命令（比如 collMod），但它不会拦住你往文档里塞个 __v2_only_field —— 那个字段照样存进去，也照样发给所有客户端，除非你在代码里显式过滤。
