如何用Spring JPA基于可选字段实现分页数据过滤？

当可选字段扩展到4-5个时，枚举所有组合显然不现实，以下是三种实用的动态查询方案，均支持Pageable分页：

方案一：Spring Data JPA Specification API（原生支持，无额外依赖） #

这是Spring官方提供的动态查询方式，通过构建Specification对象拼接查询条件，无需额外引入依赖。

实现步骤 #

1. 让Repository同时继承JpaRepository和JpaSpecificationExecutor
2. 在Service层根据DTO的非空字段构建查询条件
3. 调用findAll(Specification, Pageable)完成分页查询

代码示例 #

1. 查询DTO定义

@Data
public class UserQueryDTO {
    private String name;
    private Integer age;
    private String email;
    private String phone;
}

2. Repository接口

public interface UserRepository extends JpaRepository<User, Long>, JpaSpecificationExecutor<User> {
}

3. Service层构建动态查询

@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;

    public Page<User> queryUsers(UserQueryDTO dto, Pageable pageable) {
        Specification<User> spec = (root, query, criteriaBuilder) -> {
            List<Predicate> predicates = new ArrayList<>();
            // 仅拼接非空字段的条件
            if (StringUtils.hasText(dto.getName())) {
                predicates.add(criteriaBuilder.like(root.get("name"), "%" + dto.getName() + "%"));
            }
            if (dto.getAge() != null) {
                predicates.add(criteriaBuilder.equal(root.get("age"), dto.getAge()));
            }
            if (StringUtils.hasText(dto.getEmail())) {
                predicates.add(criteriaBuilder.equal(root.get("email"), dto.getEmail()));
            }
            if (StringUtils.hasText(dto.getPhone())) {
                predicates.add(criteriaBuilder.like(root.get("phone"), "%" + dto.getPhone() + "%"));
            }
            return criteriaBuilder.and(predicates.toArray(new Predicate[0]));
        };
        return userRepository.findAll(spec, pageable);
    }
}

方案二：QueryDSL（类型安全，代码更简洁） #

QueryDSL提供了类型安全的查询构建能力，避免字符串拼接的语法错误，代码可读性更高，适合字段较多的场景。

实现步骤 #

1. 引入QueryDSL依赖和APT插件（用于生成实体类对应的Q查询模型）
2. Repository继承QuerydslPredicateExecutor
3. 使用自动生成的Q类构建动态查询条件

代码示例 #

1. Maven依赖与插件配置

<!-- QueryDSL核心依赖 -->
<dependency>
    <groupId>com.querydsl</groupId>
    <artifactId>querydsl-jpa</artifactId>
</dependency>
<!-- APT插件：生成Q类 -->
<dependency>
    <groupId>com.querydsl</groupId>
    <artifactId>querydsl-apt</artifactId>
    <scope>provided</scope>
</dependency>

<build>
    <plugins>
        <plugin>
            <groupId>com.mysema.maven</groupId>
            <artifactId>apt-maven-plugin</artifactId>
            <version>1.1.3</version>
            <executions>
                <execution>
                    <goals>
                        <goal>process</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>target/generated-sources/java</outputDirectory>
                        <processor>com.querydsl.apt.jpa.JPAAnnotationProcessor</processor>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2. Repository接口

public interface UserRepository extends JpaRepository<User, Long>, QuerydslPredicateExecutor<User> {
}

3. Service层构建动态查询

@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;
    // 自动生成的Q类，对应User实体
    private static final QUser qUser = QUser.user;

    public Page<User> queryUsers(UserQueryDTO dto, Pageable pageable) {
        BooleanBuilder builder = new BooleanBuilder();
        // 非空字段才加入查询条件
        if (StringUtils.hasText(dto.getName())) {
            builder.and(qUser.name.like("%" + dto.getName() + "%"));
        }
        if (dto.getAge() != null) {
            builder.and(qUser.age.eq(dto.getAge()));
        }
        if (StringUtils.hasText(dto.getEmail())) {
            builder.and(qUser.email.eq(dto.getEmail()));
        }
        if (StringUtils.hasText(dto.getPhone())) {
            builder.and(qUser.phone.like("%" + dto.getPhone() + "%"));
        }
        return userRepository.findAll(builder, pageable);
    }
}

方案三：自定义动态JPQL拼接（灵活但需注意安全） #

如果熟悉JPQL语法，可以手动拼接查询语句，通过参数绑定避免SQL注入，适合字段数量适中的场景。

代码示例 #

1. Repository接口

public interface UserRepository extends JpaRepository<User, Long> {
    @Query("SELECT u FROM User u WHERE 1=1 " +
            "AND (:name IS NULL OR u.name LIKE %:name%) " +
            "AND (:age IS NULL OR u.age = :age) " +
            "AND (:email IS NULL OR u.email = :email) " +
            "AND (:phone IS NULL OR u.phone LIKE %:phone%)")
    Page<User> queryUsers(@Param("name") String name,
                          @Param("age") Integer age,
                          @Param("email") String email,
                          @Param("phone") String phone,
                          Pageable pageable);
}

2. Service层调用

@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;

    public Page<User> queryUsers(UserQueryDTO dto, Pageable pageable) {
        return userRepository.queryUsers(
                StringUtils.hasText(dto.getName()) ? dto.getName() : null,
                dto.getAge(),
                StringUtils.hasText(dto.getEmail()) ? dto.getEmail() : null,
                StringUtils.hasText(dto.getPhone()) ? dto.getPhone() : null,
                pageable
        );
    }
}

方案对比 #

根据你的场景，优先推荐QueryDSL或Specification API，两者都能轻松应对4-5个可选字段的动态查询，且完美支持Pageable分页。

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