Motor连接MongoDB必须用AsyncIOMotorClient，因pymongo为同步阻塞；所有操作需await，聚合须用aggregate()+to_list()或async for；写操作默认不抛异常，事务需显式传session；慢查询多因IO、索引或非流式处理。
Motor 连接 MongoDB 必须用 motor.motor_asyncio.AsyncIOMotorClient
直接用 pymongo.MongoClient 写异步代码会卡死，因为它是同步阻塞的——哪怕你套了 async/await，底层 I/O 依然会把事件循环拖住。Motor 是官方维护的异步驱动，所有操作都返回 Awaitable，必须配合 await 使用。
常见错误现象：RuntimeWarning: coroutine 'AsyncIOMotorCollection.find' was never awaited，或者程序启动后没报错但查询永远不返回。
- 连接字符串里别漏掉
/?retryWrites=true（MongoDB 4.0+ 默认开启，不加可能触发重试逻辑异常） - 不要在全局作用域直接
await client.admin.command("ping")—— 启动时得包在 async 函数里，或用asyncio.run()单次调用 - 连接池大小靠
maxPoolSize控制，默认 100，高并发聚合场景建议显式设为 200~500，避免连接等待
聚合查询必须用 collection.aggregate() + to_list() 或游标迭代
aggregate() 返回的是 AsyncIOMotorCommandCursor，不是 list，不能直接 for 循环或取 len。想拿全部结果，得用 await cursor.to_list(length=None)；想流式处理大结果集，得用 async for doc in cursor:。
使用场景：查日志、统计报表、ETL 中间层聚合——这些往往数据量大、耗时长，用同步驱动会拖垮整个服务。
立即学习“Python免费学习笔记（深入）”；
-
to_list(length=1000)会一次性拉 1000 条进内存，大数据量时容易 OOM；length=None更危险，等价于全量加载 - 聚合管道里慎用
$lookup，特别是关联集合没建好索引时，Motor 不会帮你优化，慢查询照样拖垮 asyncio 事件循环 - 如果聚合阶段含
$facet或多分支，确保每个子管道也符合异步语义——Motor 对语法无额外限制，但错误写法（比如在 pipeline dict 里写同步函数）会导致运行时报TypeError: unhashable type: 'dict'
insert_one() / update_many() 等写操作必须 await，且注意默认不抛异常
Motor 所有写操作默认是「发出去就完事」，即使 MongoDB 返回写入失败（比如唯一键冲突、字段类型不符），也不会自动 raise 异常，除非你显式 await 并检查结果。
常见错误现象：代码看似执行成功，但数据库没数据，或部分文档被跳过，日志里却一片空白。
-
await collection.insert_one({...})返回InsertOneResult，其acknowledged属性为False表示写操作未确认（比如用了w=0） -
update_many(..., upsert=True)成功时返回UpdateResult，要看.matched_count和.upserted_id判断是更新还是插入 - 事务中用
with await client.start_session() as s:，但 session 必须传给每个操作，如collection.find(..., session=s)，漏传就退化成普通非事务操作
调试时别信 print()，用 logging + asyncio.get_event_loop().time() 量时间
异步代码里 print 容易掩盖时序问题，比如两个并发查询的输出混在一起看不出谁先谁后；更麻烦的是，某些聚合慢查询根本不会卡住 print，但会让后续 await 滞后几百毫秒。
性能影响：Motor 本身不慢，慢通常来自网络延迟、MongoDB 查询计划差、或 Python 层没做流式处理。
- 在关键 await 前后打日志，用
time.time()记录耗时，比看 console 输出靠谱得多 - 聚合管道开头加
{"$addFields": {"_debug_ts": {"$literal": "2024-06-15"}}}可快速验证 pipeline 是否被正确发送到服务端 - 遇到
ConnectionResetError或ServerSelectionTimeoutError，先检查 MongoDB 是否启用了net.ssl.mode: requireSSL，而 Motor 连接串没配tls=True和证书路径
真正难的不是写 await，是判断哪一层在阻塞：是 MongoDB 的磁盘 IO？是 Python 解析 BSON 太慢？还是你的聚合里嵌了个 $function 调了同步代码？这些问题不会报错，只会让响应时间飘忽不定。
