Spring Data JPA 的方法命名查询可以显著减少简单 CRUD 之外的查询代码，但它的规则边界需要提前掌握。框架在启动阶段扫描 Repository 接口时，会解析方法名并生成对应的 JPQL 或 SQL 片段，解析失败通常发生在属性路径不匹配、关键字位置错误或参数顺序不一致时。理解这套解析流程，排查问题会容易得多。

一、方法命名查询的解析机制与基础规则

方法命名查询并不是随意拼写就能生效，它遵循一套固定的解析顺序。以 findByLastName 为例，框架会先识别出前缀 find，再识别主题 User，最后把 By 后面的部分当作条件表达式。常见的前缀包括 find、read、query、count、get、exists 和 delete，不同前缀会影响返回类型和底层操作。比如 countByAgeGreaterThan 返回的是 long 类型，existsByLastName 返回的是 boolean，而 deleteByAgeLessThan 执行的是删除操作。

条件表达式的解析方向是从右向左进行的。解析器会先尝试把整个条件部分匹配成一个实体属性，如果匹配不到，再尝试从右向左拆分，寻找可以继续拆分的属性路径。比如 findByAddressZipCode，如果 User 实体中同时存在 addressZipCode 属性和 address.zipCode 嵌套属性，解析器会优先按照实体实际结构选择可匹配的路径。当属性名使用驼峰命名时，这种拆分歧义尤其容易出现。为了避免解析失败，建议在实体中明确字段命名，或者直接使用下划线分隔的命名方式。

参数数量和顺序也必须与方法名中的条件一一对应。下面通过一个简单的实体和 Repository 展示基础规则。

@Entity
public class User {
    @Id
    private Long id;
    private String lastName;
    private String firstName;
    private int age;
    private String email;
    private Address address;
    // 省略 getter/setter
}
public interface UserRepository extends JpaRepository<User, Long> {
    List<User> findByLastName(String lastName);
    User findByEmail(String email);
    long countByAgeGreaterThan(int age);
    boolean existsByLastName(String lastName);
    void deleteByAgeLessThan(int age);
}

这段代码里，findByLastName 会自动生成 where u.lastName = ?1 这样的条件。参数名虽然不会直接影响 SQL，但参数顺序必须与条件顺序完全一致。如果写成 findByLastNameAndAge(String lastName, int age)，那么第一个参数对应 lastName，第二个参数对应 age，框架会根据位置绑定，而不是根据名称绑定。

二、常用条件关键字与组合查询实践

Spring Data JPA 提供了一整套条件关键字，能够覆盖多数简单查询场景。比较类关键字包括 GreaterThan、GreaterThanEqual、LessThan、LessThanEqual、Between；字符串匹配类包括 Like、NotLike、StartingWith、EndingWith、Containing；集合判断类包括 In、NotIn；空值判断可以用 IsNull 和 IsNotNull。这些关键字还可以加上 IgnoreCase 来忽略大小写，比如 findByLastNameIgnoreCase。

And 和 Or 是组合多个条件时最常用的关键字。需要注意的是，Like 和 Containing 的行为有差异：Like 要求调用方自己传入百分号，比如传入 "张%"；而 Containing 会自动在参数前后添加百分号，实现模糊匹配。另外，StartingWith 自动在参数末尾加百分号，EndingWith 则自动在参数开头加百分号。这些细节在测试时经常被忽略，导致查询结果为空。

下面是一组更完整的组合查询示例，包含排序、分页和去重。

public interface UserRepository extends JpaRepository<User, Long> {
    List<User> findByLastNameAndAgeGreaterThanEqual(String lastName, int age);
    List<User> findByFirstNameOrLastNameContainingIgnoreCase(String firstName, String keyword);
    List<User> findByAgeBetweenOrderByAgeAsc(int start, int end);
    List<User> findByLastNameLike(String pattern);
    List<User> findByLastNameStartingWith(String prefix);
    List<User> findByAgeIn(Collection<Integer> ages);
    List<User> findTop3ByLastNameOrderByAgeDesc(String lastName);
    @Query("select distinct u from User u left join fetch u.address where u.lastName = ?1")
    List<User> findWithAddressByLastName(String lastName);
}

其中 findTop3ByLastNameOrderByAgeDesc 表示查询指定姓氏的用户，并按年龄降序排列，只取前三条。类似地，First 和 Top 都可以限制返回数量。分页排序可以直接在方法签名中加入 Pageable 参数，例如 Page<User> findByLastName(String lastName, Pageable pageable)，调用方传入 PageRequest.of(0, 10, Sort.by("age").descending()) 即可获得分页结果。

三、方法名过长后的问题与替代方案

