多人游戏与网络同步 / 系统课时

房间列表接口应该返回什么

房间列表接口应该返回什么

房间列表不是“把服务端房间对象原样传给客户端”,而是为列表页提供一份稳定、可判断、可展示的数据契约。字段设计得当后,客户端能直接决定房间是否可加入、该显示什么状态,以及何时因版本或容量不匹配禁用入口。

学习目标

  • 设计房间列表最小但够用的字段集合
  • 区分展示字段、加入判断字段与稳定标识
  • 用真实 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,返回当前可展示的房间摘要。

bash
curl -s http://localhost:3000/api/rooms

预期输出

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

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

房间列表接口应该返回什么

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通