# API 文档

## 概述

本文档描述了Go Web训练项目的RESTful API接口。所有API都遵循REST设计原则，使用JSON格式进行数据交换。

## 基础信息

- **基础URL**: `http://localhost:8080/api/v1`
- **认证方式**: JWT Bearer Token
- **内容类型**: `application/json`
- **字符编码**: UTF-8

## 通用响应格式

### 成功响应

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 响应数据
  }
}
```

### 分页响应

```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    // 数据列表
  ],
  "meta": {
    "page": 1,
    "page_size": 10,
    "total": 100,
    "total_page": 10
  }
}
```

### 错误响应

```json
{
  "code": 400,
  "message": "请求参数错误",
  "data": {
    "details": "具体错误信息"
  }
}
```

## 认证

### 用户注册

**POST** `/register`

注册新用户账户。

**请求体**:
```json
{
  "username": "testuser",
  "email": "test@example.com",
  "password": "password123",
  "first_name": "张",
  "last_name": "三",
  "phone": "13800138000",
  "address": "北京市朝阳区"
}
```

**响应**:
```json
{
  "code": 201,
  "message": "注册成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "first_name": "张",
    "last_name": "三",
    "phone": "13800138000",
    "address": "北京市朝阳区",
    "is_active": true,
    "role": "user",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

### 用户登录

**POST** `/login`

用户登录获取访问令牌。

**请求体**:
```json
{
  "username": "testuser",
  "password": "password123"
}
```

**响应**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com",
      "first_name": "张",
      "last_name": "三",
      "is_active": true,
      "role": "user",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  }
}
```

## 用户管理

### 获取用户列表

**GET** `/users`

获取用户列表，支持分页和搜索。

**查询参数**:
- `page` (int, 可选): 页码，默认为1
- `page_size` (int, 可选): 每页数量，默认为10
- `search` (string, 可选): 搜索关键词

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com",
      "first_name": "张",
      "last_name": "三",
      "is_active": true,
      "role": "user",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 10,
    "total": 1,
    "total_page": 1
  }
}
```

### 获取用户详情

**GET** `/users/{id}`

获取指定用户的详细信息。

**路径参数**:
- `id` (int): 用户ID

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "first_name": "张",
    "last_name": "三",
    "phone": "13800138000",
    "address": "北京市朝阳区",
    "is_active": true,
    "role": "user",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

### 更新用户信息

**PUT** `/users/{id}`

更新指定用户的信息。

**路径参数**:
- `id` (int): 用户ID

**请求头**:
```
Authorization: Bearer <token>
```

**请求体**:
```json
{
  "first_name": "李",
  "last_name": "四",
  "phone": "13900139000",
  "address": "上海市浦东新区"
}
```

**响应**:
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "first_name": "李",
    "last_name": "四",
    "phone": "13900139000",
    "address": "上海市浦东新区",
    "is_active": true,
    "role": "user",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-02T00:00:00Z"
  }
}
```

### 删除用户

**DELETE** `/users/{id}`

删除指定用户。

**路径参数**:
- `id` (int): 用户ID

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

## 商品管理

### 获取商品列表

**GET** `/products`

获取商品列表，支持分页和搜索。

**查询参数**:
- `page` (int, 可选): 页码，默认为1
- `page_size` (int, 可选): 每页数量，默认为10
- `search` (string, 可选): 搜索关键词
- `category_id` (int, 可选): 分类ID

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "智能手机",
      "description": "最新款智能手机，配备高清摄像头和长续航电池",
      "price": 2999.00,
      "stock": 100,
      "category_id": 1,
      "image": "/uploads/products/1.jpg",
      "is_active": true,
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 10,
    "total": 1,
    "total_page": 1
  }
}
```

### 创建商品

**POST** `/products`

创建新商品。

**请求头**:
```
Authorization: Bearer <token>
```

**请求体**:
```json
{
  "name": "平板电脑",
  "description": "轻薄便携，高清屏幕",
  "price": 1999.00,
  "stock": 50,
  "category_id": 1
}
```

