Python中MongoDB序列化核心是避免字段错乱、类型丢失等，应优先用Pydantic（需严格对齐文档结构、显式处理ObjectId和嵌套模型），marshmallow适用于老项目，pymongo json_util仅适合最简场景。
Python开发中MongoDB的数据序列化，核心问题不是“选哪个库”，而是“怎么避免字段错乱、类型丢失、嵌套爆炸和性能拖累”。直接上结论：优先用 Pydantic（同步或异步场景都适用），marshmallow 适合已有复杂校验逻辑的老项目，pymongo 自带的 BSON 转换仅用于最简场景——它不处理 ObjectId、datetime 的 JSON 兼容性，也不做字段过滤。
Pydantic 模型定义必须覆盖 MongoDB 文档结构
很多人把 Pydantic 当成“只是校验器”，结果序列化时字段对不上、类型被忽略。Pydantic 模型必须与 MongoDB 文档字段严格对齐，否则 model_dump() 或 model_dump_json() 会漏字段或报错。
-
ObjectId字段必须显式声明为str并加Field(default_factory=ObjectId)或用alias映射，否则序列化后变成ObjectId('...')对象，JSON dumps 直接抛TypeError - 嵌套文档（如
author字段引用另一个集合）不能只写dict，得定义对应子模型并用Optional[AuthorModel]或List[BookModel]，否则反序列化时丢失类型约束 - 数据库里存的是 ISO 格式字符串的日期，但 Pydantic 默认解析为
datetime；如果 API 需要返回字符串，得在模型里加serialize_as=str或用@field_serializer控制输出格式
marshmallow Schema 中 Nested 和 only 参数容易误用
用 marshmallow 做嵌套序列化时，Nested(AuthorSchema, only=("id", "name")) 看似简洁，但实际行为依赖于底层 MongoEngine 对象是否已加载关联数据。如果 book.author 是未加载的 ReferenceField，Nested 会静默跳过，而不是报错或返回空对象。
-
only只控制序列化输出字段，不影响反序列化；若需双向控制，得配合load_only/dump_only -
exclude在嵌套层级里不递归生效，比如exclude=("password",)放在顶层 Schema，不会自动排除嵌套author里的password字段 - 使用
@post_load构造对象时，注意data是字典而非原始 MongoEngine 实例，手动赋值前得先检查 key 是否存在，否则KeyError
pymongo 的 json_util 仅解决基础类型转换，别当万能方案
from bson import json_util 提供的 dumps() 确实能转 ObjectId 和 datetime，但它不做任何字段筛选、不校验、不支持自定义格式（比如把时间转为秒级时间戳），更无法处理嵌套文档的深度展开。
立即学习“Python免费学习笔记（深入）”；
- 直接
json_util.dumps(doc)返回的是 JSON 字符串，不是 Python 字典；如果后续还要加工（如加字段、改结构），得先json.loads()再操作，徒增开销 - 遇到
Decimal128或自定义 BSON 类型时，json_util默认转成带$numberDecimal的对象，前端解析失败率高，必须额外写default函数处理 - 它不感知业务语义，比如
is_deleted: True的文档，照样原样序列化出去——而 Pydantic 或 marshmallow 可以在 Schema 层直接dump_only=True过滤掉
真正麻烦的不是选哪个工具，而是字段映射关系一旦松动（比如 MongoDB 文档加了新字段、改了嵌套结构），所有序列化层都会无声失效。建议把模型定义和集合 schema 一起纳入 CI 检查，哪怕只是跑个 model.model_validate(doc) 断言，也比上线后才发现 ID 字段变 None 强得多。
