在 Spring 中给 HttpServletRequest 添加自定义 Header 的完整指南

引言

在 Spring 应用开发中，我们经常需要在请求处理过程中添加自定义的 HTTP Header。由于 HttpServletRequest 对象在设计上是只读的，直接添加 Header 会遇到困难。本文将详细介绍如何通过 Filter 和 RequestWrapper 的方式优雅地解决这个问题。

问题背景

HttpServletRequest 接口本身不提供修改 Header 的方法，这是因为：

Servlet 规范设计请求对象为只读
保证请求数据的完整性和一致性
避免在多线程环境下出现数据竞争

但在实际业务场景中，我们经常需要添加一些业务相关的 Header或引用的包中会依赖header中的某个值，比如：

租户 ID（tenantId）
用户追踪信息
认证令牌
业务上下文信息

解决方案：Filter + RequestWrapper

核心思路

通过创建 HttpServletRequestWrapper 子类来包装原始请求，重写相关方法以支持自定义 Header 的添加。

完整代码实现

1. 自定义 RequestWrapper

public class RequestWrapper extends HttpServletRequestWrapper {
    
    // 可选，如需对body数据做处理
    private String mBody;
    private Map headerMap = new HashMap();

    public RequestWrapper(HttpServletRequest request) {
        super(request);
        mBody = getBodyString(request);
    }

    /**
     * 添加自定义 Header
     */
    public void addHeader(String name, String value) {
        headerMap.put(name, value);
    }

    @Override
    public String getHeader(String name) {
        String headerValue = super.getHeader(name);
        if (headerMap.containsKey(name)) {
            headerValue = headerMap.get(name);
        }
        return headerValue;
    }

    @Override
    public Enumeration getHeaderNames() {
        List names = Collections.list(super.getHeaderNames());
        names.addAll(headerMap.keySet());
        return Collections.enumeration(names);
    }

    @Override
    public Enumeration getHeaders(String name) {
        List values = Collections.list(super.getHeaders(name));
        if (headerMap.containsKey(name)) {
            values.add(headerMap.get(name));
        }
        return Collections.enumeration(values);
    }

