如何在JPA Repository中使用ExampleMatcher实现多列空值过滤？

一、先明确ExampleMatcher的局限及PropertyValueTransformer的作用 #

ExampleMatcher核心是基于实体对象的属性值生成匹配条件，原生无法直接生成IS NULL/IS NOT NULL的动态条件——因为当实体属性为null时，默认会被忽略；而withIncludeNullValues()也只是基于实体属性本身的null值生成IS NULL条件，无法根据外部参数（比如你的flag）动态切换。

至于PropertyValueTransformer的withTransformer()方法，它的作用是转换属性值后再进行匹配，比如把输入的"abc"转成"ABC"再做模糊匹配，示例代码如下：

ExampleMatcher matcher = ExampleMatcher.matching()
    .withMatcher("username", ExampleMatcher.GenericPropertyMatcher.of()
        .withTransformer(value -> value.map(String::toUpperCase)));

但它无法生成IS NULL/IS NOT NULL这类无值匹配的SQL条件，所以不适合你的场景。

二、推荐解决方案：Specification + Example 组合 #

这种方式既能利用Example快速处理普通过滤列（比如你的4个分页过滤列），又能通过Specification动态生成null/非null条件，彻底避免大量if-else。

1. 封装通用的Null/非Null条件生成方法 #

写一个可复用的Specification工具方法，根据flag生成对应列的约束：

private <T> Specification<T> buildNullCheckSpec(String columnName, Integer flag) {
    return (root, query, cb) -> {
        if (flag == null) {
            return cb.conjunction(); // 无约束，等价于查询全部
        } else if (flag == 0) {
            return cb.isNull(root.get(columnName));
        } else if (flag == 1) {
            return cb.isNotNull(root.get(columnName));
        }
        return cb.conjunction();
    };
}

2. 结合Example处理普通过滤列 #

用Example处理你的4个分页过滤列（比如等于、模糊匹配等常规条件），Example会自动忽略null属性，无需额外判断：

// 假设filterEntity是携带过滤条件的实体对象，比如包含column1、column2等4个过滤列
Example<YourEntity> filterExample = Example.of(filterEntity, ExampleMatcher.matching()
    .withIgnoreCase() // 按需配置忽略大小写
    .withStringMatcher(ExampleMatcher.StringMatcher.CONTAINING) // 按需配置模糊匹配规则
    .withIgnoreNullValues());

// 将Example转换为Specification
Specification<YourEntity> filterSpec = ExampleSpecification.of(filterExample);

3. 组合所有条件并执行分页查询 #

把普通过滤条件和null检查条件组合，调用Repository的分页方法：

// 生成目标列的null检查条件
Specification<YourEntity> nullCheckSpec = buildNullCheckSpec("targetColumn", flag);

// 组合所有条件
Specification<YourEntity> finalSpec = filterSpec.and(nullCheckSpec);

// 执行分页查询
Page<YourEntity> resultPage = yourJpaRepository.findAll(finalSpec, pageable);

4. 多列需处理null/非null的扩展 #

如果你的4个分页过滤列也需要类似的flag逻辑，只需重复调用buildNullCheckSpec方法并组合即可：

Specification<YourEntity> spec1 = buildNullCheckSpec("column1", flag1);
Specification<YourEntity> spec2 = buildNullCheckSpec("column2", flag2);
Specification<YourEntity> spec3 = buildNullCheckSpec("column3", flag3);
Specification<YourEntity> spec4 = buildNullCheckSpec("column4", flag4);

Specification<YourEntity> finalSpec = filterSpec.and(spec1).and(spec2).and(spec3).and(spec4);

三、方案优势 #

• 彻底避免大量if-else分支，代码简洁可维护；
• Example负责常规过滤逻辑，Specification负责动态null约束，职责清晰；
• 通用方法可复用，新增需处理null的列时只需一行代码调用。

内容的提问来源于stack exchange，提问作者monika-dzidic