**响应**:
```json
{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 2,
    "name": "平板电脑",
    "description": "轻薄便携，高清屏幕",
    "price": 1999.00,
    "stock": 50,
    "category_id": 1,
    "image": "",
    "is_active": true,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

### 获取商品详情

**GET** `/products/{id}`

获取指定商品的详细信息。

**路径参数**:
- `id` (int): 商品ID

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "智能手机",
    "description": "最新款智能手机，配备高清摄像头和长续航电池",
    "price": 2999.00,
    "stock": 100,
    "category_id": 1,
    "image": "/uploads/products/1.jpg",
    "is_active": true,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

### 更新商品

**PUT** `/products/{id}`

更新指定商品的信息。

**路径参数**:
- `id` (int): 商品ID

**请求头**:
```
Authorization: Bearer <token>
```

**请求体**:
```json
{
  "name": "智能手机Pro",
  "description": "升级版智能手机，更强大的性能",
  "price": 3299.00,
  "stock": 80
}
```

**响应**:
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "name": "智能手机Pro",
    "description": "升级版智能手机，更强大的性能",
    "price": 3299.00,
    "stock": 80,
    "category_id": 1,
    "image": "/uploads/products/1.jpg",
    "is_active": true,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-02T00:00:00Z"
  }
}
```

### 删除商品

**DELETE** `/products/{id}`

删除指定商品。

**路径参数**:
- `id` (int): 商品ID

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null
}
```

## 订单管理

### 获取订单列表

**GET** `/orders`

获取当前用户的订单列表，支持分页。

**查询参数**:
- `page` (int, 可选): 页码，默认为1
- `page_size` (int, 可选): 每页数量，默认为10
- `status` (string, 可选): 订单状态筛选

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "order_number": "ORD20230101001",
      "total_amount": 2999.00,
      "status": "pending",
      "shipping_address": "北京市朝阳区",
      "payment_method": "alipay",
      "payment_status": "pending",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 10,
    "total": 1,
    "total_page": 1
  }
}
```

### 创建订单

**POST** `/orders`

创建新订单。

**请求头**:
```
Authorization: Bearer <token>
```

**请求体**:
```json
{
  "items": [
    {
      "product_id": 1,
      "quantity": 1
    }
  ],
  "shipping_address": "北京市朝阳区",
  "payment_method": "alipay"
}
```

**响应**:
```json
{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 1,
    "order_number": "ORD20230101001",
    "total_amount": 2999.00,
    "status": "pending",
    "shipping_address": "北京市朝阳区",
    "payment_method": "alipay",
    "payment_status": "pending",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}
```

### 获取订单详情

**GET** `/orders/{id}`

获取指定订单的详细信息。

**路径参数**:
- `id` (int): 订单ID

**请求头**:
```
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "order_number": "ORD20230101001",
    "total_amount": 2999.00,
    "status": "pending",
    "shipping_address": "北京市朝阳区",
    "payment_method": "alipay",
    "payment_status": "pending",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z",
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "product_name": "智能手机",
        "quantity": 1,
        "price": 2999.00
      }
    ]
  }
}
```

## 文件上传

### 上传文件

**POST** `/upload`

上传文件到服务器。

**请求头**:
```
Authorization: Bearer <token>
Content-Type: multipart/form-data
```

**请求体**:
```
file: <binary>
```

**响应**:
```json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "filename": "uploads/abc123.jpg",
    "original_name": "image.jpg",
    "size": 1024000,
    "content_type": "image/jpeg"
  }
}
```

## WebSocket

### 实时通信

**WebSocket** `/ws`

建立WebSocket连接进行实时通信。

**连接参数**:
- `token` (string): JWT认证令牌

**消息格式**:
```json
{
  "type": "message",
  "data": {
    "content": "Hello, World!",
    "timestamp": "2023-01-01T00:00:00Z"
  }
}
```

## 错误代码

| 代码 | 说明 |
|------|------|
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |

## 使用示例

### JavaScript示例

```javascript
// 登录
fetch('/api/v1/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'testuser',
    password: 'password123'
  })
})
.then(response => response.json())
.then(data => {
  if (data.code === 200) {
    // 保存令牌
    localStorage.setItem('token', data.data.token);
    
    // 使用令牌获取用户列表
    fetch('/api/v1/users', {
      headers: {
        'Authorization': `Bearer ${data.data.token}`
      }
    })
    .then(response => response.json())
    .then(users => {
      console.log(users);
    });
  }
});
```

### cURL示例

```bash
# 登录
curl -X POST http://localhost:8080/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"password123"}'

# 获取用户列表
curl -X GET http://localhost:8080/api/v1/users \
  -H "Authorization: Bearer <token>"
```

## 更新日志

### v1.0.0 (2023-01-01)
- 初始版本发布
- 实现用户管理API
- 实现商品管理API
- 实现订单管理API
- 实现文件上传API
- 实现WebSocket通信