api-designlisted

# API Design — API 设计技能 根据业务需求设计专业级 API，输出 OpenAPI 3.0 规范。 ## Goal 根据业务需求设计 RESTful/GraphQL API，输出 OpenAPI 规范文档。包含路由设计、请求/响应 Schema、错误码体系、版本策略 ## Trigger - 用户要求"设计API"、"定义接口"、"写API文档" - 需要从数据库 Schema 推导 API 端点 - 需要统一团队 API 规范 ## 工作流程 ``` 业务需求 → 资源识别 → 路由设计 → Schema 定义 → 错误码 → 输出规范 ``` ## Step 1: 资源识别 从需求中提取核心资源： | 维度 | 分析内容 | |------|----------| | 名词提取 | 需求中的业务实体（用户、订单、商品...） | | 关系映射 | 资源间的一对一、一对多、多对多关系 | | 操作识别 | CRUD + 业务动作（下单、支付、审核...） | | 权限模型 | 谁能对什么资源做什么操作 | ## Step 2: 路由设计 遵循 RESTful 规范： ``` GET /api/v1/{resources} # 列表查询 POST /api/v1/{resources} # 创建资源 GET /api/v1/{resources}/{id} # 获取详情 PUT /api/v1/{resources}/{id} # 全量更新 PATCH /api/v1/{resources}/{id} # 部分更新 DELETE /api/v1/{resources}/{id} # 删除资源 ``` **嵌套资源**： ``` GET /api/v1/users/{id}/orders # 用户的订单列表 ``` **业务动作**： ``` POST /api/v1/orders/{id}/submit # 提交订单 POST /api/v1/orders/{id}/cancel # 取消订单 ``` ### 设计原则 | 原则 | 说明 | 示例 | |------|------|------| | 名词复数 | 资源用复数形式 | `/users` 不是 `/user` | | 层级清晰 | 最多嵌套2层 | `/users/{id}/orders` ✓ | | | | `/users/{id}/orders/{oid}/items/{iid}` ✗ | | 小写连字符 | 多单词用连字符 | `/user-profiles` | | 动词后置 | 业务动作用 POST + 动词 | `POST /orders/{id}/refund` | ## Step 3: 请求/响应 Schema ### 请求体设计 ```yaml CreateUserRequest: type: object required: [email, name] properties: email: type: string format: email description: 用户邮