从Hibernate 5升级到6后Instant读写时间异常的兼容配置问题

问题重现 #

项目迁移至Spring Boot 3与Hibernate 6.5.3.Final后，使用Instant类型的实体出现查询结果不符合预期的问题：

实体类定义 #

@Data
@Entity
@SuperBuilder(toBuilder = true)
@AllArgsConstructor
@NoArgsConstructor
public class TestEnity {
    @NonNull
    private UUID id;
    @NonNull
    private Instant createDate;
}

写入与数据库数据 #

通过EntityManager添加记录（当前JVM时区为本地时区，时间为12点），配置spring.jpa.properties.hibernate.type.preferred_instant_jdbc_type=TIMESTAMP后，数据库存储的create_date数据如下：

id                                      |   create_date
----------------------------------------------------------------------
3ceca36e-710f-4ea3-223b-1118b0796c7f    |   2025-04-10 12:20:30.510548
3ceca36e-710f-4ea3-223b-2228b0796c7f    |   2025-04-09 12:20:30.510548
3ceca36e-710f-4ea3-223b-3338b0796c7f    |   2025-04-08 12:20:30.510548

查询代码与异常结果 #

使用Querydsl执行范围查询（条件：createDate >= 2025-04-09T12:19:58Z && createDate <= 2025-04-10T12:29:58Z）：

SQLQueryFactory sqlQueryFactory = new SQLQueryFactory(GenaratorQsqlUtils.createConfiguration(), dataSource);

BooleanBuilder booleanBuilder = new BooleanBuilder();
booleanBuilder.and(getDateFrom(instantFrom));
booleanBuilder.and(getDateTo(instantTo));
    
long count = sqlQueryFactory.select()
                .from(testE)
                .where(booleanBuilder)
                .fetchCount();

预期获取2条记录（ID后缀1118b0796c7f和2228b0796c7f），但实际仅查询到前者。调试发现查询时create_date被转换为2025-04-10 10:20:30.510548（UTC时区），而手动将2228b0796c7f的create_date改为2025-04-09 14:20:30.510548（+02偏移）后，才能查询到2条记录。

Hibernate 5中无此问题，且无需配置preferred_instant_jdbc_type；Hibernate 6中不配置该属性时，写入数据库的时间会自动转为UTC。

原因分析 #

1. Hibernate 6对Instant类型的语义严格化
   Instant本质是UTC时间点，Hibernate 6默认遵循Java时间API的语义，将其映射到JDBC的TIMESTAMP WITH TIME ZONE类型，写入时直接以UTC存储。当配置preferred_instant_jdbc_type=TIMESTAMP（无时区类型）时，Hibernate 6会将Instant（UTC）转换为JVM时区的时间存入数据库，但查询时会反向将数据库的无时区时间解析为UTC的Instant，导致时区偏移。

2. Hibernate 5与6的处理差异
   Hibernate 5对Instant的处理未严格遵循UTC语义，直接将Instant按JVM时区映射到TIMESTAMP类型，读写时均使用JVM时区，因此没有时区转换问题。

向后兼容的配置方案 #

1. 统一读写时区配置 #

添加以下配置，让Hibernate在处理TIMESTAMP类型时，统一使用JVM时区（替换为你的实际时区，如Asia/Shanghai）：

spring.jpa.properties.hibernate.jdbc.time_zone=Asia/Shanghai
spring.jpa.properties.hibernate.type.preferred_instant_jdbc_type=TIMESTAMP

该配置会让Hibernate在写入时将Instant转换为指定时区的时间存入TIMESTAMP字段，查询时再将字段值转换为对应时区的Instant，避免偏移。

2. 对齐Querydsl的时区处理 #

确保Querydsl生成的SQL查询使用与Hibernate一致的时区。如果使用Instant作为查询参数，Hibernate的时区配置会自动处理参数的转换，无需额外修改代码；若手动拼接时间条件，需确保参数与数据库存储的时区一致。

3. 可选：改用LocalDateTime（非时区感知场景） #

如果业务逻辑不需要UTC时间感知，仅需本地时间，可以将实体类的Instant改为LocalDateTime，此时Hibernate 6会直接映射到TIMESTAMP类型，无需额外时区配置，完全兼容Hibernate 5的行为。

为什么写入时会转换为UTC？ #

Hibernate 6严格遵循Java时间API的定义：Instant代表UTC时间线上的一个瞬间，默认映射到JDBC的TIMESTAMP WITH TIME ZONE类型，写入时直接以UTC格式存储。当数据库字段为TIMESTAMP（无时区）且未配置hibernate.jdbc.time_zone时，Hibernate会将Instant（UTC）转换为UTC时间存入字段，这是语义一致性的体现。

内容的提问来源于stack exchange，提问作者Mike Sonarov