Spring Boot中如何为所有API接口自动添加自定义请求头

基于Spring MVC原生扩展点实现，和框架默认Authorization请求头的处理逻辑完全对齐，生产环境稳定可靠，全局一次配置后所有新建接口无需重复编写请求头解析代码。 #

实现步骤 #

1. 定义线程安全的请求头上下文 #

用于存储单次请求内解析到的自定义请求头值，基于ThreadLocal实现线程隔离，和Spring内置请求上下文实现逻辑一致：

public class CustomHeaderHolder {
    private static final ThreadLocal<String> MY_HEADER_CTX = new ThreadLocal<>();

    // 存入请求头值
    public static void setMyHeader(String headerValue) {
        MY_HEADER_CTX.set(headerValue);
    }

    // 获取请求头值，业务代码直接调用即可
    public static String getMyHeader() {
        return MY_HEADER_CTX.get();
    }

    // 请求结束清理值，避免线程池复用导致数据串扰
    public static void clear() {
        MY_HEADER_CTX.remove();
    }
}

2. 编写全局拦截器统一解析请求头 #

拦截所有进入控制器的请求，提前解析自定义请求头存入上下文，请求处理完成后自动清理上下文：

@Component
public class CustomHeaderParseInterceptor implements HandlerInterceptor {
    private static final String TARGET_HEADER = "my-header";

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 跳过非控制器方法的请求（比如静态资源、error页面请求）
        if (!(handler instanceof HandlerMethod)) {
            return true;
        }
        // 解析自定义请求头，和原写法required=false逻辑对齐
        String headerVal = request.getHeader(TARGET_HEADER);
        CustomHeaderHolder.setMyHeader(headerVal);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        // 必须清理，避免内存泄漏和数据串扰
        CustomHeaderHolder.clear();
    }
}

小提示：如果需要对自定义请求头做必填校验，只需要在拦截器preHandle方法中判断值是否合法，不合法直接返回对应错误响应即可，不需要在每个接口中单独编写校验逻辑。

3. 注册拦截器到Spring MVC配置 #

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Resource
    private CustomHeaderParseInterceptor customHeaderInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(customHeaderInterceptor)
                .addPathPatterns("/**") // 拦截所有接口路径
                .excludePathPatterns("/error", "/static/**", "/actuator/**"); // 按需配置排除路径
    }
}

基础使用方式 #

所有接口无需在方法参数上添加任何@RequestHeader相关代码，直接在业务逻辑中调用上下文方法即可获取解析好的请求头值：

@RestController
@RequestMapping("/api")
public class BizController {
    @PostMapping("/setNames")
    public ResponseDTO setNames() {
        // 直接获取全局自动解析的请求头值
        String myHeader = CustomHeaderHolder.getMyHeader();
        // 后续业务逻辑直接使用即可
        return ResponseDTO.success();
    }
}

进阶优化：实现原生级参数自动注入 #

如果想做到和Spring MVC原生参数注入完全一致的体验，不需要手动调用上下文方法，可以额外添加自定义参数解析器：

1. 先定义参数标记注解

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyHeader {
}

2. 实现参数解析器

@Component
public class MyHeaderArgumentResolver implements HandlerMethodArgumentResolver {
    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        // 匹配所有加了@MyHeader注解、类型为String的方法参数
        return parameter.hasParameterAnnotation(MyHeader.class)
                && parameter.getParameterType().equals(String.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
                                  NativeWebRequest webRequest, WebDataBinderFactory binderFactory) {
        return CustomHeaderHolder.getMyHeader();
    }
}

3. 把解析器注册到之前的WebMvcConfig中

@Override
public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
    resolvers.add(new MyHeaderArgumentResolver());
}

配置完成后，接口可以直接写参数自动注入，和框架原生体验无差异：

@PostMapping("/setNamesV2")
public ResponseDTO setNamesV2(@MyHeader String myHeader) {
    // 参数已经自动注入了请求头的值，直接使用即可
    return ResponseDTO.success(myHeader);
}

方案优势 #

• 无重复编码：一次配置全局生效，新建接口不需要编写任何请求头解析逻辑
• 低侵入：不需要修改现有接口方法签名，请求头解析逻辑和业务逻辑完全解耦
• 稳定可靠：基于Spring MVC原生扩展点实现，和框架本身的请求处理链路深度融合，性能损耗可以忽略
• 易维护：后续新增自定义请求头只需要修改上下文和拦截器逻辑即可，不需要改动任何业务代码
• 易扩展：支持自定义校验规则、细粒度路径拦截规则、自定义注解跳过解析等扩展能力

内容的提问来源于stack exchange，提问作者Siddharth Bhatia