hair_change_color/docs/API.md

发型更换H5项目API文档

1. 文档说明

本文档描述了发型更换H5项目的API接口规范，所有前后端交互都应遵循此文档。任何API变更都应先修改此文档，然后再进行代码实现。

1.1 文档版本

版本	日期	描述	作者
v1.0	2026-01-18	初始版本	系统生成

1.2 基本信息

• API基础路径: /api
• 响应格式: JSON
• 字符编码: UTF-8
• 认证方式: 无需认证

2. 响应格式

所有API响应均采用统一的格式：

2.1 成功响应

{
  "success": true,
  "data": {...},
  "message": ""
}

2.2 失败响应

{
  "success": false,
  "data": null,
  "message": "错误信息"
}

3. API接口列表

接口路径	方法	功能描述	请求参数	成功响应数据
/api/hairstyles	GET	获取发型列表	无	{ "hairstyles": [...] }
/api/change-hair	POST	更换发型	image: 文件 hairstyle_id: 字符串	{ "result_image": "data:image/jpeg;base64,..." }

4. 详细接口说明

4.1 获取发型列表

4.1.1 请求信息

• 路径: /api/hairstyles
• 方法: GET
• 参数: 无

4.1.2 响应信息

• 状态码: 200 OK
• 响应示例:

{
  "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
• 响应示例:

{
  "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 错误响应示例

{
  "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)

{
  "id": "string",
  "name": "string",
  "image_url": "string"
}

9.1.2 更换发型请求 (ChangeHairRequest)

FormData:
- image: File
- hairstyle_id: string

9.1.3 更换发型响应 (ChangeHairResponse)

{
  "result_image": "string"
}

9.2 开发工具推荐

• API测试: Postman, Insomnia
• 文档生成: Swagger, ReDoc
• 代码生成: OpenAPI Generator

9.3 相关链接

• RESTful API设计指南
• OpenAPI规范
• HTTP状态码