Spring Data JPA基于CrudRepository编写自定义查询报启动异常

报错核心原因 #

当前@Query注解的语法不符合Spring Data JPA的解析规则，@Query默认采用JPQL查询语言，操作对象是JPA实体类，而非数据库原生表。原有代码中写的FROM song_list是数据库表名，不符合JPQL语法要求，导致启动时查询校验失败，最终引发Bean创建异常。

修正方案 #

按照使用场景分两种合规写法：

1. 推荐写法：标准JPQL查询 #

将语句中数据库表名替换为对应的实体类类名，保持和原有实体定义的属性映射规则一致：

@Repository
public interface SongListRepository extends CrudRepository<SongList, Integer> {
    // FROM 后替换为实体类名 SongList，而非数据库表名 song_list
    @Query("SELECT sl FROM SongList sl WHERE sl.owner = :owner")
    Set<SongList> findAllSongListsForUser(@Param("owner") String owner);
}

注意：JPQL为大小写敏感语法，实体类名、实体类属性名需要和代码中的定义完全匹配。

2. 特殊场景：原生SQL查询 #

如果需要使用数据库专属的复杂语法、必须直接操作数据库表，需要显式开启原生查询开关，此时才允许直接使用数据库表名、列名：

@Repository
public interface SongListRepository extends CrudRepository<SongList, Integer> {
    // 新增 nativeQuery = true 标记为原生SQL模式
    @Query(value = "SELECT * FROM song_list sl WHERE sl.owner = :owner", nativeQuery = true)
    Set<SongList> findAllSongListsForUser(@Param("owner") String owner);
}

其他优化与踩坑提示 #

• 对于这类简单的等值查询，可以直接使用Spring Data JPA的方法命名规则生成查询语句，无需手写@Query，比如直接定义方法Set<SongList> findAllByOwner(String owner);即可实现相同功能，减少手写SQL的校验错误概率
• 确认对应的SongList类已添加@Entity注解，完成JPA实体映射
• 检查JPQL中的参数绑定：@Param("owner")的参数名需要和语句中:owner的标识完全一致，不能存在拼写偏差
• 如果实体类的字段和数据库列名通过@Column做了映射，JPQL中一律使用实体类的属性名，而非数据库列名

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