API合约设计

⭐⭐⭐ 中级 | 设计清晰、一致、易用的API接口

好的API设计应该考虑：

1. 资源模型 - 用什么来表示数据
2. 操作定义 - 支持什么操作
3. 请求/响应 - 数据格式和结构
4. 错误处理 - 错误返回方式
5. 版本管理 - 如何兼容旧版本
6. 安全性 - 认证、授权、速率限制

🎯 原则1: RESTful原则

• 使用标准HTTP方法（GET、POST、PUT、DELETE）
• 资源用名词表示（/users，不是/getUsers）
• 无状态设计
• 使用HTTP状态码传达结果

🎯 原则2: 版本管理

• URL中包含版本（/v1/users）
• 或在header中指定版本
• 制定deprecation策略
• 提前通知用户下线时间

🎯 原则3: 向后兼容

• 添加字段不破坏旧客户端
• 删除字段需要deprecation期
• 改变字段含义需要新版本
• 提供迁移指南

🎯 原则4: 一致的设计

• 命名规范（camelCase或snake_case）
• 分页方式统一
• 错误响应格式统一
• 时间戳格式统一（ISO 8601）

模式1: RESTful API设计

Prompt:

请为我的[业务实体]设计RESTful API。

实体：[实体名]
属性：[属性列表]
主要操作：[CRUD操作说明]

需要考虑：
1. 所有支持的端点（资源+方法）
2. 请求体格式（示例）
3. 响应体格式（成功和错误）
4. HTTP状态码
5. 分页（如果有列表）
6. 过滤和排序（如果需要）
7. 认证方式

请提供：
1. API规范（OpenAPI/Swagger）
2. 请求/响应示例
3. 错误处理方案

模式2: GraphQL API设计

Prompt:

请为我设计GraphQL API。

数据模型：
- User (id, name, email, posts)
- Post (id, title, content, author)

需要的查询：
1. 获取用户信息
2. 获取用户的所有文章
3. 获取文章及其作者

需要的mutations：
1. 创建用户
2. 创建文章
3. 更新文章

请提供：
1. Schema定义
2. Query和Mutation示例
3. 订阅示例（如果适用）

模式3: 错误处理设计

Prompt:

设计一致的API错误响应格式。

需要处理的错误类型：
1. 验证错误（400）
2. 认证错误（401）
3. 授权错误（403）
4. 找不到资源（404）
5. 冲突（409）
6. 服务器错误（500）

错误响应应该包含：
1. 错误代码（便于程序化处理）
2. 可读的消息（给用户看）
3. 细节信息（便于调试）
4. 建议的修正方式

请设计标准的错误响应格式。

• 开始实现 → T02: Feature Implementation
• API需要安全审查 → T11: Security Review