【网络通信】前后端消息协议表：msgid 分配的纪律

实战应用：用在哪里

前后端 Lua 消息通道（sendluamsg 与 RegisterLuaNetMsg）好用，但消息号一旦失控就是灾难：两个业务用同一个号互相覆盖，界面的数据串线排查一晚上。msgid 的分配纪律是这条通道能长期用的前提。

分配表机制

-- msgid 分配表（前后端共享的定义文件）
MSGID = {
    BOSS_HP       = 7001,
    GUILD_INFO    = 6602,
    ACTIVITY_SYNC = 7300,
    REWARD_PUSH   = 7301,
    TRADE_REFRESH = 7400,
}

-- 服务端使用：只能引用常量，不允许手写数字
function pushBossHp(actor, percent, name)
    sendluamsg(actor, MSGID.BOSS_HP, percent, 0, 0, name)
end

消息号集中在一个共享定义文件里，前后端引用同一份常量。分配的规则按业务段划分：7000 段给 BOSS 与战斗推送、6600 段给行会、7300 段给活动、9000 段保留给 GM 工具。段的边界写进文件注释，新增消息先申请段内的下一个空号。

注销与冲突检测

-- 前端注册时的冲突自检
local registered = {}
function safeRegisterLuaNetMsg(msgid, cb)
    if registered[msgid] then
        SL:Print("msgid 冲突：" .. msgid)
        return false
    end
    registered[msgid] = true
    SL:RegisterLuaNetMsg(msgid, cb)
    return true
end

前端的注册封装自带冲突检测：同一号注册两次直接报错拦截，冲突在开发期暴露而不是在玩家面前串线。服务端的分配表定期与前端注册表做核对，表里有而无人使用的消息号标记回收。消息号的文档语义（谁发的、发什么、给谁用）三列齐全，新同事看表就能上手。

验证与监控

消息通道的流量按 msgid 统计，孤儿消息（有推送无界面消费）与幽灵注册（有回调无推送）定期清理。

踩坑记录

分配表的更新曾经不走版本管理，前后端的表各自演变成两套，联调时对不上号，共享文件进 git 后冲突归零。消息参数的语义也进了注释：param1 是百分比还是数量，模糊一次就是一次联调成本。

上线要点

msgid 的段位分配留 20% 余量给新业务，段满前规划新段位。通道的消息一律是推送语义，界面初始数据的全量同步走独立的拉取协议，推送只管增量。前后端联调时用 SL:Print 打印消息号与参数的首包样本，协议的握手验证在开发期完成。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。