Spring注解秘籍：优雅地使用 @RequestHeader

前言

在 Spring Boot 开发中，HTTP 请求头（Header）是客户端和服务器之间传递元数据的重要方式。通过请求头，客户端可以传递认证信息、内容类型、语言偏好等数据。Spring Boot 提供了 @RequestHeader 注解，用于方便地从 HTTP 请求头中提取数据。本文将详细介绍 @RequestHeader 注解的使用方法，包括基本用法、默认值处理、多值头处理以及实际应用场景。

一、注解定义与核心属性

1.1 @RequestHeader 是什么

在构建现代 Web 应用或 RESTful API 时，我们经常需要从 HTTP 请求中提取元数据信息。其中，请求头（Request Headers） 是传递客户端身份、认证令牌、内容类型、语言偏好等关键信息的重要载体。@RequestHeader 是 Spring Framework 提供的一个方法参数注解，用于将 HTTP 请求头中的特定字段值自动绑定到控制器方法的参数上。它属于 Spring MVC 的数据绑定机制的一部分，与 @RequestParam、@PathVariable、@RequestBody 等注解共同构成 Spring 对 HTTP 请求的结构化解析能力。

⚠️注意：@RequestHeader 仅在 Spring MVC 的控制器方法（@Controller、@RestController）中有效，在 Service、Util 或普通 Bean 方法中使用将被忽略。

1.2 源码定义

@RequestHeader 注解的实现基于Spring MVC的参数绑定机制，它通过 @Target 和 @Retention 注解指定其作用于方法参数级别，并在运行时通过 Spring 的内部机制将请求头的值注入到相应的参数上。

1@Target({ElementType.PARAMETER})
2@Retention(RetentionPolicy.RUNTIME)
3@Documented
4public @interface RequestHeader {
5    @AliasFor("name")
6    String value() default "";
7
8    @AliasFor("value")
9    String name() default "";
10
11    boolean required() default true;
12
13    String defaultValue() default ValueConstants.DEFAULT_NONE;
14}
15

需要注意的是，value() 和 name() 是别名关系，二者等价，通常使用 value。如果方法参数的名称与请求头名称相同，那么可以省略 value 元素。然而，需要注意的是，某些请求头名称（如User-Agent）并不是有效的Java变量名，因此在这种情况下，我们不能省略value元素。

二、工作原理与请求处理流程

2.1 请求头处理流程

2.2 核心处理阶段

1. 参数解析器选择：RequestHeaderMethodArgumentResolver 处理带有 @RequestHeader 的参数
2. 请求头获取：从 HttpServletRequest 获取指定请求头值
3. 类型转换：使用 ConversionService 转换为目标类型

1public class DefaultFormattingConversionService implements ConversionService {  
2    public <T> T convert(@Nullable Object source, Class<T> targetType) {  
3        // 查找合适的转换器  
4        GenericConverter converter = getConverter(sourceType, targetType);  
5        return (T) converter.convert(source, sourceType, targetType);  
6    }  
7}  

4. 默认值处理：当请求头缺失且存在默认值时应用

1@Override  
2protected Object resolveArgument(MethodParameter parameter,  
3                                ModelAndViewContainer mavContainer,  
4                                NativeWebRequest webRequest,  
5                                WebDataBinderFactory binderFactory) throws Exception {  
6      
7    Object arg = super.resolveArgument(parameter, mavContainer, webRequest, binderFactory);  
8      
9    // 处理默认值  
10    if (arg == null && !ValueConstants.DEFAULT_NONE.equals(namedValueInfo.defaultValue())) {  
11        arg = resolveDefaultValue(namedValueInfo.defaultValue());  
12    }  
13    return arg;  
14}  

5. 必填校验：检查必需请求头是否存在

三、使用场景与最佳实践

3.1 基本用法

如果只需要获取某个特定的请求头，可以使用 @RequestHeader 注解并指定 Header 名称。假设我们需要根据用户的 Accept-Language 请求头来返回不同语言的响应，使用 @RequestHeader 可以轻松实现：

1@GetMapping("/locale")
2public String getProfile(@RequestHeader("Accept-Language") String language) {
3  // 根据locale返回不同语言的响应
4  return "response in " + language;
5}
6

⚠️注意：如果请求中没有 accept-language 这个 Header，默认会返回 400 错误。

