Spring Boot3升级后Hibernate6.1读取PostgreSQL UUID异常排查

问题背景 #

将Spring Boot从2.x升级到3.x，同时Hibernate从5.x升级到6.1版本后，PostgreSQL数据库中UUID列的读取结果出现异常。

表结构 #

Table "public.combination"
           Column           |   Type    | Collation | Nullable |      Default      
----------------------------+-----------+-----------+----------+-------------------
 id                         | uuid      |           | not null | gen_random_uuid()
 kind                       | kind_type |           | not null | 

JPA实体类 #

import java.util.UUID;

@Entity
@Table(name = "combination")
public class Combination
{
    @Id
    @Column(name = "id")
    @NotNull
    private UUID id;

    public UUID getId()
    {
        return id;
    }
    // 其他字段与方法省略
}

现有表记录 #

argas=# select * from combination ;
                  id                  |    kind     
--------------------------------------+---------------
 0f787085-9a45-4512-ae55-f6db24ab8178 | connectivity
(1 rows)

Repository查询代码 #

@Repository
public interface CombinationRepository extends CrudRepository<Combination, UUID>
{
    Iterable<Combination> findAllByKind(@NotNull Kind kind);
}

异常现象 #

• Spring Boot2+Hibernate5环境：返回正确UUID 0f787085-9a45-4512-ae55-f6db24ab8178（对应mostSigBits = 1114764626895389970，leastSigBits = -5884525917016194696）
• Spring Boot3+Hibernate6环境：返回异常UUID 30663738-3730-3835-2d39-6134352d3435（对应mostSigBits = 3487535676028631093）

已尝试方案：

• 保持运行配置一致，仅切换分支重构
• 设置hibernate.type.preferred_uuid_jdbc_type为CHAR或BINARY，问题未解决
• 使用PostgreSQL驱动版本42.5.4

解决步骤 #

1. 显式指定列类型映射 #

在实体类的@Column注解中添加columnDefinition，明确匹配PostgreSQL的uuid类型：

@Id
@Column(name = "id", columnDefinition = "uuid")
@NotNull
private UUID id;

2. 配置正确的UUID JDBC类型 #

在application.properties或application.yml中设置适配PostgreSQL的UUID类型：

hibernate.type.preferred_uuid_jdbc_type=UUID

注：Hibernate 6对类型匹配要求更严格，CHAR/BINARY不适配PostgreSQL原生UUID列，必须指定UUID。

3. 验证驱动兼容性 #

可尝试将PostgreSQL驱动升级到42.6.0+版本，确保与Hibernate 6的类型处理逻辑完全兼容。

4. 排查自定义类型转换器 #

检查项目中是否存在旧版UUID自定义转换器，Hibernate 6类型系统改动较大，旧转换器可能导致解析错误，需更新或移除。

原因分析 #

该问题并非Hibernate Bug，而是版本升级后的类型映射逻辑变化：

• Hibernate 5会自动适配PostgreSQL的uuid列到JavaUUID类型
• Hibernate 6增强了类型校验，未明确映射时，会将UUID字符串的ASCII码直接解析为UUID（异常UUID的字符对应原UUID字符串的ASCII值，如30是0的ASCII码），导致解析结果异常。

内容的提问来源于stack exchange，提问作者Thomas Wana