AuthBridge API 文档

概述

AuthBridge 是一个为 Minecraft 服务器设计的网页认证桥接系统。本文档提供完整的 RESTful API 接口说明。

基础信息:

基础URL: http://localhost:8080 (开发环境)
数据格式: JSON
认证方式: JWT Bearer Token
版本: v1.0.0

认证说明

大部分API需要在请求头中包含JWT令牌：

Authorization: Bearer <your-jwt-token>

公开接口（无需认证）：

/api/auth/** - 认证相关接口
/api/minecraft/** - Minecraft管理接口（部分）
/api-docs/** - API文档
/swagger-ui/** - Swagger界面

认证管理 API

1. API状态检测

检测AuthBridge API服务是否正常运行。

接口地址: GET /api/auth/test

请求参数: 无

响应示例:

AuthBridge API 正常运行

状态码: 200 OK

2. 发送手机验证码

向指定手机号发送6位数字验证码，用于注册、登录或重置密码。

接口地址: POST /api/auth/send-code

请求参数:

{
    "phoneNumber": "13812345678",
    "type": "REGISTER"
}

参数说明:

phoneNumber (string, 必填): 手机号，格式：1[3-9]xxxxxxxxx
type (string, 必填): 验证码类型，可选值：REGISTER, LOGIN, RESET_PASSWORD

成功响应:

{
    "success": true,
    "message": "验证码发送成功",
    "code": "123456",
    "expirationSeconds": 300
}

参数说明:

success (boolean): 操作是否成功
message (string): 响应消息
code (string): 验证码（仅测试环境返回）
expirationSeconds (integer): 验证码过期时间（秒）

错误响应:

{
    "success": false,
    "message": "验证码发送过于频繁，请稍后再试"
}

状态码: 200 OK / 400 Bad Request

3. 手机号注册

使用手机号和验证码注册新用户账户。

接口地址: POST /api/auth/register/phone

请求参数:

{
    "username": "testuser",
    "password": "password123",
    "phoneNumber": "13812345678",
    "verificationCode": "123456",
    "email": "test@example.com"
}

参数说明:

username (string, 必填): 用户名，3-20字符，仅支持字母数字下划线
password (string, 必填): 密码，6-20字符
phoneNumber (string, 必填): 手机号
verificationCode (string, 必填): 6位验证码
email (string, 可选): 邮箱地址

成功响应:

{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
        "id": 2,
        "username": "testuser",
        "email": "test@example.com",
        "phoneNumber": "13812345678",
        "role": "USER",
        "createdAt": "2024-01-01T12:00:00",
        "updatedAt": "2024-01-01T12:00:00"
    },
    "message": "注册成功"
}

错误响应:

{
    "success": false,
    "message": "验证码无效或用户名已存在"
}

状态码: 200 OK / 400 Bad Request

4. 手机号验证码登录

使用手机号和验证码进行登录。

接口地址: POST /api/auth/login/phone

请求参数:

{
    "phoneNumber": "13812345678",
    "verificationCode": "123456"
}

成功响应:

{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "phoneNumber": "13812345678",
        "role": "USER",
        "createdAt": "2024-01-01T12:00:00",
        "updatedAt": "2024-01-01T12:00:00"
    },
    "message": "登录成功"
}

状态码: 200 OK / 400 Bad Request

5. 用户名密码登录

使用用户名和密码进行登录。

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

请求参数:

{
    "username": "admin",
    "password": "password123"
}

成功响应:

{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
        "id": 1,
        "username": "admin",
        "email": "admin@authbridge.com",
        "phoneNumber": null,
        "role": "ADMIN",
        "createdAt": "2024-01-01T00:00:00",
        "updatedAt": "2024-01-01T00:00:00"
    },
    "message": "登录成功"
}

错误响应:

用户不存在: {"success": false, "message": "用户不存在"}
密码错误: {"success": false, "message": "密码错误"}
账户被锁定: {"success": false, "message": "账户已被锁定"}

状态码: 200 OK / 400 Bad Request

6. 用户登出

登出当前用户，清除会话信息。

接口地址: POST /api/auth/logout

请求头:

Authorization: Bearer <jwt-token>

响应示例:

登出成功

状态码: 200 OK

Minecraft 管理 API

1. 获取玩家信息

根据UUID获取Minecraft玩家信息。

接口地址: GET /api/minecraft/player/{uuid}

路径参数:

uuid (string): Minecraft玩家UUID

成功响应:

{
    "id": 1,
    "minecraftUuid": "550e8400-e29b-41d4-a716-446655440000",
    "minecraftUsername": "AdminPlayer",
    "premium": true,
    "online": false,
    "serverName": null,
    "worldName": null,
    "lastLogin": "2024-01-01T00:00:00",
    "xCoordinate": 0.0,
    "yCoordinate": 64.0,
    "zCoordinate": 0.0
}

状态码: 200 OK / 404 Not Found

2. 根据用户名获取玩家信息

接口地址: GET /api/minecraft/player/username/{username}

路径参数:

username (string): Minecraft用户名

响应格式: 与获取玩家信息相同

3. 玩家登录服务器

记录玩家登录到指定服务器。

接口地址: POST /api/minecraft/player/login

查询参数:

uuid (string): 玩家UUID
username (string): 玩家用户名
ip (string): 玩家IP地址
serverName (string): 服务器名称

成功响应:

{
    "success": true,
    "message": "玩家登录成功",
    "player": {
        "id": 1,
        "minecraftUuid": "550e8400-e29b-41d4-a716-446655440000",
        "minecraftUsername": "TestPlayer",
        "online": true,
        "serverName": "main",
        "lastIp": "127.0.0.1",
        "lastLogin": "2024-01-01T12:00:00"
    }
}

状态码: 200 OK

4. 玩家登出服务器

记录玩家从服务器登出。

接口地址: POST /api/minecraft/player/logout

查询参数:

uuid (string): 玩家UUID

成功响应:

{
    "success": true,
    "message": "玩家登出成功"
}

状态码: 200 OK

5. 更新玩家位置

更新玩家在游戏世界中的位置。

接口地址: POST /api/minecraft/player/location

查询参数:

uuid (string): 玩家UUID
worldName (string): 世界名称
x (double): X坐标
y (double): Y坐标
z (double): Z坐标

成功响应:

{
    "success": true,
    "message": "位置更新成功"
}

状态码: 200 OK

6. 获取在线玩家数量

获取全服在线玩家数量。

接口地址: GET /api/minecraft/stats/online-count

成功响应:

{
    "onlineCount": 2
}

状态码: 200 OK

7. 获取服务器在线玩家数量

获取指定服务器的在线玩家数量。

接口地址: GET /api/minecraft/stats/online-count/{serverName}

路径参数:

serverName (string): 服务器名称

成功响应:

{
    "serverName": "main",
    "onlineCount": 1
}

状态码: 200 OK

8. 获取在线玩家列表

获取全服在线玩家列表。

接口地址: GET /api/minecraft/players/online

成功响应:

[
    {
        "id": 1,
        "minecraftUuid": "550e8400-e29b-41d4-a716-446655440000",
        "minecraftUsername": "AdminPlayer",
        "online": true,
        "serverName": "main",
        "worldName": "world",
        "lastLogin": "2024-01-01T12:00:00"
    }
]

状态码: 200 OK

9. 获取指定服务器玩家列表

接口地址: GET /api/minecraft/players/server/{serverName}

路径参数:

serverName (string): 服务器名称

响应格式: 与获取在线玩家列表相同

10. 检查玩家在线状态

接口地址: GET /api/minecraft/player/{uuid}/online

成功响应:

{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "online": true
}

状态码: 200 OK

会话管理 API

1. 设置玩家会话

为玩家设置Redis会话缓存。

接口地址: POST /api/minecraft/player/{uuid}/session

路径参数:

uuid (string): 玩家UUID

查询参数:

sessionToken (string): 会话令牌
expireMinutes (integer): 过期时间（分钟）

成功响应:

{
    "success": true,
    "message": "会话设置成功"
}

状态码: 200 OK

2. 获取玩家会话

接口地址: GET /api/minecraft/player/{uuid}/session

成功响应:

{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "sessionToken": "test-session-token-123",
    "hasSession": true
}

状态码: 200 OK

3. 删除玩家会话

接口地址: DELETE /api/minecraft/player/{uuid}/session

成功响应:

{
    "success": true,
    "message": "会话删除成功"
}

状态码: 200 OK

错误处理

HTTP状态码说明

200 OK: 请求成功
400 Bad Request: 请求参数错误
401 Unauthorized: 未授权或JWT令牌无效
403 Forbidden: 权限不足
404 Not Found: 资源不存在
500 Internal Server Error: 服务器内部错误

标准错误响应格式

{
    "success": false,
    "message": "错误描述",
    "code": "ERROR_CODE",
    "timestamp": "2024-01-01T12:00:00"
}

常见错误码

INVALID_TOKEN: JWT令牌无效
TOKEN_EXPIRED: JWT令牌已过期
USER_NOT_FOUND: 用户不存在
INVALID_CREDENTIALS: 登录凭据无效
ACCOUNT_LOCKED: 账户被锁定
VERIFICATION_CODE_INVALID: 验证码无效
VERIFICATION_CODE_EXPIRED: 验证码已过期
PHONE_NUMBER_EXISTS: 手机号已存在
USERNAME_EXISTS: 用户名已存在

环境变量配置

数据库配置

DB_USERNAME=root
DB_PASSWORD=123456
DB_URL=jdbc:mysql://localhost:3306/authbridge

Redis配置

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DATABASE=3
REDIS_PASSWORD=

JWT配置

JWT_SECRET=your-secret-key
JWT_EXPIRATION=86400000

短信配置

SMS_ENABLED=false
SMS_PROVIDER=mock
VERIFICATION_CODE_EXPIRATION=300

测试数据

测试账户

用户名	密码	角色	手机号
admin	password123	ADMIN	-
player1	password123	USER	-

测试UUID

550e8400-e29b-41d4-a716-446655440000

接口测试

使用curl测试

# API状态检测
curl -X GET "http://localhost:8080/api/auth/test"

# 发送验证码
curl -X POST "http://localhost:8080/api/auth/send-code" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"13812345678","type":"REGISTER"}'

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

使用集成测试脚本

# Windows
./backend/api-test.bat

# Linux/Mac
./backend/api-test.sh

Swagger UI

访问 http://localhost:8080/swagger-ui.html 使用交互式API文档。

Apifox导入

导入项目根目录的 authbridge-openapi.json 或 apifox-collection.json 文件。

开发指南

本地开发环境搭建

安装依赖:
- Java 21
- MySQL 8.0+
- Redis 6.0+
- Maven 3.8+

数据库初始化:

mysql -u root -p < backend/src/main/resources/db/schema.sql
mysql -u root -p < backend/src/main/resources/db/data.sql

启动Redis:
```
redis-server
```
启动后端:
```
cd backend
mvn spring-boot:run
```
启动前端:
```
cd frontend
npm install
npm run dev
```

API版本控制

当前API版本为 v1.0.0，未来版本更新将遵循语义版本控制规范。

速率限制

验证码发送：每手机号每分钟最多1次
登录尝试：连续5次失败后锁定账户1小时
API调用：暂无全局限制

更新日志

v1.0.0 (2024-01-01)

初始版本发布
支持用户名密码登录
支持手机号验证码注册和登录
Minecraft玩家管理功能
会话管理和Redis缓存
完整的API文档和测试工具

技术支持

项目地址: https://github.com/Fzhiyu1/AuthBridge
API文档: http://localhost:8080/swagger-ui.html
问题反馈: 请在GitHub项目中提交Issue

最后更新: 2024-01-01

FilesExpand file tree

API-DOCUMENTATION.md

Latest commit

History

API-DOCUMENTATION.md

File metadata and controls

AuthBridge API 文档

概述

认证说明

认证管理 API

1. API状态检测

2. 发送手机验证码

3. 手机号注册

4. 手机号验证码登录

5. 用户名密码登录

6. 用户登出

Minecraft 管理 API

1. 获取玩家信息

2. 根据用户名获取玩家信息

3. 玩家登录服务器

4. 玩家登出服务器

5. 更新玩家位置

6. 获取在线玩家数量

7. 获取服务器在线玩家数量

8. 获取在线玩家列表

9. 获取指定服务器玩家列表

10. 检查玩家在线状态

会话管理 API

1. 设置玩家会话

2. 获取玩家会话

3. 删除玩家会话

错误处理

HTTP状态码说明

标准错误响应格式

常见错误码

环境变量配置

数据库配置

Redis配置

JWT配置

短信配置

测试数据

测试账户

测试UUID

接口测试

使用curl测试

使用集成测试脚本

Swagger UI

Apifox导入

开发指南

本地开发环境搭建

API版本控制

速率限制

更新日志

v1.0.0 (2024-01-01)

技术支持