如何使用Quarkus Panache构建依赖可选字段的动态查询

基础实体定义 #

按照Panache的简化编程规范定义Customer实体，消除冗余的样板代码：

@Entity
public class Customer extends PanacheEntity {
    // 直接用public修饰字段，无需手动编写getter/setter
    public String firstname;
    public String lastname;
    public String status;
    public String email;
}

核心实现逻辑 #

最优实现路径是使用Panache原生提供的类型安全Criteria API构建动态条件，完全替代手动拼接HQL字符串的传统方式，从根源上规避SQL注入、语法拼接错误、运行时字段校验失效等问题。
具体方法实现如下：

import io.quarkus.hibernate.orm.panache.PanacheEntity;
import io.quarkus.hibernate.orm.panache.PanachePredicate;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.List;

// 静态导入Panache的通用查询方法
import static io.quarkus.hibernate.orm.panache.Panache.*;

@ApplicationScoped
public class CustomerQueryService {

    public List<Customer> getCustomers(String firstname, String lastname, String status, String email) {
        // 初始化空的查询条件容器
        PanachePredicate combinedCondition = null;

        // 逐字段校验参数有效性，追加对应匹配规则
        if (isEffective(firstname)) {
            combinedCondition = appendCondition(combinedCondition, Customer.firstname.eq(firstname));
        }
        if (isEffective(lastname)) {
            combinedCondition = appendCondition(combinedCondition, Customer.lastname.eq(lastname));
        }
        if (isEffective(status)) {
            combinedCondition = appendCondition(combinedCondition, Customer.status.eq(status));
        }
        if (isEffective(email)) {
            combinedCondition = appendCondition(combinedCondition, Customer.email.eq(email));
        }

        // 无有效参数时返回全量数据，有匹配条件时按规则检索
        return combinedCondition == null
            ? listAll(Customer.class)
            : list(Customer.class, combinedCondition);
    }

    // 统一判断参数是否为业务认可的有效值（非null、非纯空白字符）
    private boolean isEffective(String param) {
        return param != null && !param.trim().isEmpty();
    }

    // 工具方法：按逻辑与拼接多条件
    private PanachePredicate appendCondition(PanachePredicate existing, PanachePredicate newCondition) {
        return existing == null ? newCondition : existing.and(newCondition);
    }
}

方案优势 #

• 完全匹配业务规则：所有传入参数校验通过才会作为匹配条件，所有参数无效时直接返回全量记录，无额外冗余逻辑
• 类型安全：所有字段引用都直接绑定实体属性，编译期就能校验字段拼写是否正确，不需要等到运行时才抛出查询异常
• 无注入风险：Criteria API会自动处理参数绑定和转义，不会出现手动拼接字符串带来的SQL注入问题
• 易扩展：后续如果需要调整匹配规则（比如改成模糊匹配、范围匹配），只需要修改对应字段的条件构建逻辑，不需要改动整体的查询流程

常见反模式规避 #

• 不要手动拼接HQL字符串：比如通过字符串拼接把参数值直接嵌入查询语句，不仅容易出现语法错误（比如多拼接了and关键字），还存在明确的SQL注入风险
• 不要给空参数拼接默认匹配条件：比如参数为空时不要拼接email = ''这类条件，否则会和业务规则中“参数无效不参与匹配”的要求冲突

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