Beanie 1.27.0 版本中的 PydanticObjectId 序列化问题解析

在 Beanie 1.27.0 版本升级后，开发团队遇到了关于 PydanticObjectId 和 Link 对象的序列化问题。这个问题主要影响了两种常见场景：文档字段类型声明和 FastAPI 测试客户端的使用。

在 1.26.0 版本中，PydanticObjectId 能够自动转换为字符串进行序列化，但在 1.27.0 版本中，这一行为发生了变化。具体表现为：

1. 当声明文档字段类型为 str 但实际传入 PydanticObjectId 时，会抛出 pydantic_core._pydantic_core.ValidationError
2. 使用 FastAPI 的 TestClient 进行 JSON 序列化时，会抛出 TypeError: Object of type PydanticObjectId is not JSON serializable

这个变化源于 1.27.0 版本中引入了 when_used="json" 属性，它改变了 PydanticObjectId 在核心模式生成中的行为。从技术角度来看，这个修改是有其合理性的：

• PydanticObjectId 本质上是 MongoDB 的原生类型
• 在非 JSON 序列化场景下，应该保持其原生类型特性
• 将字符串强制转换为 ObjectId 可能掩盖潜在的类型问题

对于开发者而言，正确的做法应该是：

1. 明确字段类型声明。如果字段确实存储 ObjectId，应该直接声明为 PydanticObjectId 类型
2. 对于需要存储混合类型（有时是 ObjectId，有时是字符串）的特殊场景，可以考虑实现自定义验证器
3. 数据库中存在类型不一致的情况时，建议进行数据迁移，统一存储格式

这个变更虽然带来了短期的适配成本，但从长期来看有助于建立更严格的类型系统，避免潜在的类型混淆问题。对于需要向后兼容的场景，开发者可以考虑实现自定义的序列化逻辑，或者暂时回退到 1.26.0 版本。

从 MongoDB 性能优化的角度来看，直接存储原生 ObjectId 类型通常比存储其字符串表示更高效，这也是新版本行为的另一个优势。开发者应该根据具体业务场景，在类型严格性和开发便利性之间做出适当权衡。