HTTP/1.1规范规定，头字段名不区分大小写，客户端和服务器都必须把Content-Type与content-type当作同一个头来处理。然而Ruby标准库中的Hash在比较键时是大小写敏感的，如果直接用它存放HTTP头，很容易因为书写大小写不一致而产生重复键。Faraday作为常用的HTTP客户端库，在内部提供了一个专门用于管理请求头与响应头的工具类Faraday::Utils::Headers。这个类针对HTTP头的语义做了两项关键处理：一是键访问大小写不敏感；二是重复头值不会简单覆盖，而是进行合并。下面从源码角度逐步拆解它的实现机制。
大小写不敏感的键访问原理
Faraday::Utils::Headers的源码并不复杂，它继承自Ruby的内置Hash，但重写了初始化、键读取、键写入、键删除等多个方法。这些重写的核心思路是先对传入的键调用一个转换方法，通常将其转为小写字符串，然后再调用父类Hash的对应方法。这意味着无论外部使用符号还是字符串、无论大小写如何组合，最终在Hash内部存储的键始终是统一的小写形式。比如设置为headers['Content-Type']和读取headers['content-type']，都会命中同一个内部键。
这种做法的好处是使用方完全不需要关心键的书写规范，中间件在修改请求头时可以直接使用习惯的写法。但需要留意，由于内部强制小写，原本传入的键形态会在存储时丢失。如果代码中遍历headers对象，看到的键将全部是小写字符串，而不是最初传入的混合大小写形式。这对大多数场景没有影响，因为HTTP头字段名本身就是大小写不敏感的，但如果你希望保留原始大小写用于日志展示，就需要额外记录原始形态。
headers = Faraday::Utils::Headers.new headers['Content-Type'] = 'application/json' headers['content-type'] = 'text/plain' puts headers['CONTENT-TYPE'] puts headers.inspect
上面的例子中，第一次赋值使用了Content-Type，第二次使用了content-type，第三次读取时使用了全大写的CONTENT-TYPE，但最终访问到的都是同一个内部键。输出结果会显示该键对应的值已经变成包含两个元素的数组，而不是两个独立的键。这里就引出了第二个核心行为：重复头合并。
重复头合并的规则与具体表现
在普通Hash中，对同一个键再次赋值会覆盖旧值。但HTTP规范中很多头字段是允许重复出现的，例如Accept、Cookie、Warning等。如果客户端库简单覆盖，就会丢失信息。Faraday::Utils::Headers在重写的[]=方法里加入了判断逻辑：当目标键已经存在一个值时，它不会直接替换，而是把新值追加到已有值上。如果旧值还不是数组，会先将其包装为数组；如果旧值已经是数组，则直接添加新元素。这样一来，同一个语义头无论被设置多少次，最终都能保留全部值。
h = Faraday::Utils::Headers.new h['Accept'] = 'text/html' h['accept'] = 'application/json' h['ACCEPT'] = 'application/xml' p h['accept']
执行这段代码后，h['accept']返回的是一个数组，内容依次为text/html、application/json和application/xml。可以看到，虽然三次赋值的键大小写各不相同，但都命中了同一个内部键，并且旧值没有被覆盖。如果后续需要发送请求，Faraday的不同适配器会采用不同策略来展开这个数组：有些适配器会把它用逗号连接成一个字符串，有些则会按照HTTP协议多次发送同名头。这个展开动作发生在适配器层，而不是在Utils::Headers内部。
需要注意的是，并非所有头都适合合并。例如Set-Cookie在响应头中有特殊的合并规则，不能简单用逗号连接，否则多个Cookie会被错误地合并成一个。虽然Utils::Headers统一按数组存储，但具体适配器在序列化时需要考虑每个头的特殊语义。如果你在自定义适配器中处理headers，应当根据头名称决定是逗号连接、分号连接还是逐条发送，避免产生不符合协议的数据。
在中间件与自定义适配器中的应用场景
Faraday的中间件链在请求发出前会多次调整请求头。假设一个中间件负责添加认证信息，它使用headers['Authorization'] = token，另一个中间件负责设置追踪ID，使用headers['X-Request-Id'] = id。如果使用了普通Hash，后续中间件可能因为大小写不同而看不到前序设置的头，导致重复或逻辑错误。使用Faraday::Utils::Headers后，所有中间件共享同一个大小写不敏感视图，修改和读取都基于统一的键规则，大幅降低了协作成本。
在编写自定义适配器时，你可能会直接接收到Faraday::Utils::Headers实例。适配器需要把它转换成底层HTTP库能够接受的头部结构。以Net::HTTP为例，它通常接受一个字符串键到字符串值的Hash，不支持数组值。这时你需要遍历headers，如果值是一个数组，则根据头的特性进行合并。以下是一个简单的转换示例，其中对大多数头使用逗号连接，对Set-Cookie则逐条添加。
def normalize_headers(faraday_headers)
headers = {}
faraday_headers.each do |name, value|
if value.is_a?(Array)
if name == 'Set-Cookie'
headers[name] = value
else
headers[name] = value.join(', ')
end
else
headers[name] = value
end
end
headers
end
这个示例展示了如何在适配器中处理重复头合并后的数组值：先判断是否为数组，再根据头名称决定是逗号连接还是保留为数组交给底层库处理。当然，实际适配器可能更复杂，但核心逻辑就是将Utils::Headers的大小写不敏感和数组值特性，转换为底层库期望的格式。理解了这一层，在排查头相关的问题时会清晰很多。
另外，如果你在项目中需要自己维护一套HTTP头结构，也可以直接继承或模仿Faraday::Utils::Headers来实现类似功能。但需要注意，内部转换键为小写的做法并不适用于所有场景，比如需要严格区分大小写的自定义协议头。因此在使用前应确认HTTP语义的适用性，不要盲目引入。
Ruby FaradayHTTP头处理重复头合并修改时间：2026-09-20 04:56:19