doucan/API.md

斗地主残局版 API 文档

基础信息

• 基础URL: http://<host>/api
• 响应格式: JSON

响应格式

所有API响应遵循统一格式:

{
    "status": 200,
    "code": 0,
    "message": "success",
    "data": { ... }
}

字段	类型	说明
status	int	HTTP状态码
code	int	业务状态码 (0=成功, 1=失败)
message	string	提示信息
data	object	实际业务数据

---

HTTP API

创建房间

POST /api/rooms

请求体:

{
    "playerName": "玩家昵称",
    "maxPlayers": 4
}

参数	类型	必填	说明
playerName	string	是	玩家昵称
maxPlayers	int	否	最大玩家数，默认4，范围2-10

响应:

{
    "status": 200,
    "code": 0,
    "message": "success",
    "data": {
        "roomId": "a1b2c3d4e5f6g7h8",
        "playerId": "i9j0k1l2m3n4o5p6"
    }
}

加入房间

POST /api/rooms/{roomId}/join

请求体:

{
    "playerName": "玩家昵称"
}

响应:

{
    "status": 200,
    "code": 0,
    "message": "success",
    "data": {
        "roomId": "a1b2c3d4e5f6g7h8",
        "playerId": "q7r8s9t0u1v2w3x4"
    }
}

错误响应示例

{
    "status": 400,
    "code": 1,
    "message": "room not found",
    "data": null
}

---

WebSocket API

连接地址: ws://<host>/api/ws?roomId={roomId}&playerId={playerId}

消息格式

所有消息为JSON格式:

{
    "type": "消息类型",
    "playerId": "玩家ID",
    "roomId": "房间ID",
    "data": { ... },
    "timestamp": 1708123456
}

消息类型

类型	方向	说明
ready	客户端→服务器	准备/取消准备
play	客户端→服务器	出牌
pass	客户端→服务器	不出
chat	双向	聊天消息
state	服务器→客户端	游戏状态更新
gameOver	服务器→客户端	游戏结束
error	服务器→客户端	错误消息

准备

{
    "type": "ready",
    "playerId": "xxx",
    "roomId": "xxx",
    "data": { "ready": true }
}

当所有玩家都准备后，游戏自动开始。

出牌

{
    "type": "play",
    "playerId": "xxx",
    "roomId": "xxx",
    "data": {
        "cards": [
            { "suit": 0, "value": 14 },
            { "suit": 1, "value": 14 }
        ]
    }
}

不出

{
    "type": "pass",
    "playerId": "xxx",
    "roomId": "xxx"
}

注意: 只能在上家出牌后才能"不出"，自己最后出牌时不能"不出"。

聊天

{
    "type": "chat",
    "playerId": "xxx",
    "roomId": "xxx",
    "data": "消息内容"
}

游戏状态 (服务器推送)

{
    "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)。

游戏结束 (服务器推送)

{
    "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	已结束