如何基于JPA Specification实现动态日期范围查询（支持单日期可选）

原有代码核心问题 #

• 错误使用字符串匹配操作符like处理日期类型字段的比较逻辑，日期范围筛选应使用大于/小于/区间匹配逻辑
• 完全误用Specification机制：将Specification对象直接作为日期参数传入HQL，Specification是动态构造查询条件的工具，并非参数载体
• 未处理三种日期传参场景，原有逻辑无论传入开始还是结束日期，都只匹配startDate字段，逻辑完全错误
• 空判断使用了单管道|而非短路或||，会引发空指针风险

推荐实现（基于Spring Data JPA 标准Specification机制） #

1. 调整Repository定义 #

让你的BillingSummary Repository 继承JpaSpecificationExecutor接口，即可直接使用自带的Specification查询能力，无需手动编写HQL：

public interface BillingSummaryRepository extends JpaRepository<BillingSummary, Long>, JpaSpecificationExecutor<BillingSummary> {
    // 无需自定义查询方法，JpaSpecificationExecutor已内置findAll(Specification<T> spec)方法
}

2. 编写正确的Specification构造逻辑 #

按三种传参场景分别构造筛选条件：

public List<BillingSummaryFullDTO> findBillingInvoicesSummary(BillingSummarySearchParams params) {
    Specification<BillingSummary> spec = (root, query, cb) -> {
        List<Predicate> predicates = new ArrayList<>();
        // 仅传开始日期：筛选创建时间大于等于开始日期的记录
        if (params.getStartDate() != null) {
            predicates.add(cb.greaterThanOrEqualTo(root.get("createdAt"), params.getStartDate()));
        }
        // 仅传结束日期：筛选创建时间小于等于结束日期的记录
        if (params.getEndDate() != null) {
            predicates.add(cb.lessThanOrEqualTo(root.get("createdAt"), params.getEndDate()));
        }
        // 两个日期都传的场景会自动合并为区间筛选
        return cb.and(predicates.toArray(new Predicate[0]));
    };
    // 直接调用Repository内置方法执行查询
    return billingSummaryRepository.findAll(spec)
            .stream()
            .map(billingSummaryMapper::toFullDTO)
            .collect(Collectors.toList());
}

自定义HQL实现方案（不使用Specification） #

如果需要自行编写HQL实现，无需引入Specification，直接根据参数动态拼接查询语句即可：

public List<BillingSummary> findBillingSummaryByParams(BillingSummarySearchParams params) {
    StringBuilder hqlBuilder = new StringBuilder("select e from BillingSummary e where 1=1 ");
    Map<String, Object> paramMap = new HashMap<>();

    if (params.getStartDate() != null) {
        hqlBuilder.append("and e.createdAt >= :startDate ");
        paramMap.put("startDate", params.getStartDate());
    }
    if (params.getEndDate() != null) {
        hqlBuilder.append("and e.createdAt <= :endDate ");
        paramMap.put("endDate", params.getEndDate());
    }
    hqlBuilder.append("order by e.createdAt desc");

    TypedQuery<BillingSummary> query = entityManager.createQuery(hqlBuilder.toString(), BillingSummary.class);
    for (Map.Entry<String, Object> entry : paramMap.entrySet()) {
        query.setParameter(entry.getKey(), entry.getValue());
    }
    return query.getResultList();
}

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