项目文件夹

文件

T

Alice a8c741a9d7 feat: 实现幂等键（Idempotency Key）中间件

- 实现 Express.js 幂等键中间件，支持 Idempotency-Key 请求头
- 缓存成功响应（2xx）24小时，重复请求直接返回缓存结果
- 处理并发重复请求（in-flight 去重）
- 错误响应不缓存，允许客户端重试
- 实现 POST /api/orders 订单创建端点演示幂等性
- 添加 7 组共 21 个测试用例，全部通过

2026-09-08 17:06:01 +08:00

1.9 KiB

原始文件 永久链接 Blame 文件历史

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 # 幂等性测试用例

1.9 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape