motor 是唯一支持真正异步 mongodb 操作的库，因 pymongo 底层为同步阻塞 i/o，会卡死 asyncio 事件循环；asynciomotorclient 需显式配置 maxpoolsize 和 retrywrites，并正确使用 to_list() 或 async for 消费聚合结果。
不能用 pymongo 写异步代码，哪怕套了 async/await 也会卡死事件循环——Motor 是唯一正解。
为什么 pymongo.MongoClient 在 async 函数里会拖垮整个服务
因为 pymongo 底层是同步阻塞 I/O，它不关心 asyncio；你在 async def 里调用 client.db.collection.find_one({})，Python 表面在“异步”，实际线程被 MongoDB 网络响应死死卡住，其他协程全得等。现象是：QPS 上不去、超时陡增、日志没报错但接口变慢。
- 所有
pymongo操作（哪怕只是list_databases()）都必须在独立线程池里跑（loop.run_in_executor），否则就是自欺欺人 -
Motor的AsyncIOMotorClient才是为 asyncio 设计的，所有方法返回Awaitable，真正非阻塞 - 装了
pymongo不等于能异步——必须卸载后重装motor：pip uninstall pymongo && pip install motor
AsyncIOMotorClient 初始化时必须传 maxPoolSize 和 retryWrites
默认连接池只有 100，高并发聚合场景下容易耗尽连接，导致 TimeoutError: Connection pool is full；而 retryWrites=true 在 MongoDB 4.0+ 是默认开启的，但 Motor 不显式传会触发异常重试逻辑错乱。
- 生产环境建议设
maxPoolSize=300（200~500 区间按 QPS 调整） - 务必显式加
retryWrites=True，尤其当集群启用了副本集或分片时 - 连接字符串里带
mongodb+srv://时，tls=True也得手动写上，否则可能静默失败 - 示例初始化：
client = AsyncIOMotorClient("mongodb://localhost:27017", maxPoolSize=300, retryWrites=True)
aggregate() 必须配合 to_list() 或 async for，不能直接 await
aggregate() 返回的是一个 cursor 对象（AggregationCursor），不是结果本身；直接 await collection.aggregate(pipeline) 会报 TypeError: object AggregationCursor can't be used in 'await' expression。
- 小结果集（await cursor.to_list(length=None) 最省事
- 大数据量必须用
async for doc in cursor:流式处理，否则内存爆掉 -
to_list()的length参数填None表示“全取”，填数字则只取前 N 条——别漏写None，默认是101，容易误以为查少了 - 聚合里慎用
$lookup多层嵌套，IO 放大效应明显，比单集合查询慢 3~5 倍
写操作默认不抛异常，insert_one() 成功与否得自己检查结果
Motor 的写操作（insert_one、update_many、delete_one）默认“发出去就返回”，即使 MongoDB 回复写入失败（比如唯一索引冲突、类型校验失败），也不会自动 raise 异常——这是和 pymongo 最危险的差异。
- 必须
await并检查返回值：result = await collection.insert_one(doc)，然后看result.acknowledged是否为True - 对
update_many，要关注result.matched_count和result.modified_count，二者为 0 可能意味着条件写错或数据不存在 - 事务必须显式传
session参数：async with await client.start_session() as s: await collection.insert_one(..., session=s) - 常见错误现象：代码没报错、日志显示“done”，但数据库空空如也，或部分文档被跳过
最易被忽略的是写操作的“静默失败”机制——它不像 pymongo 那样遇到唯一键冲突立刻炸，而是默默吞掉错误，除非你主动检查返回对象。这点在迁移同步代码到 Motor 时，几乎必踩坑。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
