assign042-idem - 幂等键（Idempotency Key）中间件

基于 Express.js 的幂等键中间件实现，确保重复请求不会产生重复副作用。

什么是幂等性？

幂等性是指同一个请求执行一次和执行多次的效果相同。在 HTTP API 中，GET、PUT、DELETE 等方法天然幂等，但 POST 方法不是。使用幂等键（Idempotency Key）可以让 POST 请求也具备幂等性：客户端在请求头中携带唯一的 Idempotency-Key，服务器缓存该键对应的响应，重复请求直接返回缓存结果。

功能特性

• ✅ 基于 Idempotency-Key 请求头的幂等性保证
• ✅ 自动缓存成功响应（2xx），缓存有效期 24 小时
• ✅ 处理并发重复请求（in-flight 去重）
• ✅ 不缓存错误响应（4xx/5xx），允许重试
• ✅ GET/HEAD/OPTIONS 请求不受影响
• ✅ 完整的测试覆盖

安装与运行

npm install
npm start

服务器将在 http://localhost:3000 启动。

API 使用

创建订单（POST /api/orders）

首次请求：

curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-$(date +%s)" \
  -d '{"customerId":"cust-1","items":[{"productId":"prod-1","quantity":2,"price":25}]}'

重复使用相同的 Idempotency-Key 发送请求，将返回第一次的结果，不会重复创建订单。响应会包含 X-Idempotency-Replay: true 头标识这是重放响应。

查询订单

• GET /api/orders - 列出所有订单
• GET /api/orders/:id - 按 ID 查询订单
• GET /health - 健康检查

测试

npm test

项目结构

src/
├── server.js          # Express 服务器入口
├── idempotency.js     # 幂等键中间件实现
└── routes/
    └── orders.js      # 订单路由
tests/
└── test-idempotency.js # 幂等性测试用例