Hibernate中OffsetTime与OffsetDateTime在MySQL UTC时区下的时间不一致问题

问题现象 #

MySQL服务器全局及会话时区均设为UTC（+00:00），无TIMESTAMP列，使用Hibernate操作包含OffsetTime和OffsetDateTime字段的实体时，出现明显的处理逻辑不一致：

• OffsetTime：存入09:00Z（UTC时间9点），数据库实际存储为08:00:00；从数据库查询返回后，实体中该字段变为10:00:00，前后共出现2小时偏差。
• OffsetDateTime：存入2022-12-26T09:00Z，数据库存储为2022-12-26 09:00:00.000000；查询返回后为2022-12-22T09:00:00Z，完全符合预期。

实体字段定义 #

private OffsetTime offsetTime;
private OffsetDateTime offsetDateTime;

测试代码片段 #

• 存储OffsetTime：

  setOffsetTime(LocalTime.of(9, 0).atOffset(ZoneOffset.UTC));
  

  存储前打印值为09:00Z，数据库最终存储值为08:00:00。

• 存储OffsetDateTime：

  setOffsetDateTime(LocalDateTime.of(LocalDate.now(), LocalTime.of(9, 0)).atOffset(ZoneOffset.UTC));
  

  存储前打印值为2022-12-26T09:00Z，数据库最终存储值为2022-12-26 09:00:00.000000。

原因分析 #

核心问题在于Hibernate对OffsetTime的类型映射存在逻辑缺陷，与OffsetDateTime的处理逻辑不同：

1. OffsetDateTime的正确逻辑：Hibernate将其视为带时区偏移的完整日期时间，存入MySQL的DATETIME类型时，会自动转换为UTC时间存储；取出时，再将UTC时间还原为带UTC偏移的OffsetDateTime对象，全程保留时区信息，因此没有偏差。
2. OffsetTime的错误逻辑：MySQL没有对应OffsetTime的原生类型，只能用TIME类型存储。Hibernate旧版本（如5.x早期版本）的OffsetTimeType处理器，错误地将OffsetTime的时区偏移与JVM默认时区进行了两次转换：
   • 存入时：将UTC偏移的OffsetTime转换为JVM本地时区的LocalTime，再写入数据库的TIME字段。
   • 取出时：将数据库中UTC时区的TIME值，再次转换为JVM本地时区的OffsetTime。
     两次转换叠加后，就出现了存入1小时偏差+取出1小时偏差的总问题。

解决方案 #

1. 升级Hibernate版本：直接升级到Hibernate 5.6及以上版本，或者6.x系列，这些版本已经修复了OffsetTime的时区转换bug，无需额外配置即可正常处理。
2. 自定义类型处理器：如果无法升级版本，可以手动编写OffsetTime的类型处理器，强制以UTC时区进行转换：

   public class UtcOffsetTimeType extends OffsetTimeType {
       @Override
       protected <X> X wrap(OffsetTime offsetTime, WrapperOptions options) {
           // 强制转换为UTC时间后存入数据库
           return super.wrap(offsetTime.withOffsetSameInstant(ZoneOffset.UTC), options);
       }
   
       @Override
       public OffsetTime unwrap(Object value, Class<? extends OffsetTime> type, WrapperOptions options) {
           // 取出时将TIME值绑定为UTC偏移的OffsetTime
           LocalTime localTime = (LocalTime) super.unwrap(value, LocalTime.class, options);
           return localTime.atOffset(ZoneOffset.UTC);
       }
   }
   

   然后在实体字段上指定该自定义类型：

   @Type(type = "com.your.package.UtcOffsetTimeType")
   private OffsetTime offsetTime;
   

3. 改用LocalTime替代：如果业务场景允许，直接使用LocalTime字段，配合显式的时区控制，确保存入和取出的都是UTC时间，避免OffsetTime的转换问题。

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