findFirstByOrderByUsernameAsc构建失败，排查是代码还是框架/文档问题

问题背景 #

我在代码中使用findFirstByOrderByUsernameAsc(String username)方法时出现构建失败。官方文档示例写法为User findFirstByOrderByLastnameAsc();。

我的代码 #

Repository层 #

@Repository
public interface UserRepo extends JpaRepository<Users, Integer>{
    // Users findByUsername(String username); // 可构建
    Users findFirstOrderByUsername(String username); // 可构建
    //Users findFirstByOrderByUsername(String username); // 构建失败
    //Users findFirstByOrderByUsernameAsc(String username); // 构建失败
...
}

Service层 #

@Service
public class UserDetailsServices implements UserDetailsService{

    @Autowired
    private UserRepo repo;

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {

        Users userA = repo.findFirstOrderByUsername(username); // 可构建
        //Users userB = repo.findFirstByOrderByUsername(username); // 构建失败
        //Users userC = repo.findFirstByOrderByUsernameAsc(username); // 构建失败
    //...
}

报错信息 #

findFirstByOrderByUsername的报错： #

...Could not create query for public abstract ....model.Users ....repo.UserRepo.findFirstByOrderByUsername(java.lang.String); Reason: Failed to create query for method public abstract ....model.Users ....repo.UserRepo.findFirstByOrderByUsername(java.lang.String); At least 1 parameter(s) provided but only 0 parameter(s) present in query...

findFirstByOrderByUsernameAsc的报错： #

...Could not create query for public abstract ....model.Users ....repo.UserRepo.findFirstByOrderByUsernameAsc(java.lang.String); Reason: Failed to create query for method public abstract ....model.Users ....repo.UserRepo.findFirstByOrderByUsernameAsc(java.lang.String); At least 1 parameter(s) provided but only 0 parameter(s) present in query...

使用版本信息 #

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.4.4</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>
...
<properties>
    <java.version>24</java.version>
</properties>

...

<dependency>
    <groupId>org.mariadb.jdbc</groupId>
    <artifactId>mariadb-java-client</artifactId>
    <version>2.5.2</version>
    <scope>runtime</scope>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
    <version>3.4.4</version>
</dependency>

核心疑问 #

使用findFirstByOrderByUsernameAsc会导致构建失败，请问这是我的代码存在问题，还是Spring Boot、JPA或文档可能存在bug？

解答 #

这是你的代码写法错误，不是框架或文档的bug。

Spring Data JPA的查询方法命名规则中，By关键字是用来分隔查询条件和排序/限制部分的：

• 你写的findFirstByOrderByUsernameAsc(String username)，By后面直接跟了OrderBy，没有指定查询条件字段，框架会认为这个方法不需要参数，但你传入了username参数，所以报错“提供了至少1个参数，但查询中只有0个参数”。
• 能构建的findFirstOrderByUsername(String username)属于侥幸生效，框架错误解析了方法名，把Username当成了查询条件字段，自动生成了where username = ?的查询，但这不符合规范写法。

正确写法分两种情况： #

1. 需要根据username查询并排序：明确指定查询条件字段，再跟排序规则

Users findFirstByUsernameOrderByUsernameAsc(String username);

该方法会生成select ... from users where username = ? order by username asc limit 1的SQL。

2. 不需要参数，只取按username升序的第一条数据：去掉方法参数

Users findFirstByOrderByUsernameAsc();

该方法会生成select ... from users order by username asc limit 1的SQL。

总结：错误根源是混淆了查询条件与排序部分的命名规则，By后必须先指定查询条件字段，再通过OrderBy声明排序逻辑，框架才能正确解析参数与查询条件的对应关系。

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