一个可运行的 Node.js 实验:ETag 如何让重复 GET 返回 304
接口数据不常变化,但客户端仍需确认自己手里的内容是否最新:可以让服务端返回 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 模块。
- 点赞
- 收藏
- 关注作者
评论(0)