---

学习文章：Spring Boot 中如何使用 @RequestHeader 注解

在 Spring Boot 开发中，HTTP 请求头（Header）是客户端和服务器之间传递元数据的重要方式。通过请求头，客户端可以传递认证信息、内容类型、语言偏好等数据。Spring Boot 提供了 @RequestHeader 注解，用于方便地从 HTTP 请求头中提取数据。

本文将详细介绍 @RequestHeader 注解的使用方法，包括基本用法、默认值处理、多值头处理以及实际应用场景。

---

一、@RequestHeader 注解简介

@RequestHeader 是 Spring MVC 提供的一个注解，用于将 HTTP 请求头中的值绑定到控制器方法的参数上。它的主要作用是从请求头中提取数据，并将其注入到方法参数中。

常用属性：

• value 或 name：指定请求头的名称。
• required：指示请求头是否必须存在（默认值为 true）。
• defaultValue：当请求头不存在时使用的默认值。

---

二、基本用法

1. 提取单个请求头

以下示例展示了如何从请求头中提取 User-Agent 信息。

java">import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;@RestController
public class HeaderController {@GetMapping("/user-agent")public String getUserAgent(@RequestHeader("User-Agent") String userAgent) {return "User-Agent: " + userAgent;}
}

测试：
访问 http://localhost:8080/user-agent，返回结果如下：

User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36

2. 处理可选请求头

如果请求头是可选的，可以设置 required = false，并提供一个默认值。

java">@GetMapping("/optional-header")
public String getOptionalHeader(@RequestHeader(value = "Custom-Header", required = false, defaultValue = "默认值") String customHeader) {return "Custom-Header: " + customHeader;
}

测试：

• 如果请求中包含 Custom-Header，则返回该值。
• 如果请求中不包含 Custom-Header，则返回默认值。

---

三、提取多个请求头

1. 使用多个 @RequestHeader 注解

可以同时提取多个请求头。

java">@GetMapping("/multiple-headers")
public String getMultipleHeaders(@RequestHeader("User-Agent") String userAgent,@RequestHeader("Accept-Language") String acceptLanguage) {return "User-Agent: " + userAgent + ", Accept-Language: " + acceptLanguage;
}

2. 使用 Map 提取所有请求头

如果需要提取所有请求头，可以使用 Map<String, String> 或 MultiValueMap<String, String>。

java">import java.util.Map;@GetMapping("/all-headers")
public String getAllHeaders(@RequestHeader Map<String, String> headers) {return "Headers: " + headers.toString();
}

测试：
访问 http://localhost:8080/all-headers，返回结果如下：

Headers: {host=localhost:8080, user-agent=Mozilla/5.0, accept-language=en-US,en;q=0.9}

---

四、处理多值请求头

某些请求头可能包含多个值（如 Accept 头），可以使用 List<String> 或 MultiValueMap<String, String> 来提取。

示例：提取 Accept 头的多个值

java">import java.util.List;@GetMapping("/accept-header")
public String getAcceptHeader(@RequestHeader("Accept") List<String> acceptHeaders) {return "Accept Headers: " + acceptHeaders.toString();
}

测试：
访问 http://localhost:8080/accept-header，返回结果如下：

Accept Headers: [text/html, application/xhtml+xml, application/xml;q=0.9]

---

五、实际应用场景

1. 认证和授权

在 RESTful API 中，通常使用请求头传递认证信息（如 Authorization 头）。

java">@GetMapping("/auth")
public String auth(@RequestHeader("Authorization") String authToken) {// 验证 token 的逻辑return "Auth Token: " + authToken;
}

2. 内容协商

通过 Accept 头实现内容协商，返回客户端期望的内容类型。

java">@GetMapping("/content")
public String content(@RequestHeader("Accept") String acceptHeader) {if (acceptHeader.contains("application/json")) {return "{\"message\": \"JSON Response\"}";} else {return "Plain Text Response";}
}

3. 国际化

通过 Accept-Language 头实现多语言支持。

java">@GetMapping("/greeting")
public String greeting(@RequestHeader("Accept-Language") String acceptLanguage) {if (acceptLanguage.startsWith("zh")) {return "你好！";} else {return "Hello!";}
}

---

六、注意事项

1. 请求头名称区分大小写：HTTP 请求头的名称是大小写不敏感的，但 @RequestHeader 注解中的名称是大小写敏感的。
2. 默认值处理：如果请求头不存在且未设置 defaultValue，且 required = true，则会抛出 MissingRequestHeaderException。
3. 多值头的处理：对于多值请求头，使用 List<String> 或 MultiValueMap<String, String> 来提取。

---

七、总结

通过本文的学习，你应该掌握了以下内容：

1. 如何使用 @RequestHeader 注解提取单个请求头。
2. 如何处理可选请求头和默认值。
3. 如何提取多个请求头或所有请求头。
4. 如何处理多值请求头。
5. @RequestHeader 的实际应用场景和注意事项。

@RequestHeader 是 Spring Boot 中处理 HTTP 请求头的强大工具，合理使用可以显著提升代码的可读性和灵活性。希望本文对你有所帮助，欢迎在评论区分享你的学习心得和问题！