wehub-skill-sync
445 lines
14 KiB
Markdown
445 lines
14 KiB
Markdown
---
|
||
name: fullstack-dev-api-design
|
||
description: "API 设计模式与最佳实践。适用于创建端点、选择方法/状态码、实现分页或编写 OpenAPI 规范。可避免常见的 REST/GraphQL/gRPC 错误。"
|
||
license: MIT
|
||
metadata:
|
||
version: "2.0.0"
|
||
sources:
|
||
- Microsoft REST API Guidelines
|
||
- Google API Design Guide
|
||
- Zalando RESTful API Guidelines
|
||
- JSON:API Specification
|
||
- RFC 9457 (Problem Details for HTTP APIs)
|
||
- RFC 9110 (HTTP Semantics)
|
||
---
|
||
|
||
# API 设计指南
|
||
|
||
面向后端与全栈工程师的框架无关 API 设计指南。涵盖 10 大类共 50 余条规则，按影响程度排序。覆盖 REST、GraphQL 和 gRPC。
|
||
|
||
## 适用范围
|
||
|
||
**使用此技能的场景：**
|
||
- 设计新 API 或添加端点
|
||
- 审查 API 拉取请求
|
||
- 在 REST / GraphQL / gRPC 之间做选择
|
||
- 编写 OpenAPI 规范
|
||
- 迁移或对现有 API 进行版本管理
|
||
|
||
**不适用的场景：**
|
||
- 框架特定的实现细节（请使用对应框架的技能/文档）
|
||
- 前端数据获取模式（请使用 React Query / SWR 文档）
|
||
- 认证实现细节（请使用认证库的文档）
|
||
- 数据库 schema 设计（→ `database-schema-design`）
|
||
|
||
## 所需上下文
|
||
|
||
在应用此技能前，请收集以下信息：
|
||
|
||
| 必填项 | 可选项 |
|
||
|----------|----------|
|
||
| 目标消费者（浏览器、移动端、服务） | 项目中已有的 API 约定 |
|
||
| 预期请求量（RPS 预估） | 当前的 OpenAPI / Swagger 规范 |
|
||
| 认证方式（JWT、API Key、OAuth） | 限流需求 |
|
||
| 数据模型 / 领域实体 | 缓存策略 |
|
||
|
||
---
|
||
|
||
## 快速开始清单
|
||
|
||
新建 API 端点？写代码前逐一检查：
|
||
|
||
- [ ] 资源命名为**复数名词**（`/orders`，而不是 `/getOrders`）
|
||
- [ ] URL 使用**短横线命名**，请求体字段使用**驼峰命名**
|
||
- [ ] 使用正确的 **HTTP 方法**（GET=读取，POST=创建，PUT=全量替换，PATCH=部分更新，DELETE=删除）
|
||
- [ ] 使用正确的**状态码**（201 Created、422 Validation、404 Not Found……）
|
||
- [ ] 错误响应遵循 **RFC 9457** 格式
|
||
- [ ] 所有列表端点实现**分页**（默认 20，最多 100）
|
||
- [ ] 要求**认证**（Bearer Token，而非查询参数）
|
||
- [ ] 响应头中包含**请求 ID**（`X-Request-Id`）
|
||
- [ ] 包含**限流**响应头
|
||
- [ ] 端点已在 **OpenAPI 规范**中记录
|
||
|
||
---
|
||
|
||
## 快速导航
|
||
|
||
| 需要…… | 跳转至 |
|
||
|----------|---------|
|
||
| 命名资源 URL | [1. 资源建模](#1-资源建模关键) |
|
||
| 选择 HTTP 方法与状态码 | [3. HTTP 方法与状态码](#3-http-方法与状态码关键) |
|
||
| 格式化错误响应 | [4. 错误处理](#4-错误处理高优先级) |
|
||
| 添加分页或过滤 | [6. 分页与过滤](#6-分页与过滤高优先级) |
|
||
| 选择 API 风格（REST vs GraphQL vs gRPC） | [10. API 风格决策](#10-api-风格决策树) |
|
||
| 对现有 API 进行版本管理 | [7. 版本管理](#7-版本管理中高优先级) |
|
||
| 避免常见错误 | [反模式清单](#反模式清单) |
|
||
|
||
---
|
||
|
||
## 1. 资源建模（关键）
|
||
|
||
### 核心规则
|
||
|
||
```
|
||
✅ /users — 复数名词
|
||
✅ /users/{id}/orders — 1 层嵌套
|
||
✅ /reviews?orderId={oid} — 使用查询参数展平深层嵌套
|
||
|
||
❌ /getUsers — URL 中包含动词
|
||
❌ /user — 单数
|
||
❌ /users/{uid}/orders/{oid}/items/{iid}/reviews — 超过 3 层嵌套
|
||
```
|
||
|
||
**最大嵌套层级：2 层。** 超过此限制时，提升为顶层资源并通过过滤参数查询。
|
||
|
||
### 领域对齐
|
||
|
||
资源映射到**领域概念**，而非数据库表：
|
||
|
||
```
|
||
✅ /checkout-sessions （领域聚合）
|
||
✅ /shipping-labels （领域概念）
|
||
|
||
❌ /tbl_order_header （数据库表泄露）
|
||
❌ /join_user_role （内部 schema 泄露）
|
||
```
|
||
|
||
---
|
||
|
||
## 2. URL 与命名（关键）
|
||
|
||
| 上下文 | 规范 | 示例 |
|
||
|---------|-----------|---------|
|
||
| URL 路径 | 短横线命名 | `/order-items` |
|
||
| JSON 请求体字段 | 驼峰命名 | `{ "firstName": "Jane" }` |
|
||
| 查询参数 | 驼峰命名或下划线命名（保持一致） | `?sortBy=createdAt` |
|
||
| 请求头 | 连字符大写命名 | `X-Request-Id` |
|
||
|
||
**Python 例外：** 如果整个技术栈都是 Python/下划线命名，可以在 JSON 中使用 `snake_case`——但必须在**所有端点间保持一致**。
|
||
|
||
```
|
||
✅ GET /users ❌ GET /users/
|
||
✅ GET /reports/annual ❌ GET /reports/annual.json
|
||
✅ POST /users ❌ POST /users/create
|
||
```
|
||
|
||
---
|
||
|
||
## 3. HTTP 方法与状态码（关键）
|
||
|
||
### 方法语义
|
||
|
||
| 方法 | 语义 | 幂等 | 安全 | 请求体 |
|
||
|--------|-----------|-----------|------|-------------|
|
||
| GET | 读取 | ✅ | ✅ | ❌ 从不 |
|
||
| POST | 创建 / 动作 | ❌ | ❌ | ✅ 始终 |
|
||
| PUT | 全量替换 | ✅ | ❌ | ✅ 始终 |
|
||
| PATCH | 部分更新 | ❌* | ❌ | ✅ 始终 |
|
||
| DELETE | 删除 | ✅ | ❌ | ❌ 极少 |
|
||
|
||
### 状态码快速参考
|
||
|
||
**成功类：**
|
||
|
||
| 状态码 | 使用时机 | 响应体 |
|
||
|------|------|--------------|
|
||
| 200 OK | GET、PUT、PATCH 成功 | 资源 / 结果 |
|
||
| 201 Created | POST 创建了资源 | 已创建的资源 + `Location` 请求头 |
|
||
| 202 Accepted | 异步操作已启动 | 任务 ID / 状态 URL |
|
||
| 204 No Content | DELETE 成功、PUT 无请求体 | 无 |
|
||
|
||
**客户端错误类：**
|
||
|
||
| 状态码 | 使用时机 | 关键区别 |
|
||
|------|------|-----------------|
|
||
| 400 Bad Request | 语法格式错误 | 无法解析 |
|
||
| 401 Unauthorized | 缺少或无效的认证凭据 | "你是谁？" |
|
||
| 403 Forbidden | 已认证但无权限 | "我认识你，但不行" |
|
||
| 404 Not Found | 资源不存在 | 也可用于隐藏 403 |
|
||
| 409 Conflict | 重复、版本不匹配 | 状态冲突 |
|
||
| 422 Unprocessable | 语法正确但验证失败 | 语义错误 |
|
||
| 429 Too Many Requests | 触发限流 | 包含 `Retry-After` |
|
||
|
||
**服务端错误类：** 500（意外错误）、502（上游失败）、503（过载）、504（上游超时）
|
||
|
||
---
|
||
|
||
## 4. 错误处理（高优先级）
|
||
|
||
### 标准错误格式（RFC 9457）
|
||
|
||
所有错误响应均使用此格式：
|
||
|
||
```json
|
||
{
|
||
"type": "https://api.example.com/errors/insufficient-funds",
|
||
"title": "余额不足",
|
||
"status": 422,
|
||
"detail": "账户余额 $10.00 低于提现金额 $50.00。",
|
||
"instance": "/transactions/txn_abc123",
|
||
"request_id": "req_7f3a8b2c",
|
||
"errors": [
|
||
{ "field": "amount", "message": "超出余额", "code": "INSUFFICIENT_BALANCE" }
|
||
]
|
||
}
|
||
```
|
||
|
||
### 多语言实现
|
||
|
||
**TypeScript（Express）：**
|
||
```typescript
|
||
class AppError extends Error {
|
||
constructor(
|
||
public readonly title: string,
|
||
public readonly status: number,
|
||
public readonly detail: string,
|
||
public readonly code: string,
|
||
) { super(detail); }
|
||
}
|
||
|
||
// 中间件
|
||
app.use((err, req, res, next) => {
|
||
if (err instanceof AppError) {
|
||
return res.status(err.status).json({
|
||
type: `https://api.example.com/errors/${err.code}`,
|
||
title: err.title, status: err.status,
|
||
detail: err.detail, request_id: req.id,
|
||
});
|
||
}
|
||
res.status(500).json({ title: '内部错误', status: 500, request_id: req.id });
|
||
});
|
||
```
|
||
|
||
**Python（FastAPI）：**
|
||
```python
|
||
from fastapi import Request
|
||
from fastapi.responses import JSONResponse
|
||
|
||
class AppError(Exception):
|
||
def __init__(self, title: str, status: int, detail: str, code: str):
|
||
self.title, self.status, self.detail, self.code = title, status, detail, code
|
||
|
||
@app.exception_handler(AppError)
|
||
async def app_error_handler(request: Request, exc: AppError):
|
||
return JSONResponse(status_code=exc.status, content={
|
||
"type": f"https://api.example.com/errors/{exc.code}",
|
||
"title": exc.title, "status": exc.status,
|
||
"detail": exc.detail, "request_id": request.state.request_id,
|
||
})
|
||
```
|
||
|
||
### 铁律
|
||
|
||
```
|
||
✅ 所有错误均返回 RFC 9457 错误格式
|
||
✅ 每个错误响应都包含 request_id
|
||
✅ 字段级验证错误在 `errors` 数组中返回
|
||
|
||
❌ 绝不在生产环境暴露堆栈信息
|
||
❌ 绝不为错误返回 200 状态码
|
||
❌ 绝不静默吞掉错误
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 认证与授权（高优先级）
|
||
|
||
```
|
||
✅ Authorization: Bearer eyJhbGci... （请求头）
|
||
❌ GET /users?token=eyJhbGci... （URL——会出现在日志中）
|
||
|
||
✅ 401 → "你是谁？" （缺少或无效的凭据）
|
||
✅ 403 → "你不能这样做" （已认证，无权限）
|
||
✅ 404 → 隐藏资源存在性 （需要时用来替代 403）
|
||
```
|
||
|
||
**限流响应头（始终包含）：**
|
||
```
|
||
X-RateLimit-Limit: 100
|
||
X-RateLimit-Remaining: 42
|
||
X-RateLimit-Reset: 1625097600
|
||
Retry-After: 30
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 分页与过滤（高优先级）
|
||
|
||
### 游标分页 vs 偏移分页
|
||
|
||
| 策略 | 适用场景 | 优点 | 缺点 |
|
||
|----------|------|------|------|
|
||
| **游标分页**（推荐） | 大型/动态数据集 | 数据一致，无跳变 | 无法跳转到第 N 页 |
|
||
| **偏移分页** | 小型/稳定数据集、管理后台 | 简单，支持页面跳转 | 插入/删除时数据漂移 |
|
||
|
||
**游标分页响应：**
|
||
```json
|
||
{
|
||
"data": [...],
|
||
"pagination": { "next_cursor": "eyJpZCI6MTIwfQ", "has_more": true }
|
||
}
|
||
```
|
||
|
||
**偏移分页响应：**
|
||
```json
|
||
{
|
||
"data": [...],
|
||
"pagination": { "page": 3, "per_page": 20, "total": 256, "total_pages": 13 }
|
||
}
|
||
```
|
||
|
||
**始终执行：** 默认 20 条，最多 100 条。
|
||
|
||
### 标准过滤模式
|
||
|
||
```
|
||
GET /orders?status=shipped&created_after=2025-01-01&sort=-created_at&fields=id,status
|
||
```
|
||
|
||
| 模式 | 规范 |
|
||
|---------|-----------|
|
||
| 精确匹配 | `?status=shipped` |
|
||
| 范围查询 | `?price_gte=10&price_lte=100` |
|
||
| 日期范围 | `?created_after=2025-01-01&created_before=2025-12-31` |
|
||
| 排序 | `?sort=field`（升序）、`?sort=-field`（降序） |
|
||
| 稀疏字段 | `?fields=id,name,email` |
|
||
| 搜索 | `?q=搜索+关键词` |
|
||
|
||
---
|
||
|
||
## 7. 版本管理（中高优先级）
|
||
|
||
| 策略 | 格式 | 最佳适用 |
|
||
|----------|--------|----------|
|
||
| **URL 路径**（推荐） | `/v1/users` | 公开 API |
|
||
| **请求头** | `Api-Version: 2` | 内部 API |
|
||
| **查询参数** | `?version=2` | 遗留系统（避免使用） |
|
||
|
||
**非破坏性变更（无需升级版本号）：** 新增可选的响应字段、新增端点、新增可选参数。
|
||
|
||
**破坏性变更（需新版本）：** 删除/重命名字段、更改类型、收紧验证规则、删除端点。
|
||
|
||
**弃用响应头：**
|
||
```
|
||
Sunset: Sat, 01 Mar 2026 00:00:00 GMT
|
||
Deprecation: true
|
||
Link: <https://api.example.com/v2/users>; rel="successor-version"
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 请求/响应设计（中优先级）
|
||
|
||
### 统一的响应格式
|
||
|
||
```json
|
||
{
|
||
"data": { "id": "ord_123", "status": "pending", "total": 99.50 },
|
||
"meta": { "request_id": "req_abc123", "timestamp": "2025-06-15T10:30:00Z" }
|
||
}
|
||
```
|
||
|
||
### 关键规则
|
||
|
||
| 规则 | 正确 | 错误 |
|
||
|------|---------|-------|
|
||
| 时间戳 | `"2025-06-15T10:30:00Z"`（ISO 8601） | `"06/15/2025"` 或 `1718447400` |
|
||
| 公开 ID | UUID `"550e8400-..."` | 自增 `42` |
|
||
| Null 与缺省（PATCH） | `{ "nickname": null }` = 清空字段 | 缺省字段 = 不做更改 |
|
||
| HATEOAS（公开 API） | `"links": { "cancel": "/orders/123/cancel" }` | 无可发现性 |
|
||
|
||
---
|
||
|
||
## 9. 文档——OpenAPI（中优先级）
|
||
|
||
**设计优先的工作流程：**
|
||
|
||
```
|
||
1. 编写 OpenAPI 3.1 规范
|
||
2. 与相关方审查规范
|
||
3. 生成服务端桩代码 + 客户端 SDK
|
||
4. 实现处理器
|
||
5. 在 CI 中对照规范验证响应
|
||
```
|
||
|
||
每个端点均需记录：摘要、所有参数、请求体及示例、所有响应码及 schema、认证要求。
|
||
|
||
---
|
||
|
||
## 10. API 风格决策树
|
||
|
||
```
|
||
什么样的 API？
|
||
│
|
||
├─ 浏览器 + 移动端客户端，需要灵活查询
|
||
│ └─ GraphQL
|
||
│ 规则：DataLoader（避免 N+1）、深度限制 ≤7、Relay 分页
|
||
│
|
||
├─ 标准 CRUD，面向公开消费者，缓存很重要
|
||
│ └─ REST（本指南）
|
||
│ 规则：资源、HTTP 方法、状态码、OpenAPI
|
||
│
|
||
├─ 服务间通信，高吞吐量，强类型
|
||
│ └─ gRPC
|
||
│ 规则：Protobuf schema、大数据流式传输、截止时间
|
||
│
|
||
├─ 全栈 TypeScript，同一团队拥有客户端和服务端
|
||
│ └─ tRPC
|
||
│ 规则：共享类型，无需代码生成
|
||
│
|
||
└─ 实时双向通信
|
||
└─ WebSocket / SSE
|
||
规则：心跳、重连、消息排序
|
||
```
|
||
|
||
---
|
||
|
||
## 反模式清单
|
||
|
||
| # | ❌ 不要这样做 | ✅ 应该这样做 |
|
||
|---|---------|--------------|
|
||
| 1 | URL 中包含动词（`/getUser`） | HTTP 方法 + 名词资源 |
|
||
| 2 | 错误时返回 200 | 正确的 4xx/5xx 状态码 |
|
||
| 3 | 混合使用多种命名风格 | 每个上下文保持一种规范 |
|
||
| 4 | 暴露数据库 ID | 使用 UUID 作为公开标识符 |
|
||
| 5 | 列表不进行分页 | 始终分页（默认 20 条） |
|
||
| 6 | 静默吞掉错误 | 结构化的 RFC 9457 错误 |
|
||
| 7 | Token 放在 URL 查询参数中 | Authorization 请求头 |
|
||
| 8 | 深层嵌套（3 层以上） | 使用查询参数展平 |
|
||
| 9 | 破坏性变更不升级版本 | 保持兼容或使用版本管理 |
|
||
| 10 | 不设限流 | 实现限流并通过请求头告知 |
|
||
| 11 | 无请求 ID | 每个响应都包含 `X-Request-Id` |
|
||
| 12 | 生产环境暴露堆栈信息 | 安全的错误消息 + 内部日志 |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 问题 1："这应该是新资源还是子资源？"
|
||
|
||
**现象：** URL 路径不断增长（`/users/{id}/orders/{id}/items/{id}/reviews`）
|
||
|
||
**规则：** 如果子实体本身有意义，则提升为顶层资源。如果它只在父级上下文中存在，则保持嵌套（最多 2 层）。
|
||
|
||
```
|
||
/reviews?orderId=123 ✅ （reviews 独立存在）
|
||
/orders/{id}/items ✅ （items 属于 orders，1 层）
|
||
```
|
||
|
||
### 问题 2："PUT 还是 PATCH？"
|
||
|
||
**现象：** 团队对更新语义无法达成一致。
|
||
|
||
**规则：**
|
||
- PUT = 客户端发送**完整**资源（缺失字段 → 设为默认值/null）
|
||
- PATCH = 客户端只发送**发生变化的字段**（缺失字段 → 保持不变）
|
||
- 不确定时 → **PATCH**（更安全，更少意外）
|
||
|
||
### 问题 3："400 还是 422？"
|
||
|
||
**现象：** 验证错误码不一致。
|
||
|
||
**规则：**
|
||
- 400 = 完全无法解析请求（格式错误的 JSON、错误的 content-type）
|
||
- 422 = 解析成功，但值未通过验证（无效的 email、负数数量）
|