ps：如果这篇帖子对于还在找工作和找实习的你有所帮助，可以关注我，给本贴点赞、评论、收藏并订阅专栏；同时不要吝啬您的花花

Spring Web核心请求注解详解：@PathVariable、@RequestParam、@RequestHeader

在Spring MVC/Spring Boot开发中，@PathVariable、@RequestParam、@RequestHeader是接收前端请求参数的三大核心注解，三者均用于提取HTTP请求中的数据，但参数来源、使用场景、语法规则完全不同。本文将逐一拆解用法、实战示例、配置细节，并梳理核心区别，兼顾基础入门与工程实战。

一、@PathVariable：获取URI路径变量

1. 核心定位

用于提取URL路径中的占位符参数，是RESTful API设计的标配注解，适用于资源定位类接口（如查询、删除、修改指定ID资源）。参数直接嵌入URI路径，而非拼接在URL后缀。

2. 基础语法与实战示例

语法规则：在@RequestMapping/@GetMapping等请求映射注解中定义占位符{变量名}，通过@PathVariable绑定同名方法参数。

@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 单路径变量：查询指定ID的用户
     * URL示例：http://localhost:8080/user/1001
     */
    @GetMapping("/{userId}")
    public String getUserById(@PathVariable Long userId) {
        return "查询用户ID：" + userId;
    }

    /**
     * 多路径变量+别名配置
     * URL示例：http://localhost:8080/user/1001/order/2024
     */
    @GetMapping("/{uid}/order/{orderId}")
    public String getUserOrder(
            // 别名绑定：路径占位符uid对应方法参数userId
            @PathVariable("uid") Long userId,
            @PathVariable Long orderId
    ) {
        return "用户ID：" + userId + "，订单ID：" + orderId;
    }
}

3. 关键配置项

• required：默认true，路径中必须包含该占位符，否则报404错误；设为false可实现可选路径变量（需配合null判断）
• value/name：指定路径占位符名称，用于方法参数名与占位符名不一致的场景
• 不支持默认值：路径变量不存在时直接抛出异常，无法设置defaultValue

二、@RequestParam：获取URL请求参数

1. 核心定位

用于提取URL查询参数（?key=value）或表单提交参数（application/x-www-form-urlencoded），适用于普通查询、筛选、分页类接口，是最常用的请求参数注解。

2. 基础语法与实战示例

语法规则：参数拼接在URL?后，通过@RequestParam绑定键值对，支持单值、多值、默认值配置。

@RestController
@RequestMapping("/goods")
public class GoodsController {

    /**
     * 单请求参数：查询指定名称的商品
     * URL示例：http://localhost:8080/goods/search?name=手机
     */
    @GetMapping("/search")
    public String searchGoods(@RequestParam String name) {
        return "搜索商品：" + name;
    }

    /**
     * 多参数+必填校验+默认值
     * URL示例：http://localhost:8080/goods/list?pageNum=1&pageSize=10
     * 缺省pageSize时，自动使用默认值10
     */
    @GetMapping("/list")
    public String getGoodsList(
            @RequestParam Integer pageNum,
            // 非必填+默认值配置
            @RequestParam(required = false, defaultValue = "10") Integer pageSize
    ) {
        return "页码：" + pageNum + "，每页条数：" + pageSize;
    }

    /**
     * 多值参数：接收数组/集合
     * URL示例：http://localhost:8080/goods/ids?ids=1,2,3
     */
    @GetMapping("/ids")
    public String getGoodsByIds(@RequestParam List<Long> ids) {
        return "商品ID列表：" + ids;
    }
}

3. 关键配置项

• required：默认true，请求必须携带该参数，否则报400错误；设为false可实现可选参数
• defaultValue：设置参数默认值，仅当required=false且参数未传时生效
• value/name：绑定请求参数键名，适配前端传参键与后端参数名不一致的场景
• 支持数组、List、Set等多值类型，自动拆分逗号分隔的参数值

三、@RequestHeader：获取HTTP请求头参数

1. 核心定位

用于提取HTTP请求头中的字段值，适用于获取客户端信息、鉴权凭证、请求标识等场景（如Token、User-Agent、Content-Type）。

2. 基础语法与实战示例

语法规则：直接指定请求头字段名，绑定到方法参数，支持标准请求头和自定义请求头。

@RestController
@RequestMapping("/auth")
public class AuthController {

    /**
     * 获取标准请求头：User-Agent（客户端浏览器信息）
     */
    @GetMapping("/info")
    public String getClientInfo(@RequestHeader("User-Agent") String userAgent) {
        return "客户端信息：" + userAgent;
    }

    /**
     * 获取自定义请求头+非必填+默认值
     * 前端请求头携带：token: xxxxxx
     */
    @GetMapping("/check")
    public String checkToken(
            // 自定义请求头，非必填，未传时默认值为anonymous
            @RequestHeader(value = "token", required = false, defaultValue = "anonymous") String token
    ) {
        return "当前凭证：" + token;
    }

    /**
     * 获取标准请求头：Content-Type
     */
    @PostMapping("/submit")
    public String submitData(@RequestHeader("Content-Type") String contentType) {
        return "请求类型：" + contentType;
    }
}

3. 关键配置项

• required：默认true，请求头必须包含该字段，否则报400错误；设为false可实现可选头参数
• defaultValue：设置请求头默认值，未传对应头字段时生效
• value/name：指定请求头字段名，区分大小写（标准头建议按规范书写）
• 支持获取所有请求头：通过@RequestHeader Map<String, String> headers接收全部头信息

四、三大注解核心对比（速查表格）

五、工程实战注意事项

1. 上下文流畅性：路径变量、请求参数、请求头的命名要保持语义一致，避免混乱；2. 异常处理：必传参数缺失时，Spring会抛出MissingServletRequestParameterException/MissingPathVariableException，建议全局异常捕获统一返回；3. 类型转换：Spring自动完成基础类型转换，复杂类型需自定义转换器；4. 最佳实践：RESTful接口优先用@PathVariable定位资源，@RequestParam处理查询条件，@RequestHeader仅用于请求头专属参数。

ps：如果这篇帖子对于还在找工作和找实习的你有所帮助，可以关注我，给本贴点赞、评论、收藏并订阅专栏；同时不要吝啬您的花花