必须创建复合唯一索引{user_id:1,activity_id:1}以原子性防止重复报名;建索引前须清理历史重复数据,否则因E11000错误失败;MongoDB唯一性保障仅来自索引层,应用层逻辑无法兜底。

创建复合唯一索引必须在插入前完成
MongoDB 的唯一性保障只来自索引层,不是应用逻辑能兜底的。你不能靠 Find() 判断是否存在再 Insert() —— 这个窗口期在并发下必然被击穿。真正起作用的是 createIndex({ fieldA: 1, fieldB: 1 }, { unique: true }) 这条命令执行成功后的存储引擎级校验。
常见失败场景包括:
- 集合里已有重复数据,建索引直接报
MongoServerError: E11000 duplicate key error,但你没检查返回值 - 字段含不可见字符(如末尾空格、
\u200b零宽空格),导致看似相同实则不同 - 大小写敏感但没配
collation: { locale: "en", strength: 2 },"Alice"和"alice"被当成两个键 - 字段允许
null,而 MongoDB 默认允许多个null值共存(需加sparse: true才能约束)
建索引后务必验证:db.collection.getIndexes() 输出中要有 "unique": true 且状态为 "ready"。
Go 中用 mgo 捕获 11000 错误要精准识别字段
mgo.IsDup() 只能告诉你“有重复”,但不知道是哪个字段组合冲突。实际生产中你常需要区分:是 name + lastName 冲突,还是 email + tenantId 冲突?因为后续处理逻辑可能完全不同(比如前者要提示“同名同姓已存在”,后者要拒绝注册并报警)。
推荐做法是解析错误信息中的索引名:
if mgo.IsDup(err) {
// err.Error() 类似 "E11000 duplicate key error collection: db.users index: name_1_lastName_1 dup key: { : \"Alice\", : \"Smith\" }"
// 提取 index 名称后缀,或提前约定索引命名规范,如 "name_lastname_unique"
}
不要依赖 err != nil 就重试或跳过——11000 是业务错误,不是临时故障;盲目重试可能让下游拿到错误状态。
复合索引字段顺序影响查询效率,但不影响唯一性语义
唯一性只看值的组合是否重复,和字段顺序无关。但顺序决定了这个索引能不能被查询命中:
- 索引
{ a: 1, b: 1, c: 1 }能加速{ a: 1 }、{ a: 1, b: 2 }、{ a: 1, b: 2, c: 3 }查询 - 但对
{ b: 2 }或{ c: 3 }查询完全无效 - 如果高频查询是
lastName + firstName,那就按这个顺序建索引,别为了“习惯”写成firstName + lastName
另外,数组字段参与复合唯一索引时会自动变为多键索引(multikey),此时唯一性仍跨文档生效,但单文档内数组元素组合可重复——这是设计行为,不是 bug。
分片集群上建唯一索引必须停写或走 mongos
在分片集群中,createIndex() 必须由 mongos 发起,不能连到某个 shard 上单独执行。否则索引只存在于那个 shard,全局唯一性就失效了。
更隐蔽的问题是:如果建索引期间有持续写入,部分 chunk 可能漏建索引,最终导致某些分片上约束不生效。官方明确要求「滚动建索引」时停止对该集合的所有写操作,或者接受风险走主节点强制建(仅限副本集)。
最容易被忽略的一点:分片键本身不能是唯一索引的唯一字段(除非它就是你要约束的业务字段)。如果业务要求 email 全局唯一,但 email 不是分片键,就得用代理集合或应用层协调——MongoDB 本身不支持跨分片的非分片键唯一约束。


















