API 设计规范

本资源提供了一套完整的 RESTful API 设计规范与实战工作流，涵盖资源建模、URL 规范、状态码应用及统一响应格式。适用于后端开发团队进行 API 架构设计、接口开发与文档编写。通过标准化的设计流程，帮助开发者提升接口可读性、降低前后端沟通成本，打造高质量、易维护的后端服务接口。

## RESTful API 设计规范工作流 ### 工作流概述 本工作流旨在指导后端开发者从零开始设计并落地一套标准化、高可用、易维护的 RESTful API。通过规范化的五个步骤，确保接口设计符合业界最佳实践，提升前后端协作效率与系统整体质量。 ### 分步骤操作说明 #### 步骤一：需求分析与资源建模 - **具体动作**：梳理业务需求，提取核心实体（如 User, Order, Product），并将其转化为 API 资源。 - **操作细节**：资源命名必须使用复数名词（如 `/users` 而非 `/user`）。保持资源导向，避免在 URL 中使用动词（如使用 `POST /users` 代替 `/createUser`）。 #### 步骤二：URL 路由与 HTTP 方法设计 - **具体动作**：为每个资源设计 CRUD 路由，并严格映射到标准的 HTTP 方法。 - **操作细节**： - `GET /api/v1/users`：获取列表（支持分页、过滤）。 - `GET /api/v1/users/:id`：获取单个详情。 - `POST /api/v1/users`：创建新资源。 - `PUT /api/v1/users/:id`：全量更新。 - `PATCH /api/v1/users/:id`：局部更新。 - `DELETE /api/v1/users/:id`：删除资源。 - **版本控制**：在 URL 路径中引入版本号（如 `/api/v1/`），便于后续迭代。 #### 步骤三：统一响应格式与数据结构定义 - **具体动作**：定义全局统一的 JSON 响应结构，确保前后端解析逻辑一致。 - **操作细节**：所有接口返回标准信封格式： ```json { "code": 200, "message": "success", "data": {}, "timestamp": "2025-01-21T10:00:00Z" } ``` - 列表接口需在 `data` 中包含分页元数据（如 `page`, `pageSize`, `total`, `list`）。 #### 步骤四：异常处理与 HTTP 状态码规范 - **具体动作**：设计业务错误码与 HTTP 状态码的映射机制，规范异常返回。 - **操作细节**： - `200`：请求成功。 - `201`：创建成功。 - `400`：客户端请求参数错误。 - `401`：未授权（Token 缺失或过期）。 - `403`：权限不足。 - `404`：资源不存在。 - `500`：服务器内部错误。 - 对于业务逻辑错误（如余额不足），HTTP 状态码返回 `200`，但在 `code` 中返回自定义业务错误码，并在 `message` 中返回具体提示。 #### 步骤五：API 文档编写与自动化测试 - **具体动作**：使用标准化工具生成 API 文档，并进行接口联调与测试。 - **操作细节**： - 采用 Swagger/OpenAPI 规范，通过代码注解自动生成在线文档。 - 在 Postman 中建立接口集合（Collection），配置环境变量和自动化测试脚本。 - 确保文档包含请求示例、响应示例、状态码说明及鉴权方式。 ### 注意事项与最佳实践 1. **幂等性设计**：GET、PUT、DELETE 方法应保证幂等性（多次请求结果一致），POST 不保证。 2. **过滤、排序与分页**：统一使用 Query 参数实现，如 `?sort=created_at:desc&page=1&size=20`。 3. **安全性**：敏感数据传输必须使用 HTTPS；核心接口需实现鉴权（如 JWT、OAuth2）和限流防刷。 4. **向后兼容**：API 升级时尽量保持向下兼容（如新增字段），若需破坏性更新，必须通过版本号隔离。 ### 常见问题提示 - **Q: URL 中应该使用驼峰还是短横线？** A: 推荐使用短横线（kebab-case），如 `/user-profiles`，更符合 URL 规范且阅读体验更好。 - **Q: 嵌套资源如何设计？** A: 最多嵌套一层，如 `GET /api/v1/users/:userId/orders` 获取某用户的订单。更深层级建议通过查询参数或扁平化设计。 - **Q: 字段命名规范是什么？** A: JSON 键名推荐使用小驼峰命名法（camelCase），如 `userName`、`createTime`，保持与主流编程语言对象属性命名习惯一致。