Spring Boot 3.2.2升级后String转UUID类型转换异常求助

问题场景 #

将项目升级至Spring Boot 3.2.2后，调用BulkUserRepository.getAllUsersWithBulkId()方法时触发以下异常：

java.lang.ClassCastException: Cannot cast java.lang.String to java.util.UUID

当前环境：PostgreSQL数据库，Hibernate-core 6.4.1，Java 21。

相关代码 #

BulkEntity实体类 #

@Entity
@Table(name = "bulk_user")
@NoArgsConstructor
@AllArgsConstructor
@SuperBuilder(toBuilder = true)
@Getter
@Setter
public class BulkEntity {

    @Id
    @JdbcTypeCode(Types.VARCHAR)
    @Column(name = "row_id", nullable = false)
    private UUID rowId;

    @JdbcTypeCode(Types.VARCHAR)
    @Column(name = "bulk_upload_id", length = 50, unique = true, nullable = false)
    private UUID bulkId;

    @Column(name = "data", length = 500, nullable = false)
    private String data;

    @Column(name = "application", length = 50, nullable = false)
    private String application;
}

数据库中bulk_upload_id字段类型为varchar(500)。

BulkUserRepository接口 #

@Repository
public interface BulkUserRepository extends JpaRepository<BulkEntity, UUID> {
  @Query("select b from BulkEntity b where b.bulkId =:bulkId")
  List<BulkEntity> getAllUsersWithBulkId(@Param("bulkId")UUID bulkId);
}

调用代码 #

List<BulkEntity> bulkEntityList = bulkUserRepository.getAllUsersWithBulkId(bulkId);

注：bulkId为UUID类型，bulkUserRepository通过构造函数注入。

对比正常运行的同类逻辑 #

项目中另一个User实体的类似UUID查询逻辑可正常执行：

User实体字段 #

@JdbcTypeCode(Types.VARCHAR)
@Column(name = "kc_user_Id", length = 50, unique = true, nullable = false)
private UUID kcUserId;

数据库中kcUserId字段类型为varchar(36)。

UserRepository方法 #

@Query("SELECT u FROM User u WHERE u.kcUserId=?1")
Optional<User> findByKcUserId(UUID kcUserId);

调用代码 #

userRepository.findByKcUserId(userModel.getKcUserId());

注：userModel.getKcUserId()返回UUID类型值。

问题原因分析 #

1. Hibernate 6.x对UUID与字符串类型的映射处理逻辑有调整，当数据库字段长度（varchar(500)）远大于标准UUID的36位长度时，Hibernate可能无法自动识别该字段应映射为UUID类型，而是将其解析为String，导致查询时类型转换失败。
2. 对比正常运行的kcUserId字段，其数据库长度为varchar(36)，刚好匹配UUID的标准长度，Hibernate能正确识别并完成类型映射。

解决方案 #

方案一：调整数据库字段长度（推荐） #

将bulk_upload_id字段的长度修改为varchar(36)，与标准UUID长度一致，Hibernate会自动正确映射UUID类型，无需额外配置。

方案二：显式指定Hibernate类型 #

在bulkId字段上添加@Type注解，明确指定类型为uuid-char，强制Hibernate按字符串形式处理UUID映射：

@Id
@JdbcTypeCode(Types.VARCHAR)
@Column(name = "row_id", nullable = false)
private UUID rowId;

@Type(value = "uuid-char")
@JdbcTypeCode(Types.VARCHAR)
@Column(name = "bulk_upload_id", length = 500, unique = true, nullable = false)
private UUID bulkId;

方案三：修改JPQL查询，手动转换类型 #

在JPQL查询中将传入的UUID参数转换为字符串，匹配数据库存储的格式：

@Repository
public interface BulkUserRepository extends JpaRepository<BulkEntity, UUID> {
  @Query("select b from BulkEntity b where b.bulkId = cast(:bulkId as string)")
  List<BulkEntity> getAllUsersWithBulkId(@Param("bulkId")UUID bulkId);
}

内容的提问来源于stack exchange，提问作者Kavi Chinna