jakirhussainkhan/dev-skills

API 设计

选择合适的 API 类型

类型	最佳适用场景	避免使用场景
REST	公开 API、CRUD 操作、简单客户端、物联网	复杂的嵌套数据、频繁的模式迭代
GraphQL	移动应用、复杂嵌套数据、多客户端	简单的 CRUD 操作、不熟悉的小团队
tRPC	TypeScript 单体仓库、内部全栈 TypeScript API	非 TypeScript 客户端、公开 API
gRPC	高性能微服务通信、流式处理	浏览器客户端、简单用例

---

REST API 设计

URL 约定

GET    /users              ← 列表
GET    /users/{id}         ← 单个
POST   /users              ← 创建
PUT    /users/{id}         ← 替换
PATCH  /users/{id}         ← 部分更新
DELETE /users/{id}         ← 删除

# 嵌套资源
GET    /users/{id}/orders
POST   /users/{id}/orders

# 动作（当 REST 动词不够用时）
POST   /orders/{id}/cancel
POST   /users/{id}/activate

HTTP 状态码

状态码	使用场景
200	成功的 GET、PUT、PATCH 操作
201	成功的 POST 创建操作
204	成功的 DELETE 操作（无响应体）
400	验证失败、错误请求
401	缺少或无效的身份验证
403	已认证但未授权
404	资源未找到
409	冲突（重复、版本不匹配）
422	无法处理的实体（语义错误）
429	超出速率限制
500	意外的服务器错误

响应信封

// 集合
{
  "data": [...],
  "meta": { "total": 100, "page": 1, "perPage": 20 }
}

// 单个资源
{ "data": { "id": "1", "name": "James" } }

// 错误
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "验证失败",
    "details": [{ "field": "email", "issue": "格式无效" }]
  }
}

---

API 设计原则

版本控制策略

# URL 版本控制（最直观，最易路由）
/v1/users
/v2/users

# 头部版本控制（URL 更清晰）
Accept: application/vnd.api+json;version=2

切勿破坏现有客户端。先弃用，再移除。

分页

# 偏移量分页（简单，适合小数据集）
GET /posts?page=2&perPage=20

# 游标分页（大数据集快速，适用于无限滚动）
GET /posts?cursor=eyJpZCI6MTAwfQ&limit=20

过滤与排序

GET /orders?status=pending&userId=123
GET /products?sort=-price,name    # - 前缀表示降序
GET /products?fields=id,name,price  # 稀疏字段集

幂等性

# 为幂等的操作包含幂等键
POST /payments
Idempotency-Key: unique-client-generated-uuid

---

GraphQL 设计

模式设计规则

• 描述业务领域，而非数据库结构
• 使用连接模式处理列表（支持分页）
• 变更操作返回修改后的对象
• 对有限的值集合使用枚举
• 为所有类型和字段添加描述

type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: PaginationInput): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

---

API 安全清单

• 所有端点都需要身份验证（除非明确公开）
• 按资源检查授权，而非仅按路由
• 对所有端点进行速率限制，并在认证端点上更严格
• 对每个参数和请求体字段进行输入验证
• 除非明确需要，否则不返回敏感数据
• CORS 配置使用明确的允许列表
• 在公开 API 前定义好版本控制策略