请求响应结构
适用场景
- 端点的请求字段设计
- 响应字段定义
- 校验规则编写
- 字段命名规范
核心原则
1. 字段稳定性
公开字段一旦发布不能轻易改语义
能扩展，不能删
2. 字段含义清晰
命名见名知意，不需要查文档
3. 命名一致
全 API 用同一种风格（snake_case 或 camelCase）
4. 默认不返回敏感信息
密码哈希、内部 ID、调试信息默认不返回
请求结构
Path 参数（资源标识）
GET /users/{user_id}/orders/{order_id}
- user_id: string (UUID)
- order_id: string (UUID)
Query 参数（筛选/分页/选项）
GET /users?page=1&page_size=20&status=active&sort=-created_at
- page: integer, default=1
- page_size: integer, default=20, max=100
- status: enum [active, inactive, banned]
- sort: string, prefix - means desc
- keyword: string, optional
Header（横切信息）
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
Idempotency-Key: <uuid> # POST 时
X-Request-Id: <trace-id> # 追踪
If-Match: "<etag>" # 并发控制
Accept-Language: zh-CN
Body（创建/修改数据）
POST /users
Content-Type: application/json
{
"email": "user@example.com",
"name": "张三",
"phone": "+8613800138000",
"metadata": {
"source": "web"
}
}
校验规则
每个字段必须定义：
- 类型（string / integer / boolean / array / object）
- 必填 / 可选
- 长度限制（min/max）
- 范围限制（min/max for numbers）
- 格式（email / url / uuid / date / regex）
- 枚举值
- 默认值（如有）
- 跨字段规则（如 password === password_confirm）
OpenAPI 校验示例
properties:
email:
type: string
format: email
minLength: 5
maxLength: 100
required: true
age:
type: integer
minimum: 0
maximum: 150
required: false
status:
type: string
enum: [active, inactive, banned]
default: active
tags:
type: array
items:
type: string
minItems: 0
maxItems: 10
uniqueItems: true
响应结构
单资源响应
{
"id": "usr_abc123",
"email": "user@example.com",
"name": "张三",
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
列表响应（推荐结构）
{
"data": [
{ "id": "usr_001", "name": "张三" },
{ "id": "usr_002", "name": "李四" }
],
"pagination": {
"page": 1,
"page_size": 20,
"total": 156,
"total_pages": 8
}
}
嵌套关系（避免过度嵌套）
{
"id": "ord_001",
"user": {
"id": "usr_123",
"name": "张三"
},
"items": [
{ "id": "itm_001", "product_id": "prd_a", "quantity": 2 }
],
"total": 199.50,
"status": "paid"
}
不要超过 3 层嵌套，超过用 ID + 单独 GET。
字段命名规范
风格选一种坚持：
snake_case：created_at, user_id, total_amount（推荐，可读性强）
camelCase：createdAt, userId, totalAmount
ID 字段：
- 前缀化：usr_abc123 / ord_xyz789（Stripe 风格）
- 或纯 UUID：550e8400-e29b-41d4-a716-446655440000
时间字段：
- 永远 ISO 8601 + UTC：2026-01-15T10:30:00Z
- 不要 Unix 时间戳（除非性能极致需求）
- 不要本地时间（时区混乱）
布尔字段：
- is_active / has_subscription（is/has 前缀）
- 不要 active = 1（混淆类型）
枚举：
- 字符串：status: "active"
- 不要数字：status: 1
字段稳定性策略
新增字段（兼容）：
- 客户端忽略未知字段
- 老客户端不受影响
删除字段（不兼容）：
- 必须升级版本
- 不能直接删
改字段类型（不兼容）：
- 必须升级版本
改字段语义（不兼容）：
- 必须升级版本
- 即使字段名不变
废弃字段：
- 在响应中保留但标注 deprecated
- 提供新字段
- 在 OpenAPI 文档标注
输出格式
## 请求响应：POST /users
### 请求
**Headers**：
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <uuid>
**Body**：
```json
{
"email": "user@example.com",
"name": "张三",
"phone": "+8613800138000"
}
字段定义：
| 字段 | 类型 | 必填 | 校验 | 说明 |
|---|---|---|---|---|
| string | ✅ | email format, max 100 | 邮箱 | |
| name | string | ✅ | 1~50 chars | 姓名 |
| phone | string | ❌ | E.164 format | 手机号 |
响应（成功 201）
{
"id": "usr_abc123",
"email": "user@example.com",
"name": "张三",
"phone": "+8613800138000",
"status": "active",
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 用户 ID（usr_ 前缀） |
| status | enum | active / inactive / banned |
| created_at | ISO 8601 | UTC 时间 |
## 工作流程
```text
1. 读取端点清单（来自 endpoint-design）
2. 对每个端点定义请求结构
3. 定义所有字段的类型 / 校验
4. 定义响应结构（成功 + 失败）
5. 检查字段命名一致性
6. 检查时间格式 / 布尔 / 枚举规范
7. 输出请求响应说明
质量自检
□ 字段命名风格一致（不混用 snake/camel）
□ 时间字段 ISO 8601 + UTC
□ 布尔用 true/false 不用 1/0
□ 枚举用字符串不用数字
□ 必填字段标注清楚
□ 校验规则完整（类型/长度/范围/格式）
□ 响应不返回敏感字段（密码哈希等）
□ 列表响应有分页信息
□ 嵌套不超过 3 层
常见坑
- 命名混用——createdAt 和 created_at 同时出现
- 时间格式不一——有的 Unix 时间戳，有的 ISO 8601
- 布尔用 1/0——增加客户端解析成本
- POST 后只返回 id——前端被迫再 GET
- 列表无 total——前端无法精确分页
- 敏感字段泄露——password_hash 在响应里
- 字段命名不见名知意——data1 / val / field2
- 过度嵌套——5 层嵌套，前端解析困难
配套模板
templates/request-response-template.md— 请求结构 + 响应结构 + 校验规则模板
与其他 skill 的协作
上游：
endpoint-design → 提供端点清单
resource-modeling → 提供资源结构
平行：
error-handling → 错误响应结构
pagination-filtering → 列表响应结构
下游：
openapi-mock → 写入 OpenAPI Schema
相关参考
references/request-response-guide.md— 命名风格、字段类型规范、标准字段、列表/错误统一结构、字段稳定性、可选字段 vs null、校验规则、大厂示例（Stripe Charge / GitHub Issue）
