引言
在 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 的设置细节
在实际项目中，建议根据具体需求选择合适的方案，并遵循本文提到的最佳实践，以确保代码的健壮性和可维护性。
