cJSON 1.7.19 源码精读：从数据结构到解析生成

类型系统用位掩码

cJSON 没有用 enum 逐一枚举类型，而是用了位掩码。低 8 位表示基本类型，额外的高位 bit 表示「是否引用」「键名是否常量」等标记：

/* 基本类型（低 8 位） */
#define cJSON_Invalid (0)
#define cJSON_False   (1<<0) /* 1 */
#define cJSON_True    (1<<1) /* 2 */
#define cJSON_NULL    (1<<2) /* 4 */
#define cJSON_Number  (1<<3) /* 8 */
#define cJSON_String  (1<<4) /* 16 */
#define cJSON_Array   (1<<5) /* 32 */
#define cJSON_Object  (1<<6) /* 64 */
#define cJSON_Raw     (1<<7) /* 128 */

/* 附加标记 */
#define cJSON_IsReference     256 /* 引用：Delete 时不释放 child/valuestring */
#define cJSON_StringIsConst   512 /* 键名为常量：Delete 时不释放 string */

使用示例：

• 取纯类型：(item->type) & 0xFF
• 是否引用：(item->type) & cJSON_IsReference
• 键名是否常量：(item->type) & cJSON_StringIsConst

位掩码省字段，想加新标记也方便。

树状链表示例

JSON {"name": "Alice", "age": 25, "scores": [90, 95, 88]} 解析后在内存里大致是这样：

• 根节点（Object），child 指向第一个键值对 "name": "Alice"。
• 该键值对：string = "name", valuestring = "Alice"，然后通过 next 指向 "age": 25，再 next 到 "scores": [90,95,88]。
• "scores" 的值是一个 Array 节点，其 child 指向第一个元素 90，再 next 到 95，再 next 到 88。

对象/数组的一层就是一条双向链表（兄弟关系），下一层从 child 开始。还有一个实现上的巧思：链表头节点的 prev 会指向尾节点，这样尾部追加就是 O(1)。

JSON 解析：字符串 → cJSON 树

入口 cJSON_Parse 内部调用 cJSON_ParseWithOpts，最终走到 parse_value 进行递归解析。基本流程：

1. 初始化 parse_buffer（content, length, offset, depth, hooks）。
2. 分配根节点。
3. 跳过可能的 UTF-8 BOM。
4. 跳过空白。
5. 调用 parse_value(item, buffer) 开始递归。
6. 如果需要，检查末尾的 \0。
7. 成功返回根节点；失败则 goto fail，释放已分配节点，设置全局错误。

parse_value 根据当前字符决定怎么解析：

• 'n' → 尝试匹配 "null"，offset +4。
• 'f' → 尝试匹配 "false"，offset +5。
• 't' → 尝试匹配 "true"，offset +4。
• '"' → 调用 parse_string()，处理转义和 \uXXXX。
• '-' 或数字开头 → 调用 parse_number()，内部用 strtod，对整数做溢出饱和处理。
• '[' → 调用 parse_array()，内部对每个元素递归 parse_value。
• '{' → 调用 parse_object()，先 parse_string 取键名，跳过 :，再 parse_value 取值。
• 其他字符 → 失败。

数组和对象在进入前会检查 depth >= CJSON_NESTING_LIMIT（默认 1000），超过就返回 false，防止栈溢出。

parse_array 的核心：空数组直接结束；非空就用 do-while 循环，每次 cJSON_New_Item 创建新节点，用 next/prev 接到链表尾部，然后递归解析元素。循环以是否遇到 , 决定继续。最后把链表头节点的 prev 指向尾节点，设置根节点的 child 和 type。

parse_object 类似，区别是每个元素要先解析键名（存到 valuestring 然后移到 string），再解析值。同样拼成双向链表。

解析失败时可通过 cJSON_GetErrorPtr() 获取大致错误位置，虽然多线程下不保证完全可靠。

JSON 生成：cJSON 树 → 字符串

cJSON_Print 生成格式化输出（带缩进、换行），cJSON_PrintUnformatted 生成紧凑单行。它们都调用内部函数 print：

