# [模块名称] - API设计 > **基础路径?* `/api/v1/模块名` > **端点数量?* X? > **认证要求?* JWT Token > **最后更新：** YYYY-MM-DD --- ## 📋 API概览 | 端点 | 方法 | 说明 | 认证 | |------|------|------|------| | `/api/v1/xxx/resources` | GET | 获取资源列表 | ?| | `/api/v1/xxx/resources/:id` | GET | 获取资源详情 | ?| | `/api/v1/xxx/resources` | POST | 创建资源 | ?| | `/api/v1/xxx/resources/:id` | PUT | 更新资源 | ?| | `/api/v1/xxx/resources/:id` | DELETE | 删除资源 | ?| --- ## 📚 API详细设计 ### 1. 获取资源列表 **端点?* `GET /api/v1/xxx/resources` **用途：** 获取当前用户的资源列表（分页? **请求参数?* **Query参数?* ```typescript { page?: number; // 页码，默? pageSize?: number; // 每页数量，默?0，最?00 status?: string; // 筛选：状态（active/inactive? keyword?: string; // 搜索关键? sortBy?: string; // 排序字段（createdAt/updatedAt? sortOrder?: 'asc' | 'desc'; // 排序方向，默认desc } ``` **请求示例?* ```bash GET /api/v1/xxx/resources?page=1&pageSize=10&status=active Authorization: Bearer ``` **成功响应?* `200 OK` ```json { "success": true, "data": { "items": [ { "id": 1, "userId": 123, "fieldName": "示例", "description": "描述", "status": "active", "createdAt": "2025-11-06T10:00:00.000Z", "updatedAt": "2025-11-06T10:00:00.000Z" } ], "pagination": { "page": 1, "pageSize": 10, "total": 100, "totalPages": 10 } }, "message": "获取成功" } ``` **错误响应?* ```json // 401 Unauthorized { "success": false, "error": { "code": "UNAUTHORIZED", "message": "未授权，请先登录" } } // 400 Bad Request { "success": false, "error": { "code": "INVALID_PARAMS", "message": "参数错误", "details": [ { "field": "pageSize", "message": "最大不能超?00" } ] } } ``` --- ### 2. 获取资源详情 **端点?* `GET /api/v1/xxx/resources/:id` **用途：** 获取指定资源的详细信? **路径参数?* - `id` (必填): 资源ID **请求示例?* ```bash GET /api/v1/xxx/resources/123 Authorization: Bearer ``` **成功响应?* `200 OK` ```json { "success": true, "data": { "id": 123, "userId": 456, "fieldName": "示例", "description": "详细描述", "status": "active", "createdAt": "2025-11-06T10:00:00.000Z", "updatedAt": "2025-11-06T10:00:00.000Z", // 额外的关联数? "user": { "id": 456, "name": "用户? } }, "message": "获取成功" } ``` **错误响应?* ```json // 404 Not Found { "success": false, "error": { "code": "NOT_FOUND", "message": "资源不存? } } // 403 Forbidden { "success": false, "error": { "code": "FORBIDDEN", "message": "无权访问此资? } } ``` --- ### 3. 创建资源 **端点?* `POST /api/v1/xxx/resources` **用途：** 创建新资? **请求体：** ```json { "fieldName": "资源名称", // 必填，长?-200 "description": "描述", // 可选，最?000? "status": "active" // 可选，默认active } ``` **验证规则?* - `fieldName`: 必填?-200字符，不能包含特殊字? - `description`: 可选，最?000字符 - `status`: 可选，有效值：active, inactive **请求示例?* ```bash POST /api/v1/xxx/resources Authorization: Bearer Content-Type: application/json { "fieldName": "新资?, "description": "这是一个新资源" } ``` **成功响应?* `201 Created` ```json { "success": true, "data": { "id": 124, "userId": 456, "fieldName": "新资?, "description": "这是一个新资源", "status": "active", "createdAt": "2025-11-06T10:00:00.000Z", "updatedAt": "2025-11-06T10:00:00.000Z" }, "message": "创建成功" } ``` **错误响应?* ```json // 422 Unprocessable Entity { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "参数验证失败", "details": [ { "field": "fieldName", "message": "字段名称不能为空" }, { "field": "fieldName", "message": "字段名称长度必须?-200之间" } ] } } // 409 Conflict { "success": false, "error": { "code": "ALREADY_EXISTS", "message": "该资源已存在" } } ``` --- ### 4. 更新资源 **端点?* `PUT /api/v1/xxx/resources/:id` **用途：** 更新指定资源（完整更新） **路径参数?* - `id` (必填): 资源ID **请求体：** ```json { "fieldName": "更新后的名称", "description": "更新后的描述", "status": "inactive" } ``` **请求示例?* ```bash PUT /api/v1/xxx/resources/123 Authorization: Bearer Content-Type: application/json { "fieldName": "更新后的名称", "description": "更新后的描述" } ``` **成功响应?* `200 OK` ```json { "success": true, "data": { "id": 123, "fieldName": "更新后的名称", "description": "更新后的描述", "updatedAt": "2025-11-06T11:00:00.000Z" }, "message": "更新成功" } ``` **错误响应?* ```json // 404 Not Found { "success": false, "error": { "code": "NOT_FOUND", "message": "资源不存? } } // 403 Forbidden { "success": false, "error": { "code": "FORBIDDEN", "message": "无权修改此资? } } ``` --- ### 5. 删除资源 **端点?* `DELETE /api/v1/xxx/resources/:id` **用途：** 删除指定资源（软删除? **路径参数?* - `id` (必填): 资源ID **请求示例?* ```bash DELETE /api/v1/xxx/resources/123 Authorization: Bearer ``` **成功响应?* `200 OK` ```json { "success": true, "data": null, "message": "删除成功" } ``` **错误响应?* ```json // 404 Not Found { "success": false, "error": { "code": "NOT_FOUND", "message": "资源不存? } } // 403 Forbidden { "success": false, "error": { "code": "FORBIDDEN", "message": "无权删除此资? } } // 409 Conflict { "success": false, "error": { "code": "CANNOT_DELETE", "message": "该资源有关联数据，无法删? } } ``` --- ## 🔐 认证与权? ### 认证方式 所有API都需要JWT Token认证? ``` Authorization: Bearer ``` ### 权限检? - 用户只能访问自己的资? - ADMIN角色可以访问所有资? --- ## 📊 错误码汇? | 错误?| HTTP状?| 说明 | |--------|---------|------| | UNAUTHORIZED | 401 | 未授?| | FORBIDDEN | 403 | 无权?| | NOT_FOUND | 404 | 资源不存?| | VALIDATION_ERROR | 422 | 参数验证失败 | | ALREADY_EXISTS | 409 | 资源已存?| | INTERNAL_ERROR | 500 | 服务器错?| --- ## 🚀 使用示例 ### JavaScript/TypeScript ```typescript // 获取资源列表 const response = await fetch('/api/v1/xxx/resources?page=1&pageSize=10', { headers: { 'Authorization': `Bearer ${token}`, }, }); const data = await response.json(); // 创建资源 const response = await fetch('/api/v1/xxx/resources', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ fieldName: '新资?, description: '描述', }), }); ``` ### cURL ```bash # 获取列表 curl -X GET "http://localhost:3001/api/v1/xxx/resources?page=1&pageSize=10" \ -H "Authorization: Bearer " # 创建资源 curl -X POST "http://localhost:3001/api/v1/xxx/resources" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"fieldName":"新资?,"description":"描述"}' ``` --- ## ⚠️ 注意事项 **性能优化?* - 列表接口必须支持分页，默认pageSize=10，最?00 - 避免返回过多关联数据，按需加载 - 大量数据导出使用异步任务 **安全性：** - 所有接口必须验证JWT Token - 必须检查资源归属（用户只能操作自己的资源） - 敏感字段不要返回（如密码? **向后兼容?* - API变更使用版本号（/api/v2? - 不要删除已有字段，只能标记为deprecated - 新增字段必须有默认? --- ## 🔗 相关文档 **规范?* - [API设计规范](../../04-开发规?02-API设计规范.md) - [API路由总览](../../04-开发规?04-API路由总览.md) **数据库：** - [本模块数据库设计](./01-数据库设?md) --- **最后更新：** YYYY-MM-DD **维护人：** 技术架构师