Spring 7中HttpHeaders的变更与RestTemplate适配指南

1. 问题背景与影响范围

最近在升级Spring框架到7.x版本时，发现HttpHeaders类的一个关键变更直接影响了RestTemplate的使用方式。这个改动看似微小，却可能导致大量存量代码在升级后出现难以排查的异常行为。根据社区反馈，已有多个团队在生产环境迁移时踩到这个坑。

HttpHeaders作为Spring Web模块中处理HTTP头信息的核心类，其内部实现从Spring 6开始就进行了渐进式改造。到Spring 7版本时，官方彻底重构了headers的存储结构——从原来的LinkedMultiValueMap改为全新的HeadersContainer抽象。这个改变主要出于三个考虑：

1. 性能优化：新实现减少了内存占用和GC压力
2. 线程安全：支持并发场景下的安全访问
3. 不可变支持：便于构建防御性副本

2. 新旧版本行为对比分析

2.1 Spring 6及之前版本的行为特征

在传统用法中，我们经常看到这样的代码片段：

java复制HttpHeaders headers = new HttpHeaders();
headers.set("Authorization", "Bearer xyz");
headers.add("X-Trace-ID", "12345");

// 后续操作headers对象...

此时headers内部使用LinkedMultiValueMap存储，具有以下特点：

• 允许null键和null值
• 值集合采用ArrayList存储
• 完全可变的集合结构
• 非线程安全

2.2 Spring 7版本的重大变更

新版本中相同的代码会产生不同的行为表现：

java复制HttpHeaders headers = new HttpHeaders();
headers = (HttpHeaders) headers.set("Authorization", "Bearer xyz"); // 需要接收返回值！
headers = (HttpHeaders) headers.add("X-Trace-ID", "12345"); 

关键变化点：

1. 所有修改操作(set/add)都返回新的HttpHeaders实例
2. 原始对象保持不可变
3. 内部采用CopyOnWrite机制保证线程安全
4. 禁止null键（抛出NullPointerException）

3. 典型问题场景与修复方案

3.1 RestTemplate使用中的常见陷阱

最典型的错误模式出现在Interceptor配置中：

java复制// 有问题的旧代码
ClientHttpRequestInterceptor interceptor = (request, body, execution) -> {
    HttpHeaders headers = request.getHeaders();
    headers.set("X-Request-ID", UUID.randomUUID().toString()); // 修改无效！
    return execution.execute(request, body);
};

// 正确写法
ClientHttpRequestI