升级Spring 3后JPA查询验证失败的排查方法

1. 排查JPQL基础语法问题 #

• 检查关联/属性名大小写：JPQL对实体属性、关联名称大小写敏感，比如join t.TSA里的TSA要和XXX实体中定义的关联属性名完全匹配（实体中大概率是驼峰tsa）；同理t.VVV、t.Y这些关联属性名也得和实体字段名一致。
• 修正集合空值判断：t.VOI.size = 0不是标准JPQL写法，Spring 3对语法校验更严格，应该改成size(t.VOI) = 0或者t.VOI is empty。
• 检查特殊字段名：t.stu.naù里的特殊字符ù，确认是否和实体中字段名完全一致，是否存在编码导致的解析异常。
• 模糊查询语法：like lower(:search)要注意，JPQL允许这种写法，但如果调用时没给参数加通配符%，逻辑会有问题；另外要确保参数类型和字段类型匹配。

2. 核对版本兼容性 #

• Spring 3必须搭配对应版本的Spring Data JPA（一般是3.x系列），版本不兼容会导致查询解析逻辑异常。
• 检查JPA实现（比如Hibernate）版本：Spring 3对应Hibernate 6.x以上版本，Hibernate 6对JPQL语法校验比旧版本严格很多，之前兼容的非标准写法现在会触发错误。

3. 开启日志定位细节 #

• 在配置文件中添加日志配置，打印JPQL解析过程：

  spring.jpa.show-sql=true
  spring.jpa.properties.hibernate.format_sql=true
  logging.level.org.springframework.data.jpa=DEBUG
  logging.level.org.hibernate.query.hql.internal=DEBUG
  

  通过日志可以直接看到解析失败的具体位置，比如哪一行语法不被允许、哪个关联字段找不到。

4. 分步简化查询验证 #

• 先把查询简化到最基础版本，比如只保留：

  SELECT t FROM XXX t join t.TSA where t.TSA.sta in (:statuses)
  

  验证是否能通过。如果正常，再逐步添加join、or条件、集合判断等逻辑，每次添加后启动验证，快速定位触发错误的代码段。

5. 检查参数绑定与类型匹配 #

• 核对@Param注解参数名和JPQL占位符完全一致，比如@Param("statuses")对应:statuses，避免拼写错误。
• 确认参数类型和实体字段类型匹配：比如timId是BigDecimal，实体中的timId字段类型也必须是BigDecimal；Set<String> statuses和:statuses的集合参数绑定是否符合Spring Data JPA 3.x的要求。

6. 检查关联查询合法性 #

• 确认join t.fun、join t.stu这些内连接的属性，确实是XXX实体中定义的关联（比如@ManyToOne、@OneToOne），不存在的关联会直接导致解析失败。
• 左连接left join t.VVV如果是集合关联（@OneToMany），JPQL语法上允许单纯join，但要确保VVV是实体的合法关联属性。

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