一个可运行的 Node.js 实验:ETag 如何让重复 GET 返回 304

举报
yd_235245466 发表于 2026/11/05 08:36:26 2026/11/05
【摘要】 接口数据不常变化,但客户端仍需确认自己手里的内容是否最新:可以让服务端返回 ETag,客户端下次发送 If-None-Match。若 GET 对应的资源未改变,服务端返回 304 Not Modified,客户端沿用之前保存的内容;304 不包含响应体。[1]下面用 Node.js 内置模块启动仅监听本机的 HTTP 服务,在同一进程中模拟客户端、缓存和资源更新;无需安装第三方依赖或申请云资...

接口数据不常变化,但客户端仍需确认自己手里的内容是否最新:可以让服务端返回 ETag,客户端下次发送 If-None-Match。若 GET 对应的资源未改变,服务端返回 304 Not Modified,客户端沿用之前保存的内容;304 不包含响应体。[1]

下面用 Node.js 内置模块启动仅监听本机的 HTTP 服务,在同一进程中模拟客户端、缓存和资源更新;无需安装第三方依赖或申请云资源。测试环境:Windows 11 专业版 10.0.26200、Node.js v22.22.0 x64。本文使用 AI 辅助整理,示例已在上述环境运行核验。

完整示例

保存为 etag-demo.js,在安装 Node.js 22 的命令行运行 node etag-demo.js:

'use strict';

const http = require('node:http');
const { createHash } = require('node:crypto');
const assert = require('node:assert/strict');

let version = 1;

// 此演示只处理格式正确的 If-None-Match,不是通用 HTTP 解析器。
function matches(header, etag) {
  if (!header) return false;
  if (header.trim() === '*') return true;
  // 引号内允许逗号,因此不能简单地用 split(',')。
  const tags = header.match(/(?:W\/)?"[\x21\x23-\x7e\x80-\xff]*"/g) || [];
  return tags.some(tag => (tag.startsWith('W/') ? tag.slice(2) : tag) === etag);
}

const server = http.createServer((req, res) => {
  if (req.url !== '/article') {
    res.writeHead(404).end();
    return;
  }
  if (req.method !== 'GET') {
    res.writeHead(405, { Allow: 'GET' }).end();
    return;
  }

  const body = Buffer.from(JSON.stringify({ message: 'Hello cache', version }));
  const etag = '"sha256,' + createHash('sha256').update(body).digest('hex') + '"';
  const cacheHeaders = { ETag: etag, 'Cache-Control': 'no-cache' };

  if (matches(req.headers['if-none-match'], etag)) {
    res.writeHead(304, cacheHeaders).end();
    return;
  }
  res.writeHead(200, { ...cacheHeaders, 'Content-Type': 'application/json; charset=utf-8' });
  res.end(body);
});

function get(port, tag) {
  return new Promise((resolve, reject) => {
    const headers = tag === undefined ? {} : { 'If-None-Match': tag };
    http.get({ host: '127.0.0.1', port, path: '/article', headers }, res => {
      const chunks = [];
      res.on('data', chunk => chunks.push(chunk));
      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body: Buffer.concat(chunks) }));
      res.on('error', reject);
    }).on('error', reject);
  });
}

