本文介绍通过 mongodb 唯一索引实现注册时用户名与邮箱去重的最优方案，避免应用层重复校验，提升一致性与性能，并详解错误捕获、索引创建及 go 语言（mgo/mongo-go-driver）中的具体实现。
本文介绍通过 mongodb 唯一索引实现注册时用户名与邮箱去重的最优方案，避免应用层重复校验，提升一致性与性能，并详解错误捕获、索引创建及 go 语言（mgo/mongo-go-driver）中的具体实现。
在用户注册场景中，仅依赖应用层“先查后插”的双重检查（即先 FindOne 判断 username/email 是否存在，再 Insert）不仅存在竞态条件（race condition）风险——两个并发请求可能同时通过校验并插入相同用户名，导致数据不一致；还会增加一次不必要的数据库往返，降低吞吐量。更健壮、更高效的做法是：移除前置查询，直接插入，并依托 MongoDB 的唯一索引（unique index）由数据库原子性地拒绝重复值，再在应用层精准识别并处理对应字段的冲突错误。
✅ 正确做法：为关键字段建立唯一索引
首先，确保在 users 集合上为 username 和 email 字段分别创建唯一索引（支持单字段去重）：
// MongoDB Shell 示例
db.users.createIndex({ "username": 1 }, { unique: true, name: "username_unique" });
db.users.createIndex({ "email": 1 }, { unique: true, name: "email_unique" });⚠️ 注意：不要使用复合唯一索引 {username: 1, email: 1} 来替代两个单字段索引——它只保证组合值唯一，无法阻止 user1 + email2 和 user2 + email1 同时插入导致的单字段重复。
在 Go 应用启动时（如 initDB() 函数中），推荐使用驱动提供的索引保障机制自动创建，避免手动运维遗漏。以现代官方驱动 go.mongodb.org/mongo-driver/mongo 为例：
import (
"context"
"go.mongodb.org/mongo-driver/bson"
"go.mongodb.org/mongo-driver/mongo/options"
)
func ensureUniqueIndexes(ctx context.Context, collection *mongo.Collection) error {
// 确保 username 唯一索引
_, err := collection.Indexes().CreateOne(ctx, mongo.IndexModel{
Keys: bson.D{{"username", 1}},
Options: options.Index().SetUnique(true).SetName("username_unique"),
})
if err != nil {
return fmt.Errorf("failed to create username index: %w", err)
}
// 确保 email 唯一索引
_, err = collection.Indexes().CreateOne(ctx, mongo.IndexModel{
Keys: bson.D{{"email", 1}},
Options: options.Index().SetUnique(true).SetName("email_unique"),
})
if err != nil {
return fmt.Errorf("failed to create email index: %w", err)
}
return nil
}该操作幂等安全：若索引已存在，CreateOne 将静默返回（不报错），无需额外判断。
? 错误识别与用户友好的反馈
当插入违反唯一约束时，MongoDB 返回标准错误码 11000（duplicate key）。我们可据此解析具体冲突字段：
import (
"errors"
"strings"
"go.mongodb.org/mongo-driver/mongo"
"go.mongodb.org/mongo-driver/mongo/writeerror"
)
func insertUser(ctx context.Context, collection *mongo.Collection, user User) error {
_, err := collection.InsertOne(ctx, user)
if err == nil {
return nil
}
// 检查是否为唯一键冲突
if writeException, ok := err.(mongo.WriteException); ok && len(writeException.WriteErrors) > 0 {
for _, we := range writeException.WriteErrors {
if we.Code == 11000 {
// 解析错误信息（格式示例：E11000 duplicate key error collection: db.users index: email_unique dup key: { email: "a@b.com" }）
msg := we.Message
if strings.Contains(msg, "username_unique") {
return errors.New("username already exists")
}
if strings.Contains(msg, "email_unique") {
return errors.New("email already registered")
}
return errors.New("username or email already exists")
}
}
}
return err // 其他非唯一性错误（如网络、schema等）原样抛出
}✅ 提示：生产环境建议结合 writeerror.WriteError 的 KeyPattern 字段做结构化解析（需 MongoDB 6.0+ 及较新驱动），比字符串匹配更健壮；但对大多数场景，上述基于索引名的 Contains 判断已足够清晰可靠。
? 总结与最佳实践
- 永远优先使用唯一索引：它是 MongoDB 保证数据完整性的底层机制，比任何应用层逻辑都更可靠、更高效；
- 索引命名规范化：显式指定 name（如 "username_unique"），便于后续排查、监控及自动化管理；
- 启动时确保索引：在服务初始化阶段调用 CreateOne，避免上线后因缺失索引引发静默数据污染；
- 错误处理聚焦业务语义：将底层 11000 错误转化为明确的业务提示（如 "email already registered"），提升前端交互体验；
- 不依赖 upsert 替代唯一索引：Upsert 适用于“存在则更新”逻辑，但无法替代唯一约束对非法插入的拦截能力。
通过这一设计，你不仅消除了竞态风险，还简化了注册流程逻辑，使系统更接近“数据库即真理源（source of truth）”的理想架构。
