httpx 是 Ruby 社区里一个纯 Ruby 实现的 HTTP 客户端，支持 HTTP/1.1、HTTP/2 和 HTTP/3。它的插件体系中，ResponseCache 插件让客户端具备了类似浏览器缓存的行为：命中缓存时直接返回缓存的响应对象，不发真实网络请求。而这个插件的缓存键生成逻辑中，HTTPX::Plugins::ResponseCache::KeyGenerator::Headers 扮演着关键角色。很多使用者在接入这个插件后发现缓存“有时命中有时不命中”，问题多半出在对 Headers 参与键生成的规则理解不到位。本文就来把这个类的行为彻底讲清楚。
一、Headers 类在缓存键生成中的职责
先看插件的整体结构。ResponseCache::KeyGenerator 是一个可被替换的模块，它对外暴露一个方法，接收请求对象（Request）并返回一个字符串作为缓存键。默认实现大致是把请求方法、请求路径和经过筛选的请求头拼接起来。Headers 类正是这个拼接过程中处理请求头的那一层。
它的核心职责可以概括为三点：第一，决定哪些请求头有资格参与缓存键的计算；第二，对参与的头名做归一化处理，避免大小写差异导致本应相同的请求生成不同的键；第三，配合响应中的 Vary 头，动态调整下一轮请求的键生成规则。下面这段简化代码展示了它的基本形态：
module HTTPX
module Plugins
module ResponseCache
module KeyGenerator
class Headers
def initialize(request)
@request = request
@headers = request.headers
end
# 筛选出参与缓存键计算的请求头
def cacheable_headers
@headers.select { |k, _| IMPORTANT_HEADERS.include?(k.downcase) }
end
end
end
end
end
end注意 httpx 内部的 Headers 对象本身就对头名做了大小写无关的处理，所以第二点其实是由底层 Headers 类保证的。真正需要开发者关心的是第一点和第三点，也就是筛选规则和 Vary 机制，下面分别展开。
二、哪些请求头会进入缓存键，为什么这样设计
如果对所有请求头一视同仁地拼进缓存键，会带来灾难性的后果。想象一个场景：你的应用每次请求都会带上时间戳性质的请求头，或者带上一个逐次变化的 Authorization token。这样的键每次都不同，缓存等于完全失效，还白白消耗内存。
所以默认实现里只挑选了语义上会影响响应内容的头，典型的包括 Accept、Accept-Encoding、Accept-Language 等内容协商相关的头。服务端确实会根据这些头返回不同格式的响应，比如同一个 URL，Accept-Encoding: gzip 和不带压缩的请求拿到的响应体不同，如果缓存键忽略这一点，客户端就可能把 gzip 响应体当成未压缩的返回给上层处理逻辑，直接导致解压失败。
反过来，像 User-Agent、Connection 这类头默认被排除。它们绝大多数情况下不影响响应内容，把它们纳入键只会让缓存碎片化。当然也存在例外：某些服务端确实会根据 User-Agent 返回不同内容，这时就需要依赖 Vary 机制或者自定义 KeyGenerator 来补充，稍后会讲。
三、Vary 头如何动态影响 Headers 的键生成
HTTP 协议中的 Vary 响应头由服务端下发，表示“这个响应的内容会随某些请求头的值变化”。比如响应头 Vary: User-Agent 意味着服务端针对不同 UA 返回了不同内容。缓存层如果忽略 Vary，就会把给 A 浏览器的响应错误地返回给 B 浏览器。
httpx 的处理思路是：第一次请求时，Headers 按默认规则生成键，拿到响应后解析 Vary 头，记录下“这个资源额外依赖哪些请求头”。下一次请求同一资源时，KeyGenerator 会把这些额外的头也纳入计算。用代码模拟这个流程：
def next_key(vary_header)
extra = vary_header.to_s.split(",").map(&:strip).map(&:downcase)
base_headers = cacheable_headers
extra_headers = @headers.select { |k, _| extra.include?(k.downcase) }
(base_headers.to_a + extra_headers.to_a).sort.join("|")
end这里有一个容易踩的坑：如果服务端返回 Vary: *，语义上表示“响应受更多无法枚举的因素影响”，严格来说缓存层应该放弃缓存这个响应。httpx 对这种情况的处理是将其视为不可缓存，如果你在自建 KeyGenerator 时忽略了 Vary 的检查，就可能缓存了不该缓存的内容。排查这类问题的方法是打印每次生成的键，确认键的组成部分是否符合预期：
session = HTTPX.plugin(:response_cache)
session = session.with(headers: { "accept" => "application/json" })
response = session.get("https://ipipp.com/api/data")
p response.headers["vary"] # 查看服务端声明了哪些变化维度四、自定义 KeyGenerator 与 Headers 的实践方案
httpx 允许你整体替换 KeyGenerator，这在以下场景很有用：服务端没有正确设置 Vary 但确实按某些自定义头（比如 X-Client-Version）返回不同内容；或者你希望键里加入租户信息做多租户缓存隔离。做法是通过 response_cache_key_generator 选项注入自己的对象：
class TenantAwareKeyGenerator
def call(request)
tenant = request.headers["x-tenant-id"] || "default"
base = "#{request.verb}:#{request.uri}:#{tenant}"
# 复用默认的 Headers 逻辑处理内容协商头
headers_part = request.headers
.select { |k, _| %w[accept accept-encoding accept-language].include?(k) }
.sort.map { |k, v| "#{k}=#{v}" }.join("&")
"#{base}|#{headers_part}"
end
end
session = HTTPX.plugin(:response_cache)
.with(response_cache_key_generator: TenantAwareKeyGenerator.new)这个自定义类需要响应 call 方法并接受请求对象。实践中建议保留对 Accept 系列头的处理，因为内容协商错误是缓存类 bug 里最难排查的一种——症状往往是线上偶发的乱码或解析异常，而不是明显的报错。
最后提醒两点：一是缓存键的稳定性依赖请求头的稳定性，如果你在中间件里随机注入头，先检查它是否参与键生成；二是缓存失效判断（Expires、Cache-Control）是 ResponseCache 插件的另一部分逻辑，与 KeyGenerator 无关，不要把“键相同但响应已过期”误判为键生成问题。理解了 Headers 的取舍逻辑，你就能准确预测每一次请求是否会命中缓存，让这个插件真正发挥价值。
RubyHTTPX ResponseCache缓存KeyGenerator修改时间：2026-09-09 10:37:07