如何从Motor迁移到PyMongo异步API？-MongoDB-PHP中文网

PyMongo 4.7+已整合Motor，应卸载motor、安装pymongo>=4.7，并将导入路径改为from pymongo import AsyncIOMotorClient；需显式传upsert参数、改用await cursor.to_list(length=None)、替换database_names()为list_database_names()、认证参数需规范、事务操作必须显式传session。

如何从motor迁移到pymongo异步api？

Motor连接对象不能直接替换为AsyncIOMotorClient

Motor本身就是基于PyMongo的异步封装，MotorClient和AsyncIOMotorClient在PyMongo 4.0+中已统一为同一类——AsyncIOMotorClient。如果你还在用旧版Motor（如motor==2.5），直接升级PyMongo后，motor.motor_asyncio.AsyncIOMotorClient仍可工作，但官方已将其移入pymongo命名空间。迁移第一步不是改代码逻辑，而是确认依赖版本：

卸载motor：pip uninstall motor
安装PyMongo 4.7+：pip install "pymongo>=4.7"（4.7起正式提供完整异步API）
导入路径从from motor.motor_asyncio import AsyncIOMotorClient改为from pymongo import AsyncIOMotorClient

注意：PyMongo 4.0–4.6虽带异步支持，但AsyncIOMotorClient仍在motor包里；4.7+才真正“吸收”Motor核心逻辑，motor包本身已不再维护。

await语法和方法名基本一致，但部分API被移除或重命名

绝大多数操作保持相同调用形式，比如collection.find()、database.list_collection_names()，都返回可await的对象。但以下差异必须手动修正：

collection.find_one_and_update()等原子操作现在**强制要求传upsert=False显式参数**，旧Motor默认upsert=False，PyMongo 4.7+若省略会报TypeError: find_one_and_update() missing 1 required keyword-only argument: 'upsert'
collection.aggregate()返回的AsyncIOMotorCommandCursor不再支持.to_list()的length参数（已被废弃），应改用await cursor.to_list(length=None)或分页迭代
client.get_database()和client["db_name"]行为一致，但client.database_names()已被彻底移除，改用await client.list_database_names()

连接选项和认证参数需按PyMongo规范调整

Motor兼容旧式URI参数（如maxPoolSize），但PyMongo 4.7+对连接字符串校验更严格，部分参数名已标准化：

maxPoolSize → 仍可用，但推荐用maxPoolSize（大小写敏感，旧Motor容忍maxpoolsize，PyMongo会静默忽略）
authSource必须显式指定，尤其在使用admin外数据库认证时；遗漏会导致AuthenticationFailed错误，且错误信息不提示缺失项
tlsAllowInvalidCertificates=True在生产环境会被拒绝，改用tlsCAFile或明确设置tlsInsecure=True（PyMongo 4.4+新增）
连接超时统一由timeoutMS控制（单位毫秒），connectTimeoutMS和socketTimeoutMS已被弃用

建议把连接逻辑抽成函数，并用AsyncIOMotorClient(**kwargs)构造，避免拼接URI带来的参数歧义。

事务和会话管理必须显式创建ClientSession

Motor中session常被隐式复用或省略，PyMongo异步API要求所有事务操作必须绑定显式ClientSession：

启动事务前必须async with await client.start_session() as session:
collection.insert_one(..., session=session)等操作必须传session参数，否则不在事务上下文中
事务内异常未被捕获时，PyMongo不会自动abort，需确保try/except后调用await session.abort_transaction()
session.end_session()通常由async with自动触发，但手动调用后该session不可再用