Cache API 怎样用完整请求区分缓存条目

Cache API 出现“不同查询拿到了同一份响应”时，问题通常不是 Cache 把所有请求都混在了一起，而是代码在匹配时丢掉了查询维度。cache.match() 接收的是一个 URL 字符串或 Request，默认会考虑 URL 和请求方法；如果缓存响应带有 Vary，匹配还会比较其中声明的请求头。真正稳妥的做法，是把会影响响应内容的维度放进完整的 Request，再用默认匹配规则取回条目。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/Cache/match

本文只讨论 Request 和 Cache.match() 的匹配边界，不展开 Service Worker 的安装、激活和缓存版本清理。示例用“语言 + 商品页码”作为查询维度，重点是如何避免把 ?lang=zh&page=1 和 ?lang=en&page=1 当成同一条缓存。

先确定 Cache.match 的真实匹配范围

Cache.match(request) 默认返回第一个匹配的 Response，找不到时得到 undefined。可以传 URL 字符串，也可以传 Request；使用后者更容易把方法、凭据模式和查询参数放在一个明确的请求对象里。

默认匹配可以先记成三层：

• URL：查询串默认参与匹配，所以不同的 page 或 lang 不应被主动忽略。
• 方法：默认只接受正常的 GET/HEAD 匹配语义；不要用缓存去模拟任意带请求体的写操作。
• Vary：响应声明了 Vary: Accept-Language 时，同一 URL 还会按该请求头的值区分。

这也解释了一个常见误会：Cache API 不会自动把所有 Request 请求头都拼进缓存键。只有 URL、方法和响应 Vary 声明的请求头会进入默认匹配语义；业务上真正影响响应的维度，应该由 URL 查询参数或明确的服务器缓存协议表达出来。

把查询维度放进 Request

先定义一个只负责构造请求的函数。它不把完整 URL 截短成路径，也不把会影响结果的语言和分页信息藏在外部变量中。这样，写入和读取使用同一个 Request 形状，后续排查缓存命中时也能直接打印 request.url。

function createProductRequest({ lang, page }) {
  // URLSearchParams 负责编码查询参数，避免手写字符串时漏掉转义。
  const url = new URL("https://example.com/api/products");
  url.searchParams.set("lang", lang);
  url.searchParams.set("page", String(page));

  // 查询维度会改变响应内容，因此必须保留在 Request 的 URL 中。
  return new Request(url, {
    method: "GET",
    headers: { "Accept": "application/json" },
  });
}

async function readProductCache(cache, options) {
  const request = createProductRequest(options);
  // 不传 ignoreSearch，默认让不同查询字符串得到不同匹配结果。
  const cached = await cache.match(request);
  return { request, response: cached };
}

比如先用 createProductRequest({ lang: "zh", page: 1 }) 写入，再用 lang: "en" 查询，两个 URL 不同，默认就不会互相命中。相反，如果业务真的把查询参数视为无关信息，才应该显式使用 ignoreSearch: true；这不是提升命中率的通用开关，而是改变缓存身份的业务决策。

处理响应 Vary 与 put 的覆盖行为

如果响应内容由请求头决定，例如同一 URL 根据 Accept-Language 返回不同语言，服务端应返回对应的 Vary。Cache.match 默认会读取这个声明；如果代码传入 ignoreVary: true，就会跳过这一层比较，可能把错误语言的响应交给用户。

async function fetchAndStore(cache, request) {
  // 网络响应的 Vary 声明应由服务端产生，客户端不要静默忽略它。
  const response = await fetch(request);
  if (!response.ok) {
    // 4xx/5xx 是正常 Response，不会自动进入 fetch 的 catch。
    throw new Error(`请求失败：${response.status}`);
  }

  // put 会消费响应体，所以返回页面前要保留一份 clone。
  await cache.put(request, response.clone());
  return response;
}

