Applicable Scenarios
- Request field design for endpoints
- Response field definitions
- Writing validation rules
- Field naming conventions
Core Principles
1. 字段稳定性
公开字段一旦发布不能轻易改语义
能扩展,不能删
2. 字段含义清晰
命名见名知意,不需要查文档
-
Consistent naming Use the same style across the entire API (snake_case or camelCase)
-
Do not return sensitive information by default Password hashes, internal IDs, and debug information are not returned by default
## 请求结构
### Path 参数(资源标识)
```text
GET /users/{user_id}/orders/{order_id}
- user_id: string (UUID)
- order_id: string (UUID)
Query Parameters (filtering/pagination/options)
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 (cross-cutting information)
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 (creating/modifying data)
POST /users
Content-Type: application/json
{
"email": "user@example.com",
"name": "张三",
"phone": "+8613800138000",
"metadata": {
"source": "web"
}
}
Validation Rules
Each field must define:
- 类型(string / integer / boolean / array / object)
- 必填 / 可选
- 长度限制(min/max)
- 范围限制(min/max for numbers)
- 格式(email / url / uuid / date / regex)
- 枚举值
- 默认值(如有)
- 跨字段规则(如 password === password_confirm)
OpenAPI Validation Example
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
Response Structure
Single Resource Response
{
"id": "usr_abc123",
"email": "user@example.com",
"name": "张三",
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
List Response (recommended structure)
{
"data": [
{ "id": "usr_001", "name": "张三" },
{ "id": "usr_002", "name": "李四" }
],
"pagination": {
"page": 1,
"page_size": 20,
"total": 156,
"total_pages": 8
}
}
Nested Relationships (avoid excessive nesting)
{
"id": "ord_001",
"user": {
"id": "usr_123",
"name": "张三"
},
"items": [
{ "id": "itm_001", "product_id": "prd_a", "quantity": 2 }
],
"total": 199.50,
"status": "paid"
}
Do not exceed 3 levels of nesting; for anything deeper, use an ID + a separate GET.
Field Naming Conventions
风格选一种坚持:
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
Field Stability Strategy
新增字段(兼容):
- 客户端忽略未知字段
- 老客户端不受影响
删除字段(不兼容):
- 必须升级版本
- 不能直接删
改字段类型(不兼容):
- 必须升级版本
改字段语义(不兼容):
- 必须升级版本
- 即使字段名不变
废弃字段:
- 在响应中保留但标注 deprecated
- 提供新字段
- 在 OpenAPI 文档标注
Output Format
## 请求响应:POST /users
### 请求
**Headers**:
Authorization: Bearer Content-Type: application/json Idempotency-Key:
**Body**:
```json
{
"email": "user@example.com",
"name": "张三",
"phone": "+8613800138000"
}
Field Definitions:
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
| string | ✅ | email format, max 100 | ||
| name | string | ✅ | 1~50 chars | Name |
| phone | string | ❌ | E.164 format | Phone number |
Response (success 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"
}
Field Descriptions:
| Field | Type | Description |
|---|---|---|
| id | string | User ID (usr_ prefix) |
| status | enum | active / inactive / banned |
| created_at | ISO 8601 | UTC time |
## 工作流程
```text
1. 读取端点清单(来自 endpoint-design)
2. 对每个端点定义请求结构
3. 定义所有字段的类型 / 校验
4. 定义响应结构(成功 + 失败)
5. 检查字段命名一致性
6. 检查时间格式 / 布尔 / 枚举规范
7. 输出请求响应说明
Quality Self-Check
□ 字段命名风格一致(不混用 snake/camel)
□ 时间字段 ISO 8601 + UTC
□ 布尔用 true/false 不用 1/0
□ 枚举用字符串不用数字
□ 必填字段标注清楚
□ 校验规则完整(类型/长度/范围/格式)
□ 响应不返回敏感字段(密码哈希等)
□ 列表响应有分页信息
□ 嵌套不超过 3 层
Common Pitfalls
- Mixed naming——createdAt and created_at appear at the same time
- Inconsistent time formats——some are Unix timestamps, some are ISO 8601
- Booleans using 1/0——increases client parsing cost
- Returning only id after POST——forces the frontend to GET again
- List without total——the frontend cannot paginate precisely
- Sensitive field leakage——password_hash is in the response
- Field names are not self-explanatory——data1 / val / field2
- Excessive nesting——5 levels of nesting, difficult for the frontend to parse
Supporting Templates
templates/request-response-template.md— Request structure + response structure + validation rules template
Collaboration with Other Skills
上游:
endpoint-design → 提供端点清单
resource-modeling → 提供资源结构
平行:
error-handling → 错误响应结构
pagination-filtering → 列表响应结构
下游:
openapi-mock → 写入 OpenAPI Schema
Related References
references/request-response-guide.md— Naming styles, field type conventions, standard fields, unified list/error structures, field stability, optional fields vs null, validation rules, examples from major companies (Stripe Charge / GitHub Issue)