剖析 sj.h：C99 状态机驱动的极简 JSON 解析器实现原理

在资源受限的嵌入式系统或追求极致性能的场景中，一个轻量、高效且可靠的 JSON 解析器是开发者梦寐以求的工具。sj.h 正是为此而生——一个仅约 150 行 C99 代码的单头文件库。它摒弃了复杂的内存管理，采用状态机驱动的核心架构，实现了“零分配”解析，并能精准报告错误位置。本文将深入其内部，剖析其状态机是如何工作的，揭示其简洁外表下的精妙设计。

sj.h 的设计哲学是“够用就好”。它不负责将字符串转换为整数或浮点数，也不处理 Unicode 转义，这些任务被有意留给用户。这种“甩手掌柜”式的设计并非偷懒，而是为了将核心聚焦于最本质的任务：结构解析与词法定界。它将 JSON 文本视为一个字符流，通过一个精巧的状态机，逐字符扫描，识别出对象、数组、键、值等结构的边界，并将这些边界信息（起始和结束指针）打包成 sj_Value 结构体返回给用户。用户拿到这些“坐标”后，可以自行决定如何处理其中的内容，无论是用 atoi、strtod，还是自定义的 Unicode 解码器，都游刃有余。这种设计赋予了 sj.h 无与伦比的灵活性和极低的侵入性。

状态机的核心在于 sj_Reader 结构体和与之相伴的解析函数。sj_Reader 内部维护着当前的解析状态、输入缓冲区的指针、行号和列号计数器，以及一个用于处理嵌套结构的栈。这个栈是状态机的灵魂。当解析器遇到一个 {（对象开始）或 [（数组开始）时，它会将当前的“上下文”压入栈中，并切换到相应的子状态（如 STATE_OBJECT 或 STATE_ARRAY）。在对象状态下，它会交替期待键（一个字符串）和值；在数组状态下，它会连续期待值。每当一个完整的键值对或数组元素被解析完毕，状态机就准备接收下一个分隔符（,）或结束符（} 或 ]）。遇到结束符时，状态机从栈中弹出上一个上下文，恢复到之前的解析状态，从而实现了对任意深度嵌套结构的优雅处理。整个过程是单次遍历、增量式的，无需回溯，效率极高。

状态机的流转逻辑是其高效的关键。它在一个主循环中运行，根据当前状态和读取到的下一个字符，通过一系列 if-else 或 switch 语句（在 sj.h 的实现中主要是前者）决定下一步动作。例如，在 STATE_VALUE 状态下，如果读到 "，则进入 STATE_STRING 状态开始解析字符串；如果读到 {，则压栈并进入 STATE_OBJECT；如果读到数字或 -，则进入 STATE_NUMBER。在 STATE_STRING 状态下，它会一直读取字符，直到遇到未转义的 "，期间会正确处理 \ 转义字符。这种基于字符和当前状态的精确分发，确保了状态机能够稳健地处理各种符合或不符合规范的输入。

另一个令人称道的特性是其错误定位能力。sj.h 在 sj_Reader 中持续追踪行号和列号。当解析过程中遇到非法字符或结构错误（如预期是 : 却遇到了 }）时，它可以立即停止并返回一个包含 line 和 column 信息的错误码。这对于调试复杂的 JSON 配置文件至关重要，开发者无需再逐行排查，可以直接定位到出错的精确位置。这种能力的实现，本质上是在状态机的每一次字符消费和状态转换时，同步更新行列计数器，将调试信息的收集无缝融入了解析的主流程中，几乎没有额外开销。

总而言之，sj.h 是一个教科书级别的极简主义工程范例。它通过状态机模型，将复杂的 JSON 语法解析问题分解为一系列简单的状态转换和字符匹配操作。其“零分配”的设计消除了动态内存管理的开销和不确定性，使其在嵌入式环境中表现卓越。虽然它将数值和字符串内容的最终处理交给了用户，但这恰恰是其力量所在——它提供了一个强大而灵活的骨架，开发者可以根据具体需求为其填充血肉。对于任何希望理解状态机在实际解析器中应用，或需要在 C 项目中集成一个轻量级 JSON 解析方案的开发者来说，sj.h 的源码都值得一读再读。