必须显式捕获DuplicateKeyError，因其继承自OperationFailure且旧版pymongo中不被Exception覆盖；mongoengine中需捕获NotUniqueError；事务中DuplicateKeyError触发后事务即abort，无法继续执行except内操作。
DuplicateKeyError 不能靠裸 try-except 捕获
直接写 except: 或 except Exception: 会漏掉 DuplicateKeyError，因为它继承自 OperationFailure，而某些旧版 pymongo（如 3.2.2）中它甚至不被 Exception 默认覆盖。必须显式导入并捕获。
常见错误现象：
- 代码里写了
try: collection.insert_one(...)+except:，但程序仍崩溃并打印完整 traceback - 用
mongoengine时调用.save()，DuplicateKeyError看似没被捕获——实际是 mongoengine 封装后抛出的异常类型变了，需捕获NotUniqueError而非原生DuplicateKeyError
正确做法：
- 显式导入：
from pymongo.errors import DuplicateKeyError, OperationFailure - 捕获要具体：
except DuplicateKeyError:，不要只写except Exception: - 如果同时处理其他数据库错误，可合并：
except (DuplicateKeyError, OperationFailure):
为什么事务里 catch 住 DuplicateKeyError 也救不了流程
MongoDB 事务一旦遇到写失败（包括 DuplicateKeyError），服务端立即标记该事务为 abort 状态。后续任何写操作都会立刻报 InvalidTransactionOperationError，而不是继续执行你 except 块里的 update_one 或 replace_one。
使用场景：
- 你正在用
session.with_transaction()包裹一组操作 - 其中某次
insert_one因_id冲突失败 - 你以为在
except里补个update_one就能兜底——其实根本进不去
可行替代方案：
- 改用
find_one_and_update+upsert=True，绕过 insert 阶段 - 提前查重：
if collection.find_one({"_id": doc["_id"]}) is None: insert_one(...)，但要注意并发竞争窗口 - 放弃事务，用单文档原子操作替代
insert_one 和 update_one 的参数差异直接影响冲突处理逻辑
insert_one 只管插入，撞了唯一键就硬报 DuplicateKeyError；update_one 和 replace_one 则天然支持“不存在就建、存在就改”的语义，只要配对参数得当。
关键参数组合：
-
collection.update_one({"_id": x}, {"$set": doc}, upsert=True)：推荐，原子、简洁、不抛 DuplicateKeyError -
collection.replace_one({"_id": x}, doc, upsert=True)：适合全量替换，注意会删掉原 doc 中不在新 doc 里的字段 -
collection.insert_one(doc)不带条件，就是纯插入，别指望它自动降级
性能影响：
-
upsert=True比纯insert_one多一次索引查找，但远好于先find_one再insert_one的两轮往返 - 高并发下，
upsert仍可能因竞态导致重复日志或业务逻辑错乱，需配合应用层幂等设计（如用请求 ID 做去重）
错误信息里藏着定位冲突字段的关键线索
DuplicateKeyError 的 errmsg 不只是提示“重复”，它明确告诉你哪个索引、哪几个字段撞了。比如：
E11000 duplicate key error collection: mydb.users index: email_1 dup key: { email: "a@b.com" }
这说明问题出在 email 字段的唯一索引上，不是 _id。如果你只检查 _id 是否存在，就会漏判。
实用技巧：
- 解析
err.errmsg字符串，用正则提取index:后的索引名和dup key:后的字段值 - 根据索引名决定走哪条兜底路径：是更新用户资料？还是合并设备绑定？还是拒绝注册？
- 日志里务必打全
err.code（固定为11000）和err.errmsg，别只打 str(e)
真正麻烦的不是捕获异常，而是从 errmsg 里准确还原冲突上下文，并让后续逻辑知道“这次到底撞了什么”。这个解析步骤，90% 的项目都省掉了，结果就是错误日志看不懂、修复无从下手。
