lua-yar 综合评估报告¶
评估时间：2026-07-19 评估范围：
src/yar/22 个 .lua 文件 +spec/15 个测试文件 +test/13 个文件 +.github/workflows/test.yml+docs/7 个文档 压测环境：MacBook Air 2025 32G Apple M4（10 核 arm64, macOS 26.5.1） 评估方法：四维评估（代码审查 / 性能 / Lua 风格 / 工程化），复用docs/reports/performance-benchmark.md与docs/reports/architecture-review.md基线数据，重新核对当前源码 详细子报告：见文末附录索引
一、四维评估总览¶
| 维度 | 评分 | 基线对比 | 核心结论 |
|---|---|---|---|
| 1. 代码审查（@rules:review 10 项） | 8.8 / 10 | 基线 8.5 → 上调 0.3 | 10 项全通过，0 严重问题，3 中等 / 6 轻微 |
| 2. 性能评估 | 8.5 / 10 | 基线 8.5 → 持平 | 协议库达纯 Lua 理论上限，生产瓶颈在 I/O |
| 3. Lua 代码风格 | 8.0 / 10 | 基线未单列 | local 化是唯一严重短板（22 文件仅 3 个局部化） |
| 4. 工程化/网络库 | 9.0 / 10 | 基线 8.5 → 上调 0.5 | 分层/CI/依赖管理超越标杆，文档 9 处偏差 |
| 综合 | 8.6 / 10 | 基线 8.5 → 上调 0.1 | 纯协议库标杆，local 化 + 文档同步是主要改进点 |
评分调整说明¶
- 代码审查上调 0.3：基线文档（architecture-review.md）写于代码早期，hooks/keepalive/ssl_verify/check_body_len/C 扩展注入/三版本矩阵等新功能未覆盖，实际代码质量高于文档评价。
- 性能持平：压测数据与源码完全一致（9 条热路径逐一核对），无偏差。
- Lua 风格 8.0：基线未单列此项，local 化是唯一严重偏离 lua-resty-http/dkjson 标杆的维度。
- 工程化上调 0.5：CI 从"1 流程"实际增强为"3 job + 三版本矩阵 + OpenResty E2E + 软依赖"，远超基线描述。
二、各维度详细摘要¶
2.1 代码审查（8.8/10）¶
10 项检查清单全通过：
| # | 检查项 | 结论 | 要点 |
|---|---|---|---|
| 1 | 编译 | ✅ | luacheck 0 warning / 0 error，LuaLS 注解全覆盖 |
| 2 | 命名 | ✅ | snake_case 函数 + UPPER_CASE 常量 + PascalCase 模块表 |
| 3 | 魔数 | ✅ | 协议常量集中 header.lua/framing.lua，传输常量在 constants.lua 叶子模块 |
| 4 | 设计 | ✅ 优秀 | 三层分离 + provider 抽象 + 依赖方向清晰 |
| 5 | 功能 | ✅ | 17 项功能全覆盖（协议/打包/传输/hooks/安全/ID 生成） |
| 6 | 逻辑闭环 | ✅ | 错误路径完整 + 资源释放正确 |
| 7 | 边界 | ✅ | 10 类边界场景全覆盖（空输入/partial send/注入/深度限制） |
| 8 | 简洁高效 | ✅ | 方法表 memoize + table.concat + 轻微冗余可接受 |
| 9 | 质量 | ✅ 优秀 | 模块头注释 + 60 行设计决策注释 + LuaLS 150+ 注解 |
| 10 | 鲁棒性 | ✅ | pcall 四层保护 + 软依赖降级 + 闭包可重入 |
问题清单：0 严重 / 3 中等（hooks 未纳入 DEFAULT_OPTIONS、错误分类依赖字符串匹配、JSON true/false 仅检查首字节）/ 6 轻微。
文档偏差：9 处（测试 13→15、luacheck 有→0 warning、CI 1→3 job、选项 9→12+、hooks/check_body_len/max_body_len/set_id_generator/from_codec 未记录）。注：from_codec 已合并进 register（packager-register-merge 提案，2026-07-19），此偏差项已随之解决。
2.2 性能评估（8.5/10）¶
压测数据复用（与源码逐一核对，完全一致）：
| 场景 | 标准 Lua | LuaJIT/OpenResty | 评级 |
|---|---|---|---|
| 纯 Lua JSON 全链路 | 30-34K | 95-122K | B- / B+ |
| 纯 Lua Msgpack 全链路 | 36-42K | 143-148K | B / A- |
| cjson 全链路 | 30-34K | 95-121K | B- / B+ |
| cmsgpack 全链路 | 37-42K | 146K | B / B+ |
| 真实 cosocket (keepalive) | — | 87-89K | B+ |
开销分解（LuaJIT, mock cosocket）：
Protocol.parse (反序列化) ~45%
Protocol.render (序列化) ~25%
Framing.receive_message ~15%
Header unpack/pack ~10%
dispatch ~3%
send (mock) ~2%
三大瓶颈：
1. 协议解析占全链路 ~70%（纯 Lua 序列化器逐字节处理）
2. 真实 I/O 是吞吐天花板（keepalive ~89K ops/s 单连接上限）
3. Header 打包占 ~10%（.. 拼接 + 浮点除法）
核心结论：协议库已达纯 Lua 理论上限，LuaJIT 下纯 Lua Msgpack（148K）≈ cmsgpack（146K），JIT 已完全消除 C 扩展在全链路中的优势。C 扩展仅在裸编解码层有 6-10x 加速，但协议开销（header/framing/dispatch）主导全链路。生产瓶颈在 I/O 而非协议。
2.3 Lua 代码风格（8.0/10）¶
10 项惯例评估：
| 惯例 | 评分 | 对比标杆 |
|---|---|---|
| 模块组织 | 9.5 | 对齐 lua-resty-http |
| local 化 | 4.0 | 严重落后（22 文件仅 3 个局部化） |
| 闭包使用 | 9.5 | 与 dkjson 高度一致 |
| 元表模式 | 7.0 | 不统一（7 内联 vs 3 共享） |
| require 风格 | 9.5 | + 叶子模块 |
| 命名惯例 | 9.5 | 完全对齐 |
| 错误处理 | 9.0 | 结构化 Error 超越标杆 |
| 注释风格 | 9.5 | LuaLS 150+ 业界最前沿 |
| 字符串处理 | 9.0 | byte + table.concat |
| 跨版本兼容 | 9.5 | 覆盖 5.1/JIT/5.3 最广 |
最大短板：local 化。json.lua 21 次 string.、msgpack.lua 36 次 string. + 16 次 math.、util.lua 完全未做——10 个热路径文件全未局部化。architecture-review.md §4.1 称"影响极小"在非 LuaJIT 环境下偏乐观。
2.4 工程化/网络库（9.0/10）¶
10 维度评估：
| 维度 | 评分 | 亮点 |
|---|---|---|
| A. 分层架构 | 9.5 | handle_message/handle_connection/run 三层分离教科书级 |
| B. 接口设计 | 9.0 | 五注入点 + 鸭子类型 provider |
| C. 连接管理 | 9.0 | 持久+池+部分发送检测（业界少见精细处理） |
| D. 超时控制 | 8.5 | 三段+毫秒统一，无总超时预算 |
| E. 安全性 | 9.0 | ssl_verify=true+三层校验+库不播种 |
| F. 可测试性 | 9.0 | 15 spec+E2E+PHP 互操作 |
| G. CI/CD | 9.5 | 3 job+三版本矩阵+OpenResty E2E+软依赖 |
| H. 依赖管理 | 9.5 | 零 C+软依赖+双 rockspec |
| I. 文档 | 8.5 | ADR 32 决策+LuaLS，但 9 处偏差 |
| J. 错误处理 | 9.5 | 结构化 Error+四层 pcall+hooks 降级 |
超越标杆：分层架构、连接管理（部分发送检测）、CI/CD（3 job+三版本）、依赖管理（零 C+软依赖）、文档（ADR+LuaLS）、错误处理（结构化 Error）。
需改进：文档 9 处偏差、连接健康检查、超时预算、proxy 认证、release CI。
三、交叉发现（跨维度问题关联）¶
| 问题 | 涉及维度 | 关联说明 |
|---|---|---|
| local 化不足 | 性能 + Lua 风格 | 热路径未局部化既偏离 Lua 惯例，又在标准 Lua 下有实际性能影响（architecture-review.md §4.1"影响极小"判断偏乐观） |
| 文档 9 处偏差 | 代码审查 + 工程化 | hooks/keepalive/check_body_len 等功能已实现但未文档化，代码审查与工程化均发现 |
.. 拼接 |
性能 + Lua 风格 | header.lua/protocol.lua 用 .. 拼接，性能有优化空间（O3/O4），Lua 风格上 table.concat 更地道 |
| error() level | Lua 风格 + 工程化 | request.lua level 2 正确，server 端未统一，既是风格问题也是工程化一致性问题 |
| 元表不统一 | Lua 风格 + 性能 | 7 文件内联 setmetatable({},{__index=Class}) 每次创建新元表，风格不统一且有微小性能开销 |
四、与基线文档的偏差汇总¶
docs/reports/architecture-review.md（465 行，评分 8.5/10）写于代码早期，后续迭代未同步。以下 9 处偏差在代码审查与工程化评估中均确认：
| # | 基线描述 | 实际现状 | 偏差类型 | 影响 |
|---|---|---|---|---|
| 1 | 测试 13 个 | 15 个 spec 文件 | 文档落后 | 中 |
| 2 | luacheck 有 1 个 W631 warning | 0 warnings / 0 errors | 正向偏差 | 正 |
| 3 | 错误分类用"字符串前缀" | 结构化 Error 对象（5 类 code） | 内部矛盾 | 中 |
| 4 | CI 仅"luacheck → lua test" | 3 job（test/no-luasocket/openresty）+ coverage + benchmark | 严重过时 | 高 |
| 5 | 客户端选项 9 项 | 12+ 项（keepalive/ssl_verify/http_provider/max_body_len/hooks） | 文档落后 | 中 |
| 6 | 无 hooks 机制记载 | client+server 均已实现 on_request/on_response + pcall 保护 | 文档遗漏 | 中 |
| 7 | 无 framing check_body_len 记载 | framing.lua:77-88 已实现三层校验 | 文档遗漏 | 中 |
| 8 | 无 DEFAULT_MAX_BODY_LEN 记载 | framing.lua:15 定义 10MB 上限 | 文档遗漏 | 中 |
| 9 | 无 set_id_generator/Packager.from_codec 记载 | 已实现注入式 ID 生成 + C 扩展注入（from_codec 已合并进 register，见 packager-register-merge 提案） |
文档遗漏 | 中 |
建议：在更新 architecture-review.md 时统一修正以上 9 处，或在本报告作为权威参考后标注 architecture-review.md 已过时。
五、优化方向与具体建议¶
按 P0（立即）/ P1（短期）/ P2（中期）/ P3（长期）分级，含可执行措施、预期收益、实施难度。
P0 — 立即实施（高 ROI / 基础性）¶
| # | 优化项 | 涉及维度 | 具体措施 | 预期收益 | 难度 |
|---|---|---|---|---|---|
| P0-1 | local 化热路径文件 | 性能+Lua 风格 | json.lua/msgpack.lua/util.lua 顶部添加 local string/math/table/pairs/tostring = ...；header.lua/framing.lua/protocol.lua/transport/http.lua 添加 local string/table = ... |
标准 Lua 下热路径 10-20% 提升；Lua 风格评分 4.0→8.0；对齐 lua-resty-http/dkjson 标杆 | 低 |
| P0-2 | 同步 architecture-review.md 9 处偏差 | 代码审查+工程化 | 更新测试数(15)、CI(3 job)、选项(12+)、hooks、check_body_len、max_body_len、set_id_generator、Yar.register_packager（原 from_codec 已合并）、Error 结构化 | 文档准确性；工程化评分 I 8.5→9.0 | 低 |
| P0-3 | 生产部署性能指南 | 性能 | README + docs/api.md 增加"生产部署"章节：推荐 persistent=true + 合理 pool_size；C 扩展注入示例 |
用户吞吐 30K→89K ops/s（3.0x）；标准 Lua 裸编解码 6-10x，全链路 ~1.0x | 低 |
P1 — 短期实施（中 ROI / 代码优化）¶
| # | 优化项 | 涉及维度 | 具体措施 | 预期收益 | 难度 |
|---|---|---|---|---|---|
| P1-1 | Header.pack 用 table.concat | 性能 | header.lua:43-49 将 7 段 .. 拼接改为 table.concat({...}) |
标准 Lua header 打包 ~30% 提升，全链路 ~3% | 低 |
| P1-2 | Protocol.render 用 table.concat | 性能+Lua 风格 | protocol.lua:28 将 3 段 .. 改为 table.concat({packager_name, header:pack(), payload}) |
微弱(<2%)，但代码一致性更好 | 低 |
| P1-3 | JSON encode_string 快速路径 | 性能 | json.lua:27-44 对纯 ASCII 字符串（无转义字符）走快速路径 '"' .. s .. '"'，慢速路径保留逐字节转义 |
标准 Lua JSON encode ~40-60% 提升，全链路 ~10-15% | 中 |
| P1-4 | Tcp:open 返回 ok, err | 工程化 | tcp.lua:28-40 解析失败时返回错误，而非静默 |
接口契约完整性 | 低 |
| P1-5 | 连接健康检查 | 工程化 | 持久连接加 ping 或过期时间，避免首次 send 才发现连接已断 | 减少首次失败延迟 | 中 |
| P1-6 | release CI | 工程化 | 增加 tag 触发的 luarocks publish workflow | 发布自动化 | 低 |
| P1-7 | Request/Response/Header 共享元表 | Lua 风格 | 改为类级 Class.__index = Class，避免每次 new 创建新元表 |
风格统一 7.0→8.5；微小性能提升 | 低 |
| P1-8 | hooks 纳入 DEFAULT_OPTIONS | 代码审查 | client.lua 将 hooks 选项加入 DEFAULT_OPTIONS 默认值 |
选项完整性 | 低 |
P2 — 中期实施（低 ROI / 锦上添花）¶
| # | 优化项 | 涉及维度 | 具体措施 | 预期收益 | 难度 |
|---|---|---|---|---|---|
| P2-1 | 单次 call 总超时预算 | 工程化 | 控制 connect+send+receive 总耗时上限 | 防止超时叠加 | 中 |
| P2-2 | proxy 认证支持 | 工程化 | http.lua 增加 proxy Basic Auth |
HTTPS 代理场景完整 | 中 |
| P2-3 | 覆盖率门槛 | 工程化 | 添加 luacov.cfg 设定最低覆盖率 |
防止覆盖率回退 | 低 |
| P2-4 | 统一 error() level 为 2 | Lua 风格+工程化 | server 端 error 调用补 level 参数 | 错误定位准确 | 低 |
| P2-5 | 错误分类改用 Error.code | 代码审查 | client.lua:239 用 err.code == Error.TIMEOUT 替代 string.find(e, "timeout") |
类型安全 | 中 |
| P2-6 | JSON true/false 完整匹配 | 代码审查 | json.lua:264-266 检查完整 true/false/null 而非首字节 |
防畸形数据误解析 | 低 |
P3 — 长期实施（可选 / 探索性）¶
| # | 优化项 | 涉及维度 | 具体措施 | 预期收益 | 难度 |
|---|---|---|---|---|---|
| P3-1 | rockspec 依赖版本锁定 | 工程化 | 声明 luasocket >= 3.0 等版本范围 |
依赖可重现 | 低 |
| P3-2 | 协议解析层 fuzz 测试 | 工程化 | 对 header/framing/json/msgpack 增加 fuzz | 鲁棒性验证 | 中 |
| P3-3 | 多连接并发压测 | 性能 | 增加多 worker/多协程 cosocket 并发压测 | 突破单连接 95K 天花板 | 中 |
| P3-4 | 大 body / 长时间运行压测 | 性能 | 增加 1KB-100KB body + 1 小时稳定性压测 | 内存泄漏检测 | 中 |
| P3-5 | LuaJIT FFI bit 加速 pack_u32 | 性能 | 检测 LuaJIT 后用 bit.band/bit.rshift |
<2%（JIT 已优化），不推荐 | 中 |
优化优先级总览¶
P0（立即）：local 化 + 文档同步 + 生产指南 ← 最高 ROI，3 项全低难度
P1（短期）：table.concat + JSON 快速路径 + 接口/连接/CI/元表 ← 中 ROI
P2（中期）：超时预算 + proxy 认证 + 覆盖率门槛 + error 统一 ← 低 ROI
P3（长期）：版本锁定 + fuzz + 并发压测 ← 探索性
预期收益汇总（完成 P0+P1 后）： - 性能：标准 Lua 全链路 ~20-35% 提升（local 化 10-20% + table.concat 3% + JSON 快速路径 10-15%） - Lua 风格评分：8.0 → 9.0（local 化 4.0→8.0，元表 7.0→8.5） - 工程化评分：9.0 → 9.5（文档同步 + 接口完整 + release CI） - 综合评分：8.6 → 9.0+
六、总体结论¶
lua-yar 是什么¶
纯协议库 / SDK（运行时无关）——不是平台级绑定。三层分离（handle_message 纯协议 / handle_connection 连接级 / run accept 循环）+ provider 抽象（鸭子类型覆盖 luasocket/cosocket）+ 零 C 扩展依赖 + 五个正交注入点（socket/http_provider/id_generator/packager/log_writer）。
核心优势¶
- 分层架构教科书级——纯协议层无 I/O 依赖，100% 可测
- 运行时无关——零 C 依赖 + 软依赖降级 + 鸭子类型 provider，覆盖 5.1/JIT/5.3/OpenResty
- 安全默认——ssl_verify=true + 三层 body 校验 + 库不播种（Tieske 原则）
- 工程化超越标杆——CI 3 job + 三版本矩阵 + OpenResty E2E + ADR 32 决策 + LuaLS 150+ 注解
- 性能达纯 Lua 上限——LuaJIT 下纯 Lua Msgpack 148K ≈ cmsgpack 146K，JIT 已消除 C 扩展全链路优势
- 连接管理精细——部分发送检测（区分 cosocket/luasocket 返回值语义）业界少见
核心改进点¶
- local 化——唯一严重偏离 Lua 业界惯例的维度，10 个热路径文件全未做
- 文档同步——architecture-review.md 9 处偏差，功能迭代未同步
- 连接健康检查——持久连接无 ping/过期机制
- 超时预算——无单次 call 总超时控制
最终评价¶
8.6 / 10 — 纯协议库标杆，有明确改进空间但无严重缺陷。
在 Lua 生态中，lua-yar 在分层架构、CI/CD、依赖管理、文档（ADR+LuaLS）、错误处理（结构化 Error）五个维度超越标杆库（lua-resty-http/dkjson/Tieske）。local 化是唯一严重短板，但修复成本低（P0，纯机械添加 local 声明）。性能已达纯 Lua 理论上限，生产瓶颈在 I/O 而非协议，优化 ROI 梯度清晰。
附录：详细子报告索引¶
| 报告 | 位置 | 内容 |
|---|---|---|
| 代码审查 | brain/.../review-1-code-review.md |
@rules:review 10 项逐项 + 9 文档偏差 + 问题清单 |
| 性能评估 | brain/.../review-2-performance.md |
压测数据复用 + 9 热路径核对 + 3 瓶颈 + O1-O8 优化 |
| Lua 风格 | brain/.../review-3-lua-style.md |
10 项惯例 + local 化统计表 + 标杆对比矩阵 |
| 工程化 | brain/.../review-4-engineering.md |
10 维度 + 标杆对比 + 9 基线偏差 + 改进优先级 |
基线文档：
docs/reports/architecture-review.md（465 行，8.5/10）、docs/reports/performance-benchmark.md（303 行，8 章）