10、信令协议设计：JSON协议设计、消息类型定义、状态机管理、错误处理

信令协议，说白了就是客户端和服务器之间沟通的「暗号」。没有它，WebRTC 的媒体流根本建立不起来。我最早做多人视频会议时，觉得信令不就是传个 SDP 嘛，随便搞搞就行。结果呢？线上各种消息对不上、状态乱跳、错误满天飞。嗯，从那以后我老老实实把协议设计当成了头等大事。

今天我们就来聊聊，怎么设计一套靠谱的信令协议。我会从 JSON 格式讲起，再到消息类型、状态机，最后说说错误处理——这些都是我在实战中踩过的坑。

10.1 JSON 协议设计：轻量、可读、可扩展

为什么选 JSON？说白了，它够轻、够简单。WebRTC 的信令不需要像 HTTP/2 那样复杂的二进制帧，JSON 的文本格式足够表达所有信息。而且调试方便——你想想看，出问题时直接看日志里的 JSON 字符串，一眼就能发现问题。

我个人习惯把信令消息设计成这样的结构：

{
  "type": "join_room",
  "seq": 1001,
  "timestamp": 1700000000000,
  "payload": {
    "room_id": "room_001",
    "user_id": "user_abc",
    "display_name": "张三"
  }
}

这里有几个关键字段：

• type：消息类型，必填。服务器根据这个字段路由处理逻辑。
• seq：序列号，可选但强烈建议加。我在项目中遇到过消息重复或丢失的情况，有了 seq 就能做去重和重传。
• timestamp：时间戳，用于排查延迟问题。
• payload：业务数据，不同消息类型携带不同的 payload。

10.2 消息类型定义：不多不少，够用就好

消息类型怎么定？我的原则是：每个消息只做一件事。别搞什么「万能消息」，那会让状态机变得一团糟。

下面是我在多人视频会议中常用的消息类型：

10.3 状态机管理：别让客户端「乱跑」

信令协议最怕什么？状态混乱。客户端还没加入房间就发 offer，或者已经离开了还在发 ICE——这种问题我调试过无数次。

解决方案就是：给客户端定义一个状态机。每个状态只允许处理特定的消息。

下面是我常用的状态机设计：

状态定义：
- DISCONNECTED：未连接
- CONNECTING：正在连接信令服务器
- CONNECTED：已连接，但未加入房间
- JOINING：正在加入房间
- IN_ROOM：已在房间中
- LEAVING：正在离开房间

状态转换规则：
- DISCONNECTED → CONNECTING：发起连接
- CONNECTING → CONNECTED：连接成功
- CONNECTED → JOINING：发送 join_room
- JOINING → IN_ROOM：收到 join_room_ack
- IN_ROOM → LEAVING：发送 leave_room
- LEAVING → CONNECTED：离开完成
- 任何状态 → DISCONNECTED：连接断开

你想想看，有了这个状态机，客户端收到消息时先检查当前状态是否合法。比如在 CONNECTED 状态下收到 offer，直接丢弃并报错——因为还没加入房间，不可能有 peer 给你发 offer。

10.4 错误处理：优雅地「说人话」

错误处理是信令协议里最容易忽视的部分。很多人的做法是：出错了就发一个 "error" 消息，里面写个数字错误码。客户端收到后一脸懵——这啥意思？

我的做法是：错误消息要「说人话」。除了错误码，还要有 readable 的错误描述，最好再带一个建议操作。

{
  "type": "error",
  "seq": 1005,
  "payload": {
    "code": 4003,
    "message": "房间已满",
    "detail": "房间 room_001 已达到最大人数限制（10人）",
    "suggestion": "请稍后再试，或联系管理员扩容"
  }
}

常见的错误码我这样定义：

10.5 核心逻辑流程图

说了这么多，不如一张图来得直观。下面是我设计的信令协议核心流程：

这张图展示了客户端和服务器之间的状态流转。注意看，每个箭头都对应一个消息类型。状态机确保客户端不会「跳步」——比如直接从 DISCONNECTED 跳到 IN_ROOM，那是不允许的。

10.6 实战中的几个要点

最后，分享几个我在项目中积累的经验：

• 消息去重：网络不稳定时，同一个消息可能收到两次。用 seq 做去重，服务器只处理第一个。
• 超时处理：发送 join_room 后，如果 5 秒内没收到 ack，客户端应该重试或报错。别让用户一直转圈。
• 心跳保活：每 30 秒发一次 ping，服务器回复 pong。连续 3 次没收到 pong，就认为连接断了。
• 日志记录：所有信令消息都打日志，包括发送和接收。出问题时，日志就是你的救命稻草。

好了，信令协议设计就聊到这里。记住一句话：协议设计得越清晰，后面调试越省心。别嫌麻烦，把消息类型、状态机、错误处理都定义好，后面你会感谢自己的。