268 lines
6.8 KiB
Markdown
268 lines
6.8 KiB
Markdown
# 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`)
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"key1": "value1",
|
||
"key2": "value2"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 失败响应 (`4xx`, `5xx`)
|
||
|
||
```json
|
||
{
|
||
"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`后调用此接口。
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"code": "wx-login-code-from-miniprogram"
|
||
}
|
||
```
|
||
- **成功响应 (`200 OK`)**:
|
||
- **描述**: 返回JWT和新/老用户信息。
|
||
- **响应体**:
|
||
```json
|
||
{
|
||
"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。
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"nickname": "新的昵称",
|
||
"avatarUrl": "新的头像URL"
|
||
}
|
||
```
|
||
- **成功响应 (`200 OK`)**:
|
||
- **描述**: 返回更新后的用户信息。
|
||
- **响应体**:
|
||
```json
|
||
{
|
||
"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`)**:
|
||
- **描述**: 返回包含统计数据的完整用户信息。
|
||
- **响应体**:
|
||
```json
|
||
{
|
||
"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`)**:
|
||
- **描述**: 返回用户的公开信息（不含敏感数据）。
|
||
- **响应体**:
|
||
```json
|
||
{
|
||
"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`)**:
|
||
- **描述**: 返回分页的游戏历史记录。
|
||
- **响应体**:
|
||
```json
|
||
{
|
||
"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`)**:
|
||
- **描述**: 返回排名列表。
|
||
- **响应体**:
|
||
```json
|
||
{
|
||
"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. 连接成功后，发送第一条消息进行认证。
|
||
- **认证消息**:
|
||
```json
|
||
{
|
||
"type": "AUTHENTICATE",
|
||
"payload": {
|
||
"token": "jwt.string.here"
|
||
}
|
||
}
|
||
```
|
||
- **认证成功响应**:
|
||
```json
|
||
{
|
||
"type": "AUTHENTICATED",
|
||
"payload": {
|
||
"userId": "user-id",
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
- **后续通信**: 详见《实时通信模块详设文档》。 |