    /**
     * 获取请求体内容
     */
    private String getBodyString(ServletRequest request) {
        StringBuilder sb = new StringBuilder();
        try (InputStream inputStream = request.getInputStream();
             BufferedReader reader = new BufferedReader(
                 new InputStreamReader(inputStream, StandardCharsets.UTF_8))) {
            
            String line;
            while ((line = reader.readLine()) != null) {
                sb.append(line);
            }
        } catch (IOException e) {
            logger.error(\"读取请求体失败\", e);
        }
        return sb.toString();
    }

    // 其他必要的方法重写...
}

2. 实现自定义 Filter

@Component
@Order(10000)
@WebFilter(filterName = \"HttpServletRequestFilter\", urlPatterns = \"/*\")
public class HttpServletRequestFilter implements Filter {
    
    private static final Set EXCLUDE_PATHS = Set.of(
        \"/health\", \"/actuator/health\", \"/favicon.ico\"
    );
    
    private static final Logger logger = LoggerFactory.getLogger(HttpServletRequestFilter.class);

    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, 
                         FilterChain filterChain) throws IOException, ServletException {
        
        HttpServletRequest httpRequest = (HttpServletRequest) servletRequest;
        String path = httpRequest.getRequestURI();
        
        // 跳过不需要处理的路径
        if (shouldSkipProcessing(path)) {
            filterChain.doFilter(servletRequest, servletResponse);
            return;
        }
        
        // 包装请求
        RequestWrapper requestWrapper = new RequestWrapper(httpRequest);
        
        // 设置自定义 Header，这里可以在别处设置，比如从token中解析后调用setCustomHeaders
        setCustomHeaders(requestWrapper);
        
        // 继续过滤器链
        filterChain.doFilter(requestWrapper, servletResponse);
    }

    /**
     * 判断是否跳过处理
     */
    private boolean shouldSkipProcessing(String path) {
        return EXCLUDE_PATHS.stream().anyMatch(path::startsWith);
    }

    /**
     * 设置自定义 Header
     */
    private void setCustomHeaders(HttpServletRequest request) {
        try {
            // 示例：从用户上下文中获取租户ID
            User user = UserContext.getUser();
            if (user != null && user.getTenantId() != null) {
                setHeaderTenantId(request, user.getTenantId());
            }
            
            // 可以添加更多自定义 Header
            // setOtherHeaders(request);
            
        } catch (Exception e) {
            logger.warn(\"设置自定义 Header 失败\", e);
        }
    }

    /**
     * 设置租户ID Header
     */
    private void setHeaderTenantId(HttpServletRequest request, String tenantId) {
        if (request instanceof StandardMultipartHttpServletRequest) {
            // 处理文件上传请求
            StandardMultipartHttpServletRequest multipartRequest = 
                (StandardMultipartHttpServletRequest) request;
            HttpServletRequest originalRequest = multipartRequest.getRequest();
            if (originalRequest instanceof RequestWrapper) {
                ((RequestWrapper) originalRequest).addHeader(\"tenantId\", tenantId);
            }
        } else if (request instanceof RequestWrapper) {
            // 处理普通请求
            ((RequestWrapper) request).addHeader(\"tenantId\", tenantId);
        }
        // 其他类型的请求可以根据需要扩展
    }

    @Override
    public void init(FilterConfig filterConfig) {
        logger.info(\"HttpServletRequestFilter 初始化完成\");
    }

    @Override
    public void destroy() {
        logger.info(\"HttpServletRequestFilter 销毁\");
    }
}

关键技术点解析

1. HttpServletRequestWrapper 的作用

HttpServletRequestWrapper 是装饰器模式的实现，它允许我们：

包装原始请求对象
选择性重写方法
保持其他方法的默认行为

2. 必须重写的方法

要支持自定义 Header，必须重写以下三个方法：

getHeader(String name) – 获取单个 Header 值
getHeaders(String name) – 获取 Header 的所有值
getHeaderNames() – 获取所有 Header 名称

3. 请求体处理

由于 HTTP 请求的输入流只能读取一次，我们需要在包装时保存请求体内容：

private String getBodyString(ServletRequest request) {
    // 读取并保存请求体，支持重复读取
}

4. 特殊请求类型处理

对于 MultipartHttpServletRequest（文件上传）等特殊请求类型，需要特殊处理：

if (request instanceof StandardMultipartHttpServletRequest) {
    // 获取底层请求对象进行处理
}

使用示例

在 Controller 中获取自定义 Header：

@RestController
public class TestController {
    
    @GetMapping(\"/api/data\")
    public ResponseEntity getData(HttpServletRequest request) {
        // 获取自定义的 tenantId Header
        String tenantId = request.getHeader(\"tenantId\");
        
        // 使用 tenantId 进行业务处理
        List result = dataService.getDataByTenant(tenantId);
        
        return ResponseEntity.ok(result);
    }
}

最佳实践建议

1. 性能优化

路径排除：对健康检查等不需要处理的路径进行排除
懒加载：只在需要时读取请求体
资源清理：及时关闭流和清理 ThreadLocal

2. 错误处理

异常捕获：妥善处理可能出现的异常
降级策略：在无法设置 Header 时提供合理的降级方案
日志记录：记录关键操作和错误信息

3. 可维护性

配置化：将排除路径等配置外部化
模块化：将 Header 设置逻辑分离到独立的服务中
文档化：记录自定义 Header 的含义和用途

替代方案比较

1. ThreadLocal 方式

优点：简单高效
缺点：需要在同一线程内传递，对异步支持不友好

2. Request Attribute 方式

优点：实现简单
缺点：不符合 HTTP Header 的语义

3. Filter + Wrapper 方式（本文方案）

优点：符合 Servlet 规范，支持所有请求类型
缺点：实现相对复杂

总结

通过 Filter 和 HttpServletRequestWrapper 的组合，我们可以优雅地在 Spring 应用中添加自定义 HTTP Header。这种方案：

符合 Servlet 规范，不破坏现有框架行为
支持所有请求类型，包括文件上传等特殊场景
具有良好的扩展性，可以方便地添加更多自定义 Header
保持代码整洁，业务代码无需关心 Header 的设置细节

在实际项目中，建议根据具体需求选择合适的方案，并遵循本文提到的最佳实践，以确保代码的健壮性和可维护性。

引言