Spring Cloud Gateway 中 TokenRelay 过滤器与 ReadOnlyHttpHeaders 异常问题分析

问题背景

在 Spring Cloud Gateway 项目中，当开发者升级到 Spring Boot 3.3.5 版本后，TokenRelay 过滤器开始出现异常。该异常表现为对 HTTP 头部的修改操作被拒绝，核心错误信息显示为 UnsupportedOperationException，指出当前使用的是 ReadOnlyHttpHeaders 类型。

技术根源

这一问题源于 Spring Framework 对 HTTP 头部处理机制的变更。在较新版本中，Spring Framework 默认将 HTTP 头部设置为只读状态，这是出于安全考虑的设计选择。然而，这种改变与 Spring Cloud Gateway 中 TokenRelay 过滤器的预期行为产生了冲突。

TokenRelay 过滤器的核心功能是在网关层面中继 OAuth2 令牌。当请求通过网关时，该过滤器需要：

1. 从当前认证上下文中提取访问令牌
2. 将令牌添加到下游请求的 Authorization 头部
3. 转发请求到目标服务

这一过程需要对请求头部进行修改操作，而只读头部的限制直接阻碍了这一功能的正常执行。

影响范围

该问题不仅影响 TokenRelay 过滤器，实际上任何需要对请求头部进行修改的操作都会受到影响。这包括但不限于：

• 自定义网关过滤器中对头部的修改
• 安全相关的头部操作
• 请求转发时的头部调整

临时解决方案

对于需要立即解决问题的开发者，可以采用以下两种临时方案：

方案一：配置 Spring Security 防火墙

通过调整 Spring Security 的防火墙配置，可以避免头部被设置为只读状态：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
    http
        // 其他安全配置
        .headers(headers -> headers
            .hsts(hsts -> hsts.disable())
        );
    return http.build();
}

方案二：自定义 WebFilter 处理

创建一个前置 WebFilter，在请求处理早期阶段对头部进行可写化处理：

public class MutableHeadersWebFilter implements WebFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        HttpHeaders headers = new HttpHeaders();
        headers.addAll(request.getHeaders());
        
        ServerHttpRequest mutatedRequest = request.mutate()
            .headers(httpHeaders -> httpHeaders.clear())
            .build();
            
        return chain.filter(exchange.mutate().request(mutatedRequest).build());
    }
}

长期解决方案

Spring Framework 团队已经意识到这一问题，并在后续版本中进行了修复。建议开发者：

1. 关注 Spring Framework 的更新日志
2. 在合适的时机升级到包含修复的版本
3. 评估临时方案的安全影响，在升级后及时移除

最佳实践建议

对于使用 Spring Cloud Gateway 的开发者，在处理类似问题时建议：

1. 在升级依赖版本前，充分测试关键功能
2. 了解各组件间的版本兼容性
3. 对于安全相关的变更保持高度敏感
4. 建立完善的监控机制，及时发现类似问题

总结

这次事件展示了微服务架构中组件间依赖关系的复杂性。作为网关核心组件，Spring Cloud Gateway 需要平衡安全性和功能性。开发者应当理解底层框架的设计意图，同时掌握应对此类兼容性问题的技巧。随着 Spring 生态系统的持续演进，这类问题将得到更好的协调解决。