本文介绍如何在使用 mongodb java 驱动（同步版）向集合插入自定义 pojo 类（如 user）时，为指定字段（如 userid）创建唯一索引，确保数据完整性，并提供可直接运行的代码示例与关键注意事项。
本文介绍如何在使用 mongodb java 驱动（同步版）向集合插入自定义 pojo 类（如 user）时，为指定字段（如 userid）创建唯一索引，确保数据完整性，并提供可直接运行的代码示例与关键注意事项。
在 Java 中使用 MongoDB 驱动操作 POJO 类型（如 MongoCollection<User>）时，为字段（如 userID）设置唯一性并非通过 SQL 式的建表语句或注解自动完成，而是需显式创建唯一索引。该索引作用于集合层面，与 Java 类是否被序列化无关——只要字段名与类型匹配，索引即生效。
以下为完整、可落地的实现步骤：
✅ 正确创建唯一索引（推荐方式）
import com.mongodb.client.MongoCollection;
import com.mongodb.client.model.IndexOptions;
import com.mongodb.client.model.Indexes;
import org.bson.Document;
// 假设已获取 MongoDatabase db 和 User 实例 user
MongoCollection<User> userCollection = db.getCollection("users", User.class);
// 创建唯一索引：对 "userID" 字段升序建立唯一索引
IndexOptions uniqueIndexOptions = new IndexOptions().unique(true);
userCollection.createIndex(Indexes.ascending("userID"), uniqueIndexOptions);⚠️ 注意：Indexes.ascending("userID") 生成的是 Bson 对象，对应 MongoDB 命令中的 { "userID": 1 }；IndexOptions().unique(true) 则等价于 { "unique": true }。二者缺一不可，且*必须使用 `com.mongodb.client.model.包下的工具类**，而非字符串或 JSON 字面量——否则将触发编译错误（如Syntax error on token "{", delete this token`）。
✅ 索引创建时机建议
- 首次初始化集合时调用一次即可（例如在应用启动阶段），无需每次 addUser() 都执行；
- 若索引已存在，createIndex() 是幂等操作，不会报错；
- 可添加异常处理增强健壮性：
try {
userCollection.createIndex(Indexes.ascending("userID"),
new IndexOptions().unique(true).name("user_id_unique"));
} catch (MongoCommandException e) {
if (e.getErrorCode() == 85) { // Index already exists
System.out.println("Unique index on 'userID' already exists.");
} else {
throw e;
}
}✅ 实体类注意事项（User.java）
确保 userID 字段在 Java 类中可被 BSON 序列化器正确映射：
立即学习“Java免费学习笔记（深入）”；
public class User {
private String userID; // 推荐使用驼峰命名，与 MongoDB 字段名一致（或通过 @BsonProperty 注解映射）
private String name;
// 必须提供无参构造函数（驱动反序列化所需）
public User() {}
public User(String userID, String name) {
this.userID = userID;
this.name = name;
}
// getter/setter 省略...
}若 MongoDB 中实际存储字段名为 "user_id"（下划线风格），请使用 @BsonProperty("user_id") 显式标注：
@BsonProperty("user_id")
private String userID;❌ 常见错误规避
- ❌ 错误写法（语法非法）：
userCollection.createIndex({"userID": 1}, {unique: true}); // Java 不支持 JSON 字面量 - ❌ 忘记导入 org.bson.Document 或 com.mongodb.client.model.* 相关类；
- ❌ 在未创建索引前重复插入相同 userID，将导致 MongoBulkWriteException 或 MongoWriteException（错误码 11000），此时应捕获并友好提示用户：“用户ID已存在”。
✅ 验证索引是否生效
可通过 MongoDB Shell 或 Compass 查看索引：
db.users.getIndexes()
// 输出应包含类似：
// { "v" : 2, "key" : { "userID" : 1 }, "name" : "user_id_unique", "unique" : true }综上，使用 MongoCollection<T> 操作 POJO 完全支持唯一索引，关键在于正确使用驱动提供的 Indexes 工具类和 IndexOptions 构建索引定义。索引一旦建立，MongoDB 将在写入层强制保证 userID 全局唯一，无需 Java 层额外校验，既高效又可靠。
