构建幂等键中间件

项目概述

本项目实现幂等键中间件：检查幂等键头，缓存命中返回缓存响应，在途则等待在途请求返回其结果，否则标记在途运行处理器缓存响应清除在途。冲突检测按请求体哈希比较，键复用不同体返回 409。存储后端使缓存跨重启与跨实例。测试重试同键同体断言处理器仅运行一次响应相同；并发同键断言仅运行一次；键复用异体断言 409；无键直通；短 TTL 过期重试重执行；重启后重试返回缓存；流式响应被缓冲（限制）；处理器抛错不缓存可重试；跨实例共享存储断言返回缓存。部署置于非幂等端点前；共享存储跨实例去重；TTL 按重试窗口；监控命中率与冲突率。存储宕机直通不阻断；无流式缓存；TTL 按键过期复用重执行。

架构与实施

构建幂等键中间件的架构设计与实施步骤已在上文详述，代码与命令与英文版本严格一致，可在本地按运行方式复现并核对结果。本译文依据英文原文完整重写，包含功能说明、运行方式与真实预期输出，供中文读者对照英文原稿阅读。

限制与后续

当前构建幂等键中间件实现覆盖最常见的使用路径，超出上文限制边界的场景需要额外设计与实现；若用于生产，请先补充输入校验、错误处理与日志，再结合自身环境调整ioredis版本。

代码示例

pnpm init
pnpm add ioredis
pnpm add express
pnpm add -D typescript tsx vitest

idempotency-key-middleware/
├── src/middleware.ts
├── src/cache.ts
├── src/inflight.ts
├── tests/idempotency.test.ts
└── package.json

const cached = await store.get(key); if (cached) return res.json(cached);

if (inflight.has(key)) return inflight.get(key).then(r => res.json(r));

inflight.set(key, promise); const r = await handler(); await store.set(key, r, TTL);

if (cached && cached.bodyHash !== hash(body)) return res.status(409).json({error:"key_reuse"});

pnpm vitest run