Java 后端 / 知识点

Spring Boot 开发速查手册

手册条目

读取分页、筛选和排序等查询字符串参数。

接收查询参数

用于读取 URL 中 ?page=2&size=10&keyword=book 这类查询参数。参数较少时优先使用 @RequestParam;参数较多时可封装为查询对象,避免控制器方法过长。

基本语法

@RequestParam 用于把查询字符串绑定到方法参数。生产代码建议显式指定参数名,避免依赖编译后的 Java 参数名。

写法 行为
@RequestParam("page") int page 必传;缺失或无法转换为整数时返回 400
@RequestParam(defaultValue = "20") int size 缺失时使用默认值,不再视为必传
@RequestParam(required = false) String keyword 可选;缺失时为 null
@RequestParam("tag") List<String> tags 接收重复参数,如 ?tag=java&tag=spring

主示例

下面的示例接收页码、每页数量、关键字和排序规则,并限制分页边界,避免一次请求拉取过多数据。

java
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;

@SpringBootApplication
public class QueryParamApplication {

    public static void main(String[] args) {
        SpringApplication.run(QueryParamApplication.class, args);
    }

    @RestController
    static class ProductController {

        @GetMapping("/api/products")
        QueryResult list(
                @RequestParam(name = "page", defaultValue = "1") int page,
                @RequestParam(name = "size", defaultValue = "20") int size,
                @RequestParam(name = "keyword", required = false) String keyword,
                @RequestParam(name = "sort", defaultValue = "createdAt,desc") String sort) {

            // 限制分页参数,避免非法值直接进入数据库查询。
            if (page < 1 || size < 1 || size > 100) {
                throw new ResponseStatusException(
                        HttpStatus.BAD_REQUEST,
                        "page must be >= 1 and size must be between 1 and 100"
                );
            }
            return new QueryResult(page, size, keyword, sort);
        }
    }

    record QueryResult(int page, int size, String keyword, String sort) {
    }
}

预期结果:应用启动后,GET /api/products 可以访问;缺少 page、size 或 sort 时分别使用 1、20 和 createdAt,desc。

bash
curl 'http://localhost:8080/api/products?page=2&size=10&keyword=book&sort=price,asc'

预期输出:

json
{"page":2,"size":10,"keyword":"book","sort":"price,asc"}

读取方法:page 和 size 控制分页,keyword 用于筛选,sort 可在服务层拆成字段与方向。命令中的 URL 使用单引号包裹,可避免 Shell 把 & 解释为后台执行符。

高频用法

当参数超过约 5 个时,可以定义 ProductQuery 并使用 @ModelAttribute ProductQuery query 自动绑定同名查询参数。日期、枚举等类型建议配合 @DateTimeFormat 或自定义 Converter,不要在控制器中手工解析字符串。

多值筛选可使用重复参数,例如 ?status=PAID&status=REFUNDED,对应 @RequestParam("status") List<String> statuses。是否支持逗号拆分应由接口契约明确约定,不要依赖客户端的隐式行为。

风险与边界

未限制 size 时,大结果集请求可能导致数据库慢查询、内存上涨或接口超时。安全做法是设置默认值和最大值,并在数据访问层继续使用分页查询。

不要把外部传入的排序字段直接拼入 SQL。应将字段映射到固定白名单,例如只允许 createdAt、price,方向只允许 asc、desc,再交给 ORM 或查询构造器处理。

排障清单

出现 400 时先检查参数是否缺失、名称是否一致,以及数字或日期格式是否可转换。参数始终为 null 时,确认请求使用的是 URL 查询字符串,而不是 JSON 请求体。

筛选未生效时,检查控制器是否把参数继续传到服务层,以及空字符串是否需要归一化为 null。分页异常时,再确认前端页码约定是从 0 开始还是从 1 开始。

目录与阅读设置

记录一个想法

Spring Boot 开发速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通