1. 分配一块初始 256 字节的 printbuffer。
2. 调用 print_value(item, buffer) 递归填充。
3. 根据实际长度 realloc 或重新 malloc 拷贝，返回字符串。调用方需用 cJSON_free 释放。

print_value 通过 (item->type) & 0xFF 拿到基本类型，再分派：

• cJSON_NULL → 写入 "null"。
• cJSON_False → 写入 "false"。
• cJSON_True → 写入 "true"。
• cJSON_Number → print_number()。对 NaN/Inf 输出 "null"；整数用 %d，浮点先用 %1.15g，不够精确再用 %1.17g，同时统一小数点 locale。
• cJSON_String → print_string() → print_string_ptr()，加上双引号，转义特殊字符。
• cJSON_Raw → 原样 memcpy valuestring。
• cJSON_Array → 写 [，遍历子节点逐个 print_value，元素间加 ,，最后写 ]。
• cJSON_Object → 写 {，对每个子节点先输出键名（print_string_ptr），再 :，再输出值，最后 }。

缓冲区由 ensure() 管理，空间不够时按 2 倍扩容（直到 INT_MAX）。内部用 realloc 或 malloc+memcpy+free，取决于是否设置了自定义 hooks 的 realloc。

一些值得留意的设计

• 树状链表：child 负责父子，next/prev 负责兄弟，尾指针藏在 head->prev 里，尾部追加 O(1)。
• 位掩码类型：一个 int 同时管基本类型和引用/常量等标记，省字段。
• 内存安全：解析失败统一 goto fail + cJSON_Delete；cJSON_Delete 对兄弟用循环，对子树用递归，且尊重 IsReference/StringIsConst 标记。
• 可插拔分配器：internal_hooks 封装 malloc/free/realloc，用户可以替换；不用标准库的 malloc/free 时则禁用 realloc，避免跨分配器 realloc。
• 数字与 locale：NaN/Inf 输出为 "null"；浮点输出精度分 15 位和 17 位两步；解析数字时替换当期 locale 的小数点。
• 嵌套保护：CJSON_NESTING_LIMIT 默认 1000，防止恶意深层 JSON 炸栈。

注释风格建议

读 cJSON 源码或者自己写注释，可以按三个层次来，和本项目里带注释的 cJSON_annotated.c/.h 风格一致：

函数级注释（Doxygen 风格）

写明作用、参数、返回值、内存释放责任、线程安全。比如：

/**
 * @brief 解析 JSON 字符串，生成 cJSON 树
 * @param value 以 '\0' 结尾的 JSON 字符串
 * @return 成功：根节点指针；失败：NULL
 * @note 返回的节点树必须调用 cJSON_Delete() 释放
 * @note 失败时可调用 cJSON_GetErrorPtr() 获取出错位置
 */
CJSON_PUBLIC(cJSON *)cJSON_Parse(const char* value);

凡是返回新分配内存的函数，都要写清楚谁释放、用什么 API 释放。

代码块注释

对一整段逻辑用块注释概括：做什么、为什么这么写、内存/错误处理上的注意点。例如：

/* ===== 递归解析 JSON 数组 ===== *
 * 步骤：遇到 '[' 后循环解析每个元素，用 next/prev 构成链表，
 * 最后 head->prev = 尾节点。失败则 cJSON_Delete(head) 统一释放。
 * 递归深度受 CJSON_NESTING_LIMIT 限制。
 */

关键行注释

对容易误解、或与安全/规范相关的行随手加短注释：

input_buffer->offset++; /* 跳过 '['，进入数组内容 */
buffer_skip_whitespace(input_buffer); /* 跳过 \r\n\t 等空白，符合 JSON 规范 */
if(input_buffer->depth >= CJSON_NESTING_LIMIT) /* 嵌套过深，防止栈溢出 */
    return false;

三层次配合读起来会更顺。

如何编译和测试

docs/cJSON_annotated.c 和 docs/cJSON_annotated.h 是带注释的文档副本，不能替代工程文件。实际编译、运行、测试请用仓库根目录下的原始 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 源码：https://github.com/DaveGamble/cJSON
• JSON 规范：https://www.json.org/