初始化斗地主残局版项目
This commit is contained in:
277
API.md
Normal file
277
API.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 斗地主残局版 API 文档
|
||||
|
||||
## 基础信息
|
||||
|
||||
- 基础URL: `http://<host>/api`
|
||||
- 响应格式: JSON
|
||||
|
||||
## 响应格式
|
||||
|
||||
所有API响应遵循统一格式:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 200,
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| status | int | HTTP状态码 |
|
||||
| code | int | 业务状态码 (0=成功, 1=失败) |
|
||||
| message | string | 提示信息 |
|
||||
| data | object | 实际业务数据 |
|
||||
|
||||
---
|
||||
|
||||
## HTTP API
|
||||
|
||||
### 创建房间
|
||||
|
||||
**POST** `/api/rooms`
|
||||
|
||||
请求体:
|
||||
```json
|
||||
{
|
||||
"playerName": "玩家昵称",
|
||||
"maxPlayers": 4
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| playerName | string | 是 | 玩家昵称 |
|
||||
| maxPlayers | int | 否 | 最大玩家数，默认4，范围2-10 |
|
||||
|
||||
响应:
|
||||
```json
|
||||
{
|
||||
"status": 200,
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"roomId": "a1b2c3d4e5f6g7h8",
|
||||
"playerId": "i9j0k1l2m3n4o5p6"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 加入房间
|
||||
|
||||
**POST** `/api/rooms/{roomId}/join`
|
||||
|
||||
请求体:
|
||||
```json
|
||||
{
|
||||
"playerName": "玩家昵称"
|
||||
}
|
||||
```
|
||||
|
||||
响应:
|
||||
```json
|
||||
{
|
||||
"status": 200,
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"roomId": "a1b2c3d4e5f6g7h8",
|
||||
"playerId": "q7r8s9t0u1v2w3x4"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 400,
|
||||
"code": 1,
|
||||
"message": "room not found",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WebSocket API
|
||||
|
||||
**连接地址**: `ws://<host>/api/ws?roomId={roomId}&playerId={playerId}`
|
||||
|
||||
### 消息格式
|
||||
|
||||
所有消息为JSON格式:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "消息类型",
|
||||
"playerId": "玩家ID",
|
||||
"roomId": "房间ID",
|
||||
"data": { ... },
|
||||
"timestamp": 1708123456
|
||||
}
|
||||
```
|
||||
|
||||
### 消息类型
|
||||
|
||||
| 类型 | 方向 | 说明 |
|
||||
|------|------|------|
|
||||
| ready | 客户端→服务器 | 准备/取消准备 |
|
||||
| play | 客户端→服务器 | 出牌 |
|
||||
| pass | 客户端→服务器 | 不出 |
|
||||
| chat | 双向 | 聊天消息 |
|
||||
| state | 服务器→客户端 | 游戏状态更新 |
|
||||
| gameOver | 服务器→客户端 | 游戏结束 |
|
||||
| error | 服务器→客户端 | 错误消息 |
|
||||
|
||||
### 准备
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "ready",
|
||||
"playerId": "xxx",
|
||||
"roomId": "xxx",
|
||||
"data": { "ready": true }
|
||||
}
|
||||
```
|
||||
|
||||
当所有玩家都准备后，游戏自动开始。
|
||||
|
||||
### 出牌
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "play",
|
||||
"playerId": "xxx",
|
||||
"roomId": "xxx",
|
||||
"data": {
|
||||
"cards": [
|
||||
{ "suit": 0, "value": 14 },
|
||||
{ "suit": 1, "value": 14 }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 不出
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "pass",
|
||||
"playerId": "xxx",
|
||||
"roomId": "xxx"
|
||||
}
|
||||
```
|
||||
|
||||
注意: 只能在上家出牌后才能"不出"，自己最后出牌时不能"不出"。
|
||||
|
||||
### 聊天
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "chat",
|
||||
"playerId": "xxx",
|
||||
"roomId": "xxx",
|
||||
"data": "消息内容"
|
||||
}
|
||||
```
|
||||
|
||||
### 游戏状态 (服务器推送)
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "state",
|
||||
"data": {
|
||||
"id": "a1b2c3d4e5f6g7h8",
|
||||
"players": [
|
||||
{
|
||||
"id": "xxx",
|
||||
"name": "玩家1",
|
||||
"cards": [...],
|
||||
"cardCount": 5,
|
||||
"isReady": true,
|
||||
"isOnline": true
|
||||
}
|
||||
],
|
||||
"currentTurn": 0,
|
||||
"state": 1,
|
||||
"lastPlay": {
|
||||
"playerId": "xxx",
|
||||
"cards": [...],
|
||||
"cardType": 2
|
||||
},
|
||||
"roundCount": 1,
|
||||
"maxPlayers": 4
|
||||
},
|
||||
"timestamp": 1708123456
|
||||
}
|
||||
```
|
||||
|
||||
注意: 只有当前玩家能看到自己的手牌(cards)，其他玩家只能看到牌数(cardCount)。
|
||||
|
||||
### 游戏结束 (服务器推送)
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "gameOver",
|
||||
"data": {
|
||||
"winnerId": "xxx"
|
||||
},
|
||||
"timestamp": 1708123456
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据类型
|
||||
|
||||
### Card (牌)
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| suit | int | 花色 |
|
||||
| value | int | 点数 |
|
||||
|
||||
花色值:
|
||||
- 0: 红桃 ♥
|
||||
- 1: 方块 ♦
|
||||
- 2: 梅花 ♣
|
||||
- 3: 黑桃 ♠
|
||||
- 4: 王 (Joker)
|
||||
- 5: 超人强 (Super)
|
||||
|
||||
点数值:
|
||||
- 3-10: 对应点数
|
||||
- 11: J
|
||||
- 12: Q
|
||||
- 13: K
|
||||
- 14: A
|
||||
- 15: 2
|
||||
- 16: 小王
|
||||
- 17: 大王
|
||||
- 18: 超人强
|
||||
|
||||
### CardType (牌型)
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| 0 | 无效 |
|
||||
| 1 | 单牌 |
|
||||
| 2 | 对子 |
|
||||
| 3 | 三张 (未使用) |
|
||||
| 4 | 三带一 |
|
||||
| 5 | 三带对 (未使用) |
|
||||
| 6 | 顺子 |
|
||||
| 7 | 连对 |
|
||||
| 8 | 炸弹 |
|
||||
| 9 | 火箭 |
|
||||
|
||||
### RoomState (房间状态)
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| 0 | 等待中 |
|
||||
| 1 | 游戏中 |
|
||||
| 2 | 已结束 |
|
||||
Reference in New Issue
Block a user