datawhale/whale-town-end
3
4
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
032c97a1fc4a529e4ad60beb3ce8614253dc9be3
whale-town-end/docs/api/api-documentation.md
moyin 032c97a1fc docs: 全面更新API接口文档 
- 重构文档结构，按功能模块分类
- 新增应用状态接口 (GET /)
- 完善用户认证接口，新增4个邮箱验证相关接口
- 新增管理员后台接口，包含用户管理和日志管理
- 更新错误代码说明和数据验证规则
- 完善使用示例和注意事项
- 更新版本日志至v1.0.0

涵盖后端所有API接口，提供完整的开发参考文档
2025-12-23 19:51:34 +08:00

20 KiB
Raw Blame History

Pixel Game Server API接口文档

概述

本文档描述了像素游戏服务器的完整API接口，包括用户认证、管理员后台、应用状态等功能。

基础URL: http://localhost:3000
API文档地址: http://localhost:3000/api-docs
项目名称: Pixel Game Server
版本: 1.0.0

通用响应格式

所有API接口都遵循统一的响应格式：

{
  "success": boolean,
  "data": object | null,
  "message": string,
  "error_code": string | null
}

字段说明

  • success: 请求是否成功
  • data: 响应数据（成功时返回）
  • message: 响应消息
  • error_code: 错误代码（失败时返回）

接口分类

1. 应用状态接口 (App)

  • GET / - 获取应用状态

2. 用户认证接口 (Auth)

  • POST /auth/login - 用户登录
  • POST /auth/register - 用户注册
  • POST /auth/github - GitHub OAuth登录
  • POST /auth/forgot-password - 发送密码重置验证码
  • POST /auth/reset-password - 重置密码
  • PUT /auth/change-password - 修改密码
  • POST /auth/send-email-verification - 发送邮箱验证码
  • POST /auth/verify-email - 验证邮箱验证码
  • POST /auth/resend-email-verification - 重新发送邮箱验证码
  • POST /auth/debug-verification-code - 调试验证码信息（开发环境）

3. 管理员接口 (Admin)

  • POST /admin/auth/login - 管理员登录
  • GET /admin/users - 获取用户列表
  • GET /admin/users/:id - 获取用户详情
  • POST /admin/users/:id/reset-password - 重置用户密码
  • GET /admin/logs/runtime - 获取运行日志
  • GET /admin/logs/archive - 下载日志压缩包

接口列表

应用状态接口

1. 获取应用状态

接口地址: GET /

功能描述: 返回应用的基本运行状态信息，用于健康检查和监控

请求参数

无

响应示例

成功响应 (200):

{
  "service": "Pixel Game Server",
  "version": "1.0.0",
  "status": "running",
  "timestamp": "2025-12-23T10:00:00.000Z",
  "uptime": 3600,
  "environment": "development",
  "storage_mode": "memory"
}
字段名 类型 说明
service string 服务名称
version string 服务版本
status string 运行状态 (running/starting/stopping/error)
timestamp string 当前时间戳
uptime number 运行时间（秒）
environment string 运行环境 (development/production/test)
storage_mode string 存储模式 (database/memory)

用户认证接口

1. 用户登录

接口地址: POST /auth/login

功能描述: 用户登录，支持用户名、邮箱或手机号登录

请求参数

{
  "identifier": "testuser",
  "password": "password123"
}
参数名 类型 必填 说明
identifier string 是 登录标识符，支持用户名、邮箱或手机号
password string 是 用户密码

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "user": {
      "id": "1",
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "+8613800138000",
      "avatar_url": "https://example.com/avatar.jpg",
      "role": 1,
      "created_at": "2025-12-17T10:00:00.000Z"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "is_new_user": false,
    "message": "登录成功"
  },
  "message": "登录成功"
}

失败响应 (401):

{
  "success": false,
  "message": "用户名或密码错误",
  "error_code": "LOGIN_FAILED"
}

2. 用户注册

接口地址: POST /auth/register

功能描述: 创建新用户账户

请求参数

{
  "username": "testuser",
  "password": "password123",
  "nickname": "测试用户",
  "email": "test@example.com",
  "phone": "+8613800138000"
}
参数名 类型 必填 说明
username string 是 用户名，只能包含字母、数字和下划线，长度1-50字符
password string 是 密码，必须包含字母和数字，长度8-128字符
nickname string 是 用户昵称，长度1-50字符
email string 否 邮箱地址
phone string 否 手机号码

响应示例

