9.3 工程习惯：风格、性能与版本迁徙

9.3 工程习惯：风格、性能与版本迁徙

本节摘要：跨现场维护 Lua 的三份随行手册。风格手册：命名、local 纪律、模块军规的成文清单。性能手册：从"热点局部化"到"垃圾节制"的优先级排序——先测量再优化，优化按清单从上往下做。版本手册：5.1 到 5.4 的迁徙对照表，unpack、setfenv、整数、位运算、_ENV 这些跨现场必然遇到的差异点逐一给出演进理由与迁移写法。

三份手册的由来

Lua 代码的维护周期常常比想象的长：一段 5.1 时代的网关脚本可能同时活在三个现场（老网关跑 5.1、新集群跑 OpenResty 的 LuaJIT、工具链跑官方 5.4）。风格手册管"同事能不能读懂"，性能手册管"帧预算与延迟预算能不能守住"，版本手册管"同一段代码能不能在三个现场都正确"。三份手册都是清单式的——本文集不主张背规则，主张把清单贴在项目里，评审时逐条过。

风格手册

命名。局部变量短名（i、t、fn）、模块与公共函数中划线或驼峰选一种贯彻、布尔值用 is/has/can 前缀（isEmpty 比 empty 诚实）。Lua 社区没有官方风格章程，常见开源库大致趋同：两空格或四空格缩进、分号不用、冒号调用方法、点调用普通函数——选一套写进项目说明即可。

local 纪律（1.3 节的成文版）：

• 一切变量默认 local，需要全局暴露的只允许通过"模块返回表"这一条通道；
• 禁止裸赋值创建全局（可用严格模式在开发期抓：setmetatable(_G, { __newindex = function(_, k) error("global leak: " .. k, 2) end })，上线前摘除或降级为告警）；
• 模块顶部的 local 是"模块级常量区"，函数内的 local 是"函数级临时区"，两个区域不混用同名。

函数与模块（第 2、6 章军规回收）：递归用 local function；依赖显式 require 置顶；模块不放副作用，初始化收进显式 init 函数；公共接口一张表，私有全 local。

错误处理风格（第 6 章的落地）：抛错带层级 error(msg, 2)（写库时）；错误对象带 code 字段（要程序分支时）；宿主回调必装 pcall 壳；不要用 pcall 包住大段业务逻辑当 try-catch 用——Lua 的错误是"停止信号"不是流程控制，靠错误传递做分支的代码比返回值判断更难读。

💡 一条元规则：风格清单的价值不在"哪条更好"，而在"全项目一致"。两空格还是四空格争论十年没有赢家，混合缩进的项目三天就输。

性能手册

先立总纲：Lua 脚本很少是系统瓶颈，别为不存在的瓶颈扭曲代码。测量先行（宿主侧 profiler、debug.sethook 采样、简单计时包裹），确认热点再动手。热点确认后，按下面的优先级从上往下做——上面的动作收益大、风险小，下面的收益递减、可读性代价递增：

1. 局部化热点访问：循环体里的全局与表字段提升为 local（local sqrt = math.sqrt）——寄存器访问换哈希查找，零风险；
2. 拼接纪律：循环内字符串拼接换 table.concat（4.1 节的平方级账单）；
3. 避免每帧/每请求造垃圾：临时表能复用就复用（宿主提供的表池、或模块级缓存表加 clear 约定）；闭包不在热路径里创建（每次创建都是一次分配加捕获）；
4. 表操作换挡：大量键值插入改位置式数组、pairs 遍历改 ipairs（数组段直寻）、必要处 table.move 批量搬；
5. 字符串当键的代价意识：运行时拼接出来的键（"user:" .. id）每次都是新串新哈希——常量前缀部分能提则提；
6. 尾调用写法（2.2 节）：深递归与状态机保持 return f(...) 形态，栈深不涨；
7. 下沉 C/FFI：以上全做仍不够（真热点、每帧百万次级），按 9.2 节三判据下沉。

两条反向提醒。不要过早微优化：t[k] 换 rawget、局部缓存满天飞、单字母变量名——可读性换不来可测量的收益就是纯亏。不要与 GC 为敌：手工 collectgarbage 调参（停顿倍率、步长）是最后手段，且强依赖负载画像——5.4 的分代模式开箱即用，先试官方默认再谈调参。

版本手册：5.1 到 5.4 的迁徙

四大现场把各版本凑齐了：老网关与 OpenResty 生态在 5.1/LuaJIT，Redis 在 5.1，工具链在新版官方。同一段代码要跨版本活着，先过这张表：

逐行给两句解释性注释。unpack 是最高频的兼容点，一段兼容行解决。setfenv 到 _ENV：功能等价、写法从运行时函数变成词法可见的名字——沙箱代码全部要重写（但更简单了，1.3 节见过三行版）。整数登场是最大语义变化：老代码里 3/2 得 1（5.1 整数相除截断），5.3 起得 1.5——依赖整除行为的算术要逐处排查；位运算与大整数 ID 场景则是纯收益。每迭代新循环变量只影响"闭包捕获循环变量"的代码（2.2 节的事故现场），用定格写法一劳永逸。bit32 是 5.2 的过渡产物，新代码不要再引。

跨版本项目的组织建议：建一个 compat 模块收拢全部版本判断（unpack、位运算、continue 模拟），业务代码只 import compat 不直接碰差异点——版本知识集中一处，将来现场升级只改一个文件。

