升级Spring Boot 2.0后原有SQL抛出QuerySyntaxException异常求助

Hey there! Let's break down this issue you're facing after upgrading to Spring Boot 2.0. The key thing to note here is that Spring Boot 2.x ships with Hibernate 5.x (up from Hibernate 4.x in Spring Boot 1.x), and Hibernate 5 has much stricter syntax validation for HQL queries—so queries that slipped through before might now throw this "Invalid path" error.

Here are the most common causes and fixes:

1. 实体属性名与HQL路径大小写不匹配 #

Hibernate 5 enforces exact case matching for entity property names (unlike the more lenient 4.x). If your HQL uses a different case than the actual property in your Java entity, it'll throw this error.

• 错误示例:
  实体类属性是private String userName;，但HQL写的是：

  FROM User u WHERE u.user_name = :username
  

• 正确示例:
  严格匹配实体类中的驼峰属性名：

  FROM User u WHERE u.userName = :username
  

2. 关联实体的路径引用错误 #

如果你的查询涉及关联实体（比如一对多、多对一关系），一定要检查是否使用了父实体中定义的正确关联属性名。

• 错误示例:
  实体Order的关联属性是private Customer buyer;，但HQL写的是：

  FROM Order o WHERE o.customer.id = :customerId
  

• 正确示例:
  使用实体中定义的准确属性名：

  FROM Order o WHERE o.buyer.id = :customerId
  

3. 混淆了数据库列名与实体属性名 #

记住：HQL是面向实体的，不是面向数据库表的。你必须引用Java实体的属性名，而不是底层数据库的列名。Hibernate 5不再容忍这种混用。

• 错误示例:
  数据库列是user_email，但实体属性是userEmail，HQL写的是：

  FROM User u WHERE u.user_email = :email
  

• 正确示例:
  使用实体类的属性名：

  FROM User u WHERE u.userEmail = :email
  

4. 别名使用不当 #

如果在HQL中给实体分配了别名，一定要在引用属性时持续使用该别名。跳过别名或使用错误别名都会触发路径错误。

• 错误示例:

  FROM User WHERE user.name = :name
  

  （这里没有定义别名user，Hibernate无法识别这个路径）
• 正确示例:
  要么正确使用别名，要么完全省略别名：

  FROM User u WHERE u.name = :name
  

  FROM User WHERE name = :name
  

5. 属性名与HQL关键字冲突 #

如果你的实体属性名和HQL关键字重名（比如order、group、select），Hibernate 5会标记为无效。解决方法是用反引号（`）包裹属性名。

• 示例:
  实体有属性private String order;，对应的HQL应写为：

  FROM Order o WHERE o.`order` = :orderValue
  

快速排查小技巧 #

开启Hibernate的查询日志，查看解析后的查询语句。在application.properties中添加以下配置，即可打印HQL和生成的SQL：

logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

这能帮你精准定位路径错误的位置。

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