Spring Data JPA Repository自定义@Query查询非法参数异常问题

报错根因 #

你遇到的Validation failed for query异常，是应用启动阶段框架校验自定义JPQL语句时直接抛出的，根本走不到数据库执行环节。
你写的查询语句存在JPQL硬伤：

• JPQL的语法规则要求，查询实体时必须给实体指定别名，引用实体属性时只能通过别名关联，不允许直接拿实体类名当前缀拼接属性。你原语句里直接写Student.groupId、Student.studentLogin的形式，会导致框架解析属性映射时完全找不到对应关系，直接触发校验拦截。

正确改写方式 #

给Student实体加简短别名，所有属性引用都通过别名关联，推荐用可读性更好的命名参数替代无意义的位置占位符，改写后的代码：

@Query("SELECT s.groupId FROM Student s WHERE s.studentLogin = :studentLogin")
Integer getGroupIdByStudentLogin(String studentLogin);

如果习惯用位置参数的写法，合法的语句形式为：

@Query("SELECT s.groupId FROM Student s WHERE s.studentLogin = ?1")
Integer getGroupIdByStudentLogin(String studentLogin);

容易忽略的排查细节 #

• 确认导入的@Query注解是Spring Data JPA提供的注解，没有误引入其他框架的同名注解
• 确认SELECT里的groupId、WHERE条件里的studentLogin是Student实体类真实定义的属性名，不是数据库表的列名——JPQL只识别实体属性，原生SQL才需要写数据库列名
• 确认方法返回值和实体中groupId的属性类型完全匹配，如果实体里groupId是Long类型，需要把方法返回值同步改成Long，避免语法校验通过后抛类型转换异常
• 如果实体类通过@Entity注解自定义了实体名，要确认JPQL里写的Student和自定义的实体名完全一致，不存在不匹配的情况

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