【框架设计】聊天命令解析器：斜杠命令的路由与参数解析

实战应用：用在哪里

GM 后台、客服工具、玩家快捷指令都需要"输入一行命令、执行一个动作"的能力。命令解析器把 /加钱 玩家名 500 这类输入解析成命令名与参数表，路由到对应处理函数。一个 40 行的解析器可以承载全部命令入口，新增命令变成注册一条数据。

解析器实现

local commands = {}

local function register(name, minArgs, types, fn)
    commands[name] = { minArgs = minArgs, types = types, fn = fn }
end

local function dispatch(input)
    local parts = {}
    for word in input:gmatch("%S+") do parts[#parts + 1] = word end
    local cmd = table.remove(parts, 1)
    local def = commands[cmd]
    if not def then return false, "未知命令: " .. tostring(cmd) end
    if #parts < def.minArgs then return false, "参数不足" end
    for i, t in ipairs(def.types) do
        if t == "number" and tonumber(parts[i]) == nil then
            return false, "第" .. i .. "个参数需要数字"
        end
    end
    return def.fn(unpack(parts))
end

命令注册时声明最少参数数与参数类型，dispatch 统一做存在性、数量、类型三道校验，业务函数只收干净参数。

权限与审计的挂接点

解析器预留两个钩子：执行前的权限校验（命令表带 level 字段，与 GM 权限分级篇的权限表对接）、执行后的审计日志（谁在何时执行了什么命令、参数是什么）。这两钩让命令入口天然满足安全审计要求，新增命令不需要重复写权限与日志代码。

命令表的维护

命令定义集中在一张注册表，支持运行时注册与注销（活动临时命令）。文档从注册表自动生成（遍历 commands 输出命令名、参数、说明），命令帮助永远与实现同步——手写帮助文档的方式在命令数量超过十个后必然过时。

命令别名与帮助的自动生成：注册时支持别名表（add 与 additem 同指一个处理函数），帮助文档遍历 commands 输出命令名、参数说明与示例。参数类型扩展一个 player 类型（玩家名自动解析为 uid），业务函数拿到的直接是可用标识。这三件都做齐后，新增一个命令只需要注册一行，帮助与权限自动跟上。

命令同时支持 help 子命令，输入后遍历注册表输出全部命令的名称、参数与说明，命令的帮助信息永远与实现同步。

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