# 发型更换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)