Spring Web MVC中@RequestHeader无法获取请求头值的问题

可能的原因及解决方案 #

1. 确认请求头传递是否正确 #

首先确保请求中确实携带了Auth-Username和Auth-Password头，且名称完全匹配（注意连字符、大小写，虽然HTTP头规范不区分大小写，但Spring的@RequestHeader默认严格匹配配置的名称）。

• 用curl命令测试：

  curl -H "Auth-Username: test_user" -H "Auth-Password: test_pass" http://localhost:8080/[你的接口路径]/test_user
  

• 在控制器方法中添加日志打印，直接输出读取到的头值，确认是否为null：

  System.out.println("读取到的Auth-Username: " + authUsername);
  System.out.println("读取到的Auth-Password: " + authPassword);
  

2. 检查请求头的必填性与异常反馈 #

@RequestHeader默认是必填项，如果请求未携带对应头，Spring会抛出MissingRequestHeaderException并返回400错误。如果未收到该错误：

• 说明请求根本没携带这些头，或请求未到达控制器；
• 若需要允许头可选，可添加required=false参数：

  @RequestHeader(value = "Auth-Username", required = false) String authUsername
  

3. 排查过滤器/拦截器对请求头的影响 #

如果项目中有自定义Filter、Interceptor或安全框架，可能会修改或丢弃请求头：

• 检查跨域（CORS）配置：若为前端跨域请求，需确保CORS的allowedHeaders包含Auth-Username和Auth-Password，否则浏览器会在预检请求后丢弃这些头；
• 检查所有自定义拦截逻辑，确认未对请求头做删除或覆盖操作。

4. 修复依赖冲突 #

你的build.gradle中同时引入了javax.servlet-api和jakarta.servlet-api，Spring 6.x基于Jakarta EE 9+，二者存在冲突，会导致Servlet API相关功能异常：

• 删除javax.servlet:javax.servlet-api:4.0.1依赖；
• 将javax.annotation:javax.annotation-api:1.3.2替换为Jakarta版本：

  implementation 'jakarta.annotation:jakarta.annotation-api:2.1.1'
  

5. 手动通过HttpServletRequest获取请求头 #

绕过@RequestHeader注解，直接用HttpServletRequest读取头，验证是否能获取到值：

public ResponseEntity<TraineeResponseDTO> getTrainee(@PathVariable String username,
                                                     HttpServletRequest request) {
    String authUsername = request.getHeader("Auth-Username");
    String authPassword = request.getHeader("Auth-Password");
    // 后续逻辑...
}

• 若手动能获取，说明@RequestHeader绑定存在异常，需检查Spring配置或依赖；
• 若手动也无法获取，说明请求头未被正确传递到服务器。

6. 检查Swagger测试配置 #

使用Springfox Swagger测试时，需确保Swagger UI能正确识别并传递请求头：

• 添加@ApiHeaders注解声明头参数，方便在Swagger UI中输入：

  @ApiOperation(value = "fetch Trainee", response = TraineeResponseDTO.class)
  @ApiHeaders({
      @ApiHeader(name = "Auth-Username", value = "认证用户名", required = true),
      @ApiHeader(name = "Auth-Password", value = "认证密码", required = true)
  })
  

内容的提问来源于stack exchange，提问作者j0hnny.b