成功响应 (201):

{
  "success": true,
  "data": {
    "user": {
      "id": "2",
      "username": "testuser",
      "nickname": "测试用户",
      "email": "test@example.com",
      "phone": "+8613800138000",
      "avatar_url": null,
      "role": 1,
      "created_at": "2025-12-17T10:00:00.000Z"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "is_new_user": true,
    "message": "注册成功"
  },
  "message": "注册成功"
}

失败响应 (409):

{
  "success": false,
  "message": "用户名已存在",
  "error_code": "REGISTER_FAILED"
}

3. GitHub OAuth登录

接口地址: POST /auth/github

功能描述: 使用GitHub账户登录或注册

请求参数

{
  "github_id": "12345678",
  "username": "octocat",
  "nickname": "The Octocat",
  "email": "octocat@github.com",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif"
}
参数名 类型 必填 说明
github_id string 是 GitHub用户ID
username string 是 GitHub用户名
nickname string 是 GitHub显示名称
email string 否 GitHub邮箱地址
avatar_url string 否 GitHub头像URL

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "user": {
      "id": "3",
      "username": "octocat",
      "nickname": "The Octocat",
      "email": "octocat@github.com",
      "phone": null,
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "role": 1,
      "created_at": "2025-12-17T10:00:00.000Z"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "is_new_user": true,
    "message": "GitHub账户绑定成功"
  },
  "message": "GitHub账户绑定成功"
}

4. 发送密码重置验证码

接口地址: POST /auth/forgot-password

功能描述: 向用户邮箱或手机发送密码重置验证码

请求参数

{
  "identifier": "test@example.com"
}
参数名 类型 必填 说明
identifier string 是 邮箱或手机号

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "verification_code": "123456"
  },
  "message": "验证码已发送，请查收"
}

注意: 实际应用中不应返回验证码，这里仅用于演示。

5. 重置密码

接口地址: POST /auth/reset-password

功能描述: 使用验证码重置用户密码

请求参数

{
  "identifier": "test@example.com",
  "verification_code": "123456",
  "new_password": "newpassword123"
}
参数名 类型 必填 说明
identifier string 是 邮箱或手机号
verification_code string 是 6位数字验证码
new_password string 是 新密码，必须包含字母和数字，长度8-128字符

响应示例

成功响应 (200):

{
  "success": true,
  "message": "密码重置成功"
}

6. 修改密码

接口地址: PUT /auth/change-password

功能描述: 用户修改自己的密码（需要提供旧密码）

请求参数

{
  "user_id": "1",
  "old_password": "oldpassword123",
  "new_password": "newpassword123"
}
参数名 类型 必填 说明
user_id string 是 用户ID（实际应用中应从JWT令牌中获取）
old_password string 是 当前密码
new_password string 是 新密码，必须包含字母和数字，长度8-128字符

响应示例

成功响应 (200):

{
  "success": true,
  "message": "密码修改成功"
}

7. 发送邮箱验证码

接口地址: POST /auth/send-email-verification

功能描述: 向指定邮箱发送验证码，用于注册时的邮箱验证

请求参数

{
  "email": "test@example.com"
}
参数名 类型 必填 说明
email string 是 邮箱地址

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "verification_code": "123456",
    "is_test_mode": false
  },
  "message": "验证码已发送，请查收"
}

测试模式响应 (206):

{
  "success": false,
  "data": {
    "verification_code": "059174",
    "is_test_mode": true
  },
  "message": "⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码，或配置邮件服务以启用真实发送。",
  "error_code": "TEST_MODE_ONLY"
}

8. 验证邮箱验证码

接口地址: POST /auth/verify-email

功能描述: 使用验证码验证邮箱

请求参数

{
  "email": "test@example.com",
  "verification_code": "123456"
}
参数名 类型 必填 说明
email string 是 邮箱地址
verification_code string 是 6位数字验证码

响应示例

成功响应 (200):

{
  "success": true,
  "message": "邮箱验证成功"
}

9. 重新发送邮箱验证码

接口地址: POST /auth/resend-email-verification

功能描述: 重新向指定邮箱发送验证码

请求参数

{
  "email": "test@example.com"
}
参数名 类型 必填 说明
email string 是 邮箱地址

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "verification_code": "123456",
    "is_test_mode": false
  },
  "message": "验证码已重新发送，请查收"
}

10. 调试验证码信息

接口地址: POST /auth/debug-verification-code

功能描述: 获取验证码的详细调试信息（仅开发环境使用）

