🔗 API 文档

用户管理系统 RESTful API 接口文档

📖 目录

🌟 API 概览

基础信息

  • Base URL: http://localhost:31111
  • 认证方式: JWT Bearer Token
  • 数据格式: JSON
  • 字符编码: UTF-8

通用响应格式

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

错误响应格式

{ "success": false, "message": "错误描述", "error": "ERROR_CODE" }

HTTP 状态码

  • 200: 请求成功
  • 400: 请求参数错误
  • 401: 认证失败
  • 403: 权限不足
  • 404: 资源不存在
  • 500: 服务器内部错误
🔐 认证接口
POST /api/auth/login
用户登录，获取访问令牌

请求参数:

usernameOrEmail (string, required) - 用户名或邮箱
password (string, required) - 密码
POST /api/auth/login Content-Type: application/json { "usernameOrEmail": "admin", "password": "123456" } # 响应 { "success": true, "message": "登录成功", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "user": { "id": 1, "username": "admin", "email": "admin@example.com", "roles": ["admin"] }, "expires_at": "2024-01-16T12:00:00Z" } }
POST /api/auth/register
用户注册

请求参数:

username (string, required) - 用户名
email (string, required) - 邮箱
password (string, required) - 密码
real_name (string, optional) - 真实姓名
nickname (string, optional) - 昵称
phone (string, optional) - 手机号
referral_code (string, optional) - 推荐码
POST /api/auth/register Content-Type: application/json { "username": "newuser", "email": "newuser@example.com", "password": "password123", "real_name": "新用户", "nickname": "小新", "phone": "13800138000", "referral_code": "USR12345" }
POST /api/auth/logout
用户登出

请求头:

Authorization (string, required) - Bearer {token}
X-Session-ID (string, required) - 会话ID
POST /api/auth/refresh
刷新访问令牌

请求参数:

token (string, required) - 当前token
👥 用户管理
GET /api/users
获取用户列表（需要认证）

查询参数:

page (int, optional) - 页码，默认1
limit (int, optional) - 每页数量，默认10，最大100
search (string, optional) - 搜索关键词
status (string, optional) - 用户状态过滤
GET /api/users?page=1&limit=10&search=admin&status=active Authorization: Bearer {token} # 响应 { "success": true, "data": { "users": [...], "total": 100, "page": 1, "limit": 10, "total_pages": 10 } }
GET /api/users/{id}
获取单个用户详情

路径参数:

id (int, required) - 用户ID
PUT /api/users/{id}
更新用户信息

路径参数:

id (int, required) - 用户ID

请求参数:

real_name (string, optional) - 真实姓名
nickname (string, optional) - 昵称
phone (string, optional) - 手机号
DELETE /api/users/{id}
删除用户（仅管理员）

路径参数:

id (int, required) - 用户ID
🛠️ 管理接口

管理接口需要管理员权限，包括：

  • GET /api/admin/users - 获取用户管理数据
  • GET /api/admin/roles - 获取角色管理数据
  • GET /api/admin/permissions - 获取权限管理数据
  • GET /api/admin/applications - 获取应用管理数据
  • GET /api/admin/distribution - 获取分销管理数据
💰 分销系统

分销系统相关API正在开发中，将包括：

  • 推荐关系管理
  • 佣金计算和结算
  • 提现申请和处理
  • 分销数据统计