SpringDataJPA系统（3） Defining Query Methods的命名语法与参数

DQM的命名语法与参数

在工作中，你是否经常为方法名的语义、命名规范而发愁？是否要为不同的查询条件写各种的 SQL 语句？是否为同一个实体的查询，写一个超级通用的查询方法或者 SQL？如果其他开发同事不查看你写的 SQL 语句，而直接看方法名的话，却不知道你想查什么而郁闷？

Spring Data JPA 的 Defining Query Methods（DQM）通过方法名和参数，可以很好地解决上面的问题，也能让我们的方法名的语义更加清晰，开发效率也会提升很多。

可以说Spring Data JPA 的最大特色是利用方法名定义查询方法（Defining Query Methods）来做 CRUD 操作。
DQM 语法共有 2 种，可以实现上面的那些问题：

• 一种是直接通过方法名就可以实现
• 另一种是 @Query 手动在方法上定义

定义查询方法的配置和使用方法

若想要实现 CRUD 的操作，常规做法是写一大堆 SQL 语句。但在 JPA 里面，只需要继承 Spring Data Common 里面的任意 Repository 接口或者子接口，然后直接通过方法名就可以实现，神不神奇？

比如我们要增加一个根据Email地址来查询用户，可以在接口中这么写：

然后你不用写具体的实现就可以直接使用该方法来达到根据邮箱地址查询用户的目的了，测试下该方法，完全没问题

方法查询策略设置

在平时的工作中，你可以通过方法名，或者定义方法名上面添加 @Query 注解两种方式来实现 CRUD 的目的，而 Spring 给我们提供了两种切换方式。

在实际生产中还没有遇到要修改默认策略的情况，但我们必须要知道有这样的配置方法，做到心中有数，这样我们才能知道为什么方法名可以，@Query 也可以。

通过 @EnableJpaRepositories 注解来配置方法的查询策略，共有三种方式：

• Create：直接根据方法名进行创建，规则是根据方法名称的构造进行尝试，一般的方法是从方法名中删除给定的一组已知前缀，并解析该方法的其余部分。如果方法名不符合规则，启动的时候会报异常，这种情况可以理解为，即使配置了 @Query 也是没有用的。

• USE_DECLARED_QUERY：声明方式创建，启动的时候会尝试找到一个声明的查询，如果没有找到将抛出一个异常，可以理解为必须配置 @Query。

• CREATE_IF_NOT_FOUND：这个是默认的，除非有特殊需求，可以理解为这是以上 2 种方式的兼容版。先用声明方式（@Query）进行查找，如果没有找到与方法相匹配的查询，那用 Create 的方法名创建规则创建一个查询；这两者都不满足的情况下，启动就会报错。（所以一般用默认就足够了）

DQM语法

该语法是：带查询功能的方法名由查询策略（关键字）+ 查询字段 + 一些限制性条件组成，具有语义清晰、功能完整的特性，我们实际工作中 80% 的 API 查询都可以简单实现。

我们来看一个复杂点的例子，这是一个 and 条件更多、distinct or 排序、忽略大小写的例子。

interface PersonRepository extends Repository<User, Long> {
   // and 的查询关系
   List<User> findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);
   // 包含 distinct 去重，or 的 sql 语法
   List<User> findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
   // 根据 lastname 字段查询忽略大小写
   List<User> findByLastnameIgnoreCase(String lastname);
   // 根据 lastname 和 firstname 查询 equal 并且忽略大小写
   List<User> findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname); 
  // 对查询结果根据 lastname 排序，正序
   List<User> findByLastnameOrderByFirstnameAsc(String lastname);
  // 对查询结果根据 lastname 排序，倒序
   List<User> findByLastnameOrderByFirstnameDesc(String lastname);
}

下面罗列了DMQ里的一些关键字列表：
可以前往官方看更加详细的介绍：https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#jpa.query-methods

• 方法名的表达式通常是实体属性连接运算符的组合，如 And、or、Between、LessThan、GreaterThan、Like 等属性连接运算表达式，不同的数据库（NoSQL、MySQL）可能产生的效果不一样，如果遇到问题，我们可以打开 SQL 日志观察。
• IgnoreCase 可以针对单个属性（如 findByLastnameIgnoreCase(…)），也可以针对查询条件里面所有的实体属性忽略大小写（所有属性必须在 String 情况下，如 findByLastnameAndFirstnameAllIgnoreCase(…)）
• OrderBy 可以在某些属性的排序上提供方向（Asc 或 Desc），称为静态排序，也可以通过一个方便的参数 Sort 实现指定字段的动态排序的查询方法（如 repository.findAll(Sort.by(Sort.Direction.ASC, "myField"))）

