feat: 添加完整的项目设计文档，替换旧的原型需求文档
This commit is contained in:
史悦
268
02_详细设计文档/API接口设计详设.md
Normal file
268
02_详细设计文档/API接口设计详设.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# 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",
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
- **后续通信**: 详见《实时通信模块详设文档》。
|
||||
Reference in New Issue
Block a user