async function demo() {
  await new Promise((resolve, reject) => {
    server.once('error', reject);
    server.listen(0, '127.0.0.1', resolve);
  });
  try {
    const port = server.address().port;
    const first = await get(port);
    const etag = first.headers.etag;
    assert.equal(first.status, 200);
    assert.equal(first.body.toString(), '{"message":"Hello cache","version":1}');
    assert.equal(first.headers['cache-control'], 'no-cache');
    console.log(`首次 GET: ${first.status}; bodyBytes=${first.body.length}; ETag=${etag}`);

    const unchanged = await get(port, etag);
    assert.equal(unchanged.status, 304);
    assert.equal(unchanged.body.length, 0);
    assert.equal(unchanged.headers.etag, etag);
    assert.equal(unchanged.headers['cache-control'], 'no-cache');
    assert.ok(unchanged.headers.date);
    const usedBody = unchanged.status === 304 ? first.body : unchanged.body;
    const reused = usedBody === first.body;
    assert.equal(usedBody.toString(), '{"message":"Hello cache","version":1}');
    console.log(`匹配 ETag: ${unchanged.status}; bodyBytes=${unchanged.body.length}; 复用缓存=${reused}`);
    console.log(`缓存内容: ${usedBody.toString()}`);

    const weak = await get(port, `W/${etag}`);
    const list = await get(port, `"other,tag", ${etag}`);
    const wildcard = await get(port, '*');
    for (const item of [weak, list, wildcard]) {
      assert.equal(item.status, 304);
      assert.equal(item.body.length, 0);
    }
    console.log(`弱标签、含逗号列表、*: ${weak.status}, ${list.status}, ${wildcard.status}`);

    const mismatch = await get(port, '"old-version"');
    assert.equal(mismatch.status, 200);
    assert.deepEqual(mismatch.body, first.body);
    console.log(`不匹配 ETag: ${mismatch.status}`);

    version = 2; // 模拟资源更新;客户端仍使用旧 ETag。
    const changed = await get(port, etag);
    assert.equal(changed.status, 200);
    assert.notEqual(changed.headers.etag, etag);
    assert.equal(changed.body.toString(), '{"message":"Hello cache","version":2}');
    console.log(`更新后用旧 ETag: ${changed.status}; bodyBytes=${changed.body.length}; ETag 已变化=${changed.headers.etag !== etag}`);
  } finally {
    await new Promise((resolve, reject) => server.close(err => err ? reject(err) : resolve()));
  }
}

demo().catch(err => { console.error(err); process.exitCode = 1; });

脚本使用内置的 node:http 创建服务和发起请求;端口 0 让系统分配空闲端口,实验结束后关闭服务。[3] 本次实际运行结果:

首次 GET: 200; bodyBytes=37; ETag="sha256,bd94b57eb9e28f047214e9b6b312ca90b978727613256d338b69b9e4c78c6389"
匹配 ETag: 304; bodyBytes=0; 复用缓存=true
缓存内容: {"message":"Hello cache","version":1}
弱标签、含逗号列表、*: 304, 304, 304
不匹配 ETag: 200
更新后用旧 ETag: 200; bodyBytes=37; ETag 已变化=true

结果怎么看

  • 首次请求返回 200、JSON 和 ETag。示例根据实际 JSON 字节计算 SHA-256,并用带双引号、不带 W/ 的形式发出标签;其中 sha256, 仅是示例自定义的标签内容,不是协议要求。
  • 第二次携带同一个 ETag:服务端返回 304,响应体长度为 0;客户端代码显式使用首次请求保存的 first.body。304 没有带回一份新 JSON。
  • If-None-Match 使用弱比较,因此 W/ 加上相同的标签仍匹配。合法列表支持多个标签,标签引号内部本身也允许逗号,不能对头值盲目 split(',');值为 * 时,已有当前表示也会匹配。[1]
  • Cache-Control: no-cache 不是禁止保存:缓存可以保存,但复用前需要成功验证。需要禁止缓存存储时,应考虑 no-store,并按业务确定其他策略。[2]
  • 将 version 改为 2 后,即使请求仍携带旧标签,也会得到新的 200、响应体和 ETag。304 省去的是响应体传输,不是一次网络往返,也不必然省去服务端生成或计算哈希的成本。

使用边界

示例只覆盖单一 GET 资源、合法的 If-None-Match 和无压缩 JSON;没有实现完整 HTTP 条件请求、畸形头解析、HEAD、If-Modified-Since 或写入方法的并发控制,不能直接作为生产中间件。生产中建议使用成熟框架的条件请求实现,并在可复用时预计算版本或哈希。若根据语言、压缩等协商返回不同表示,强 ETag 应与实际表示一致,并正确设置 Vary;涉及用户或敏感数据时,也要结合认证和 private、no-store 等缓存策略,避免共享缓存泄露。[1][2]

Sources

[1] RFC 9110, HTTP Semantics,第 8.8、13.1.2 和 15.4.5 节。
[2] RFC 9111, HTTP Caching,第 5.2 节。
[3] Node.js 22 官方文档,HTTP、Net 和 Crypto 模块。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。