多人游戏与网络同步 / 系统课时
房间列表接口应该返回什么
房间列表接口应该返回什么
房间列表不是“把服务端房间对象原样传给客户端”,而是为列表页提供一份稳定、可判断、可展示的数据契约。字段设计得当后,客户端能直接决定房间是否可加入、该显示什么状态,以及何时因版本或容量不匹配禁用入口。
学习目标
- 设计房间列表最小但够用的字段集合
- 区分展示字段、加入判断字段与稳定标识
- 用真实 HTTP 响应验证客户端拿到的数据契约
先从客户端要做的判断反推字段
列表页通常要完成三件事:识别房间、展示摘要、决定能否加入。接口字段应围绕这些任务设计,而不是把房间内部状态全部暴露出去。
建议至少包含以下信息:
| 字段 | 示例 | 主要用途 |
|---|---|---|
roomId |
room_8f31 |
稳定标识,用于进入房间、列表 diff 与缓存 |
name |
周末练习房 |
列表展示 |
playerCount |
3 |
当前人数 |
capacity |
4 |
最大容量,用于判断是否已满 |
status |
waiting |
判断是否允许加入 |
mapId |
forest |
展示或筛选地图 |
gameVersion |
1.8.2 |
判断客户端版本是否兼容 |
updatedAt |
2026-10-05T05:10:00Z |
判断数据新旧与辅助排障 |
roomId 应是稳定且唯一的标识。不要用房间名充当主键,因为名称可能重复、可修改,也不适合直接作为后续加入房间接口的参数。
状态字段要表达“能不能加入”
playerCount < capacity 只能说明房间还有空位,不能完整代表可加入。房间可能正在结算、已经锁定,或处于迁移阶段,因此还需要明确的 status。
常见状态可以收敛为少量业务状态,例如 waiting、playing、closed。如果大厅只允许进入等待中的房间,客户端判断可以非常直接:状态必须为 waiting,人数必须小于容量,版本还必须兼容。
如果加入规则很复杂,还可以由服务端额外返回 joinable 与 joinDisabledReason。不过这两个字段应是服务端已经计算出的结果,而不是代替 status、容量和版本等事实字段。
用一个列表响应固定契约
下面用 curl 请求一个房间列表接口。这里假设服务端提供 GET /api/rooms,返回当前可展示的房间摘要。
curl -s http://localhost:3000/api/rooms预期输出
{
"rooms": [
{
"roomId": "room_8f31",
"name": "周末练习房",
"playerCount": 3,
"capacity": 4,
"status": "waiting",
"mapId": "forest",
"gameVersion": "1.8.2",
"updatedAt": "2026-10-05T05:10:00Z"
}
]
}实际的房间 ID、时间和值会变化,但字段名称与类型应保持稳定。客户端可以把 roomId 作为列表项 key,并根据人数、状态和版本计算按钮是否可用。
别把详情接口的字段塞进列表
列表接口通常会被频繁刷新,因此数据量要小。玩家完整资料、聊天记录、队伍槽位、语音状态、房主权限详情等信息应放到房间详情接口中,在用户进入房间后再获取。
可以把列表接口理解成“房间索引”:它只提供做第一层决策需要的信息。字段过少会迫使客户端再次请求才能判断;字段过多则会让轮询、序列化和状态更新都变重。
给字段增加明确边界
字段类型和边界要在接口契约中固定。例如 playerCount 与 capacity 应是非负整数,并满足 playerCount <= capacity;status 应只取已声明枚举;gameVersion 应采用项目约定的版本格式。
客户端收到异常数据时不要静默修正业务事实。比如服务端返回 playerCount: 5、capacity: 4,更合理的处理是记录异常并禁用加入,而不是擅自把人数截断成 4。稳定的房间列表首先来自稳定的数据契约,然后才是漂亮的 UI。