DFJ/02_详细设计文档/API接口设计详设.md

API接口设计详设文档

文档版本: v1.0
撰写人: 后端架构师
创建日期: 2024年9月11日

1. 设计原则与规范

• RESTful风格: API遵循RESTful设计原则，使用标准的HTTP方法 (GET, POST, PUT, DELETE)。
• JSON格式: 所有请求体和响应体均使用application/json格式。
• URL版本控制: API版本通过URL前缀进行管理，例如 /api/v1/...。
• 身份认证: 所有需要认证的接口都通过Authorization: Bearer <JWT>头进行身份验证。
• 统一响应格式: 所有API响应都遵循统一的数据结构，便于客户端处理。
• 错误处理: 使用标准的HTTP状态码表示请求结果，并在响应体中提供详细的错误信息。

2. 统一响应格式

2.1 成功响应 (2xx)

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    "key1": "value1",
    "key2": "value2"
  }
}

2.2 失败响应 (4xx, 5xx)

{
  "success": false,
  "code": 401,
  "message": "身份认证失败",
  "error": {
    "type": "AuthenticationError",
    "details": "JWT token is invalid or expired."
  }
}

3. API接口详解

3.1 用户认证模块 (/api/v1/auth)

3.1.1 POST /auth/login

• 功能: 微信小程序登录。客户端使用wx.login()获取code后调用此接口。
• 请求体:

  {
    "code": "wx-login-code-from-miniprogram"
  }
  

• 成功响应 (200 OK):
  • 描述: 返回JWT和新/老用户信息。
  • 响应体:

    {
      "success": true,
      "code": 200,
      "message": "登录成功",
      "data": {
        "token": "jwt.string.here",
        "isNewUser": false,
        "user": {
          "id": "user-openid",
          "nickname": "张三",
          "avatarUrl": "url-to-avatar"
        }
      }
    }
    

• 失败响应:
  • 400 Bad Request: code无效或缺失。
  • 500 Internal Server Error: 微信服务器接口调用失败。

3.1.2 PUT /auth/profile

• 功能: 更新用户信息（昵称、头像）。
• 认证: 需要JWT。
• 请求体:

  {
    "nickname": "新的昵称",
    "avatarUrl": "新的头像URL"
  }
  

• 成功响应 (200 OK):
  • 描述: 返回更新后的用户信息。
  • 响应体:

    {
      "success": true,
      "code": 200,
      "message": "用户信息更新成功",
      "data": {
        "id": "user-openid",
        "nickname": "新的昵称",
        "avatarUrl": "新的头像URL"
        // ...
      }
    }
    

3.2 用户信息模块 (/api/v1/users)

3.2.1 GET /users/me

• 功能: 获取当前登录用户的详细信息。
• 认证: 需要JWT。
• 成功响应 (200 OK):
  • 描述: 返回包含统计数据的完整用户信息。
  • 响应体:

    {
      "success": true,
      "code": 200,
      "message": "获取成功",
      "data": {
        "id": "user-openid",
        "nickname": "张三",
        "avatarUrl": "url-to-avatar",
        "stats": {
          "gamesPlayed": 100,
          "gamesWon": 60,
          "winRate": 60.0,
          "eloRating": 1350
        },
        "createdAt": "2024-09-10T..."
      }
    }
    

3.2.2 GET /users/:id

• 功能: 获取指定ID用户的公开信息。
• 认证: 可选。
• 成功响应 (200 OK):
  • 描述: 返回用户的公开信息（不含敏感数据）。
  • 响应体:

    {
      "success": true,
      "code": 200,
      "message": "获取成功",
      "data": {
        "id": "other-user-id",
        "nickname": "李四",
        "avatarUrl": "url-to-avatar",
        "stats": {
          "gamesPlayed": 120,
          "winRate": 55.0,
          "eloRating": 1300
        }
      }
    }
    

• 失败响应:
  • 404 Not Found: 用户不存在。

3.3 游戏模块 (/api/v1/games)

3.3.1 GET /games/history

• 功能: 获取当前用户的历史对局列表（分页）。
• 认证: 需要JWT。
• 查询参数:
  • page (number, default: 1): 页码。
  • limit (number, default: 10): 每页数量。
• 成功响应 (200 OK):
  • 描述: 返回分页的游戏历史记录。
  • 响应体:

    {
      "success": true,
      "code": 200,
      "message": "获取成功",
      "data": {
        "games": [
          {
            "gameId": "game-id-1",
            "opponent": { "id": "user-id-2", "nickname": "李四" },
            "result": "win", // "win" | "loss"
            "finishedAt": "2024-09-11T...",
            "duration": 600 // 秒
          }
        ],
        "pagination": {
          "currentPage": 1,
          "totalPages": 10,
          "totalGames": 100
        }
      }
    }
    

3.3.2 GET /games/:id

• 功能: 获取指定游戏对局的详细信息（用于复盘）。
• 认证: 需要JWT，且用户必须是该对局的参与者。
• 成功响应 (200 OK):
  • 描述: 返回完整的游戏会话数据。
  • 响应体: (完整的 GameSession 对象)
• 失败响应:
  • 403 Forbidden: 无权访问该对局。
  • 404 Not Found: 游戏不存在。

3.4 排行榜模块 (/api/v1/leaderboard)

3.4.1 GET /leaderboard

• 功能: 获取Elo积分排行榜。
• 认证: 可选。
• 查询参数:
  • limit (number, default: 100): 返回的条目数。
• 成功响应 (200 OK):
  • 描述: 返回排名列表。
  • 响应体:

    {
      "success": true,
      "code": 200,
      "message": "获取成功",
      "data": {
        "ranking": [
          {
            "rank": 1,
            "user": { "id": "user-id-1", "nickname": "高手" },
            "eloRating": 2000
          },
          {
            "rank": 2,
            "user": { "id": "user-id-2", "nickname": "大师" },
            "eloRating": 1950
          }
        ],
        "lastUpdatedAt": "2024-09-11T..."
      }
    }
    

4. WebSocket API

WebSocket通信不属于RESTful API，但其认证和初始状态获取与HTTP API紧密相关。

• 连接地址: wss://your-domain.com/ws
• 认证流程:
  1. 客户端通过POST /api/v1/auth/login获取JWT。
  2. 建立WebSocket连接。
  3. 连接成功后，发送第一条消息进行认证。
• 认证消息:

  {
    "type": "AUTHENTICATE",
    "payload": {
      "token": "jwt.string.here"
    }
  }
  

• 认证成功响应:

  {
    "type": "AUTHENTICATED",
    "payload": {
      "userId": "user-id",
      // ...
    }
  }
  

• 后续通信: 详见《实时通信模块详设文档》。