十年前我在一个智能硬件创业公司干活，通信产品是协议写一款带WiFi的插座。硬件工程师把板子画好了，通信我负责写固件。协议写那时候我们和手机App的通信通信协议，就是协议写我在一个txt文件里手写的，用空格分隔字段。通信后来设备量大了，协议写App团队换了人，通信新来的协议写同事看不懂那份文档，跑来问我："这个字节到底是通信高位在前还是低位在前？"我盯着他指的那行，自己也愣住了。协议写

通信协议的通信本质，就是协议写双方提前约定好的"黑话"。你发"天王盖地虎"，通信我回"宝塔镇河妖"，对上了才算自己人。写协议文档，就是在把这段黑话白纸黑字记录下来，让十年后的人也能对上暗号。

我的经验是，第一步先定传输层。TCP还是UDP？长连接还是短连接？这决定了后面所有字段的设计。比如我们那个插座，用的是TCP长连接，因为要随时接收服务器的控制指令。你要是做传感器上报，UDP就够了，丢了包重发一次也不心疼。这一步别含糊，传输层选错了，后面全是坑。

第二步是定义消息头。我见过最蠢的协议，一上来就是业务数据，结果后面想加个版本号，所有设备都得返厂升级。消息头至少要有：魔数（用来快速判断是不是有效包）、版本号、消息类型、消息长度。长度字段特别重要，TCP是流式传输，没有长度你根本不知道一条消息在哪结束。有个同事跟我说他以前的项目用"\r\n"当分隔符，结果业务数据里有个换行符，整个系统就崩了——后来他改用了TLV格式，Tag-Length-Value，每个字段自带长度，再也不怕数据里有什么妖魔鬼怪。

第三步才是业务字段。这里我强烈建议用JSON而不是自定义二进制格式。为什么？因为可读性好。你写一个二进制协议，发送方要shift左移右移拼字节，接收方要按位与按位或拆字节，debug的时候看十六进制dump看得眼睛都快瞎了。JSON虽然多占几个字节，但现在WiFi带宽没那么金贵，省下的开发时间够你多睡好几个觉了。当然，如果你做的是NB-IoT那种每KB都要计费的场景，那就老老实实写二进制，但记得把每个bit的含义画成图表。

还有一件事，文档里必须写清楚字节序。大端还是小端？这问题看起来幼稚，但我真见过两个团队因为这个联调了三天。还有字段的类型，int32还是uint16？范围是多少？默认值是什么？这些细节不写清楚，对方就只能靠猜。猜对了算运气好，猜错了就是线上事故。

最后，协议文档一定要写"变更记录"。今天加了个字段，明天改了个枚举值，你不记录，三个月后连你自己都不记得当初为什么这么设计。我见过最规范的协议文档，每一版变更都附上了修改人和日期，甚至还有一段话解释为什么改。这不仅仅是流程要求，更是对后来者的尊重。

对了，写完文档别急着发出去。找个没参与过这个项目的人，让他只看文档实现一个模拟客户端。如果他能在半小时内跑通，说明你的文档合格。如果他一头雾水来问你，那恭喜你，找到了文档里的盲区。这个过程很痛苦，但比上线后出问题强一百倍。

写协议这事，看着简单，其实考验的是换位思考的能力。你得把自己当成一个啥都不知道的陌生人，然后问自己：光看这份文档，我能写出正确的代码吗？大多数人写文档的时候，脑子里已经装满了上下文，觉得什么都是理所当然的。但通信的另一端，那个可怜的工程师，他什么都不知道。