jiebanke/API_DOCS.md

📚 API 接口文档

📋 文档说明

本文档详细描述了杰邦科项目的所有API接口，包括请求参数、响应格式和错误代码。

🔐 认证方式

JWT Token 认证

所有需要认证的API必须在请求头中携带Token：

Authorization: Bearer <your_jwt_token>

Token 获取

通过登录接口获取Token，Token有效期为7天。

👥 用户模块

用户注册

Endpoint: POST /api/v1/users/register

请求参数:

{
  "username": "string, required, 3-20字符",
  "password": "string, required, 6-20字符",
  "email": "string, optional, 邮箱格式",
  "phone": "string, optional, 手机号格式"
}

响应示例:

{
  "code": 200,
  "message": "注册成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

错误代码:

• 400: 参数验证失败
• 409: 用户名已存在
• 500: 服务器内部错误

用户登录

Endpoint: POST /api/v1/users/login

请求参数:

{
  "username": "string, required",
  "password": "string, required"
}

响应示例:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com"
    }
  }
}

错误代码:

• 400: 参数验证失败
• 401: 用户名或密码错误
• 500: 服务器内部错误

获取用户信息

Endpoint: GET /api/v1/users/profile

请求头:

Authorization: Bearer <token>

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "phone": "13800138000",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

错误代码:

• 401: 未授权访问
• 404: 用户不存在
• 500: 服务器内部错误

🛒 订单模块

创建订单

Endpoint: POST /api/v1/orders

请求头:

Authorization: Bearer <token>

请求参数:

{
  "items": [
    {
      "productId": 1,
      "quantity": 2,
      "price": 100.00
    }
  ],
  "shippingAddress": {
    "recipient": "张三",
    "phone": "13800138000",
    "address": "北京市朝阳区xxx路xxx号"
  },
  "remark": "string, optional"
}

响应示例:

{
  "code": 200,
  "message": "订单创建成功",
  "data": {
    "id": 1001,
    "orderNo": "ORDER202401010001",
    "totalAmount": 200.00,
    "status": "pending",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

查询订单列表

Endpoint: GET /api/v1/orders

请求头:

Authorization: Bearer <token>

查询参数:

?page=1&limit=10&status=pending

参数	类型	说明
page	number	页码，默认1
limit	number	每页数量，默认10
status	string	订单状态过滤

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1001,
        "orderNo": "ORDER202401010001",
        "totalAmount": 200.00,
        "status": "pending",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 100,
      "pages": 10
    }
  }
}

📦 商品模块

获取商品列表

Endpoint: GET /api/v1/products

查询参数:

?page=1&limit=10&category=electronics&sort=price_desc

参数	类型	说明
page	number	页码，默认1
limit	number	每页数量，默认10
category	string	商品分类过滤
sort	string	排序方式

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "iPhone 15",
        "price": 5999.00,
        "originalPrice": 6999.00,
        "image": "/images/iphone15.jpg",
        "category": "electronics",
        "stock": 100,
        "description": "最新款iPhone手机"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1000,
      "pages": 100
    }
  }
}

获取商品详情

Endpoint: GET /api/v1/products/:id

路径参数:

• id: 商品ID

响应示例:

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "iPhone 15",
    "price": 5999.00,
    "originalPrice": 6999.00,
    "images": [
      "/images/iphone15-1.jpg",
      "/images/iphone15-2.jpg"
    ],
    "category": "electronics",
    "brand": "Apple",
    "stock": 100,
    "description": "最新款iPhone手机",
    "specifications": {
      "color": "黑色",
      "storage": "256GB",
      "screen": "6.1英寸"
    },
    "reviews": {
      "averageRating": 4.8,
      "totalReviews": 150
    }
  }
}

📊 数据字典

订单状态

状态值	描述
pending	待支付
paid	已支付
shipped	已发货
completed	已完成
cancelled	已取消

商品分类

分类值	描述
electronics	电子产品
clothing	服装服饰
books	图书文具
home	家居生活
sports	运动户外

错误代码

代码	描述
200	成功
400	请求参数错误
401	未授权访问
403	禁止访问
404	资源不存在
409	资源冲突
500	服务器内部错误
503	服务不可用

🔗 API 版本控制

当前API版本为v1，所有接口前缀为/api/v1/。

版本更新策略：

• 向后兼容的修改直接更新
• 不兼容的修改创建新版本v2
• 旧版本API保持维护至少6个月

📡 接口限流

限流策略

• 匿名用户: 60请求/分钟
• 认证用户: 120请求/分钟
• VIP用户: 300请求/分钟

限流响应

当超过限流阈值时返回：

{
  "code": 429,
  "message": "请求过于频繁，请稍后再试",
  "retryAfter": 60
}

🧪 接口测试

使用curl测试

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

# 获取用户信息
curl -X GET http://localhost:3000/api/v1/users/profile \
  -H "Authorization: Bearer <token>"

使用Postman测试

1. 导入Postman集合文件
2. 设置环境变量（base_url, token等）
3. 运行测试用例

📝 更新日志

v1.0.0 (2024-01-01)

• 用户注册登录接口
• 订单管理接口
• 商品管理接口
• 基础认证系统

---

最后更新: 2024年 📅