Главная Обзор Помощь
Вход
mige
/
Godemo
1
0
Ответвить 0
Файлы Задачи 0 Вики
Дерево: 83b8af0d73
Ветки Метки
Godemo
/
web-training
/
docs
/
api.md

api.md 12 KB
История Исходник

API 文档

概述

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

基础信息

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

通用响应格式

成功响应

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

分页响应

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

错误响应

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

认证

用户注册

POST /register

注册新用户账户。

请求体:

{
  "username": "testuser",
  "email": "[email protected]",
  "password": "password123",
  "first_name": "张",
  "last_name": "三",
  "phone": "13800138000",
  "address": "北京市朝阳区"
}

响应:

{
  "code": 201,
  "message": "注册成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "[email protected]",
    "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

用户登录获取访问令牌。

请求体:

{
  "username": "testuser",
  "password": "password123"
}

响应:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "[email protected]",
      "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>

响应:

{
  "code": 200,
  "message": "获取成功",
  "data": [
    {
      "id": 1,
      "username": "testuser",
      "email": "[email protected]",
      "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>

响应:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "[email protected]",
    "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>

请求体:

{
  "first_name": "李",
  "last_name": "四",
  "phone": "13900139000",
  "address": "上海市浦东新区"
}

响应:

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "[email protected]",
    "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>

响应:

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

商品管理

获取商品列表

GET /products

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

查询参数:

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

请求头:

Authorization: Bearer <token>

响应:

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

请求体:

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

响应:

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

响应:

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

请求体:

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

响应:

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

响应:

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

订单管理

获取订单列表

GET /orders

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

查询参数:

  • page (int, 可选): 页码，默认为1
  • page_size (int, 可选): 每页数量，默认为10
  • status (string, 可选): 订单状态筛选

请求头:

Authorization: Bearer <token>

响应:

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

请求体:

{
  "items": [
    {
      "product_id": 1,
      "quantity": 1
    }
  ],
  "shipping_address": "北京市朝阳区",
  "payment_method": "alipay"
}

响应:

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

响应:

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

响应:

{
  "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认证令牌

消息格式:

{
  "type": "message",
  "data": {
    "content": "Hello, World!",
    "timestamp": "2023-01-01T00:00:00Z"
  }
}

错误代码

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

使用示例

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示例

# 登录
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通信