常用注解——@RequestParam、@RequestBody、@RequestHeader、@CookieValue

SpringMVC常用注解------@RequestParam、@RequestBody、@RequestHeader、@CookieValue

系列导读 ：本文包括 @RequestParam、@RequestBody、@RequestHeader、@CookieValue，结合大量实例掌握其使用场景与细节。

---

前言

SpringMVC提供了一套完善的注解体系，用于处理HTTP请求的各个环节。本篇重点介绍与请求参数获取相关的四个核心注解，理解它们的作用与区别，能让你更灵活、更规范地处理各类请求数据。

---

一、@RequestParam注解

1.1 基本说明

@RequestParam 用于将请求参数绑定到Controller方法的形参上，在前后端参数名不一致或需要设置默认值时非常有用。

属性	类型	默认值	说明
value	String	---	请求参数的名称（key）
required	boolean	true	是否必须提供该参数
defaultValue	String	---	参数不存在时的默认值

1.2 解决前后端参数名不一致问题

场景 ：前端传递 username 和 address，但后端方法的形参命名为 name 和 addr。

不加注解时，后台无法接收到数据（两个参数均为null）：

// ❌ 参数名不匹配，接收到的 name 和 addr 均为 null
@RequestMapping("testRequestParam")
public String testRequestParam(String name, String addr) {
    System.out.println("name:" + name + " addr:" + addr);
    return "success";
}

使用 @RequestParam 后，通过 value 指定对应的请求参数名：

// ✅ 使用@RequestParam建立前后端参数名的映射关系
@RequestMapping("testRequestParam")
public String testRequestParam(
    @RequestParam("username") String name,
    @RequestParam("address") String addr) {

    System.out.println("name:" + name + " addr:" + addr);
    return "success";
}

1.3 required属性------控制参数是否必须

required 默认值为 true，即该参数是必须的。如果前台不传递该参数，会报错：

HTTP Status 400 - Required String parameter 'address' is not present

将 required 设为 false，则参数变为可选，不传时值为 null：

@RequestMapping("testRequestParam")
public String testRequestParam(
    @RequestParam("username") String name,
    @RequestParam(value = "address", required = false) String addr) {

    System.out.println("name:" + name + " addr:" + addr);  // addr 可能为 null
    return "success";
}

1.4 defaultValue属性------设置参数默认值

当参数未传递时，使用指定的默认值替代 null：

@RequestMapping("testRequestParam")
public String testRequestParam(
    @RequestParam("username") String name,
    @RequestParam(value = "address", required = false, defaultValue = "中国") String addr) {

    System.out.println("name:" + name + " addr:" + addr);
    // 若未传 address 参数，输出：addr=中国
    return "success";
}

1.5 完整使用示例

<%-- JSP页面 --%>
<a href="${pageContext.request.contextPath}/demo1/testRequestParam?username=eric&address=china">
    测试RequestParam注解
</a>

@Controller
@RequestMapping("demo1")
public class HelloController {

    @RequestMapping("testRequestParam")
    public String testRequestParam(
        @RequestParam(value = "username", required = true) String name,
        @RequestParam(value = "address", required = false, defaultValue = "未知地址") String addr) {

        System.out.println("用户名：" + name);
        System.out.println("地址：" + addr);
        return "success";
    }
}

---

二、@RequestBody注解

2.1 基本说明

@RequestBody 用于获取请求实体内容（请求体），即接收请求体中的原始数据。

属性	说明
required	是否必须有请求体，默认 true。GET请求会报错；设为 false 时GET请求得到 null

⚠️ 重要 ：GET请求没有请求体，@RequestBody 不适用于GET请求。

2.2 接收表单提交的数据（同步请求）

表单POST提交时，请求体内容是 key=value&key=value 格式的字符串：

<form action="demo1/useRequestBody" method="post">
    用户名称：<input type="text"     name="username"><br/>
    用户密码：<input type="password" name="password"><br/>
    用户年龄：<input type="text"     name="age"><br/>
    <input type="submit" value="保存">
</form>

@RequestMapping("useRequestBody")
public String useRequestBody(@RequestBody String body) {
    // 输出：username=eric&password=admin&age=12
    System.out.println(body);
    return "success";
}

2.3 接收Ajax发送的JSON数据（异步请求）

在前后端分离或Ajax交互场景下，@RequestBody 更常用于接收JSON格式的请求体。

前端Ajax代码：

<script src="http://libs.baidu.com/jquery/1.9.0/jquery.js"></script>
<script type="text/javascript">
$(function(){
    $("#testJson").click(function(){
        $.ajax({
            type: "post",
            url: "${pageContext.request.contextPath}/hello/testAjax",
            contentType: "application/json;charset=UTF-8",
            data: '{"id":1,"name":"test","money":999.0}',
            dataType: "json",
            success: function(data){
                console.log(data);
            }
        });
    });
});
</script>
<button id="testJson">发送JSON数据</button>

