save code

2026-01-18 20:04:25 +08:00
parent 9a00ac3907
commit bf2d7d2bba
6 changed files with 516 additions and 98 deletions
@@ -0,0 +1,205 @@
+# 发型更换H5项目API文档
+
+## 1. 文档说明
+
+本文档描述了发型更换H5项目的API接口规范，所有前后端交互都应遵循此文档。任何API变更都应先修改此文档，然后再进行代码实现。
+
+### 1.1 文档版本
+
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| v1.0 | 2026-01-18 | 初始版本 | 系统生成 |
+
+### 1.2 基本信息
+
+- **API基础路径**: `/api`
+- **响应格式**: JSON
+- **字符编码**: UTF-8
+- **认证方式**: 无需认证
+
+## 2. 响应格式
+
+所有API响应均采用统一的格式：
+
+### 2.1 成功响应
+
+```json
+{
+  "success": true,
+  "data": {...},
+  "message": ""
+}
+```
+
+### 2.2 失败响应
+
+```json
+{
+  "success": false,
+  "data": null,
+  "message": "错误信息"
+}
+```
+
+## 3. API接口列表
+
+| 接口路径 | 方法 | 功能描述 | 请求参数 | 成功响应数据 |
+|---------|------|----------|---------|-------------|
+| `/api/hairstyles` | GET | 获取发型列表 | 无 | `{ "hairstyles": [...] }` |
+| `/api/change-hair` | POST | 更换发型 | image: 文件<br>hairstyle_id: 字符串 | `{ "result_image": "data:image/jpeg;base64,..." }` |
+
+## 4. 详细接口说明
+
+### 4.1 获取发型列表
+
+#### 4.1.1 请求信息
+- **路径**: `/api/hairstyles`
+- **方法**: GET
+- **参数**: 无
+
+#### 4.1.2 响应信息
+- **状态码**: 200 OK
+- **响应示例**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "hairstyles": [
+      {
+        "id": "hair_001",
+        "name": "发型1",
+        "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267183426772993.jpg"
+      },
+      {
+        "id": "hair_002",
+        "name": "发型2",
+        "image_url": "https://xiangsilian.oss-cn-beijing.aliyuncs.com/hair_images/1953267306382794754.jpg"
+      }
+    ]
+  },
+  "message": ""
+}
+```
+
+#### 4.1.3 字段说明
+
+| 字段名 | 类型 | 描述 |
+|-------|------|------|
+| `id` | 字符串 | 发型唯一标识符 |
+| `name` | 字符串 | 发型名称 |
+| `image_url` | 字符串 | 发型图片的OSS URL |
+
+### 4.2 更换发型
+
+#### 4.2.1 请求信息
+- **路径**: `/api/change-hair`
+- **方法**: POST
+- **参数**:
+  - `image`: 文件 (必填) - 用户上传的图片文件
+  - `hairstyle_id`: 字符串 (必填) - 要更换的发型ID
+
+#### 4.2.2 响应信息
+- **状态码**: 200 OK
+- **响应示例**:
+
+```json
+{
+  "success": true,
+  "data": {
+    "result_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
+  },
+  "message": ""
+}
+```
+
+#### 4.2.3 字段说明
+
+| 字段名 | 类型 | 描述 |
+|-------|------|------|
+| `result_image` | 字符串 | 发型更换后的图片，Base64编码格式 |
+
+## 5. 错误处理
+
+### 5.1 常见错误状态码
+
+| 状态码 | 描述 | 示例消息 |
+|-------|------|---------|
+| 400 | 请求参数错误 | "请上传图片"、"请选择发型" |
+| 500 | 服务器内部错误 | "获取发型列表失败: [错误信息]" |
+
+### 5.2 错误响应示例
+
+```json
+{
+  "success": false,
+  "data": null,
+  "message": "请上传图片"
+}
+```
+
+## 6. API变更流程
+
+1. **文档修改**: 先修改本API文档，记录变更内容、原因和影响范围
+2. **代码实现**: 根据文档修改后端API实现
+3. **前端适配**: 前端根据文档修改进行适配
+4. **测试验证**: 测试新API的功能和兼容性
+5. **部署上线**: 按计划部署变更
+
+## 7. 版本控制
+
+当API需要重大变更时，应采用版本控制机制：
+
+1. **URL版本控制**: 在API路径中添加版本号，如 `/api/v2/hairstyles`
+2. **向后兼容**: 保留旧版本API一段时间，确保前端有足够时间迁移
+3. **弃用通知**: 在响应中添加弃用警告，提示开发者使用新API
+
+## 8. 最佳实践
+
+1. **使用标准HTTP方法**: GET用于获取数据，POST用于提交数据
+2. **保持接口幂等性**: 相同请求应产生相同结果
+3. **合理设置缓存**: 对频繁访问的数据进行缓存，提高性能
+4. **限流保护**: 对API调用进行限流，防止滥用
+5. **日志记录**: 记录API调用日志，便于问题排查
+
+## 9. 附录
+
+### 9.1 数据结构定义
+
+#### 9.1.1 发型对象 (Hairstyle)
+
+```json
+{
+  "id": "string",
+  "name": "string",
+  "image_url": "string"
+}
+```
+
+#### 9.1.2 更换发型请求 (ChangeHairRequest)
+
+```
+FormData:
+- image: File
+- hairstyle_id: string
+```
+
+#### 9.1.3 更换发型响应 (ChangeHairResponse)
+
+```json
+{
+  "result_image": "string"
+}
+```
+
+### 9.2 开发工具推荐
+
+- **API测试**: Postman, Insomnia
+- **文档生成**: Swagger, ReDoc
+- **代码生成**: OpenAPI Generator
+
+### 9.3 相关链接
+
+- [RESTful API设计指南](https://restfulapi.net/)
+- [OpenAPI规范](https://swagger.io/specification/)
+- [HTTP状态码](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)