代码概述
该代码实现了一个带内存缓存、超时控制与指数退避重试的 fetch 封装函数 fetchWithRetry。其特性包括：
- 请求超时通过 AbortController 实现
- 对临时性错误（如 408/429/5xx）进行指数退避 + 抖动的重试
- 成功响应可按 TTL 进行内存缓存（按 method + url + body 作为键）
- 自动根据 Content-Type 解析 JSON 或文本
- 非成功响应（非可重试）会抛出包含 status 与响应文本的错误对象
核心注释
// 基于内存的简单缓存：key 为请求签名，value 为 { expireAt: 过期时间戳(ms), data: 解析后的响应数据 }
const cache = new Map();
/**
* 生成缓存键：由 HTTP 方法、URL 与请求体组成，确保相同请求命中缓存
* - 对字符串类型的 body 原样使用
* - 对非字符串 body 使用 JSON.stringify；若为 falsy 值（如 0/false/null/undefined），会被当作空字符串序列化
*/
function cacheKey(url, options) {
const { method = 'GET', body } = options || {};
// 注意：body || '' 会将 0/false 等值归一为空串，可能导致不同 falsy 值共享同一键
return method + ' ' + url + ' ' + (typeof body === 'string' ? body : JSON.stringify(body || ''));
}
/**
* 带重试、超时与可选缓存的 fetch 包装器
* @param {string} url - 请求地址
* @param {Object} [opts={}] - 配置项
* @param {number} [opts.retries=3] - 最大重试次数（不含初始尝试，总尝试 = retries + 1）
* @param {number} [opts.retryDelay=300] - 初始退避延迟（毫秒），随尝试次数指数级增长
* @param {number} [opts.timeout=8000] - 单次请求超时时间（毫秒）
* @param {number} [opts.jitter=0.25] - 抖动比例（0~1），用于在退避延迟上增加随机扰动
* @param {number} [opts.cacheTTL=0] - 缓存存活时间（毫秒），0 表示不缓存
* @param {string} [opts.method='GET'] - HTTP 方法
* @param {HeadersInit} [opts.headers] - 请求头
* @param {BodyInit} [opts.body] - 请求体
* @returns {Promise<any>} - 解析后的响应数据（JSON 或文本）
* @throws {Error} - 超时、中断、不可重试的 HTTP 错误，或最终重试失败
*/
export async function fetchWithRetry(url, opts = {}) {
const {
retries = 3, // 最大重试次数（指数退避适用）
retryDelay = 300, // 初始退避基准（ms）
timeout = 8000, // 单次请求超时（ms）
jitter = 0.25, // 抖动比例（±jitter 区间）
cacheTTL = 0, // 缓存时长（ms），0 表示禁用缓存
method = 'GET', // HTTP 方法
headers, // 请求头，原样传递给 fetch
body // 请求体，原样传递给 fetch
} = opts;
// 基于方法、URL、body 生成缓存键（只针对成功响应缓存）
const key = cacheKey(url, { method, body });
// 命中缓存且未过期则直接返回
if (cacheTTL > 0 && cache.has(key)) {
const { expireAt, data } = cache.get(key);
if (Date.now() < expireAt) return data; // 缓存未过期
cache.delete(key); // 过期即清理
}
let attempt = 0; // 当前尝试次数，从 0 起；总尝试次数最多为 retries + 1
let lastErr; // 记录最后一次错误以便最终抛出
// 注意：实际退出由条件判断与抛错控制，while 作为尝试框架
while (attempt <= retries) {
// 为本次尝试创建可中止控制器，用于超时
const ac = new AbortController();
// 到达超时阈值则中止请求；AbortError 将被统一转换为超时错误信息
const id = setTimeout(() => ac.abort(new Error('timeout')), timeout);
try {
// 发起请求；headers 与 body 透传，不做方法-体校验（允许 GET 携带 body）
const res = await fetch(url, {
method,
headers,
body,
signal: ac.signal
});
clearTimeout(id); // 请求完成即清理超时定时器（无论成功与否）
// 非 2xx/3xx 视为失败
if (!res.ok) {
// 对临时性错误码进行重试：408(请求超时)、429(限流) 与常见 5xx
if ([408, 429, 500, 502, 503, 504].includes(res.status) && attempt < retries) {
// 指数退避：base = retryDelay * 2^attempt
const base = retryDelay * Math.pow(2, attempt);
// 全抖动：rand ∈ [1 - jitter, 1 + jitter]
const rand = 1 + (Math.random() * 2 - 1) * jitter;
// 等待退避时间后重试
await new Promise(r => setTimeout(r, base * rand));
attempt++;
continue; // 继续下一次尝试
}
// 不可重试或已达最大次数：读取响应文本用于错误信息补充
const text = await res.text().catch(() => '');
const error = new Error('HTTP ' + res.status + ' ' + res.statusText);
error.status = res.status; // 附加状态码
error.body = text; // 附加响应体文本（便于诊断）
throw error;
}
// 按内容类型解析响应体：JSON 优先，否则按文本处理
const ct = res.headers.get('content-type') || '';
const data = ct.includes('application/json') ? await res.json() : await res.text();
// 成功响应可写入缓存（仅缓存解析后的数据）
if (cacheTTL > 0) {
cache.set(key, { expireAt: Date.now() + cacheTTL, data });
}
return data; // 返回解析结果
} catch (err) {
clearTimeout(id); // 异常时同样清理超时定时器
// 将 AbortError 归一化为可读的超时错误信息
lastErr = err.name === 'AbortError' ? new Error('Request timeout') : err;
// 若已达最大重试次数，则抛出最后的错误
if (attempt >= retries) throw lastErr;
// 其他错误（网络错误、超时等）同样走指数退避重试
const base = retryDelay * Math.pow(2, attempt);
const rand = 1 + (Math.random() * 2 - 1) * jitter;
await new Promise(r => setTimeout(r, base * rand));
attempt++;
}
}
// 理论上不应到达此处；兜底抛出最后记录的错误
throw lastErr;
}
技术要点
- 最大尝试次数：总尝试 = retries + 1（初始尝试 + retries 次重试），attempt 从 0 递增。
- 重试条件：
- HTTP 状态码为 408/429/500/502/503/504 且尚未达到最大重试次数。
- 网络错误、超时（AbortError 被归一化为 "Request timeout"）等异常。
- 指数退避与抖动：
- 基础延迟 base = retryDelay × 2^attempt。
- 抖动因子 rand = 1 + U(-jitter, +jitter)，实际等待 = base × rand，减少同质化重试风暴。
- 超时控制：每次尝试使用独立 AbortController；超时触发后中止 fetch 并清理定时器。
- 缓存策略：
- 仅缓存成功响应的解析结果（JSON 对象或文本字符串），不缓存 Response 对象及其头部。
- 缓存键包含 method、url 与 body，其中：
- 字符串 body 原样参与键计算；
- 非字符串 body 通过 JSON.stringify(body || '') 参与，故 0/false/null/undefined 等 falsy 会被视作空串的序列化，可能共享同一键。
- cacheTTL 为毫秒级绝对过期时间（expireAt = Date.now() + cacheTTL）。
- 响应解析：当 Content-Type 包含 application/json 时按 JSON 解析，否则按文本解析。
- 错误信息：对于不可重试的 HTTP 响应，抛出的 Error 附带 status 与 body，便于定位问题。
- 选项透传：headers 与 body 原样传递，不对方法与请求体的搭配进行约束处理。
使用示例
const data = await fetchWithRetry('https://api.example.com/users', {
cacheTTL: 5000, // 缓存 5s
retries: 2, // 最多重试 2 次（总尝试 3 次）
timeout: 4000 // 单次超时 4s
});
// data 为 JSON 或文本，取决于响应 Content-Type
const result = await fetchWithRetry('https://api.example.com/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username: 'alice', password: 'secret' }),
retries: 4, // 更高的重试上限
retryDelay: 500, // 初始退避 500ms
jitter: 0.3, // 30% 抖动
timeout: 6000 // 6s 超时
});
