backendapi-development

# 后端 API 开发方法论 ## API 契约管理 ### 契约来源 实现 API 前，**必须**阅读 `architecture.md` §5（API 设计），获取： - API 规范（RESTful/GraphQL） - 接口列表（方法、路径、描述、认证要求） - 请求/响应格式约定 - 错误码规范 ### 契约遵守原则 1. **严格实现**：API 端点的方法、路径、参数必须与 architecture.md §5 一致 2. **响应格式**：遵循统一的成功/错误响应结构 3. **偏差记录**：如需偏离契约，必须在输出报告中标注原因 4. **类型导出**：将请求/响应类型导出到共享文件，供前端引用 ## RESTful API 设计 ### 资源命名规范 | 操作 | HTTP 方法 | 路径 | 说明 | |------|-----------|------|------| | 列表 | GET | `/api/users` | 获取用户列表 | | 详情 | GET | `/api/users/:id` | 获取单个用户 | | 创建 | POST | `/api/users` | 创建新用户 | | 更新 | PUT/PATCH | `/api/users/:id` | 更新用户 | | 删除 | DELETE | `/api/users/:id` | 删除用户 | ### 统一响应格式 **成功响应**： ```json { "success": true, "data": { ... }, "message": "Operation successful" } ``` **错误响应**： ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid input data", "details": [ { "field": "email", "message": "Invalid email format" } ] } } ``` ### 分页规范 **请求参数**： ``` GET /api/users?page=1&pageSize=20&sortBy=createdAt&order=desc ``` **响应格式**： ```json { "success": true, "data": { "items": [...], "pagination": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } } } ``` ## 请求验证 ### 输入验证层级 1. **路由层**：验证路径参数和查询参数 2. **中间件层**：验证请求体格式和必填字段 3. **Service 层**：验证业务规则 ### 验证示例 ```typescript // 使用验证库（如 Zod、Joi、class-validator） import { z } from 'zod'; const CreateUserSchema = z.object({ name: z.string().min(1).max(100), email: z.string().ema...