在MongoDB中理解唯一索引防止重复插入的原理
唯一索引的工作原理
在MongoDB中，唯一索引通过在指定字段上建立唯一约束来阻止重复值的插入。当应用尝试插入带有已存在唯一字段值的文档时，数据库会返回错误码 11000，表示重复键错误。
此外，唯一索引不仅用于字段唯一性，还可用作主键的替代方案，在设计集合结构时具有重要意义。索引背后的机制通常依赖于 B-树/有序结构，用以高效地检测重复并维护数据有序性。
db.users.createIndex({ "email": 1 }, { unique: true })对于多字段组合的唯一索引，可以确保多列组合的唯一性。组合唯一键（compound index）在多字段唯一性场景非常常见，例如同时以用户名和邮箱联合约束。
为什么会有重复插入风险
在并发写入和分布式部署场景中，可能有多个进程同时尝试写入相同的唯一字段值。如果没有数据库端的唯一约束，就会产生重复记录。
通过数据库端的唯一索引，可以将重复插入的风险降到最低，从而实现幂等性的一部分。索引作为最终的约束层极其关键。
在MongoDB中创建唯一索引的常见实现方式
通过MongoDB Shell（命令行）创建唯一索引
最直接的方式是在 MongoDB Shell 中对集合创建唯一索引。简单命令即可实现，例如对邮箱字段创建唯一索引。
该操作会对集合中已存在的重复值产生冲突，需要先清理重复数据再创建。执行前请备份数据，以防误操作造成数据损失。
db.users.createIndex({ "email": 1 }, { unique: true })通过 Atlas UI 或 Atlas API 创建唯一索引
在云端 Atlas 集群中，可以通过 UI 的索引管理或 API 设置来创建唯一索引。便于在集群级别进行策略化管理，适合多环境部署。
用户在创建索引时可勾选“Unique”选项，Atlas 将自动处理并发场景中的冲突。注意索引生效后需对已有重复值进行清理，否则创建会失败。
Java开发者的实战：使用MongoDB Java驱动实现唯一性
依赖与版本选择
选择合适版本的 MongoDB Java 驱动对实现稳定性至关重要。建议使用官方驱动 4.x 及以上版本，并确保与 Java 版本兼容。
通过 Maven 引入依赖，通常包含以下坐标：org.mongodb:mongodb-driver-sync 与 org.mongodb:mongodb-driver-core，以及 org.bson 的支持。
/* Maven 依赖示例 - 适用于 Java 项目 */
org.mongodb mongodb-driver-sync 4.5.0
org.mongodb mongodb-driver-core 4.5.0
实例代码：从插入前检查到抛出异常
通过 Java 驱动进行唯一性写入时，捕获 MongoWriteException 并判断错误码 11000可以实现对重复键的处理和幂等性保障。
下面给出一个简化的写入封装，演示如何在遇到重复键时抛出自定义异常或进行重试控制。
import com.mongodb.MongoWriteException;
import com.mongodb.client.MongoCollection;
import org.bson.Document;public class UserService {private final MongoCollection users;public UserService(MongoCollection users) {this.users = users;}public void insertUser(Document user) {try {users.insertOne(user);} catch (MongoWriteException e) {if (e.getError().getCode() == 11000) {// 处理重复键错误，保持幂等性throw new RuntimeException("Duplicate key: user already exists", e);} else {throw e;}}}
}
处理并发写入与重复键错误的策略
重复键错误的异常处理
当唯一索引冲突发生时，MongoDB 会抛出 MongoWriteException，错误代码通常是 11000。在 Java 应用中，应该捕获该异常并进行幂等性处理，避免业务逻辑受阻。
为避免异常成本过高，可以在应用层进行幂等性设计，例如对关键字段实现业务级唯一标识并确保每次写入都是幂等的。数据库唯一索引仍然是最终约束。
try {collection.insertOne(doc);
} catch (MongoWriteException e) {if (e.getError().getCode() == 11000) {// 处理重复键} else {throw e;}
}乐观锁与幂等性设计
幂等性设计是分布式系统的核心原则之一。通过使用唯一字段作为业务标识并确保每次写入都是幂等的，可以降低重复写入风险。结合唯一索引，通常在高并发场景下需要额外的原子操作或事务支持。
MongoDB 的事务特性在副本集环境中可用，可保障跨集合写入的原子性。在复杂场景下，考虑在事务内完成检查和写入。
// 伪代码：在事务中执行原子性写入示例
client.startSession().withTransaction((session) -> {collection.withSession(session).updateOne(filter, update, new UpdateOptions().upsert(true));return null;
});性能与容量考虑：唯一索引对写吞吐与查询的影响
索引选择与字段基于查询
建立唯一索引会增加写入成本，因为数据库需要维护索引树以确保唯一性。应仅在必要字段上建立唯一索引，并确保查询能够利用被索引的字段进行过滤。
对于经常用作查询条件或排序的字段，添加唯一索引可以提升读取性能。在设计阶段就要评估查询计划，以确保索引带来正向收益。
db.orders.createIndex({ "orderId": 1 }, { unique: true })覆盖索引与查询性能
覆盖索引能够让查询仅从索引中返回结果，避免回表。在设计索引时考虑字段的覆盖能力，以提升查询效率。
在高吞吐场景中，合理的索引结构能显著降低延迟。定期监控写入延迟并调整索引，以保持系统稳定性。
错误排查：常见问题清单
已有唯一索引导致插入失败
如果遇到新建唯一索引失败，往往是因为集合中存在重复值。需要先清理重复数据，或对重复值进行去重处理。
可以使用聚合查询找出重复项并进行处理。找出重复键的字段及对应重复记录以便后续处理。
db.users.aggregate([{ $group: { _id: "$email", count: { $sum: 1 }, docs: { $push: "$_id" } } },{ $match: { count: { $gt: 1 } } }
])数据不一致的情况
在分布式场景下，偶发的崩溃或恢复可能导致轻微不一致。重新索引或清理数据是常见的修复手段。
为了避免此类问题，建议在写入时结合事务或幂等性处理，确保跨集合操作的原子性。在支持的环境下使用事务可以降低不一致风险。
完整实战代码集锦
完整的插入流程示例
以下示例展示了一个端到端的插入流程：初始化集合、创建唯一索引、执行写入、以及对重复项的处理与日志记录。
import com.mongodb.client.*;
import com.mongodb.client.model.IndexOptions;
import com.mongodb.client.model.Indexes;
import com.mongodb.MongoWriteException;
import org.bson.Document;public class FullInsertDemo {public static void main(String[] args) {try (MongoClient client = MongoClients.create("mongodb://localhost:27017")) {MongoDatabase db = client.getDatabase("demo");MongoCollection users = db.getCollection("users");// 1) 确保唯一索引users.createIndex(Indexes.ascending("email"), new IndexOptions().unique(true));// 2) 插入文档Document user = new Document("email", "alice@example.com").append("name", "Alice");try {users.insertOne(user);System.out.println("Inserted");} catch (MongoWriteException e) {if (e.getError().getCode() == 11000) {System.out.println("Duplicate email, skip insert");} else {throw e;}}}}
}