请求参数

{
  "email": "test@example.com"
}
参数名 类型 必填 说明
email string 是 邮箱地址

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "email": "test@example.com",
    "verification_code": "123456",
    "expires_at": "2025-12-23T10:15:00.000Z",
    "created_at": "2025-12-23T10:00:00.000Z"
  },
  "message": "调试信息获取成功"
}

管理员接口

注意：所有管理员接口都需要在 Header 中携带 Authorization: Bearer <token>，且用户角色必须为管理员 (role=9)。

1. 管理员登录

接口地址: POST /admin/auth/login

功能描述: 管理员登录，仅允许 role=9 的账户登录后台

请求参数

{
  "identifier": "admin",
  "password": "Admin123456"
}
参数名 类型 必填 说明
identifier string 是 登录标识符（用户名/邮箱/手机号）
password string 是 密码

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "admin": {
      "id": "1",
      "username": "admin",
      "nickname": "管理员",
      "role": 9
    },
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": 1766102400000
  },
  "message": "管理员登录成功"
}

2. 获取用户列表

接口地址: GET /admin/users

功能描述: 分页获取所有注册用户列表

请求参数

参数名 类型 必填 说明
limit number 否 每页数量，默认100
offset number 否 偏移量，默认0

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "1",
        "username": "user1",
        "nickname": "小明",
        "email": "user1@example.com",
        "email_verified": false,
        "phone": "+8613800138000",
        "avatar_url": "https://example.com/avatar.png",
        "role": 1,
        "created_at": "2025-12-19T00:00:00.000Z",
        "updated_at": "2025-12-19T00:00:00.000Z"
      }
    ],
    "limit": 100,
    "offset": 0
  },
  "message": "用户列表获取成功"
}

3. 获取用户详情

接口地址: GET /admin/users/:id

功能描述: 获取指定用户的详细信息

请求参数

参数名 类型 必填 说明
id string 是 用户ID（路径参数）

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "user": {
      "id": "1",
      "username": "user1",
      "nickname": "小明",
      "email": "user1@example.com",
      "email_verified": false,
      "phone": "+8613800138000",
      "avatar_url": "https://example.com/avatar.png",
      "role": 1,
      "created_at": "2025-12-19T00:00:00.000Z",
      "updated_at": "2025-12-19T00:00:00.000Z"
    }
  },
  "message": "用户信息获取成功"
}

4. 重置用户密码

接口地址: POST /admin/users/:id/reset-password

功能描述: 管理员强制重置指定用户的密码

请求参数

参数名 类型 必填 说明
id string 是 用户ID（路径参数）
new_password string 是 新密码（至少8位，包含字母和数字） 
{
  "new_password": "NewPass1234"
}

响应示例

成功响应 (200):

{
  "success": true,
  "message": "密码重置成功"
}

5. 获取运行日志

接口地址: GET /admin/logs/runtime

功能描述: 从 logs/ 目录读取最近的日志行

请求参数

参数名 类型 必填 说明
lines number 否 返回行数，默认200，最大2000

响应示例

成功响应 (200):

{
  "success": true,
  "data": {
    "file": "dev.log",
    "updated_at": "2025-12-19T19:10:15.000Z",
    "lines": [
      "[2025-12-19 19:10:15] INFO: Server started",
      "[2025-12-19 19:10:16] INFO: Database connected"
    ]
  },
  "message": "运行日志获取成功"
}

6. 下载日志压缩包

接口地址: GET /admin/logs/archive

功能描述: 将 logs/ 目录打包为 tar.gz 并下载

请求参数

无

响应示例

成功响应 (200):

  • Content-Type: application/gzip
  • Content-Disposition: attachment; filename="logs-2025-12-23T10-00-00-000Z.tar.gz"
  • 返回二进制流（tar.gz 文件）

错误代码说明

错误代码 说明
LOGIN_FAILED 登录失败
REGISTER_FAILED 注册失败
GITHUB_OAUTH_FAILED GitHub OAuth失败
SEND_CODE_FAILED 发送验证码失败
RESET_PASSWORD_FAILED 重置密码失败
CHANGE_PASSWORD_FAILED 修改密码失败
TEST_MODE_ONLY 测试模式（验证码未真实发送）
ADMIN_LOGIN_FAILED 管理员登录失败
ADMIN_USERS_FAILED 获取用户列表失败
ADMIN_OPERATION_FAILED 管理员操作失败

数据验证规则

