assign042-idem-1788856435
Alice
a8c741a9d7
- 实现 Express.js 幂等键中间件，支持 Idempotency-Key 请求头 - 缓存成功响应（2xx）24小时，重复请求直接返回缓存结果 - 处理并发重复请求（in-flight 去重） - 错误响应不缓存，允许客户端重试 - 实现 POST /api/orders 订单创建端点演示幂等性 - 添加 7 组共 21 个测试用例，全部通过
64 行
1.9 KiB
Markdown
64 行
1.9 KiB
Markdown
# 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 请求不受影响
|
||
- ✅ 完整的测试覆盖
|
||
|
||
## 安装与运行
|
||
|
||
```bash
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
服务器将在 http://localhost:3000 启动。
|
||
|
||
## API 使用
|
||
|
||
### 创建订单（POST /api/orders）
|
||
|
||
首次请求：
|
||
```bash
|
||
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` - 健康检查
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
npm test
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/
|
||
├── server.js # Express 服务器入口
|
||
├── idempotency.js # 幂等键中间件实现
|
||
└── routes/
|
||
└── orders.js # 订单路由
|
||
tests/
|
||
└── test-idempotency.js # 幂等性测试用例
|
||
```
|