分页与排序

Spring Data JPA 为了方便我们排序和分页，支持了两个特殊类型的参数：Sort 和 Pageable。

Sort 在查询的时候可以实现动态排序

Sort 里面的dierection决定了我们哪些字段的排序方向（ASC 正序、DESC 倒序）

Pageable 在查询的时候可以实现分页效果和动态排序双重效果，我们看下下面这些例子：

Page<User> findByManagerId(String lastname, Pageable pageable);//根据分页参数查询User，返回一个带分页结果的Page(下一课时详解)对象（方法一）
Slice<User>findByManagerId(String lastname, Pageable pageable);//我们根据分页参数返回一个Slice的user结果（方法二）
List<User> findByManagerId(String lastname, Sort sort);//根据排序结果返回一个List（方法三）
List<User> findByManagerId(String lastname, Pageable pageable);//根据分页参数返回一个List对象（方法四）

• 方法一：允许将 org.springframework.data.domain.Pageable 实例传递给查询方法，将分页参数添加到静态定义的查询中，通过 Page 返回的结果得知可用的元素和页面的总数。这种分页查询方法可能是昂贵的（会默认执行一条 count 的 SQL 语句），所以用的时候要考虑一下使用场景。

• 方法二：返回结果是 Slice，因为只知道是否有下一个 Slice 可用，而不知道 count，所以当查询较大的结果集时，只知道数据是足够的，也就是说用在业务场景中时不用关心一共有多少页。目前项目开发中越来越推荐使用这个。

• 方法三：如果只需要排序，需在 org.springframework.data.domain.Sort 参数中添加一个参数，正如上面看到的，只需返回一个 List 也是有可能的。

• 方法四：排序选项也通过 Pageable 实例处理，在这种情况下，Page 将不会创建构建实际实例所需的附加元数据（即不需要计算和查询分页相关数据），而仅仅用来做限制查询给定范围的实体。

方法二比较实用，下面是它的一个具体实现和测试

限制查询数量

有的时候我们想直接查询前几条数据，也不需要动态排序，那么就可以简单地在方法名字中使用 First 和 Top 关键字，来限制返回条数。
下面是几个方法示例：

User findFirstByOrderByLastnameAsc();
User findTopByOrderByAgeDesc();
List<User> findDistinctUserTop3ByLastname(String lastname, Pageable pageable);
List<User> findFirst10ByLastname(String lastname, Sort sort);
List<User> findTop10ByLastname(String lastname, Pageable pageable);

• 查询方法在使用 First 或 Top 时，数值可以追加到 First 或 Top 后面，指定返回最大结果的大小
• 如果数字被省略，则假设结果大小为 1
• 限制表达式也支持 Distinct 关键字
• 支持将结果包装到 Optional 中
• 如果将 Pageable 作为参数，以 Top 和 First 后面的数字为准，即分页将在限制结果中应用

关于NULL支持

• @NonNullApi：在包级别用于声明参数，以及返回值的默认行为是不接受或产生空值的。
• @NonNull：用于不能为空的参数或返回值（在 @NonNullApi 适用的参数和返回值上不需要）
• @Nullable：用于可以为空的参数或返回值

在资源库的package-info.java文件中加入@NonNullApi注解，表示该模块下返回值不接受或产生空值

当我们查询参数为空或数据库没有数据返回值为空时，则都会抛出异常，下面是测试示例代码

但好像返回值为空抛异常不是很友好，所以我们可以使用Optional来进行返回值包装，如下所示：

原理解析

每个版本更新后可能支持的语法和效果会有所不同，注意看最新的官方文档介绍。我们这里介绍下其简单实现原理。
通过org.springframework.data.repository.query.parser.PartTree 查看相关源码了解其逻辑和处理方法


根据源码我们也可以分析出来，query method 包含其他的表达式，比如 find、count、delete、exist 等关键字在 by 之前通过正则表达式匹配。

由此可知，我们方法中的关键字不是乱填的，是枚举帮我们定义好的。接下来打开枚举类 Type 源码看下，比什么都清楚。
所以知道了这些通过看源码就可以知道框架支持了哪些逻辑关键字，比如 NotIn、Like、In、Exists 等，有的时候比查文档和任何人写的博客都准确、还快。

总结

DQM的命名规范值得我们去借鉴，在我们开发的给一些方法取名字的时候可以按照这个规范去执行，有利于提升方法的表意性。
我们还可以自己定义一个自己的BaseService，声明了常用的CRUD操作。我们也可以建立自己的 PagingAndSortingService、ComplexityService、SampleService 等来划分不同的 service接口，供不同目的 Service 子类继承。