接收为字符串：

@RequestMapping("testAjax")
public void testAjax(@RequestBody String body) {
    // 输出：{"id":1,"name":"test","money":999.0}
    System.out.println(body);
}

接收并自动转换为POJO对象（需要Jackson依赖）：

首先引入Jackson依赖：

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.9.0</version>
</dependency>

然后定义对应的POJO类（属性名与JSON的key对应）：

public class Account {
    private Integer id;
    private String name;
    private Double money;
    // getter/setter 省略...
}

Controller方法形参直接使用POJO类型：

@RequestMapping("testAjax")
public void testAjax(@RequestBody Account account) {
    // SpringMVC自动将JSON字符串反序列化为Account对象
    System.out.println(account); // Account{id=1, name='test', money=999.0}
}

也可以使用 Map<String, Object> 接收：

@RequestMapping("testAjax")
public void testAjax(@RequestBody Map<String, Object> map) {
    System.out.println(map); // {id=1, name=test, money=999.0}
}

---

三、@RequestHeader注解

3.1 基本说明

@RequestHeader 用于获取请求头中指定字段的值。

属性	说明
value	请求头的名称
required	是否必须有此请求头，默认 true

3.2 使用示例

<a href="demo1/useRequestHeader">获取请求消息头</a>

@RequestMapping("useRequestHeader")
public String useRequestHeader(
    @RequestHeader(value = "Accept-Language") String acceptLanguage) {

    // 输出当前浏览器的语言设置，如：zh-CN,zh;q=0.9
    System.out.println("Accept-Language: " + acceptLanguage);
    return "success";
}

3.3 常见请求头字段

请求头	说明
Accept	客户端能接受的内容类型
Accept-Language	客户端偏好的语言
Accept-Encoding	客户端支持的压缩方式
User-Agent	客户端信息（浏览器、操作系统等）
Content-Type	请求体的MIME类型
Authorization	认证信息（Token等）
Cookie	Cookie数据

// 获取User-Agent（客户端信息）
@RequestMapping("getUserAgent")
public String getUserAgent(
    @RequestHeader(value = "User-Agent") String userAgent) {
    System.out.println("User-Agent: " + userAgent);
    return "success";
}

// 获取Token（不强制要求存在）
@RequestMapping("getToken")
public String getToken(
    @RequestHeader(value = "Authorization", required = false) String token) {
    System.out.println("Token: " + token);
    return "success";
}

---

四、@CookieValue注解

4.1 基本说明

@CookieValue 用于获取Cookie中指定名称的值，并将其注入到方法形参中。

属性	说明
value	Cookie的名称
required	是否必须有此Cookie，默认 true
defaultValue	Cookie不存在时的默认值

4.2 使用示例

<a href="demo1/useCookieValue">绑定Cookie的值</a>

@RequestMapping("useCookieValue")
public String useCookieValue(
    @CookieValue(value = "JSESSIONID", required = false) String sessionId) {

    // 输出会话ID，如：0E55620C30D7D4BB8FCBCF84C0950F67
    System.out.println("JSESSIONID: " + sessionId);
    return "success";
}

4.3 实际应用场景

// 从Cookie中获取用户的语言偏好
@RequestMapping("getLanguage")
public String getLanguage(
    @CookieValue(value = "lang", defaultValue = "zh-CN") String language) {
    System.out.println("用户语言偏好：" + language);
    return "success";
}

// 从Cookie中获取记住我的Token
@RequestMapping("checkRememberMe")
public String checkRememberMe(
    @CookieValue(value = "rememberMeToken", required = false) String token) {
    if (token != null) {
        System.out.println("发现记住我Token：" + token);
        // 根据token自动登录...
    }
    return "success";
}

---

五、四个注解的对比总结

注解	数据来源	常见场景
@RequestParam	URL查询参数 / 表单字段	获取 ?key=value 参数，解决前后端参数名不一致
@RequestBody	请求体（Body）	接收Ajax发送的JSON数据
@RequestHeader	请求头（Headers）	获取 Token、Accept-Language 等请求头信息
@CookieValue	Cookie	获取会话ID、用户偏好等Cookie数据

---

六、小结

本篇详细讲解了SpringMVC中与请求数据获取相关的四个核心注解：

1. @RequestParam：解决参数名不一致、设置参数必填性和默认值
2. @RequestBody：获取请求体原始数据，常用于接收JSON
3. @RequestHeader：获取请求头中的指定字段
4. @CookieValue：获取Cookie中指定名称的值