开发REST API时@RequestHeader注解的作用、使用场景及最佳实践

为什么需要使用@RequestHeader注解？ #

@RequestHeader是Spring Web提供的原生注解，作用是将HTTP请求中指定的请求头参数，直接绑定到Controller层的方法入参上。
在你提到的登录接口场景下，x-client-id、x-b2b-domain这类参数属于请求的元数据，不属于用户登录的业务请求参数范畴，放在请求头传递符合HTTP协议规范：既不需要修改请求体的结构，也不需要把这类公共参数拼接在URL上造成泄露，用@RequestHeader可以直接提取，代码实现更简洁。 #

实际使用场景 #

• 传递全局公共参数：比如你代码里的客户端标识x-client-id（区分调用方是SPA、移动端、小程序等）、多租户标识x-b2b-domain（区分不同企业租户），还有接口版本号、客户端版本号这类所有接口通用的参数，不需要每个接口的请求体都重复定义对应字段，统一放在请求头传递即可。
• 认证安全相关参数：常见的JWT Token、接口请求签名、防重放的随机串、时间戳等安全校验参数，一般都会放在请求头传递，用@RequestHeader提取后做鉴权逻辑。
• 国际化适配：前端传递的Accept-Language标准头，后端直接提取后返回对应语言的提示信息，不需要侵入业务参数。
• 日志埋点统计：用户设备标识、渠道来源等统计类参数，放在请求头里可以在网关、拦截器层直接读取做统计，不需要解析业务请求体。

使用最佳实践 #

• 合理设置required属性：非必传的请求头一定要显式设置required = false，必要时搭配默认值使用，避免客户端未传对应头时直接抛出400参数错误，你代码中的配置就符合该规范。
• 自定义头统一命名：自定义的业务请求头建议统一加x-前缀（和你代码里的x-client-id、x-b2b-domain一致），和HTTP标准请求头做区分，避免命名冲突。
• 敏感参数必做校验：租户标识、鉴权信息这类核心参数，提取后必须做合法性校验，比如校验x-client-id是否属于后端允许的客户端范围，避免非法参数注入。
• 高频公共头全局处理：如果多个接口都需要用到同一个请求头（比如鉴权Token），不要每个Controller方法都重复声明@RequestHeader参数，可以通过拦截器、@ControllerAdvice全局提取后存入请求上下文，减少重复代码。
• 避免传递大体积内容：服务端对请求头的大小有默认限制（比如Tomcat默认是8KB），大容量参数要放在请求体传递，不要放在请求头里触发大小限制报错。

对应接口代码参考 #

@PostMapping(value = "/first-time/user")
public UserLoggedInInformation firstTimeAuthenticate(@Valid @NotNull
                                    @RequestBody UserPasswordData userPasswordData,
                                                     @RequestHeader(value    = "x-client-id",required = false) String xClientId,
                                                     @RequestHeader(value    = "x-b2b-domain",required = false) String domain) {

    log.debug("Rest Request to check first time user : {} from Application: {} and Domain: {}",userPasswordData,xClientId,domain);

   return authenticationOperations.authenticateFirstTime(xClientId,domain,userPasswordData.getUsername(),userPasswordData.getPassword());
    
}

你提供的这段代码是@RequestHeader的典型合理用法：两个自定义头都属于跨业务的公共参数，放在请求头传递不需要修改业务请求体UserPasswordData的结构，也方便网关层做流量管控、权限校验时直接读取参数，无需解析请求体。 #

内容的提问来源于stack exchange，提问作者Bikash Mohapatra