jiebanke/backend/api-documentation.md

结伴客后端API文档

1. 认证相关接口

用户注册

请求方法: POST 请求路径: /api/v1/auth/register 请求体:

{
  "username": "string", // 用户名（必需）
  "password": "string", // 密码（必需，至少6位）
  "nickname": "string", // 昵称（可选）
  "email": "string", // 邮箱（可选）
  "phone": "string" // 手机号（可选）
}

响应:

{
  "success": true,
  "data": {
    "user": { // 用户信息（不含敏感信息）
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.com",
      "phone": "13800000000",
      // 其他用户字段...
    },
    "token": "string"
  },
  "message": "注册成功"
}

错误响应:

• 400: 用户名已存在 / 邮箱已存在 / 手机号已存在 / 密码长度不能少于6位
• 500: 服务器内部错误

用户登录

请求方法: POST 请求路径: /api/v1/auth/login 请求体:

{
  "username": "string", // 用户名/邮箱/手机号（必需）
  "password": "string" // 密码（必需）
}

响应:

{
  "success": true,
  "data": {
    "user": { // 用户信息（不含敏感信息）
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.com",
      "phone": "13800000000",
      // 其他用户字段...
    },
    "token": "string"
  },
  "message": "登录成功"
}

错误响应:

• 400: 用户名和密码不能为空
• 401: 密码错误
• 403: 账户已被禁用
• 404: 用户不存在
• 500: 服务器内部错误

2. 用户管理接口

获取当前用户信息

请求方法: GET 请求路径: /api/v1/users/profile 请求头: Authorization: Bearer {token} 响应:

{
  "success": true,
  "data": {
    "user": { // 用户信息（不含敏感信息）
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@jiebanke.com",
      "phone": "13800000000",
      // 其他用户字段...
    }
  }
}

错误响应:

• 401: 未提供认证token / 无效的认证token / token已过期 / 用户不存在
• 403: 账户已被禁用
• 500: 服务器内部错误

更新用户个人信息

请求方法: PUT 请求路径: /api/v1/users/profile 请求头: Authorization: Bearer {token} 请求体:

{
  "nickname": "string", // 昵称（可选）
  "avatar": "string", // 头像URL（可选）
  "gender": "string", // 性别（可选，可选值：male, female, other）
  "birthday": "string", // 生日（可选，格式：YYYY-MM-DD）
  "phone": "string", // 手机号（可选）
  "email": "string" // 邮箱（可选）
}

响应:

{
  "success": true,
  "data": {
    "user": { // 更新后的用户信息（不含敏感信息）
      "id": 1,
      "username": "testuser",
      "nickname": "新昵称",
      "email": "new@email.com",
      "phone": "13900000000",
      // 其他用户字段...
    },
    "message": "个人信息更新成功"
  }
}

错误响应:

• 400: 没有有效的更新字段 / 邮箱已被其他用户使用 / 手机号已被其他用户使用
• 401: 未提供认证token / 无效的认证token / token已过期 / 用户不存在
• 403: 账户已被禁用
• 500: 更新用户信息失败 / 服务器内部错误

3. 管理员接口

搜索用户

请求方法: GET 请求路径: /api/v1/admin/users/search 请求头: Authorization: Bearer {token} 请求参数:

• keyword: 搜索关键词（可选，模糊匹配用户名、昵称、邮箱、手机号）
• userType: 用户类型（可选）
• page: 当前页码（可选，默认：1）
• pageSize: 每页记录数（可选，默认：10）

响应:

{
  "success": true,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "testuser",
        "user_type": "farmer",
        "real_name": "测试用户",
        "avatar_url": "",
        "email": "test@jiebanke.com",
        "phone": "13800000000",
        "status": "active",
        "created_at": "2024-01-01T12:00:00Z",
        "updated_at": "2024-01-01T12:00:00Z"
      }
      // 更多用户...
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10,
    "pages": 1
  }
}

错误响应:

• 401: 未提供认证token / 无效的认证token / token已过期 / 管理员不存在
• 403: 管理员账号已被禁用 / 需要管理员权限 / 权限不足
• 500: 服务器内部错误

批量更新用户状态

请求方法: POST 请求路径: /api/v1/admin/users/batch-status 请求头: Authorization: Bearer {token} 请求体:

{
  "userIds": [1, 2, 3], // 用户ID列表（必需）
  "status": "active" // 状态（必需，可选值：active, inactive）
}

响应:

{
  "success": true,
  "data": {
    "message": "成功更新 3 个用户状态",
    "affectedRows": 3
  }
}

错误响应:

• 400: 请选择要操作的用户 / 无效的状态值
• 401: 未提供认证token / 无效的认证token / token已过期 / 管理员不存在
• 403: 管理员账号已被禁用 / 需要管理员权限 / 权限不足
• 500: 服务器内部错误

4. 系统接口

健康检查

请求方法: GET 请求路径: /health 响应:

{
  "status": "OK",
  "timestamp": "2024-01-01T12:00:00Z",
  "uptime": 1234.56,
  "environment": "production"
}

系统统计

请求方法: GET 请求路径: /system-stats 响应:

{
  "status": "OK",
  "timestamp": "2024-01-01T12:00:00Z",
  "environment": "production",
  "nodeVersion": "v18.16.0",
  "memoryUsage": {
    "rss": 123456789,
    "heapTotal": 12345678,
    "heapUsed": 1234567,
    "external": 123456
  },
  "uptime": 1234.56,
  "cpuCount": 8,
  "platform": "linux",
  "architecture": "x64"
}

5. 错误码说明

错误码	描述	HTTP状态码
400	请求参数错误	400
401	未授权（无效token、token过期等）	401
403	权限不足或账户被禁用	403
404	资源不存在	404
429	请求过于频繁	429
500	服务器内部错误	500
503	服务不可用（如数据库连接失败）	503

6. 认证机制

系统使用JWT（JSON Web Token）进行认证，所有需要认证的接口都需要在请求头中包含Authorization: Bearer {token}。

Token有效期

• 默认有效期为7天
• 可通过环境变量JWT_EXPIRE自定义

Token安全

• 生产环境请确保设置安全的JWT_SECRET环境变量
• 避免在客户端存储敏感信息

7. 接口限制

• 接口请求频率限制：生产环境15分钟内最多100次请求，开发环境15分钟内最多1000次请求
• 请求体大小限制：10kb
• 支持的请求内容类型：application/json

8. Swagger文档

在开发环境或设置ENABLE_SWAGGER=true环境变量时，可通过以下地址访问Swagger文档：

• https://webapi.jiebanke.com/api-docs