如上这段代码用于根据客户端的 Accept-Language 请求头返回相应语言的响应，其功能是根据客户端的 HTTP 请求头 Accept-Language 来返回不同语言的响应。使用这种方式代码简洁、语义清晰，无需注入 HttpServletRequest，自动完成字符串转换（支持基本类型、枚举等）。在某些情况下，可能会过度依赖Spring框架的注解，导致代码难以移植。

3.2 可选参数与默认值

默认情况下，Header 是必须的。如果请求中没有该 Header，将抛出异常并返回 400。如果希望在请求头缺失时不出现异常，可以将 required 设置为 false，此时需要手动判断。或者设置 Header 默认值，required 会自动设置为 false，这样即使请求中没有该 Header，也会使用默认值，避免 null 判断。

1@PostMapping("/submit")
2public ResponseEntity<?> submit(
3    @RequestHeader(value = "X-Request-Id", required = false) String requestId,
4    @RequestHeader(value = "User-Agent", defaultValue = "unknown") String userAgent) {
5  if(traceId == null){
6    // 自动生成
7    traceId = generateTraceId(); 
8  }
9    return AppInfo(traceId, userAgent);
10}
11

defaultValue 仅在 required = false 且请求头缺失时生效，若同时设置 required = true 和 defaultValue，defaultValue 不会被使用（因为 Spring 认为该头必须存在）。

3.3 获取所有 Headers

@RequestHeader 可以获取单个请求头的值，也可以获取所有请求头，并将其作为 MultiValueMap 或 Map 类型传递给方法参数。如果不确定请求中会包含哪些 Headers，或者不希望方法参数列表太长，可以使用 @RequestHeader 不指定名称，直接获取所有 Headers，可以选择使用以下几种类型接收：

• 使用 Map 接收所有请求头，只获取每个 Header 的第一个值。

1@GetMapping("/analytics")  
2public Map<String, String> analyzeHeaders(@RequestHeader Map<String, String> headers) {  
3  // headers 包含所有请求头（key 不区分大小写，统一转为小写。注意：实际保留原始大小写）  
4  return headers;  
5}  

• 使用 MultiValueMap 接收请求头，可以获取多个值。

1@RequestMapping("/listHeaders")  
2public Map<String, Object> listHeaders(@RequestHeader MultiValueMap<String, String> headers) {  
3  Map<String, Object> result = new HashMap<>();  
4  headers.forEach((key, value) -> {  
5       // 日志中输出所有请求头  
6      System.out.println(String.format("Header '%s' = %s", key, value));  
7  });  
8  result.put("code", 0);  
9  result.put("msg", "success");  
10  result.put("headers", headers);  
11  return result;  
12}  

• 使用 HttpHeaders 接收请求头，这是Spring提供的一个专门用于处理请求头的类，它实现了 MultiValueMap<String, String> 接口，主要用于获取标准 Header。

1@RequestMapping("/getAllHttpHeaders")  
2public Map<String, Object> getAllHttpHeaders(@RequestHeader HttpHeaders headers) {  
3  headers.forEach((key, value) -> {  
4       // 日志中输出所有请求头  
5      System.out.println(String.format("getAllHttpHeaders '%s' = %s", key, value));  
6  });  
7  Map<String, Object> result = new HashMap<>();  
8  result.put("code", 0);  
9  result.put("msg", "success");  
10  result.put("headers", headers);  
11  return result;  
12}  

⚠️ 注意：如果指定的 Header 不存在，从 Map、MultiValueMap 或 HttpHeaders 获取时会返回 null。

3.4 处理多值请求头

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

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

四、最佳实践总结

4.1 请求头使用规范

4.2 与 HttpServletRequest.getHeader() 的对比

五、总结

在现代Web应用程序中，安全性是一个至关重要的方面，特别是当我们处理敏感数据或执行受限操作时。@RequestHeader 注解在这方面发挥了重要作用，它允许开发者轻松地从HTTP请求头中提取信息，例如认证令牌，并据此进行安全决策。通过这种方式，我们能够精确控制对受限端点的访问，仅允许通过身份验证的用户访问敏感数据。这不仅增强了应用程序的安全性，还提供了一种灵活的方法来处理各种基于请求头的逻辑。

然而，合理使用这一工具的同时，开发者也需要关注安全性的其它方面，比如确保敏感信息的加密存储、使用HTTPS来保护数据传输的安全等。此外，实现鲁棒的身份验证逻辑和错误处理机制也是至关重要的，以确保应用程序能够妥善处理无效或恶意的请求。

《Spring注解秘籍：优雅地使用 @RequestHeader》 是转载文章，点击查看原文。