首页 > 软件编程 > java > SpringBoot 接口传参常用注解

SpringBoot 中处理接口传参时常用的注解及使用场景分析

2026-02-03 09:29:08 作者：Elieal

SpringBoot提供了多种注解来处理不同位置的参数,包括路径参数、URL请求参数、请求体参数、请求头参数和Cookie参数,每种注解都有其特定的使用场景和核心用法,下面给大家介绍SpringBoot中处理接口传参时常用的注解及使用场景分析,感兴趣的朋友跟随小编一起看看吧

SpringBoot 接收前端参数的核心注解都基于 Spring MVC，主要解决不同位置参数（URL 路径、请求头、请求体、URL 参数等）的绑定问题，下面按使用场景分类说明：

1. 路径参数（URL 中 /{xxx} 形式）：@PathVariable

核心作用：绑定 URL 路径中的动态参数（如/user/123中的123）到方法参数。
使用场景：RESTful 风格接口，获取资源 ID、分类标识等。
核心用法：

@RestController
@RequestMapping("/user")
public class UserController {
    // 访问路径：/user/123
    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return "获取到用户ID：" + id;
    }
    // 多路径参数 + 指定参数名（参数名与路径变量名不一致时）
    @GetMapping("/{id}/order/{orderId}")
    public String getUserOrder(
        @PathVariable("id") Long userId, 
        @PathVariable("orderId") Long orderId
    ) {
        return "用户ID：" + userId + "，订单ID：" + orderId;
    }
}

关键说明：默认要求路径变量名与方法参数名一致，不一致时需用@PathVariable("xxx")指定。

2. URL 请求参数（?key=value 形式）：@RequestParam

核心作用：绑定 URL 中?后的查询参数（如/user?name=张三）到方法参数。
使用场景：分页、筛选、简单条件查询（如page=1&size=10）。
核心用法：

@RestController
@RequestMapping("/user")
public class UserController {
    // 访问路径：/user/list?name=张三&age=20
    @GetMapping("/list")
    public String getUserList(
        @RequestParam String name, // 必传参数
        @RequestParam(required = false, defaultValue = "18") Integer age // 非必传+默认值
    ) {
        return "姓名：" + name + "，年龄：" + age;
    }
}

关键属性：
- required：是否必传，默认true（不传会报错）；
- defaultValue：参数未传时的默认值（仅required=false时生效）；
- value：指定 URL 参数名（与方法参数名不一致时用）。

3. 请求体参数（JSON/XML）：@RequestBody

核心作用：绑定 HTTP 请求体（通常是 JSON 格式）到 Java 对象（POJO）。
使用场景：POST/PUT 请求，传递复杂数据（如新增 / 修改用户信息）。
核心用法：

// 1. 定义POJO（接收前端JSON）
public class UserDTO {
    private String name;
    private Integer age;
    // 省略getter/setter
}
// 2. 控制器接收参数
@RestController
@RequestMapping("/user")
public class UserController {
    // 前端POST请求体：{"name":"张三","age":20}
    @PostMapping("/add")
    public String addUser(@RequestBody UserDTO userDTO) {
        return "新增用户：" + userDTO.getName() + "，年龄：" + userDTO.getAge();
    }
}

关键说明：
- 仅支持 POST/PUT 等有请求体的请求（GET 请求无请求体，用会报错）；
- 前端需保证 Content-Type 为application/json，否则解析失败；
- 可搭配@Valid/@Validated做参数校验（如@NotBlank(message = "姓名不能为空")）。

4. 请求头参数：@RequestHeader

核心作用：绑定 HTTP 请求头中的参数（如 Token、Content-Type）。
使用场景：获取令牌（Token）、语言标识（Accept-Language）等。
核心用法：

@RestController
@RequestMapping("/user")
public class UserController {
    @GetMapping("/info")
    public String getUserInfo(
        @RequestHeader("token") String token, // 获取token请求头
        @RequestHeader(value = "Accept-Language", required = false) String lang // 非必传
    ) {
        return "Token：" + token + "，语言：" + (lang == null ? "zh-CN" : lang);
    }
}

5. Cookie 参数：@CookieValue

核心作用：绑定 HTTP Cookie 中的参数。
使用场景：获取前端存储的 Cookie（如用户登录态）。
核心用法：

@RestController
@RequestMapping("/user")
public class UserController {
    @GetMapping("/cookie")
    public String getCookie(@CookieValue("JSESSIONID") String sessionId) {
        return "SessionID：" + sessionId;
    }
}

6. 无注解（自动绑定）

核心作用：当参数是简单类型（String、Integer、Long 等）或 POJO 时，SpringBoot 会自动绑定 URL 参数 / 表单参数到方法参数。
使用场景：简单表单提交、参数名与 POJO 字段名完全一致的场景。
核心用法：

// 1. 简单类型自动绑定（访问路径：/user/simple?name=李四）
@GetMapping("/simple")
public String simpleParam(String name) {
    return "姓名：" + name;
}
// 2. POJO自动绑定（访问路径：/user/pojo?name=李四&age=22）
@GetMapping("/pojo")
public String pojoParam(UserDTO userDTO) {
    return "姓名：" + userDTO.getName() + "，年龄：" + userDTO.getAge();
}

关键说明：仅适用于 URL 参数 / 表单参数（application/x-www-form-urlencoded），无法绑定 JSON 请求体。

总结

@PathVariable：绑定 URL 路径中的动态参数（RESTful 接口核心）；
@RequestParam：绑定 URL 查询参数（?key=value），支持必传 / 默认值配置；
@RequestBody：绑定 JSON 请求体到 POJO（POST/PUT 传递复杂数据）；
@RequestHeader/@CookieValue：分别绑定请求头、Cookie 中的参数；
无注解自动绑定：适用于简单 URL / 表单参数，无需额外注解。

核心原则：根据参数位置（路径、查询、请求体、请求头）选择对应注解，复杂数据用@RequestBody，简单筛选用@RequestParam，RESTful 资源标识用@PathVariable。

到此这篇关于SpringBoot 中处理接口传参时常用的注解的文章就介绍到这了,更多相关SpringBoot 接口传参常用注解内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！