cJSON 1.7.19 源码剖析：数据结构与解析实现

32 位下因为指针短，大概 40 字节左右。

类型没有用 enum，而是用位掩码定义在低 8 位：cJSON_False 是 1，True 是 2，Number 是 8，String 是 16，Array 是 32，Object 是 64，Raw 是 128。这样一来，还可以在高位上附加标记，比如 cJSON_IsReference (256) 和 cJSON_StringIsConst (512)，用来控制释放行为。要取纯类型就 type & 0xFF，判断是否引用就 type & cJSON_IsReference，很干净。

举个例子，JSON 字符串 {"name": "Alice", "age": 25, "scores": [90, 95, 88]} 解析之后的内存结构差不多是这样：

• 根节点 type 是 Object，child 指向第一个键值对 "name":"Alice"。
• 该键值对节点：string="name"，valuestring="Alice"，type 是 String。它的 next 指向下一个键值对 "age":25，再 next 指向 "scores":[90,95,88]。
• "scores" 的值是一个 Array 节点，它的 child 指向第一个数字节点 90，90 的 next 指向 95，再 next 指向 88。

数组/对象的一层就是一条双向链表（next/prev），向下走一层靠 child。另外有个小技巧：链表头的 prev 始终指向最后一个节点，这样在尾部追加节点就是 O(1)。

解析过程：从字符串到 cJSON 树

入口是 cJSON_Parse(const char *value)，它内部调用 cJSON_ParseWithOpts，再调用 cJSON_ParseWithLengthOpts，初始化一个 parse_buffer，分配根节点，跳过可能的 BOM 和空白，然后调 parse_value 开始递归解析。如果要求必须 0 结尾，最后还会检查 \0。失败会走 goto fail 释放已分配节点，并设置 global_error。

所以核心就落在 parse_value 上，它根据当前字符决定下一步：

• 见到 n 就匹配 null
• f 匹配 false
• t 匹配 true
• " 调 parse_string 解析字符串，包括 \uXXXX 转义
• - 或数字开头的调 parse_number，内部用 strtod，还做了 int 溢出饱和
• [ 调 parse_array
• { 调 parse_object
• 其他字符直接失败

parse_array 和 parse_object 都会先检查深度是否超过 CJSON_NESTING_LIMIT（默认 1000），防止恶意嵌套撑爆栈。

parse_array 省略 [ 后，如果是 ] 就生成空数组；否则进 do-while 循环：每次 new 一个节点，挂到当前链表尾，然后递归 parse_value 解析这个元素，直到遇到 ] 或 , 继续。最后把 head->prev 指向尾节点，item->child = head。

parse_object 类似，只是每个循环里先 parse_string 得到键名（先临时存在 valuestring，然后移到 string 字段），跳过 :，再 parse_value 得到值，用 next/prev 串起来。

解析失败的时候，错误位置会记在 global_error，可以拿 cJSON_GetErrorPtr() 取到——不过多线程下这个变量是全局的，得小心。

生成：从 cJSON 树到字符串

生成由 cJSON_Print（带缩进和换行）或 cJSON_PrintUnformatted（紧凑）开始。内部 print 函数先分配一个 256 字节的 printbuffer，然后调 print_value 递归输出。输出过程中用 ensure 函数动态扩容，空间不够就两倍 realloc。

print_value 同样按 type 分派：Null 输出 "null"，True/False 对应 "true"/"false"，数字调用 print_number（NaN/Inf 输出 "null"，整数用 %d，浮点数先用 15 位精度，不够再 17 位，并处理 locale 小数点），字符串调用 print_string_ptr 加引号并转义，Raw 类型直接输出 valuestring，数组和对象则分别输出 [...] 和 {...}，中间递归调用 print_value。

返回的字符串需要用 cJSON_free 释放，否则内存泄漏。

回过头看，cJSON 有几个设计点我觉得挺巧的：

• 树状链表：child 指向子节点，next/prev 串兄弟，加上 head->prev 指尾，既能表达复杂的 JSON 结构，又保证尾部插入 O(1)。
• 位掩码类型：一个 int 既表示基本类型，又能标记是否引用、键名是否常量，省字段、好扩展。
• 内存管理：解析失败统一 goto fail + cJSON_Delete，释放时对兄弟用循环、对子树用递归，并且尊重 IsReference 和 StringIsConst，避免错误释放。
• 可插拔的分配器：用 internal_hooks 封装 malloc/free/realloc，用户能自己替换；如果不用标准库，就把 realloc 置空，内部会用 malloc+memcpy+free 来模拟扩容。
• 数字处理：NaN/Inf 输出 "null"，确保不出非法 JSON；小数解析时还会将 locale 下的其他小数点字符（比如逗号）替换回 .，兼顾本地化。
• 嵌套深度限制：默认 1000 层，防止栈溢出，实际中很少有人会用到这么深的 JSON。

深度注释实践

如果像我一样要给 cJSON 加注释，可以分三层来写：

函数级：用 Doxygen 风格，说明作用、参数、返回值，尤其要写清楚谁负责释放内存、是否线程安全。

代码块注释：对一整段逻辑说明在做啥、为什么这么做、有哪些内存/错误处理的注意点。

关键行注释：对容易误解或者和安全相关的行做简短说明，比如 offset++ 跳过 [ 时注释一下，或者嵌套深度检查那里说明是为了防栈溢出。

在仓库的 docs/ 目录下，我已经放了两份带注释的副本 cJSON_annotated.c 和 cJSON_annotated.h，可以参考——注意它们不能直接替换原始文件用，只是文档。

如何运行与测试

说明：docs/cJSON_annotated.c 和 docs/cJSON_annotated.h 是带注释的文档型副本，不能直接替代工程里的 cJSON 使用；实际编译、运行、测试请用仓库根目录下的原始 cJSON.c 和 cJSON.h。

单文件 demo 编译（推荐）

在 fuzzing/docs/ 下已提供一个单文件测试程序 test_cjson_demo.c，用「原始 cJSON」编译即可：

Linux / macOS / MinGW（gcc）：

cd /path/to/cJSON-1.7.19/fuzzing/docs
gcc -o test_cjson_demo test_cjson_demo.c ../../cJSON.c -I../../ -lm
./test_cjson_demo

Windows（MSVC Developer Command Prompt）：

cd d:\path\to\cJSON-1.7.19\fuzzing\docs
cl test_cjson_demo.c ../../cJSON.c /I../../ /Fe:test_cjson_demo.exe
test_cjson_demo.exe

该 demo 覆盖：解析、打印、手动建树、类型判断、链表遍历、错误处理、Minify、Duplicate、版本信息等，可以和 cJSON_annotated.c/.h 的注释对照看。

用官方测试套件（CMake）

若要跑 cJSON 仓库自带的单元测试：

cd /path/to/cJSON-1.7.19
mkdir build && cd build
cmake ..
cmake --build .
ctest

以上大概就是 cJSON 1.7.19 的数据结构和解析/生成流程。真正用的时候，一个 demo 跑一遍，对照着看源码，很快就能上手。

参考资料

• cJSON 源码：https://github.com/DaveGamble/cJSON
• JSON 规范：https://www.json.org/