async function getProduct(cache, options) {
  const { request, response: cached } = await readProductCache(cache, options);
  if (cached) {
    return { source: "cache", response: cached };
  }

  // 未命中时用同一个 Request 拉取并写回，避免读写键不一致。
  const response = await fetchAndStore(cache, request);
  return { source: "network", response };
}

Cache.put() 对同一匹配键再次写入时会覆盖原条目，因此请求构造必须稳定。如果一次用完整查询 URL 写入，另一次却只用路径读取，就会出现“明明写过但读不到”；反过来，如果写入时主动忽略查询，也可能让后写入的语言或页码覆盖先前的响应。

用命中和未命中指标复盘

只看最终页面很难判断缓存是否串数据。可以在缓存读取层记录请求 URL、命中来源和异常，然后用固定请求序列复盘。下面的指标不是浏览器性能基准，而是一次可重复的工程检查：同一查询第二次请求应命中，不同查询应分别经历一次未命中。

async function getProductWithMetrics(cache, options, metrics) {
  const { request, response: cached } = await readProductCache(cache, options);
  const key = request.url;

  if (cached) {
    // 记录完整 URL，排查时可以看出是哪一个查询发生了命中。
    metrics.hit += 1;
    metrics.byKey[key] = (metrics.byKey[key] ?? 0) + 1;
    return cached;
  }

  metrics.miss += 1;
  const response = await fetchAndStore(cache, request);
  metrics.network += 1;
  return response;
}

const metrics = { hit: 0, miss: 0, network: 0, byKey: {} };
// 固定序列：首次查询回源，重复查询命中，不同语言使用不同 URL。
await getProductWithMetrics(cache, { lang: "zh", page: 1 }, metrics);
await getProductWithMetrics(cache, { lang: "zh", page: 1 }, metrics);
await getProductWithMetrics(cache, { lang: "en", page: 1 }, metrics);
console.table(metrics);

这个序列的预期是两次未命中、一次命中、两次网络请求。若第三次英文请求却直接命中了中文条目，优先检查是否在别处把查询串删掉，或者是否给 match() 传了 ignoreSearch: true。若同一 URL 的不同语言仍然串数据，再检查响应的 Vary 是否包含实际参与内容协商的请求头，以及是否误用了 ignoreVary。

复查三个容易误用的选项

无条件使用 ignoreSearch。它会忽略 URL 查询部分。只有当查询参数确实不影响响应时才适合使用；搜索词、页码、筛选条件通常都不能忽略。

把 ignoreVary 当成修复手段。它只是跳过 Vary 请求头匹配，可能掩盖服务端内容协商的真实边界。正确做法是让响应声明正确的 Vary，客户端保持默认匹配。

用 ignoreMethod 解决缓存读不到。默认方法检查是在保护缓存语义，不是故障。读接口应使用 GET/HEAD；如果把 POST 的请求体也作为结果依据，不能只靠 ignoreMethod 把它伪装成普通 GET 缓存。

总结

Cache API 区分缓存条目的关键，不是把任意对象都当成自动缓存键，而是让缓存匹配规则与响应语义一致：保留会影响结果的完整 URL，使用稳定的 Request 进行读写，交给 Vary 表达请求头维度，默认不要打开 ignoreSearch、ignoreVary 和 ignoreMethod。最后用固定请求序列记录 hit、miss 和 network，才能快速发现错误复用。

相关问题

Cache.match 找不到刚 put 的条目怎么办？先比较写入和读取时的完整 URL、方法以及 Vary 相关请求头，最常见原因是两次构造的 Request 不一致。

不同查询参数一定会分成不同缓存吗？默认情况下查询串参与匹配，但如果显式设置 ignoreSearch，或在读写路径中自行删掉查询参数，就会改变这个结果。

Cache API 会自动缓存所有请求头吗？不会。默认匹配只在响应的 Vary 声明相关时比较请求头；其他业务维度应通过 URL 或明确的缓存协议表达。