Skip to content

api_all.md

Latest commit

 

History

History
266 lines (225 loc) · 5.58 KB

api_all.md

File metadata and controls

266 lines (225 loc) · 5.58 KB
Raw

玩家管理系统 API 文档

本文档详细描述了玩家管理系统提供的所有API端点。

基础信息

  • API 基础 URL: http://154.12.60.228:5000
  • 请求和响应格式: JSON
  • 默认端口: 5000

API 端点列表

1. 获取所有玩家信息

描述: 获取系统中所有玩家的基本信息

请求:

  • 方法: GET
  • 路径: /api/players
  • 参数: 无
  • 认证: 无

响应:

  • 状态码: 200 OK
  • 内容: JSON对象，包含所有玩家信息
  • 示例:
{
  "a1b2c3d4": {
    "id": "a1b2c3d4",
    "nickname": "玩家1",
    "email": "player1@example.com",
    "password": "$2b$12$randomhashvalue",
    "battle_records": []
  },
  "e5f6g7h8": {
    "id": "e5f6g7h8",
    "nickname": "玩家2",
    "email": "player2@example.com",
    "password": "$2b$12$anotherhashvalue",
    "battle_records": [ ... ]
  }
}

2. 创建新玩家

描述: 在系统中创建一个新玩家账户

请求:

  • 方法: POST
  • 路径: /api/players
  • 参数: JSON请求体
    • nickname (必需): 玩家昵称
    • email (必需): 玩家邮箱（必须唯一）
    • password (必需): 玩家密码（将被加密存储）
  • 认证: 无

响应:

  • 状态码: 201 Created (成功)
  • 状态码: 400 Bad Request (缺少必填字段或邮箱已存在)
  • 内容: 创建的玩家信息（包含生成的ID和加密后的密码）
  • 示例:
{
  "id": "a1b2c3d4",
  "nickname": "新玩家",
  "email": "newplayer@example.com",
  "password": "$2b$12$randomhashvalue",
  "battle_records": []
}

3. 获取单个玩家信息

描述: 获取指定ID的玩家详细信息

请求:

  • 方法: GET
  • 路径: /api/players/<player_id>
  • 参数: URL路径中的player_id
  • 认证: 无

响应:

  • 状态码: 200 OK (成功)
  • 状态码: 404 Not Found (玩家不存在)
  • 内容: 玩家详细信息
  • 示例:
{
  "id": "a1b2c3d4",
  "nickname": "玩家1",
  "email": "player1@example.com",
  "password": "$2b$12$randomhashvalue",
  "battle_records": [ ... ]
}

4. 更新玩家昵称

描述: 更新指定玩家的昵称

请求:

  • 方法: PUT
  • 路径: /api/players/<player_id>/nickname
  • 参数:
    • URL路径中的player_id
    • JSON请求体中的nickname字段
  • 认证: 无

响应:

  • 状态码: 200 OK (成功)
  • 状态码: 404 Not Found (玩家不存在)
  • 状态码: 400 Bad Request (缺少nickname字段)
  • 内容: 更新后的玩家信息
  • 示例:
{
  "id": "a1b2c3d4",
  "nickname": "新昵称",
  "email": "player1@example.com",
  "password": "$2b$12$randomhashvalue",
  "battle_records": [ ... ]
}

5. 更新玩家邮箱

描述: 更新指定玩家的邮箱地址

请求:

  • 方法: PUT
  • 路径: /api/players/<player_id>/email
  • 参数:
    • URL路径中的player_id
    • JSON请求体中的email字段
  • 认证: 无

响应:

  • 状态码: 200 OK (成功)
  • 状态码: 404 Not Found (玩家不存在)
  • 状态码: 400 Bad Request (缺少email字段或邮箱已被使用)
  • 内容: 更新后的玩家信息
  • 示例:
{
  "id": "a1b2c3d4",
  "nickname": "玩家1",
  "email": "newemail@example.com",
  "password": "$2b$12$randomhashvalue",
  "battle_records": [ ... ]
}

6. 更新玩家密码

描述: 更新指定玩家的密码（需要验证当前密码）

请求:

  • 方法: PUT
  • 路径: /api/players/<player_id>/password
  • 参数:
    • URL路径中的player_id
    • JSON请求体
      • current_password: 当前密码
      • new_password: 新密码
  • 认证: 无

响应:

  • 状态码: 200 OK (成功)
  • 状态码: 404 Not Found (玩家不存在)
  • 状态码: 400 Bad Request (缺少密码字段)
  • 状态码: 401 Unauthorized (当前密码不正确)
  • 内容: 成功消息
  • 示例:
{
  "message": "Password updated successfully"
}

7. 添加对战记录

描述: 为指定玩家添加一条对战记录

请求:

  • 方法: POST
  • 路径: /api/players/<player_id>/battle_records
  • 参数:
    • URL路径中的player_id
    • JSON请求体
      • opponent: 对手名称
      • result: 对战结果 (win, lose, draw)
      • score: 对战得分
      • timestamp (可选): 对战时间戳
  • 认证: 无

响应:

  • 状态码: 201 Created (成功)
  • 状态码: 404 Not Found (玩家不存在)
  • 状态码: 400 Bad Request (缺少必填字段)
  • 内容: 创建的对战记录（包含生成的ID）
  • 示例:
{
  "id": "r5s6t7u8",
  "opponent": "对手玩家",
  "result": "win",
  "score": "100-80",
  "timestamp": "1620000000"
}

8. 获取对战记录

描述: 获取指定玩家的所有对战记录

请求:

  • 方法: GET
  • 路径: /api/players/<player_id>/battle_records
  • 参数: URL路径中的player_id
  • 认证: 无

响应:

  • 状态码: 200 OK (成功)
  • 状态码: 404 Not Found (玩家不存在)
  • 内容: 对战记录列表
  • 示例:
[
  {
    "id": "r5s6t7u8",
    "opponent": "对手玩家1",
    "result": "win",
    "score": "100-80",
    "timestamp": "1620000000"
  },
  {
    "id": "v9w0x1y2",
    "opponent": "对手玩家2",
    "result": "lose",
    "score": "70-90",
    "timestamp": "1620000100"
  }
]

错误处理

API会返回以下常见错误状态码：

  • 400 Bad Request: 请求参数错误或缺少必需字段
  • 401 Unauthorized: 密码验证失败
  • 404 Not Found: 请求的资源不存在

所有错误响应都包含一个JSON对象，其中包含错误描述：

{
  "error": "错误描述文本"
}

数据存储

  • 所有玩家数据存储在players.json文件中
  • 密码使用bcrypt算法加密存储，无法直接解密
  • 玩家ID和对战记录ID使用UUID生成，确保唯一性