如何在Quarkus MongoDB Panache中标记字段为唯一值？

开发者阿泽

2026-9-30

Quarkus MongoDB Panache 字段唯一约束配置方案

Quarkus MongoDB Panache 没有单独封装唯一约束相关注解，唯一约束能力基于 MongoDB 原生的唯一索引实现，有两种常用配置方式：

方式1：注解快速配置（单字段唯一约束）

这是最简便的配置方式，适合单字段唯一约束场景：

在实体类需要设置唯一约束的字段上添加@Indexed(unique = true)注解
在应用配置文件中开启自动索引创建开关

代码示例：

import io.quarkus.mongodb.panache.PanacheMongoEntity;
import org.bson.codecs.pojo.annotations.Indexed;

public class User extends PanacheMongoEntity {
    // 将email字段设为唯一
    @Indexed(unique = true)
    public String email;

    public String username;
}

application.properties 配置：

# 开启MongoDB索引自动创建，默认关闭
quarkus.mongodb.auto-index-creation = true

方式2：手动编程创建（适配复杂场景）

如果需要配置复合唯一索引，或者需要自定义索引的其他属性，直接通过MongoCollection的API手动创建即可，推荐在应用启动时执行：

import io.quarkus.runtime.StartupEvent;
import jakarta.enterprise.event.Observes;
import com.mongodb.client.model.Indexes;
import com.mongodb.client.model.IndexOptions;

public class MongoIndexInitializer {
    // 应用启动时自动执行索引创建
    void initIndexes(@Observes StartupEvent event) {
        // 单字段唯一索引示例
        User.mongoCollection().createIndex(
            Indexes.ascending("email"),
            new IndexOptions().unique(true)
        );

        // 复合唯一索引示例：username+email组合唯一
        User.mongoCollection().createIndex(
            Indexes.compoundIndex(
                Indexes.ascending("username"),
                Indexes.ascending("email")
            ),
            new IndexOptions().unique(true)
        );
    }
}