用户名规则

  • 长度：1-50字符
  • 格式：只能包含字母、数字和下划线
  • 正则表达式：^[a-zA-Z0-9_]+$

密码规则

  • 长度：8-128字符
  • 格式：必须包含字母和数字
  • 正则表达式：^(?=.*[a-zA-Z])(?=.*\d)

验证码规则

  • 长度：6位数字
  • 正则表达式：^\d{6}$
  • 有效期：通常为5-15分钟

邮箱规则

  • 格式：符合标准邮箱格式
  • 验证：支持邮箱验证码验证

管理员权限

  • 角色：role=9 为管理员
  • 认证：需要 JWT Token
  • 权限：可管理所有用户数据

使用示例

JavaScript/TypeScript 示例

// 获取应用状态
const statusResponse = await fetch('http://localhost:3000/');
const statusData = await statusResponse.json();
console.log('服务状态:', statusData.status);

// 用户登录
const loginResponse = await fetch('http://localhost:3000/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    identifier: 'testuser',
    password: 'password123'
  })
});

const loginData = await loginResponse.json();
if (loginData.success) {
  const token = loginData.data.access_token;
  // 保存token用于后续请求
  localStorage.setItem('token', token);
}

// 用户注册（带邮箱验证）
// 1. 先发送邮箱验证码
const sendCodeResponse = await fetch('http://localhost:3000/auth/send-email-verification', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'newuser@example.com'
  })
});

// 2. 用户输入验证码后进行注册
const registerResponse = await fetch('http://localhost:3000/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    username: 'newuser',
    password: 'password123',
    nickname: '新用户',
    email: 'newuser@example.com',
    email_verification_code: '123456'
  })
});

// 管理员登录
const adminLoginResponse = await fetch('http://localhost:3000/admin/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    identifier: 'admin',
    password: 'Admin123456'
  })
});

const adminData = await adminLoginResponse.json();
if (adminData.success) {
  const adminToken = adminData.data.access_token;
  
  // 获取用户列表
  const usersResponse = await fetch('http://localhost:3000/admin/users?limit=10&offset=0', {
    headers: {
      'Authorization': `Bearer ${adminToken}`
    }
  });
  
  const usersData = await usersResponse.json();
  console.log('用户列表:', usersData.data.users);
}

cURL 示例

# 获取应用状态
curl -X GET http://localhost:3000/

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

# 发送邮箱验证码
curl -X POST http://localhost:3000/auth/send-email-verification \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com"
  }'

# 用户注册
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "password123",
    "nickname": "新用户",
    "email": "newuser@example.com",
    "email_verification_code": "123456"
  }'

# 管理员登录
curl -X POST http://localhost:3000/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "admin",
    "password": "Admin123456"
  }'

# 获取用户列表（需要管理员Token）
curl -X GET "http://localhost:3000/admin/users?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# 重置用户密码
curl -X POST http://localhost:3000/admin/users/1/reset-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -d '{
    "new_password": "NewPass1234"
  }'

# 获取运行日志
curl -X GET "http://localhost:3000/admin/logs/runtime?lines=100" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# 下载日志压缩包
curl -X GET http://localhost:3000/admin/logs/archive \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -o logs.tar.gz

注意事项

  1. 安全性: 实际应用中应使用HTTPS协议
  2. 令牌: 示例中的access_token是JWT格式，需要妥善保存
  3. 验证码:
    • 实际应用中不应在响应中返回验证码
    • 测试模式下会在控制台显示验证码
    • 验证码有效期通常为5-15分钟
  4. 用户ID: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递
  5. 错误处理: 建议在客户端实现适当的错误处理和用户提示
  6. 限流: 建议对登录、注册等接口实施限流策略
  7. 管理员权限:
    • 管理员接口需要 role=9 的用户权限
    • 需要在请求头中携带有效的JWT Token
    • Token格式：Authorization: Bearer <token>
  8. 存储模式:
    • 数据库模式：数据持久化存储在MySQL
    • 内存模式：数据存储在内存中，重启后丢失
  9. 邮箱验证:
    • 注册时如果提供邮箱，需要先获取验证码
    • 支持重新发送验证码功能
    • 调试接口仅用于开发环境

更新日志

  • v1.0.0 (2025-12-23):
    • 完整的API文档更新
    • 新增应用状态接口
    • 新增邮箱验证相关接口
    • 新增管理员后台接口
    • 新增日志管理功能
    • 完善错误代码和使用示例
Reference in New Issue View Git Blame Copy Permalink