Spring Cloud Gateway GatewayFilter注入请求头抛出UnsupportedOperationException问题

这个问题我之前踩过坑！核心原因很明确：Spring Cloud Gateway默认提供的ServerHttpRequest Headers是只读的不可修改集合，你直接调用exchange.getRequest().getHeaders().add()必然会触发UnsupportedOperationException——因为底层用的是Collections.UnmodifiableMap，压根不支持修改操作。

正确的做法是通过ServerHttpRequest.mutate()方法创建可修改的请求构建器，添加完自定义请求头后生成新的请求对象，再用这个新请求构建新的ServerWebExchange，最后传递给过滤链。

修改后的完整代码如下：

@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    // 执行授权操作
    String jwt = "xxxxx";
    
    // 创建带自定义请求头的新请求
    ServerHttpRequest modifiedRequest = exchange.getRequest().mutate()
            .header("headerkey", jwt)
            .build();
    
    // 基于新请求构建新的Exchange
    ServerWebExchange newExchange = exchange.mutate().request(modifiedRequest).build();
    
    return chain.filter(newExchange);
}

额外提一句：Spring Cloud Gateway从设计上就保证了原始请求对象的不可变性，所以任何对请求/响应的修改都需要通过这种「mutate创建新实例」的方式来做，这是官方推荐的标准操作，既保证了线程安全，也符合网关的设计原则。

内容的提问来源于stack exchange，提问作者thaneesh shanand