public interface BaseService<T, ID> {
    Class<T> getDomainClass();
    <S extends T> S save(S entity);
    <S extends T> List<S> saveAll(Iterable<S> entities);
    void delete(T entity);
    void deleteById(ID id);
    void deleteAll();
    void deleteAll(Iterable<? extends T> entities);
    void deleteInBatch(Iterable<T> entities);
    void deleteAllInBatch();
    T getOne(ID id);
    <S extends T> Optional<S> findOne(Example<S> example);
    Optional<T> findById(ID id);
    List<T> findAll();
    List<T> findAll(Sort sort);
    Page<T> findAll(Pageable pageable);
    <S extends T> List<S> findAll(Example<S> example);
    <S extends T> List<S> findAll(Example<S> example, Sort sort);
    <S extends T> Page<S> findAll(Example<S> example, Pageable pageable);
    List<T> findAllById(Iterable<ID> ids);
    long count();
    <S extends T> long count(Example<S> example);
    <S extends T> boolean exists(Example<S> example);
    boolean existsById(ID id);
    void flush();
    <S extends T> S saveAndFlush(S entity);
}

下面是对Baseservice的基本实现

public class BaseServiceImpl<T, ID, R extends JpaRepository<T, ID>> implements BaseService<T, ID> {
    private static final Map<Class, Class> DOMAIN_CLASS_CACHE = new ConcurrentHashMap<>();
    private final R repository;
    public BaseServiceImpl(R repository) {
        this.repository = repository;
    }
    @Override
    public Class<T> getDomainClass() {
        Class thisClass = getClass();
        Class<T> domainClass = DOMAIN_CLASS_CACHE.get(thisClass);
        if (Objects.isNull(domainClass)) {
            domainClass = GenericsUtils.getGenericClass(thisClass, 0);
            DOMAIN_CLASS_CACHE.putIfAbsent(thisClass, domainClass);
        }
        return domainClass;
    }
    protected R getRepository() {
        return repository;
    }
    @Override
    public <S extends T> S save(S entity) {
        return repository.save(entity);
    }
    @Override
    public <S extends T> List<S> saveAll(Iterable<S> entities) {
        return repository.saveAll(entities);
    }
    @Override
    public void delete(T entity) {
        repository.delete(entity);
    }
    @Override
    public void deleteById(ID id) {
        repository.deleteById(id);
    }
    @Override
    public void deleteAll() {
        repository.deleteAll();
    }
    @Override
    public void deleteAll(Iterable<? extends T> entities) {
        repository.deleteAll(entities);
    }
    @Override
    public void deleteInBatch(Iterable<T> entities) {
        repository.deleteInBatch(entities);
    }
    @Override
    public void deleteAllInBatch() {
        repository.deleteAllInBatch();
    }
    @Override
    public T getOne(ID id) {
        return repository.getOne(id);
    }
    @Override
    public <S extends T> Optional<S> findOne(Example<S> example) {
        return repository.findOne(example);
    }
    @Override
    public Optional<T> findById(ID id) {
        return repository.findById(id);
    }
    @Override
    public List<T> findAll() {
        return repository.findAll();
    }
    @Override
    public List<T> findAll(Sort sort) {
        return repository.findAll(sort);
    }
    @Override
    public Page<T> findAll(Pageable pageable) {
        return repository.findAll(pageable);
    }

    @Override
    public <S extends T> List<S> findAll(Example<S> example) {
        return repository.findAll(example);
    }
    @Override
    public <S extends T> List<S> findAll(Example<S> example, Sort sort) {
        return repository.findAll(example, sort);
    }

    @Override
    public <S extends T> Page<S> findAll(Example<S> example, Pageable pageable) {
        return repository.findAll(example, pageable);
    }
    @Override
    public List<T> findAllById(Iterable<ID> ids) {
        return repository.findAllById(ids);
    }
    @Override
    public long count() {
        return repository.count();
    }
    @Override
    public <S extends T> long count(Example<S> example) {
        return repository.count(example);
    }
    @Override
    public <S extends T> boolean exists(Example<S> example) {
        return repository.exists(example);
    }
    @Override
    public boolean existsById(ID id) {
        return repository.existsById(id);
    }
    @Override
    public void flush() {
        repository.flush();
    }
    @Override
    public <S extends T> S saveAndFlush(S entity) {
        return repository.saveAndFlush(entity);
    }
}

以上代码就是 BaseService 常用的 CURD 实现代码，我们这里面大部分也是直接调用 Repository 提供的方法。mybatics-plus框架中也实现了基本服务层代码，可以去参考下。