完整课程入口：996 全套课程体系 ｜ Lua 学习路径 ｜ 幂尔框架 mirs.cn
功能代码写错了热更就能修，协议一旦上线就同时活在 N 个历史版本的客户端里，改一个字段要照顾所有还在跑的包体。所以协议设计值得在动手前花足功夫。本文是一份经过实战检验的协议设计清单。
名字即文档：字段名用完整语义（remain_refresh_times 而不是 rt），协议文件是前后端共同的契约，省这几个字符毫无意义。类型显式：数值字段明确有无符号与位数，金币类字段一律 64 位——32 位上限 21 亿，开服活动翻几倍就溢出，事故级别的经典。边界收敛：字符串字段定义最大长度，数组字段定义最大条数，服务器入口统一裁剪，防止一条 10MB 的昵称打爆内存。
单职责消息好维护：LoginReq 就只登录，不要捎带拉取公告。但响应可以适度聚合——打开主界面时一次 SnapshotRes 返回十项关键数据，好过客户端连发十个请求。判断标准是"变更频率与消费场景"：一起变化、一起消费的数据放一条消息里。
每个消息必带三个基础字段：seq 序号（去重与重连补发）、result 错误码（统一错误码表，前端据此提示）、可选的提示文本。错误码提前规划区段：1xxx 通用、2xxx 背包、3xxx 任务……新功能申请新区段，避免后期码值打架。
协议演进三原则：新增字段只加在末尾，老端解析时会自动跳过未知字段；废弃字段置空保留，绝不复用编号，防止新结构被旧端误解；消息号只增不回收。配套一个版本协商字段：登录时客户端上报支持的协议版本区间，服务器按版本发对应形态的消息。灰度期新旧客户端混跑，靠这套规则保证互不踩踏。
协议文档（字段表、错误码表、时序图）进版本库与代码同走 review；写一个协议自测工具——按 .proto/定义表自动生成样例请求循环打服务器，新协议上线前跑一遍，字段类型错误当场现形。协议层的投入是典型的"前人栽树"：设计时多守的每一条纪律，都是未来三年联调与排障时少流的汗。
sendluamsg(actor, msgid, param1, param2, param3, sMsg, sendScope, targetMapId)
发送消息，协议出站统一走这一个口，方便加日志和签名
| 参数 | 类型 | 说明 |
|---|---|---|
| actor | object | 玩家对象(必填参数) |
| msgid | integer | 消息ID(必填参数) |
| param1 | integer | 参数1 |
| param2 | integer | 参数2 |
| param3 | integer | 参数3 |
| sMsg | string | 消息内容 |
sendluamsg(actor, 996, 0, 2, 3, "发送给自己的网络消息",0)
sendluamsg(actor, 996, 1, 1, 1, "发送给全服的网络消息",1)
handlerequest(actor, msgid, param1, param2, param3, sMsg)
监听消息，协议入站统一入口，按 msgid 分派到各业务处理函数
| 参数 | 类型 | 说明 |
|---|---|---|
| actor | object | 玩家对象(必填参数) |
| msgid | integer | 消息ID(必填参数) |
| param1 | integer | 参数1(必填参数) |
| param2 | integer | 参数2(必填参数) |
| param3 | integer | 参数3(必填参数) |
| sMsg | string | 消息内容(必填参数) |
tbl2jsonex(str)
表格转换成字符串，把协议字段表转成紧凑串
| 参数 | 类型 | 说明 |
|---|---|---|
| str | table | 需要转表的table |
json2tbl(str, reslut)
字符串转换成表格，收到后还原为 table，再走字段校验
| 参数 | 类型 | 说明 |
|---|---|---|
| str | string | 需要转表的json |
parsetext(text, object)
解析文本，字段定义写成文本时，用引擎的解析口读取，避免手写 split
| 参数 | 类型 | 说明 |
|---|---|---|
| text | string | 文本内容(必填参数) |
| object | object | 玩家对象(1-50)(必填参数) |
md5str(str)
MD5加密，整包摘要随协议带给服务端校验
| 参数 | 类型 | 说明 |
|---|---|---|
| str | string | “需要加密的文本 |
sendrefluamsg(actor, msgid, param1, param2, param3, sMsg)
发送视野内广播消息，视野内同步类协议，注意别在广播里塞可变长字段
| 参数 | 类型 | 说明 |
|---|---|---|
| actor | object | 玩家对象(必填参数) |
| msgid | integer | 消息ID(必填参数) |
| param1 | integer | 参数1 |
| param2 | integer | 参数2 |
| param3 | integer | 参数3 |
| sMsg | string | 消息内容 |