Hibernate 6 中使用 extract() 函数报错的正确解决方案

hibernate 6 严格区分时间点（temporal）与时间间隔（duration），原 hql 中 `extr

act(day from (current_timestamp - alarm.date))` 因语义错误被拒绝；应改用 `by day` 时间算术运算符实现天数差判断。

在 Hibernate 6+（尤其是配合 Spring Boot 3.x 和 Java 17）中，HQL 的日期时间算术规则发生了重要演进：时间差运算（如 A - B）的结果类型不再是 Temporal，而是 Duration——即一个表示纳秒级时长的量值，而非可提取年/月/日的“时间点”。因此，旧版 Hibernate 5 中惯用的 extract(day from (t1 - t2)) 在 Hibernate 6 中会明确抛出 QueryException，提示参数类型不匹配（extract() 第二参数需为 TEMPORAL，但实际传入的是 java.time.Duration）。

✅ 正确写法（HQL / JPQL）：

(current_date - alarm.date) by day < 1

该表达式含义清晰：

• current_date - alarm.date → 返回 Duration 类型（单位：纳秒）；
• by day → 将该 Duration 按自然日向下取整转换为 long 类型的天数（例如：36小时 → 1 天，48小时 → 2 天）；
• 最终生成符合 Oracle 12c 方言的 SQL（如 TRUNC(SYSDATE) - TRUNC(alarm_dt)

⚠️ 注意事项：

• 避免继续使用 Calendar：@Temporal + Calendar 是 Java 7 时代的遗留方案，已过时且线程不安全。推荐改为 java.time.LocalDate（仅日期）或 java.time.LocalDateTime（日期+时间），并配合 @Column(columnDefinition = "DATE") 或 @Column(columnDefinition = "TIMESTAMP") 显式声明数据库类型。
• 若实体字段需保留日期精度（无时分秒），建议重构为：

  @Column(name = "ALARM_DT")
  private LocalDate date; // 替代 Calendar

  对应 HQL 可简化为：

  (current_date - alarm.date) < 1 // LocalDate 直接支持日期减法，结果即为 Period（HQL 自动映射为天数）

• by day 还支持其他单位：by hour, by minute, by second，适用于不同粒度的时效判断。

? 总结：Hibernate 6 的时间算术设计更贴近领域语义——“两个时间点之差”本质是“持续时间”，而非另一个时间点。摒弃 extract() 对 Duration 的误用，拥抱 by 语法，不仅能解决当前报错，更能写出类型安全、可读性强、跨方言兼容的现代 JPQL 查询。