Spring Boot JPA查询：传入null参数时如何忽略该条件而非匹配null值？

你不想写自定义SQL的话，Spring Data JPA本身提供了几种原生方案来实现动态忽略null参数的查询：

1. 用Specification API（最推荐） #

Specification可以动态拼接查询条件，完全根据参数是否为null来决定是否加入对应条件，灵活性最高。

第一步，让你的Repository继承JpaSpecificationExecutor<Result>：

public interface ResultRepository extends JpaRepository<Result, Long>, JpaSpecificationExecutor<Result> {
}

然后编写查询逻辑：

public List<Result> getResults(String availability, String category, long cursor, Pageable pageable) {
    Specification<Result> spec = (root, query, cb) -> {
        List<Predicate> conditions = new ArrayList<>();
        
        // availability不为null时才加这个条件
        if (availability != null) {
            conditions.add(cb.equal(root.get("availability"), availability));
        }
        // category不为null时才加这个条件
        if (category != null) {
            conditions.add(cb.equal(root.get("itemCategory"), category));
        }
        // 必加的id范围条件
        conditions.add(cb.lessThan(root.get("id"), cursor));
        
        // 设置排序规则
        query.orderBy(cb.desc(root.get("id")));
        
        return cb.and(conditions.toArray(new Predicate[0]));
    };
    
    // 执行分页查询，返回内容列表
    return resultRepository.findAll(spec, pageable).getContent();
}

2. 用Query By Example（QBE） #

QBE是通过创建实体示例来构建查询，默认会自动忽略示例中为null的属性，适合简单的相等条件场景。

注意：QBE不支持范围查询（比如id < cursor），所以需要额外处理这类条件：

public List<Result> getResults(String availability, String category, long cursor, Pageable pageable) {
    // 创建查询示例实体，只设置非null的参数
    Result example = new Result();
    example.setAvailability(availability);
    example.setItemCategory(category);
    
    // 创建匹配器，忽略id字段（因为id要用范围条件）
    ExampleMatcher matcher = ExampleMatcher.matching()
            .withIgnorePaths("id");
    
    Example<Result> queryExample = Example.of(example, matcher);
    
    // 先按示例查询，再过滤id条件并排序
    return resultRepository.findAll(queryExample, pageable)
            .stream()
            .filter(res -> res.getId() < cursor)
            .sorted(Comparator.comparing(Result::getId).reversed())
            .collect(Collectors.toList());
}

3. 全局Null处理配置（谨慎使用） #

从Spring Data JPA 2.0开始，可以通过全局配置让查询方法自动忽略null参数，但这个配置会影响所有查询方法，且对范围条件的支持有限。

首先给方法参数加上@Nullable注解：

Optional<List<Result>> findAllByAvailabilityAndItemCategoryAndIdLessThanOrderByIdDesc(
        @Nullable String availability, 
        @Nullable String category, 
        long cursor, 
        Pageable pageable
);

然后在JPA配置类里设置null处理策略为IGNORE：

@Configuration
public class JpaConfig extends JpaBaseConfiguration {
    @Override
    protected Map<String, Object> getVendorProperties() {
        Map<String, Object> props = new HashMap<>();
        props.put("spring.data.jpa.repository.query.null-handling", "IGNORE");
        return props;
    }

    // 省略其他必要的配置方法...
}

这个方法虽然简单，但全局生效可能带来意想不到的问题，所以更推荐用Specification。

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