Spring JPA Query By Example全空探针场景下返回错误的实现方案

Spring Data JPA的Query By Example（QBE）本身没有内置配置项来拦截全空探针的情况，但可以通过以下几种方式实现你需要的错误返回或降级逻辑：

1. 前置校验探针状态 #

在调用QBE查询前，手动检查探针对象的所有属性是否均为null，触发自定义逻辑：

// 工具方法：判断对象所有属性是否为null
private boolean isAllPropertiesNull(Object probe) {
    for (Field field : probe.getClass().getDeclaredFields()) {
        field.setAccessible(true);
        try {
            if (field.get(probe) != null) {
                return false;
            }
        } catch (IllegalAccessException e) {
            throw new RuntimeException("Failed to check probe properties", e);
        }
    }
    return true;
}

// 业务代码中调用
public List<YourEntity> filterEntities(YourEntity probe) {
    if (isAllPropertiesNull(probe)) {
        // 方案1：抛出自定义异常返回错误
        throw new IllegalArgumentException("At least one filter condition is required");
        // 方案2：降级返回空列表
        // return Collections.emptyList();
    }
    Example<YourEntity> example = Example.of(probe);
    return yourRepository.findAll(example);
}

注意：如果实体包含继承关系或嵌套对象，需要递归检查嵌套属性；也可以借助BeanUtils等工具库简化属性遍历逻辑。

2. 扩展QueryByExampleExecutor自定义查询逻辑 #

自定义Repository实现类，重写findAll(Example)方法，加入全空探针的判断：

@Repository
public class YourEntityRepositoryImpl implements YourEntityRepositoryCustom {

    @Autowired
    private EntityManager entityManager;

    @Override
    public List<YourEntity> findAll(Example<YourEntity> example) {
        YourEntity probe = example.getProbe();
        if (isAllPropertiesNull(probe)) {
            throw new IllegalArgumentException("No filter conditions specified");
        }
        // 执行原生QBE查询逻辑
        CriteriaBuilder cb = entityManager.getCriteriaBuilder();
        CriteriaQuery<YourEntity> cq = cb.createQuery(YourEntity.class);
        Root<YourEntity> root = cq.from(YourEntity.class);
        Predicate predicate = ExampleMatcherAccessor.getPredicate(root, cb, example);
        cq.where(predicate);
        return entityManager.createQuery(cq).getResultList();
    }

    // 复用前面的isAllPropertiesNull方法
}

让你的Repository接口同时继承自定义的YourEntityRepositoryCustom和JpaRepository/QueryByExampleExecutor即可生效。

3. 利用Spring AOP全局拦截QBE查询 #

通过AOP拦截所有Repository的findAll(Example)方法，在执行前统一校验探针：

@Aspect
@Component
public class ExampleQueryAspect {

    @Before("execution(* org.springframework.data.repository.query.QueryByExampleExecutor.findAll(..)) && args(example)")
    public void beforeFindAllWithExample(Example<?> example) {
        Object probe = example.getProbe();
        if (isAllPropertiesNull(probe)) {
            throw new IllegalArgumentException("Filter conditions cannot be all null");
        }
    }

    // 复用isAllPropertiesNull方法
}

这种方式无需修改Repository代码，适合全局统一处理所有QBE查询场景。

额外注意 #

• 对于基本类型（如int默认0），需要在isAllPropertiesNull中区分是用户主动设置的默认值还是未赋值，可结合ExampleMatcher的忽略规则做判断。
• 降级操作可根据业务需求灵活选择，比如返回空列表、抛出业务异常或返回特定提示，无需依赖分页或必填字段限制。

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