whale-town-end/docs/api/api-documentation.md

用户认证API接口文档

概述

本文档描述了像素游戏服务器的用户认证相关API接口，包括登录、注册、密码找回等功能。

基础URL: http://localhost:3000
API文档地址: http://localhost:3000/api-docs

通用响应格式

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

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

字段说明

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

接口列表

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": "密码修改成功"
}

错误代码说明

错误代码	说明
LOGIN_FAILED	登录失败
REGISTER_FAILED	注册失败
GITHUB_OAUTH_FAILED	GitHub OAuth失败
SEND_CODE_FAILED	发送验证码失败
RESET_PASSWORD_FAILED	重置密码失败
CHANGE_PASSWORD_FAILED	修改密码失败

数据验证规则

用户名规则

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

密码规则

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

验证码规则

• 长度：6位数字
• 正则表达式：^\d{6}$

使用示例

JavaScript/TypeScript 示例

// 用户登录
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);
}

// 用户注册
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'
  })
});

const registerData = await registerResponse.json();

cURL 示例

# 用户登录
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/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "password123",
    "nickname": "新用户",
    "email": "newuser@example.com"
  }'

# 发送密码重置验证码
curl -X POST http://localhost:3000/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "test@example.com"
  }'

# 重置密码
curl -X POST http://localhost:3000/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "test@example.com",
    "verification_code": "123456",
    "new_password": "newpassword123"
  }'

注意事项

1. 安全性: 实际应用中应使用HTTPS协议
2. 令牌: 示例中的access_token是简单的Base64编码，实际应用中应使用JWT
3. 验证码: 实际应用中不应在响应中返回验证码
4. 用户ID: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递
5. 错误处理: 建议在客户端实现适当的错误处理和用户提示
6. 限流: 建议对登录、注册等接口实施限流策略

更新日志

• v1.0.0 (2025-12-17): 初始版本，包含基础的用户认证功能