Request Queue ESM v0.1.0

一个可发布的 ESM 请求队列库，默认提供 Axios 门面，同时通过 Transport 防腐层支持替换为 Fetch 或其他请求库。

当前版本：v0.1.0。相对 0.0.2 的主要变化：核心模块拆分、Fetch Cookie 凭据与持久化缓存隔离、getKeyContext 用户隔离约定、子路径 TypeScript 可继承声明、validateStatus 与更完整的测试与文档。详见 CHANGELOG.md。

能力

• 相同请求 single-flight 合并：多个逻辑调用共享一次物理 HTTP 请求。
• GET、HEAD 默认合并；POST、PUT、PATCH、DELETE 默认独立。
• 每个调用方拥有独立 Promise、取消状态和逻辑 traceId。
• 合并后的每个逻辑调用独立 timeout；最后一个订阅者离开后才中断物理请求。
• 最后一个订阅者取消后才中断物理请求；正在 abort 的旧任务会立即与新请求隔离，并最多保留 30 秒诊断记录。
• 并发数、请求优先级、可选的优先级老化。
• 请求级缓存开关、TTL、物理保留时间、强制回源。
• join-first 与 cache-first 两种运行中请求策略。
• 缓存写入屏障、写入版本控制、删除/清空防回写。
• 默认返回 response.data.data，可返回 response.data 或统一响应对象。
• 内存、LocalStorage、IndexedDB、Redis 缓存适配器。
• Axios 与 Fetch Transport；可自行实现其他 HTTP 客户端适配器。

快速开始

npm install @wwchao6411/request-queue axios

import axios from 'axios';
import {
  createAxiosRequestQueue,
  MemoryCacheStore
} from '@wwchao6411/request-queue';

const axiosInstance = axios.create({
  baseURL: '/api',
  timeout: 15_000
});

export const requestQueue = createAxiosRequestQueue({
  axiosInstance,
  cacheStore: new MemoryCacheStore(),
  queueOptions: {
    maxConcurrent: 6,
    defaultCacheTTL: 60_000,
    defaultInFlightPolicy: 'join-first',
    getKeyContext: () => ({
      token: localStorage.getItem('token'),
      tenantId: localStorage.getItem('tenantId')
    })
  }
});

const users = await requestQueue.get('/users', {
  params: { page: 1 },
  cache: true,
  cacheTTL: 30_000
});

完整配置、竞态语义、缓存适配器、Transport 防腐层和全部示例见：使用说明.md。默认最多排队 200 个物理任务；可通过 maxQueueSize 调整或设为 Infinity。队列暂停期间，新物理任务也受该上限限制。

Authorization、Cookie、X-Auth-Token、X-Access-Token、X-Api-Key 与 X-Tenant-Id 都会参与默认合并键，用于隔离不同身份或租户的请求；若由 Axios interceptor 注入，还应通过 getKeyContext 同步提供给队列。

持久化缓存默认不会保存包含 Authorization、Cookie、X-Auth-Token、X-Access-Token、X-Api-Key 的请求，也不会保存 withCredentials: true 或 Fetch credentials: 'include' | 'same-origin' 的请求（浏览器可能自动带 Cookie）。Axios defaults 与 Fetch defaultHeaders 也会参与该判断。Cookie 值无法进入 merge/cache 键：使用 Cookie 会话时，必须通过 getKeyContext 提供 userId / sessionId 等身份，否则内存缓存仍可能跨用户命中。Axios interceptor 后置注入的认证信息无法自动识别，应禁用持久化缓存或在入队前提供认证头。可用 sensitiveHeaderNames 仅扩展保护集合；只有在确认响应不含敏感数据时，才传入 allowSensitiveCache: true 显式允许。

timeout 是每个逻辑调用从创建时开始计算的 deadline，包含排队与缓存读取。相同请求即使合并为一个物理 HTTP 请求，也会分别超时：某一调用超时不会影响其他订阅者；只有最后一个订阅者离开时才中断物理请求。timeout 不再参与自动 merge/cache 键。

取消仍会 reject RequestCancelledError；逻辑超时会 reject RequestTimeoutError。库已为未消费的取消 rejection 添加内部观察，不会触发运行时未处理拒绝。30 秒 aborting 追踪仅清理诊断统计，不会强制终止不合作的 Transport。

测试

npm test

当前包含 71 个测试，覆盖合并、逻辑调用独立 timeout、取消隔离、缓存 TTL、写入屏障、乱序响应、失效栅栏、默认认证头隔离、Fetch/Axios Cookie 凭据与缓存隔离、getKeyContext 用户隔离、interceptor 后置鉴权、Axios/Fetch Transport、Redis 缓存、validateStatus、子路径 TypeScript 继承、cacheStore 校验与 cacheErrorMode 等。