API 设计知识库
一、API 设计核心原则
| 原则 | 说明 | 示例 |
|---|
| 简单易用 | 接口语义清晰，符合直觉 | 使用标准 HTTP 方法，避免自定义动词 |
| 一致性 | 所有接口遵循相同的设计规范 | 统一命名风格（如驼峰或下划线）、统一错误格式 |
| 无状态 | 每个请求包含所有必要信息，不依赖服务端存储上下文 | 使用 Token 认证，不在服务端保存 Session |
| 向后兼容 | 旧版客户端不因接口更新而失效 | 使用版本控制、只增不删、可选字段设计 |
| 可发现性 | 接口结构让开发者容易理解和使用 | 合理使用 HTTP 状态码，提供 OpenAPI 文档 |
二、RESTful API 设计规范
1. 资源命名
| 规范 | 正确示例 | 错误示例 |
|---|
| 使用名词而非动词 | POST /users | POST /createUser |
| 使用复数形式 | GET /users/123 | GET /user/123 |
| 使用小写字母 + 连字符 | /user-profiles | /userProfiles 或 /user_profiles |
| 使用嵌套表示关联 | GET /users/123/orders | GET /orders?userId=123（简单场景下可接受） |
2. HTTP 方法使用标准
| 方法 | 含义 | 幂等性 | 安全性 | 示例 |
|---|
| GET | 获取资源 | 是 | 是 | GET /users/123 |
| POST | 创建资源 | 否 | 否 | POST /users |
| PUT | 完整更新资源（需提供全部字段） | 是 | 否 | PUT /users/123 |
| PATCH | 部分更新资源 | 否 | 否 | PATCH /users/123 |
| DELETE | 删除资源 | 是 | 否 | DELETE /users/123 |
幂等性说明： 多次执行相同请求，结果一致。GET、PUT、DELETE 是幂等的；POST、PATCH 通常不是。
3. HTTP 状态码使用规范
| 分类 | 状态码 | 含义 | 使用场景 |
|---|
| 成功（2xx） | 200 OK | 请求成功 | GET、PUT、PATCH、DELETE 成功 |
| 201 Created | 资源创建成功 | POST 成功后，响应头带 Location |
| 204 No Content | 请求成功但无返回体 | DELETE 成功 |
| 客户端错误（4xx） | 400 Bad Request | 参数错误、格式错误 | JSON 解析失败、必填字段缺失 |
| 401 Unauthorized | 未认证 | 缺少 Token 或 Token 无效 |
| 403 Forbidden | 无权限 | Token 有效但权限不足 |
| 404 Not Found | 资源不存在 | 请求的 URL 或资源 ID 不存在 |
| 409 Conflict | 资源冲突 | 创建时资源已存在 |
| 422 Unprocessable Entity | 语义错误 | 业务逻辑校验失败 |
| 429 Too Many Requests | 请求过多 | 触发限流 |
| 服务端错误（5xx） | 500 Internal Server Error | 服务器内部错误 | 代码异常、数据库连接失败 |
| 502 Bad Gateway | 网关错误 | 上游服务不可用 |
| 503 Service Unavailable | 服务不可用 | 服务过载或维护中 |
4. 响应结构设计
成功响应格式
{
"code": 200,
"message": "success",
"data": {
"id": 123,
"username": "john_doe"
}
}
