本文详解 Hibernate 6 推荐的 @UuidGenerator 注解用法，替代已弃用的 @GenericGenerator + UuidGenerator.class 组合，解决 Bean 类型不匹配错误，并说明其灵活性与标准兼容性。
本文详解 hibernate 6 推荐的 `@uuidgenerator` 注解用法，替代已弃用的 `@genericgenerator` + `uuidgenerator.class` 组合，解决 bean 类型不匹配错误，并说明其灵活性与标准兼容性。
在 Hibernate 6 中，旧版基于 @GenericGenerator 和 org.hibernate.id.UUIDGenerator 的 UUID 主键配置方式已被正式弃用（自 6.0 起），且底层实现已重构。你遇到的错误：
Parameter 0 of constructor in org.hibernate.id.uuid.UuidGenerator required a bean of type 'org.hibernate.annotations.UuidGenerator' that could not be found
根本原因在于：org.hibernate.id.uuid.UuidGenerator 是一个标识符生成器实现类，而非 Spring Bean；它依赖 @UuidGenerator 注解提供的元数据（如生成策略、版本、格式等）进行初始化。直接通过 @GenericGenerator(type = UuidGenerator.class) 强制注册，会触发 Hibernate 尝试注入一个并不存在的 org.hibernate.annotations.UuidGenerator 类型 Bean —— 这个类型实际是注解（@interface），不是可注入组件，因此导致类型不匹配异常。
✅ 正确做法是直接使用 Hibernate 6 原生支持的 @UuidGenerator 注解，它是专为 RFC 4122 UUID 设计的声明式生成器，语义清晰、配置简洁、完全兼容新架构：
import jakarta.persistence.Id;
import org.hibernate.annotations.UuidGenerator;
import java.util.UUID;
@Entity
public class Product {
@Id
@UuidGenerator // ✅ 默认生成 version 4 (random) UUID
private UUID id;
// 其他字段...
}
若需指定 UUID 版本或格式，@UuidGenerator 提供了灵活选项：
| 属性 | 说明 | 示例 |
|---|---|---|
style |
指定 UUID 版本（UUID_STYLE.V4, V7, V8） |
@UuidGenerator(style = UUID_STYLE.V7) |
format |
控制字符串表示形式（STRING, HEX, BASE64） |
@UuidGenerator(format = UUID_FORMAT.HEX) |
length |
仅当 format = HEX 时有效，指定十六进制长度（默认 32） |
@UuidGenerator(format = HEX, length = 16) |
@Id
@UuidGenerator(
style = UUID_STYLE.V7, // RFC 9562 标准的时间有序 UUID
format = UUID_FORMAT.STRING // "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
)
private String id; // 也可声明为 String 类型
⚠️ 注意事项：
- 不要混用
@GeneratedValue(strategy = GenerationType.AUTO)与@UuidGenerator—— 后者已隐含主键生成逻辑，显式声明GenerationType.AUTO会导致冲突； - 确保使用的是 Hibernate ORM 6.2+ 版本（推荐 6.3+），低版本可能缺少
UUID_STYLE.V7/V8等新特性； - 若实体 ID 字段为
String，Hibernate 会自动调用UUID.toString()序列化；若为UUID类型，则直接存储二进制/对象（取决于方言）； -
@UuidGenerator是 Hibernate 原生注解，无需额外配置@GenericGenerator或自定义IdentifierGenerator实现，大幅降低配置复杂度。
总结：@UuidGenerator 是 Hibernate 6 对 UUID 主键生成的现代化、标准化解决方案。它取代了过时的 @GenericGenerator + 手动指定 generator 类的方式，不仅消除了 Bean 注入异常，还提供了对 UUID 版本、格式、性能特性的精细控制。迁移时只需删除冗余注解，一行 @UuidGenerator 即可完成升级。
