零依赖也能做工业级：MT502 工牌定位测试工具的技术栈与实践效果

这个项目要解决什么#

工厂里的定位工牌（MT502）通过 LoRa 基站把报文透传出来，但要验证「工牌到底发了什么、发的对不对」，以前要么靠抓包肉眼看十六进制，要么等厂商给工具。这个项目就是给自己造一个趁手的测试台：基站 TCP 连上来，工具负责拆包、解析、展示、下发指令，一条链路全打通。

它给自己定了三条硬约束，后面所有技术选型都由此展开：

1. 零 npm 依赖 —— 只用 Node 内置模块
2. 无外部数据库服务 —— 数据落本地文件，不装 MySQL / Redis
3. 全中文 —— 注释、控制台输出、界面、文档一律中文

技术栈#

代码规模：src/ 12 个模块约 2400 行，public/ 5 个页面约 1800 行，测试与工具合计约 3300 行。

有意思的是「零依赖」并没有牺牲多少东西：HTTP 手写路由不到 300 行，Canvas 画阶梯线不到 200 行，Excel 导出用 XML 拼字符串就够了。真正花工作量的地方在协议解析，而不是这些基础设施。

架构与数据流#

上行是「字节流 → 帧 → 内存 → 接口 → 页面」，下行是「命令 → 帧 → 广播」。两套协议在 dispatch.js 处按帧头分流，之后存储、展示、报警各自独立，互不影响。

三个真正花功夫的技术点#

1
// 起始标识是 2 字节时，只到了第一个字节必须判半包，不能当垃圾丢弃
2
if (head === MAOTE_H0) {
3
  if (pos + 1 >= buf.length) { r = null; }        // 半包等待
4
  else if (buf[pos + 1] === MAOTE_H1) { r = maote.tryFrame(buf, pos, flush); }
5
  else { r = { invalid: true }; }
6
}

项目效果#

1
parser.test.js          21 项  ✓  （手册示例 + 粘包/半包/脏数据）
2
maote_parser.test.js    16 项  ✓  （含混合流任意交错）
3
maote_store.test.js     19 项  ✓
4
maote_commands.test.js  19 项  ✓
5
ui_maote_table.test.js   8 项  ✓  （无浏览器，vm 里跑内联脚本）
6
e2e.test.js               ✓   （spawn 真实服务 + 模拟基站）

几个值得记下来的教训#

单测造的帧永远满足自己的假设。 UWB 信标解析曾经全空，根因是协议文档把卫星段写成绝对偏移，却没说清状态位为 0 时这段到底发不发——该型号固件照样发 12 字节全 0，导致数量字节被读成「搜星数 0」。12 个用例全绿也没能拦住。最后的解法是改成候选布局 + 帧总长度自校验：两个候选起点都试算，谁刚好把消息体吃完就用谁。

Number(null) === 0 是个陷阱。 报警导出页曾经永远空白，因为可选时间参数缺失时 Number(q.get('to')) 得到 0，而 Number.isFinite(0) 为真，于是把所有时间戳都当成「超出上界」过滤掉了。可选数值参数必须先判空再转数字。

「计数 + 定长数组」的边界要按整条全长判定。 曾经因为边界写成 off + 9 <= len（实际每条 10 字节），遇到「校验位正确但消息体残缺」的畸形帧会越界抛 RangeError，而异常发生在 TCP data 回调里 —— 一台异常终端就能让整个服务进程退出。

小结#

这个项目证明了一件事：工业场景的工具不一定要重。零依赖、单文件数据库、原生前端，加起来不到 8000 行代码，却把双协议解析、实时监控、报警导出、长期数据沉淀全做齐了，还能一键拷到车间电脑上跑。

真正的复杂度从来不在框架选型上，而在协议本身的坑里——那些文档没写清楚、固件行为和手册不一致、TCP 分包恰好切断双字节帧头的地方。这些只能靠压测、真机报文和长度自校验去兜底。