本文介绍使用 JPQL @Query 结合占位符条件（?1 is null or ...）实现多可选字段的动态分页查询，避免冗长的 if-else 组合，兼顾可读性、可维护性与数据库性能。
本文介绍使用 jpql `@query` 结合占位符条件（`?1 is null or ...`）实现多可选字段的动态分页查询，避免冗长的 if-else 组合，兼顾可读性、可维护性与数据库性能。
在 Spring Data JPA 开发中，面对含多个可选搜索条件（如 cityId、type、status、minPrice、maxPrice 等）的分页接口，若沿用传统 if-else 分支判断 + 多个 Repository 方法的方式，不仅代码急剧膨胀（n 个字段将导致 2ⁿ 种组合），还严重损害可维护性与扩展性。更优解是采用单一条带条件过滤的 JPQL 查询，利用数据库原生对 NULL 的短路逻辑，实现“字段非空才参与过滤”的语义。
✅ 推荐方案：JPQL 动态条件查询（推荐）
在 Repository 接口中定义如下 @Query 方法：
@Repository
public interface AdvertSearchRepository extends JpaRepository<AdvertSearch, Long> {
@Query("SELECT a FROM AdvertSearch a " +
"WHERE (:cityId IS NULL OR a.city.id = :cityId) " +
" AND (:type IS NULL OR a.type = :type) " +
" AND (:status IS NULL OR a.status = :status) " +
" AND (:minPrice IS NULL OR a.price >= :minPrice) " +
" AND (:maxPrice IS NULL OR a.price <= :maxPrice)")
Page<AdvertSearch> searchByConditions(
@Param("cityId") Integer cityId,
@Param("type") OfficeType type,
@Param("status") AdvertStatus status,
@Param("minPrice") BigDecimal minPrice,
@Param("maxPrice") BigDecimal maxPrice,
Pageable pageable
);
}? 关键原理：(:param IS NULL OR a.field = :param) 是标准 SQL 短路表达式。当参数为 null 时，前半部分为 true，整个 AND 条件恒成立，该子句不构成实际过滤；仅当参数非空时，后半部分生效，精准匹配字段值。
✅ 使用示例（Service 层）
@Service
public class AdvertSearchService {
public AdvertSearchResponseDto findAdvertSearchAsPage(
AdvertSearchPageRequestDto dto, Pageable pageable) {
Page<AdvertSearch> result = advertSearchRepository.searchByConditions(
dto.getCityId(),
dto.getType(),
dto.getStatus(), // 新增字段，无需新增分支
dto.getMinPrice(),
dto.getMaxPrice(),
pageable
);
return new AdvertSearchResponseDto(result.getContent(), result.getTotalElements());
}
}对应 DTO 可平滑扩展字段，而 Repository 和 Service 层零逻辑修改：
@Data
public class AdvertSearchPageRequestDto {
private Integer cityId;
private OfficeType type;
private AdvertStatus status; // ✅ 新增
private BigDecimal minPrice; // ✅ 新增
private BigDecimal maxPrice; // ✅ 新增
}⚠️ 注意事项与最佳实践
- 性能提示：确保被查询字段（如 city.id, type, price）已建立适当索引，尤其组合查询时考虑复合索引（例如 (type, city_id, price)）。
- NULL 安全性：本方案依赖数据库对 IS NULL 的高效处理，MySQL / PostgreSQL / H2 均完全支持；避免在 WHERE 子句中对字段做函数操作（如 COALESCE(a.city.id, -1) = ?），否则将导致索引失效。
- 类型一致性：确保传入参数类型与实体字段类型严格匹配（如 Integer ↔ Integer，而非 int），否则可能引发 Parameter value [null] did not match expected type 异常。
-
替代方案对比：
- ❌ ExampleMatcher（JPA Example）：对复杂条件（范围查询、关联字段）支持弱，且 Pageable 集成不够直观；
- ❌ Criteria API：类型安全但代码冗长，可读性差，调试成本高；
- ✅ @Query + 命名参数：简洁、可控、易测试、SQL 级别可优化，是中大型项目首选。
✅ 总结
通过 @Query 中 :param IS NULL OR field = :param 模式，可将任意数量的可选字段统一收敛至一个分页查询方法，彻底告别嵌套 if-else。该方案兼具开发效率、运行性能与长期可维护性，是 Spring Data JPA 动态查询场景下的工业级实践标准。
