HQL 語法錯誤排查指南：unexpected token: null 經典案例分析

Hibernate HQL 語法異常「unexpected token: null」根因排查與防範清單

報錯信息：

org.hibernate.hql.internal.ast.QuerySyntaxException: unexpected token: null near line 1, column 290
[select count(*) from cn.com.taiji.sample.entity.User t where 1=1 and (t.name like :userName or t.namePy like :userName or t.loginName like :userName and t.status =:status and not exists(select b.user from cn.com.sample.entity.UserRole b where b.role.id =:roleId and b.user.id = t.id)]

核心錯誤原因

括號不匹配：SQL 末尾缺少右括號 `)`。完整 WHERE 子句以 `(` 開頭，但 `not exists` 子查詢結束後缺少閉合主查詢的右括號。

常見 HQL 語法陷阱清單

1. 括號配對錯誤：複雜條件嵌套時最易漏寫 `)`，建議格式化 SQL 後逐行對齊檢查
2. 引號規範：字符串字面量必須用單引號，雙引號在 HQL 中無效
3. 操作符空格：`=:` 應緊湊書寫，`like :` 中冒號前建議保留空格
4. 多餘空格/不見字符：複製粘貼時可能攜帶零寬空格或特殊字符
5. 別名衝突：子查詢別名與外層重複導致解析歧義
6. 參數綁定名稱錯誤：冒號參數名與 setParameter 不一致

修正後的正確 HQL

select count(*) from User t 
where 1=1 
and (t.name like :userName or t.namePy like :userName or t.loginName like :userName) 
and t.status = :status 
and not exists (
    select b.user from UserRole b 
    where b.role.id = :roleId and b.user.id = t.id
)

調試技巧

• 啟用 Hibernate SQL 日誌：`hibernate.show_sql=true`、`hibernate.format_sql=true`
• 使用 IDE 插件（如 Hibernate Console）驗證 HQL 語法
• 複雜查詢拆解測試：先跑子查詢，再組合主查詢
• 注意實體類名 vs 表名：HQL 操作實體屬性，非數據庫列名

養成格式化寫法 + 分層驗證習慣，可消除 90% 的 HQL 語法異常。