compat 模块的全貌

9.3 节开头提过的 compat 模块给出完整骨架，跨版本项目直接取用：

-- compat.lua：版本差异的集中收容所
local compat = {}

-- 解包函数：5.1 叫 unpack，5.2 起 table.unpack
compat.unpack = unpack or table.unpack

-- 带环境的加载：5.1 用 setfenv，5.2 起用 load 第四参数
if setfenv then                              -- 5.1 环境里有 setfenv
    compat.loadenv = function(code, name, env)
        local f = assert(loadstring(code, name))
        return setfenv(f, env)
    end
else
    compat.loadenv = load                    -- 5.2+：原生支持环境参数
end

-- 整除：5.3 前没有 // 运算符（多数场景 floor 够用，负数边界要精确再补）
compat.idiv = function(a, b) return math.floor(a / b) end

-- 版本探测标志：业务代码按需分支
compat.IS_51 = (setfenv ~= nil)
compat.HAS_INT = (math.type ~= nil)          -- 5.3+ 有整数子类型

return compat
​

业务代码的用法一目了然：local unpack = require("compat").unpack，之后无差别使用；6.3 节的沙箱代码在 5.1 现场就换用 compat.loadenv。compat 的每一条都该带适用边界注释（比如 idiv 的负数精度），否则它自己就成新的坑源。现场升级时（比如全量迁到 5.4），compat 逐条清空、最终整个文件删除——它的存在价值就是有朝日不再存在。

性能剖析的最小工具

"测量先行"要有工具才不落空。零依赖的采样剖析器骨架（sethook 加计数，6.2 节伏笔的兑现）：

local Sampler = {}
Sampler.__index = Sampler

function Sampler.new(interval)
    return setmetatable({ counts = {}, n = 0 }, Sampler)
end

function Sampler:start(interval)
    local self_h = self
    debug.sethook(function()
        local info = debug.getinfo(2, "S")           -- 只取来源（最便宜）
        if info and info.short_src then
            local key = info.short_src .. ":" .. (info.currentline or 0)
            self_h.counts[key] = (self_h.counts[key] or 0) + 1
            self_h.n = self_h.n + 1
        end
    end, "", interval or 1000)                        -- 每 N 条指令采样一次
end

function Sampler:stop()
    debug.sethook()
    local top = {}
    for k, c in pairs(self.counts) do top[#top + 1] = { k, c } end
    table.sort(top, function(a, b) return a[2] > b[2] end)
    for i = 1, math.min(#top, 10) do
        print(("%5.1f%%  %s"):format(top[i][2] * 100 / self.n, top[i][1]))
    end
end

-- 使用：包住被测段落
local s = Sampler.new()
s:start()
run_hot_path()
s:stop()      -- 打印最热的十行
​

统计式剖析的原理：每隔 N 条指令抓一次"现在在哪"，样本分布近似耗时分布。五十行不到的骨架没有计时精度可言，但找热点绰绰有余——热点的样本占比常是长尾的（前三行占七成样本是常态）。拿它跑一遍再决定优化哪段，比翻代码猜效率诚实得多；要更精细的火焰图再上专用工具（宿主侧 profiler、OpenResty 的 flame 工具链）。

代码评审清单

三份手册合成一页评审单，供拉取请求逐条过：

• 变量全 local、无裸全局（严格模式可抓）；模块无副作用、依赖置顶；
• 错误：写库的抛错带 2、可恢复错返回值不带异常、回调有壳；
• 性能：循环内无字符串拼接、无每帧闭包、热点字段已局部化（有采样数据支撑）；
• 版本：现场版本清单过一遍（unpack、整除、位运算走 compat）；
• 表：无洞数组、删除用 remove、稀疏换字典；
• 生命周期：表内大对象显式断引用、协程有退出路径、共享区键有 TTL。

六组各一行，评审变成查表——纪律的价值在于可执行，不可检查的规范等于没有。

三份手册的一次合用

用一个真实场景把三份手册串起来：一段 5.1 的老网关限流脚本要迁到新集群。版本手册先扫差异：脚本用了 unpack（加兼容行）、整数除法（改成 // 前先确认逻辑语义）、bit 库（换 compat 层）。风格手册再过一遍：三个裸全局收进模块表、错误消息补 error(msg, 2)。性能手册最后：新集群压测发现热点在每请求拼接限流键——前缀常量提出、拼接改 format。三步各司其职，先让它对（版本）、再让它整洁（风格）、最后让它快（性能）——顺序反了就要返工。

本节要点回顾

• 风格元规则是全项目一致：local 纪律成文、全局泄漏开发期抓、模块军规回收、pcall 不当流程控制用；
• 性能总纲是测量先行：七级优先级从局部化到下沉 C，从上往下做；与 GC 为敌是最后手段；
• 版本对照表十行：unpack、setfenv、goto、整数、位运算、整除、分代 GC、警告、循环变量、close——跨现场必踩点全覆盖；
• compat 模块集中版本判断（unpack、loadenv、idiv、探测标志），每条带适用边界，现场升级时逐条清空；
• 迁徙三部曲：先对（版本）、再整洁（风格）、后快（性能），顺序不可反；
• 性能七级顺口溜：局部化、拼接纪律、垃圾节制、表换挡、键前缀、尾调用、再下沉——前三级零风险先做完。

行李、通道、习惯都齐了。下一节，全册收官：不停机换逻辑的热更新实战。