API.md 7.0 KB
API 接口文档
基础信息
- Base URL:
http://localhost:8080/api - Content-Type:
application/json - 认证方式: Bearer Token (Authorization:
Bearer {token}) - 超时时间: 10秒
通用响应格式
{
"success": true,
"message": "操作成功",
"data": { ... }
}
1. 认证模块
1.1 用户登录
接口: POST /auth/login
描述: 用户登录接口，返回用户信息和认证Token
请求体:
{
"username": "string",
"password": "string"
}
响应体:
{
"success": true,
"message": "登录成功",
"data": {
"userId": 1,
"username": "string",
"email": "string",
"studyAbility": 1,
"currentLevel": 1,
"experience": 0,
"token": "string"
}
}
1.2 用户注册
接口: POST /auth/register
描述: 用户注册接口
请求体:
{
"username": "string",
"password": "string",
"email": "string"
}
响应体:
{
"success": true,
"message": "注册成功",
"data": {
"userId": 1,
"username": "string",
"email": "string",
"studyAbility": 1,
"currentLevel": 1,
"experience": 0,
"token": "string"
}
}
2. 游戏模块
2.1 保存游戏结果
接口: POST /game/result
描述: 保存完整的游戏结果数据
认证: 需要Bearer Token
请求体:
{
"playTime": 180.5,
"roomsCompleted": 10,
"correctAnswers": 15,
"wrongAnswers": 3,
"difficulty": 2,
"isCompleted": true,
"goldCollected": 150
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| playTime | float | 是 | 游戏时长(秒) |
| roomsCompleted | int | 是 | 完成房间数 |
| correctAnswers | int | 是 | 正确答题数 |
| wrongAnswers | int | 是 | 错误答题数 |
| difficulty | int | 是 | 游戏难度等级 |
| isCompleted | bool | 是 | 是否通关 |
| goldCollected | int | 是 | 收集金币数 |
响应体:
{
"success": true,
"message": "保存成功",
"data": {
"userId": 1,
"playTime": 180.5,
"roomsCompleted": 10,
"correctAnswers": 15,
"wrongAnswers": 3,
"difficulty": 2,
"isCompleted": true,
"goldCollected": 150,
"createdAt": "2024-01-01T12:00:00Z"
}
}
2.2 获取难度配置
接口: GET /game/difficulty
描述: 获取难度等级配置信息
响应体:
{
"success": true,
"message": "获取成功",
"data": [
{
"difficultyLevel": 1,
"studyAbilityMin": 1,
"studyAbilityMax": 33,
"description": "简单难度"
},
{
"difficultyLevel": 2,
"studyAbilityMin": 34,
"studyAbilityMax": 66,
"description": "中等难度"
},
{
"difficultyLevel": 3,
"studyAbilityMin": 67,
"studyAbilityMax": 100,
"description": "困难难度"
}
]
}
2.3 获取题库
接口: GET /game/questions?difficulty={difficulty}
描述: 根据难度获取题目列表
查询参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | difficulty | int | 是 | 难度等级 |
响应体:
{
"success": true,
"message": "获取成功",
"data": [
{
"questionId": 1,
"questionText": "1 + 1 = ?",
"correctAnswer": 2,
"wrongAnswers": [1, 3, 4],
"difficulty": 1
}
]
}
3. 用户模块
3.1 更新学习力
接口: PUT /user/study-ability
描述: 更新玩家学习力等级
认证: 需要Bearer Token
请求体:
{
"studyAbility": 5
}
响应体:
{
"success": true,
"message": "更新成功",
"data": {
"userId": 1,
"studyAbility": 5,
"currentLevel": 2,
"experience": 100
}
}
3.2 更新玩家等级
接口: PUT /user/level
描述: 更新玩家等级和经验值
认证: 需要Bearer Token
请求体:
{
"currentLevel": 5,
"experience": 50
}
响应体:
{
"success": true,
"message": "更新成功",
"data": {
"userId": 1,
"currentLevel": 5,
"experience": 50,
"maxHealth": 14,
"attackPower": 1
}
}
4. 成就模块
4.1 获取成就数据
接口: GET /achievements
描述: 获取当前用户的所有成就进度
认证: 需要Bearer Token
响应体:
{
"success": true,
"message": "获取成功",
"data": [
{
"achievementId": "complete_10_rooms",
"currentValue": 10,
"isUnlocked": true,
"unlockedAt": "2024-01-01T12:00:00Z"
}
]
}
4.2 同步成就数据
接口: POST /achievements/sync
描述: 同步玩家成就进度到服务器
认证: 需要Bearer Token
请求体:
{
"achievements": [
{
"achievementId": "complete_10_rooms",
"currentValue": 10,
"isUnlocked": true
}
]
}
响应体:
{
"success": true,
"message": "同步成功",
"data": [
{
"achievementId": "complete_10_rooms",
"currentValue": 10,
"isUnlocked": true,
"unlockedAt": "2024-01-01T12:00:00Z"
}
]
}
5. 管理模块
5.1 管理员登录
接口: POST /admin/auth/login
描述: 管理员登录接口
请求体:
{
"username": "admin",
"password": "admin123"
}
响应体:
{
"success": true,
"message": "登录成功",
"data": {
"token": "string"
}
}
5.2 获取用户列表
接口: GET /admin/users
描述: 获取所有用户列表
认证: 需要管理员Bearer Token
响应体:
{
"success": true,
"message": "获取成功",
"data": [
{
"userId": 1,
"username": "player1",
"email": "player1@example.com",
"studyAbility": 5,
"currentLevel": 3,
"experience": 50,
"status": "NORMAL",
"createdAt": "2024-01-01T12:00:00Z"
}
]
}
5.3 题目管理
接口列表:
GET /admin/questions- 获取题目列表POST /admin/questions- 添加题目PUT /admin/questions/{id}- 更新题目DELETE /admin/questions/{id}- 删除题目
6. 健康检查
接口: GET /health
描述: 服务健康检查
响应体:
{
"success": true,
"message": "服务正常"
}
7. 错误码说明
| HTTP状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权/Token无效 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |