Spring Boot 3中JPA Specification过滤失效问题排查与解决

核心原因 #

升级到Spring Boot 3.0.1后，JPA生态全面从javax.persistence迁移到jakarta.persistence，你的Specification过滤器失效主要是以下问题导致：

1. Criteria API导入包错误：构建Predicate时仍使用旧的javax.persistence.criteria.*类（如CriteriaBuilder、Root），而非新的jakarta.persistence.criteria.*，导致生成的Predicate无法被Spring Data JPA 3.x正确识别，最终仅生成1=1的占位条件。
2. 隐性编译兼容问题：IDE可能自动导入了旧包，代码编译通过但运行时逻辑不生效——Jakarta和javax的Criteria API是两套独立类，Spring Data JPA 3.x只识别Jakarta版本的API。
3. 实体类元数据异常：如果实体类中残留javax.persistence的注解（如@Entity、@Column），会导致Hibernate无法正确解析实体字段，Criteria API无法定位到title等字段，自然生成不了过滤条件。

修复步骤 #

• 统一替换Criteria相关导入：检查所有Specification实现类，确保导入的是Jakarta包下的类：

  // 正确导入
  import jakarta.persistence.criteria.CriteriaBuilder;
  import jakarta.persistence.criteria.CriteriaQuery;
  import jakarta.persistence.criteria.Predicate;
  import jakarta.persistence.criteria.Root;
  // 移除旧导入
  // import javax.persistence.criteria.*;
  

• 校验实体类注解：确保实体类的所有JPA注解都替换为jakarta.persistence包下的：

  import jakarta.persistence.Entity;
  import jakarta.persistence.Column;
  import jakarta.persistence.Id;
  
  @Entity
  public class Role {
      @Id
      private Long id;
      @Column
      private String title;
      // getter/setter
  }
  

• 调试toPredicate方法：在Specification的toPredicate方法中加日志或断点，确认传入非空过滤参数时，是否正确生成Predicate而非返回null。示例正确实现：

  public class RoleSpecification implements Specification<Role> {
      private final String title;
  
      public RoleSpecification(String title) {
          this.title = title;
      }
  
      @Override
      public Predicate toPredicate(Root<Role> root, CriteriaQuery<?> query, CriteriaBuilder cb) {
          List<Predicate> predicates = new ArrayList<>();
          if (title != null && !title.isEmpty()) {
              predicates.add(cb.like(root.get("title"), "%" + title + "%"));
          }
          return cb.and(predicates.toArray(new Predicate[0]));
      }
  }
  

• 确认依赖版本适配：Spring Boot 3.0.1默认依赖的Spring Data JPA版本为3.0.x，不要手动指定低于3.0的版本，避免API不兼容。

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