概念概述
CDN 边缘缓存（Edge Caching at the CDN）指的是：边缘缓存把响应存储在靠近用户的 CDN 节点，降低延迟与回源负载，但要求谨慎的缓存键与显式失效策略。
从更严格的定义看，Edge caching is the practice of storing responses at points of presence near end users so subsequent requests are answered without reaching the origin server. 该概念在工程实践中的价值，在于它能帮助团队用统一的语言描述一个具体的质量属性或设计约束，从而在评审与协作中减少歧义。
为什么需要它
It is applied to static assets, public API responses, and any content that many users request identically. 它与 Request Deduplication、Cache-Control Directives、Cache Key Normalisation 等概念经常一起出现，用于解决相近的工程问题。理解它的适用场景，有助于在多种备选方案之间做出有依据的取舍，而不是凭直觉选择技术方案。
常见误解
- every response can be cached at the edge safely
- purging a URL removes all of its variants at once
需要避免的反模式
- caching personalised responses under a key that omits the user
- relying only on time-based expiry to remove changed content
实践要点
- Correctness depends on the cache key, so responses that vary by header, cookie, or geography must either make that variance part of the key or be marked private.
- Invalidation is harder at the edge than in a single cache, so explicit purge by tag or surrogate key is usually more reliable than waiting for expiry.
- Stale-while-revalidate lets an edge serve a slightly old copy while fetching a fresh one in the background, hiding origin latency from users during revalidation.
参考来源
https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching
代码示例
interface CacheEntry<T> {
value: T;
expiresAt: number;
}
function Cached<T>(ttlMs: number) {
return function (
target: object,
propertyKey: string,
descriptor: TypedPropertyDescriptor<(...args: never[]) => Promise<T>>,
) {
const original = descriptor.value!;
const store = new Map<string, CacheEntry<T>>();
descriptor.value = async function (this: unknown, ...args: never[]) {
const key = propertyKey + ':' + JSON.stringify(args);
const hit = store.get(key);
const now = Date.now();
if (hit && hit.expiresAt > now) {
(this as { __cacheHits?: number }).__cacheHits ??= 0;
return hit.value;
}
const value = await original.apply(this, args);
store.set(key, { value, expiresAt: now + ttlMs });
return value;
};
return descriptor;
};
}
class ExchangeRates {
private hits = 0;
@Cached(30_000)
async ratesFor(base: string): Promise<Record<string, number>> {
const res = await fetch('https://api.example.com/rates?base=' + base);
return res.json();
}
@Cached(300_000)
async currencies(): Promise<string[]> {
return ['USD', 'EUR', 'JPY'];
}
}
const rates = new ExchangeRates();
const first = await rates.ratesFor('USD');
const second = await rates.ratesFor('USD');
console.log('cached identity:', first === second);import { createHash } from "node:crypto";
function getHeader(headers, name) {
const key = Object.keys(headers).find(
(candidate) => candidate.toLowerCase() === name,
);
return key === undefined ? undefined : headers[key];
}
function requireNonNegativeInteger(value, label) {
if (!Number.isInteger(value) || value < 0) {
throw new RangeError(`${label} must be a non-negative integer`);
}
}
export function createEtag(body, options = {}) {
if (typeof body !== "string" && !Buffer.isBuffer(body)) {
throw new TypeError("body must be a string or Buffer");
}
const { weak = false } = options;
const digest = createHash("sha256")
.update(body)
.digest("base64url")
.slice(0, 27);
return `${weak ? "W/" : ""}"${digest}"`;
}
export function buildCacheControl(options = {}) {
const {
visibility = "public",
maxAge = 0,
sharedMaxAge,
staleWhileRevalidate,
immutable = false,
} = options;
if (visibility !== "public" && visibility !== "private") {
throw new RangeError("visibility must be public or private");
}
requireNonNegativeInteger(maxAge, "maxAge");
const directives = [visibility, `max-age=${maxAge}`];
if (sharedMaxAge !== undefined) {
requireNonNegativeInteger(sharedMaxAge, "sharedMaxAge");
directives.push(`s-maxage=${sharedMaxAge}`);
}
if (staleWhileRevalidate !== undefined) {
requireNonNegativeInteger(staleWhileRevalidate, "staleWhileRevalidate");
directives.push(`stale-while-revalidate=${staleWhileRevalidate}`);
}
if (immutable) {
if (maxAge === 0) {
throw new RangeError("immutable requires maxAge greater than zero");
}
directives.push("immutable");
}
return directives.join(", ");
}
export function cacheHeaders(options = {}) {
const {
body,
maxAge = 0,
visibility = "public",
lastModified,
weak = false,
staleWhileRevalidate,
} = options;
if (body === undefined) {
throw new TypeError("body is required");
}
const headers = {
"Cache-Control": buildCacheControl({
visibility,
maxAge,
staleWhileRevalidate,
}),
ETag: createEtag(body, { weak }),
};
if (lastModified !== undefined) {
const date = new Date(lastModified);
if (Number.isNaN(date.getTime())) {
throw new RangeError("lastModified must be a valid date");
}
headers["Last-Modified"] = date.toUTCString();
}
return headers;
}
function opaqueTag(tag) {
return tag.trim().replace(/^W\//i, "");
}
export function evaluateConditionalRequest(
method,
requestHeaders = {},
responseHeaders = {},
) {
const normalizedMethod =
typeof method === "string" ? method.toUpperCase() : "";
if (normalizedMethod !== "GET" && normalizedMethod !== "HEAD") {
return { status: 200, headers: { ...responseHeaders } };
}
const etag = getHeader(responseHeaders, "etag");
const lastModified = getHeader(responseHeaders, "last-modified");
const cacheControl = getHeader(responseHeaders, "cache-control");
const ifNoneMatch = getHeader(requestHeaders, "if-none-match");
let notModified = false;
if (ifNoneMatch !== undefined && etag !== undefined) {
const candidates = ifNoneMatch.split(",").map((tag) => tag.trim());
notModified =
candidates.includes("*") ||
candidates.some((tag) => opaqueTag(tag) === opaqueTag(etag));
} else {
const ifModifiedSince = getHeader(requestHeaders, "if-modified-since");
if (ifModifiedSince !== undefined && lastModified !== undefined) {
const since = Date.parse(ifModifiedSince);
const modified = Date.parse(lastModified);
if (!Number.isNaN(since) && !Number.isNaN(modified)) {
notModified =
Math.floor(modified / 1000) <= Math.floor(since / 1000);
}
}
}
if (!notModified) {
return { status: 200, headers: { ...responseHeaders } };
}
const headers = {};
if (etag !== undefined) headers.ETag = etag;
if (cacheControl !== undefined) headers["Cache-Control"] = cacheControl;
if (lastModified !== undefined) headers["Last-Modified"] = lastModified;
return { status: 304, headers };
}
const body = JSON.stringify({ items: [1, 2, 3] });
const headers = cacheHeaders({
body,
maxAge: 60,
staleWhileRevalidate: 30,
lastModified: "2026-10-21T10:00:00Z",
});
console.log(headers);
console.log(evaluateConditionalRequest("GET", {}, headers).status);
console.log(
evaluateConditionalRequest("GET", { "if-none-match": headers.ETag }, headers)
.status,
);
console.log(
evaluateConditionalRequest(
"GET",
{ "if-modified-since": headers["Last-Modified"] },
headers,
).status,
);
console.log(
evaluateConditionalRequest("POST", { "if-none-match": headers.ETag }, headers)
.status,
);