Beanie ODM 中 PydanticObjectId 字段的 JSON Schema 生成问题解析

在 MongoDB 数据库操作中，Beanie ODM 是一个优秀的异步对象文档映射器，它基于 Pydantic 和 Motor 构建。然而，开发者在实际使用过程中可能会遇到一个常见问题：当在 FastAPI 的路由中使用 PydanticObjectId 作为响应模型时，会出现 JSON Schema 生成失败的情况。

问题现象

当开发者尝试在 FastAPI 的 APIRouter 中使用 PydanticObjectId 作为 response_model 时，系统会抛出 pydantic.errors.PydanticInvalidForJsonSchema 异常。错误信息明确指出无法为 core_schema.PlainValidatorFunctionSchema 生成 JSON Schema。

典型错误场景如下：

@sample_router.post("$", response_model=PydanticObjectId)
async def create_sample():
    sample = await self.sample_service.create()
    return sample.id

问题根源

这个问题的本质在于 Pydantic 2.x 版本对 JSON Schema 生成机制的改变。Beanie 中的 PydanticObjectId 类型继承自 Pydantic 的自定义类型系统，但在转换为 JSON Schema 时，Pydantic 2.x 无法正确处理某些验证函数的结构。

具体来说：

1. PydanticObjectId 内部使用了 PlainValidatorFunctionSchema 进行验证
2. Pydantic 2.x 的 JSON Schema 生成器无法自动处理这种验证器结构
3. FastAPI 依赖 OpenAPI/Swagger 规范，需要所有响应类型都能生成有效的 JSON Schema

解决方案

临时解决方案

对于急需解决问题的开发者，可以采用以下临时方案：

1. 字符串替代方案：

@router.post("/items/{item_id}")
async def my_endpoint(item_id: str):
    # 在函数内部手动转换为 ObjectId
    from bson import ObjectId
    obj_id = ObjectId(item_id)

2. 模型定义调整：

class MyModel(BaseModel):
    id: Optional[str] = Field(default=None, alias="_id")

长期解决方案

Beanie 团队在 1.29.0 版本中已经修复了这个问题。解决方案的核心是：

1. 重写了 PydanticObjectId 的 JSON Schema 生成逻辑
2. 确保类型系统与 Pydantic 2.x 的 Schema 生成机制兼容
3. 保留了 ObjectId 的完整类型信息

最佳实践

为了避免类似问题，建议开发者：

1. 保持 Beanie 和 Pydantic 版本同步更新
2. 对于关键业务接口，考虑添加单元测试验证 OpenAPI 文档生成
3. 复杂模型建议先单独测试 JSON Schema 生成能力

版本兼容性说明

经过验证，以下组合可以正常工作：

• Beanie 1.29.0 + Pydantic 2.10.6
• Beanie 最新版本 + Pydantic 2.11.x

如果升级后问题仍然存在，建议检查：

1. 项目中是否有其他依赖锁定了旧版本
2. 自定义类型是否与 PydanticObjectId 产生冲突
3. 中间件或装饰器是否影响了 Schema 生成

通过理解这个问题背后的机制，开发者可以更好地在 MongoDB 和 FastAPI 的生态系统中构建稳健的应用系统。