条件一旦超过三个，方法名就会变得非常长，可读性明显下降。例如 findByLastNameAndFirstNameAndAgeGreaterThanAndEmailContaining 这样的方法名不仅难以维护，还容易产生解析歧义。另一个问题是 Or 和 And 混合使用时，方法名表达的优先级可能并不符合业务预期。Spring Data JPA 对条件关键字的解析顺序并不是完全按照自然语言阅读顺序进行，因此在涉及 Or 时建议避免使用命名查询，改用显式的 JPQL 来明确查询逻辑。

当方法名无法满足需求时，最直接的替代方案是 @Query 注解。通过 JPQL 或原生 SQL，可以把查询条件写得非常清晰，而且支持命名参数和位置参数。对于复杂的分组、连接、子查询等情况，@Query 是比长方法名更合适的选择。下面给出一个复杂订单查询示例。

public interface OrderRepository extends JpaRepository<Order, Long> {
    @Query("select o from Order o where o.status = :status and (o.amount > :minAmount or o.priority = :priority) order by o.createdAt desc")
    List<Order> findHighValueOrders(@Param("status") String status,
                                     @Param("minAmount") BigDecimal minAmount,
                                     @Param("priority") int priority);
    @Query(value = "select * from orders where status = ?1 and amount > ?2", nativeQuery = true)
    List<Order> findNativeOrders(String status, BigDecimal amount);
}

使用 @Query 时要注意，JPQL 中的实体名和属性名必须与实体类名称和字段名称保持一致，而不是数据库表名和列名。如果使用原生 SQL，则需要设置 nativeQuery = true，并且列名要对应数据库中的实际列名。命名参数通过 @Param 注解绑定，位置参数则使用问号加索引的方式进行绑定。

四、用 Specification 和 QueryDSL 构建复杂动态查询

方法命名查询适合固定的条件组合，@Query 适合静态但较复杂的查询，而真正需要根据前端传参动态拼接条件的场景，更适合使用 Specification。JPA 的 Specification 接口通过 toPredicate 方法构建动态条件，可以配合 CriteriaBuilder 灵活组合 and、or、like、greaterThan 等条件。这样既能避免长方法名，又能保持查询逻辑清晰。

下面是一个基于 Specification 的动态查询构建示例。每个条件都可以独立判断是否需要加入，多个条件之间也可以自由组合。

public class UserSpecifications {
    public static Specification<User> lastNameLike(String keyword) {
        return (root, query, cb) -> cb.like(root.get("lastName"), "%" + keyword + "%");
    }
    public static Specification<User> ageGreaterThan(int age) {
        return (root, query, cb) -> cb.greaterThan(root.get("age"), age);
    }
    public static Specification<User> addressCity(String city) {
        return (root, query, cb) -> cb.equal(root.get("address").get("city"), city);
    }
}
// 使用
Specification<User> spec = Specification.where(UserSpecifications.lastNameLike("张"))
        .and(UserSpecifications.ageGreaterThan(20));
List<User> users = userRepository.findAll(spec);

Specification 的优势是条件可以根据业务参数动态决定是否生效，比如搜索框中用户没有填写年龄时，就不拼接年龄条件。它的缺点是属性名仍然使用字符串表示，拼写错误只有在运行时才会暴露。

如果项目对类型安全要求较高，可以引入 QueryDSL。QueryDSL 会生成 QUser 这样的查询元数据类，属性访问通过生成的方法完成，编译期就能发现字段名错误。下面是一个 QueryDSL 的典型用法。

QUser user = QUser.user;
JPAQueryFactory queryFactory = new JPAQueryFactory(entityManager);
List<User> result = queryFactory.selectFrom(user)
        .where(user.lastName.like("%张%")
                .and(user.age.gt(20))
                .and(user.address.city.eq("上海")))
        .orderBy(user.age.desc())
        .offset(0)
        .limit(10)
        .fetch();

QueryDSL 的查询结构非常接近 SQL，但又具备 Java 的编译期检查能力。对于经常变动、条件较多的后台管理查询，使用 QueryDSL 可以显著降低低级错误。不过引入 QueryDSL 需要额外的注解处理器和构建配置，项目初期需要评估维护成本。

五、命名查询与复杂查询的取舍建议

从实际项目经验来看，方法命名查询最适合条件数量在三个以内、查询维度固定且不需要动态拼接的小型查询。它的价值在于零注解、零 SQL，仅靠接口声明就能完成数据访问。当条件增加、出现 Or 逻辑或者涉及关联查询时，就应该升级为 @Query。如果查询条件完全依赖前端传入的筛选表单，则优先考虑 Specification 或 QueryDSL。

这几种方式并不是互斥的，同一个 Repository 中可以同时存在方法命名查询、@Query 查询和继承自 JpaSpecificationExecutor 的动态查询。关键是把简单逻辑留给框架推导，把复杂逻辑控制在自己手中。通过合理划分，不仅代码更清晰，排查问题的成本也会大幅降低。