MongoDB插入嵌套字典时直接传原始dict即可，PyMongo自动转为BSON并保留结构；禁用json.dumps()避免存为字符串，注意字段名不可含点号、需正确构造datetime和ObjectId等类型。
插入嵌套字典时，MongoDB 会自动展开层级，无需手动序列化
MongoDB 原生支持 BSON 格式，而 Python 的 dict（只要不含不支持的类型）可直接被 PyMongo 转为 BSON 文档。嵌套的 dict、list、甚至 datetime、ObjectId 都能原样存入，结构完全保留。
常见错误是试图用 json.dumps() 先转成字符串再插入——这会让整个嵌套结构变成一个字段值（字符串），失去查询能力。
- ✅ 正确：直接传原始
dict给collection.insert_one() - ❌ 错误：先
json.dumps(data)再插入 → 存进去的是字符串，不是嵌套文档 - ⚠️ 注意：
dict中不能含set、自定义类实例、不可哈希类型；否则抛TypeError: unhashable type
处理 datetime 和 ObjectId 等特殊类型要显式构造
Python 的 datetime 对象会被 PyMongo 自动转为 BSON 的 DateTime 类型，但必须来自 datetime 模块（不是字符串或时间戳整数）。ObjectId 同理，需从 bson.objectid.ObjectId 显式创建。
示例：
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
立即学习“Python免费学习笔记（深入）”；
from datetime import datetime
from bson.objectid import ObjectId
data = {
"user": {
"name": "Alice",
"joined_at": datetime(2024, 3, 15, 10, 30),
"profile_id": ObjectId("65f1a2b3c4d5e6f789012345")
},
"tags": ["python", "mongodb"]
}
- 若用字符串
"2024-03-15"，MongoDB 会存为字符串，无法按日期范围查询 - 若用时间戳整数
1710498600，也会存为数字，不是日期类型 -
ObjectId字符串必须是 24 位十六进制，否则抛InvalidId异常
避免嵌套过深或字段名含点号（.）和空字符（\x00）
MongoDB 不允许字段名中出现 . 或 null 字节（\x00），否则插入时直接报错：InvalidDocument: key 'a.b' must not contain '.'。嵌套字典若由外部数据生成（如 JSON API 响应），可能带这类非法键名。
- 检查并替换非法键：用递归函数把
.替换为_，或删掉\x00 - 深度建议控制在 100 层以内（BSON 限制），实际业务中超过 5 层就该考虑是否建模合理
- 如果嵌套结构动态变化且键名不可控，可在插入前用
collections.abc.Mapping+isinstance()遍历校验
批量插入时，嵌套字典同样适用，但要注意内存和超时
collection.insert_many([dict1, dict2, ...]) 支持含嵌套结构的多个文档，PyMongo 会逐个验证并转换。但若单个 dict 过大（>16MB），或列表总长度极大，可能触发 DocumentTooLarge 或网络超时。
- 单文档上限是 16MB（BSON 规范），嵌套本身不额外增加开销，但深层复制或引用可能隐式增大内存占用
- 插入前可用
bson.BSON.encode(doc).__len__()预估大小（注意：这会触发一次编码，仅用于调试） - 大批量场景建议分批，例如每 100 条调用一次
insert_many，并捕获BulkWriteError
