RyanJson

RyanJson

希望有兴趣的大佬多试试，找找bug、提提意见

📢 使用过程中遇到问题？欢迎提交 Issue 或在 RT-Thread 社区 提问，感谢支持！

一个针对资源受限的嵌入式设备优化的Json库，内存占用极小的通用Json库，简洁高效！

示例代码请参考RyanJsonExample文件夹！

1、介绍

RyanJson 是一个小巧的 C 语言 JSON 解析器，支持 JSON 文本解析与生成，专门针对嵌入式平台的 低内存占用 进行优化。

初衷：项目重构后 JSON 结构复杂度提升，cJSON 内存占用过高，无法满足需求。

✅ 特性亮点

• 💡 极致内存优化：在资源受限设备上实现 40-70% 内存节省（对比 cJSON），在 RT-Thread 平台 malloc 头部空间为 12 字节时节省约 40%，无 malloc 头部空间可接近 70%。同时保持工业级健壮性，运行速度与 cJSON 基本持平。
• ✅ 模糊测试：LLVM Fuzzer，千万级输入，覆盖率 99.9%，稳定性极高，确保在各种非法输入和极端场景下依旧安全。
• ✅ 运行时安全分析验证，使用 Sanitizer 系列工具，捕获内存越界、Use-after-free、数据竞争、未定义行为、内存泄漏等问题，提升代码健壮性与安全性
• ✅ 高质量代码保障 ， 引入 clang-tidy 与 Cppcheck 进行静态分析，实现接近语法级的"零缺陷"，显著提升可维护性与可读性
• ✅ AI 辅助开发与审查，结合 coderabbitai 与 Copilot ，在编码与代码审查阶段持续优化代码质量，构建多层安全防线
• ✅ 6 大类专项测试用例，覆盖广泛场景，全链路内存泄漏检测，强化稳定性与可靠性
• ✅ 低内存占用：动态扩展方案，内存空间利用率超高。
• ✅ 开发人员友好：轻松集成，类 cJSON API，迁移成本低。
• ✅ 严格但不严苛：符合 RFC 8295 绝大部分JSON标准，支持无限的Json嵌套级别（需注意堆栈空间）、灵活的配置修改项
• ✅ 可扩展性：允许注释(需调用mini函数清除注释后再解析)、尾随逗号等无效字符(parse时可配置是否允许)等

2、设计

**RyanJson设计时大量借鉴了 json 和 cJSON ! **

Json语法是JavaScript对象语法的子集，可通过下面两个连接学习json语法。

JSON规范

Parsing JSON is a Minefield 建议看看

在json语法中，数据以键值对的形式存储（数组的子项没有key）

在RyanJson解析器中，使用结构体来表示一个键值对，是存储的最小单元，结构如下：

// Json 的最基础节点，所有 Json 元素都由该节点表示。
// 结构体中仅包含固定的 next 指针，用于单向链表串联。
// 其余数据（flag、key、stringValue、numberValue、doubleValue 等）均通过动态内存分配管理。
struct RyanJsonNode
{
    struct RyanJsonNode *next; // 单链表节点指针

    /*
     * 在 next 后紧跟一个字节的 flag，用于描述节点的核心信息：
     *
     * 位分布如下：
     * bit7   bit6   bit5   bit4   bit3   bit2   bit1   bit0
     * -----------------------------------------------------
     * 保留   KeyLen KeyLen HasKey NumExt Type2 Type1 Type0
     *
     * 各位含义：
     * - bit0-2 : 节点类型
     *            000=Unknown, 001=Null, 010=Bool, 011=Number,
     *            100=String, 101=Array, 110=Object, 111=Reserved
     *
     * - bit3   : 扩展位
     *            Bool 类型：0=false, 1=true
     *            Number 类型：0=int, 1=double
     *
     * - bit4   : 是否包含 Key
     *            0=无 Key（数组元素）
     *            1=有 Key（对象成员）
     *
     * - bit5-6 : Key 长度字段字节数
     *            00=1字节 (≤255)
     *            01=2字节 (≤65535)
     *            10=3字节 (≤16M)
     *            11=4字节 (≤UINT32_MAX)
     *
     * - bit7   : 保留位（未来可用于压缩标记、特殊类型等）
     */

    /*
     * flag 后若节点包含 key / strValue，则跟随一个指针，
     * 指向存储区：[ keyLen | key | stringValue ]
     * 其中 keyLen 的大小由 flag 中的长度信息决定（最多 4 字节）。
     *
     * 在指针之后，根据节点类型存储具体数据：
     * - null / bool : 由 flag 表示
     * - string      : 由上述指针指向
     * - number      : 根据 flag 决定存储 int(4字节) 或 double(8字节)
     * - object      : 动态分配空间存储子节点，链表结构如下：
     *
     *   {
     *       "name": "RyanJson",
     *   next (
     *       "version": "xxx",
     *   next (
     *       "repository": "https://github.com/Ryan-CW-Code/RyanJson",
     *   next (
     *       "keywords": ["json", "streamlined", "parser"],
     *   next (
     *       "others": { ... }
     *   )))
     *   }
     */

    /*
     * 设计特点：
     * - 一个 Json 节点最多 malloc 两次（一次节点本身，一次可选的 key/stringValue），
     *   对嵌入式系统非常友好，减少 malloc 头部开销。
     *
     * - key 和 stringValue 必须通过指针管理：
     *   * 如果直接放在节点里，虽然只需一次 malloc，
     *     但修改场景会遇到替换/释放困难。
     *   * 用户可能传递的 Json 对象不是指针，无法直接替换节点，
     *     要求应用层传递指针会增加侵入性，不符合“应用层无需修改”的目标。
     *
     * - 因此采用指针方式，保证灵活性和低侵入性。
     */
};


typedef struct RyanJsonNode *RyanJson_t;

3、测试体系

LLVM模糊测试（核心亮点），模糊测试是 RyanJson 的 核心稳定性保障，针对嵌入式环境的复杂场景进行了深度设计与验证。

📊 特点与优势

• 千万级测试样本：LLVM Fuzzer 自动生成并执行千万级随机与非法 JSON 输入。
• 覆盖率极高：
  • 模糊测试文件行覆盖率 100%
  • 核心 JSON 代码行覆盖率 99.9%
  • 千万级输入并且警告复杂逻辑测试下无崩溃、无泄漏。
• 异常场景全覆盖：内存申请失败、扩容失败、非法转义字符、尾随逗号、嵌套过深、随机类型切换。
• 内存安全验证：结合 Sanitizer 工具链，确保无泄漏、无悬空指针、无越界。
• 鲁棒性验证：弱网、随机内存故障、长时间运行等极端条件下保持稳定。

测试类别	测试目标
内存故障测试	验证内存不足时的健壮性
解析 Json 节点测试	随机非法/合法输入解析
循环遍历删除节点测试	确保链表删除安全性
循环遍历分离节点测试	验证节点分离逻辑正确性
Json 压缩去除转义测试	检查转义字符处理健壮性
Json 打印和解析测试	序列化与反序列化一致性
循环遍历获取 Value 测试	确保随机访问稳定性
循环遍历随机复制 Json 节点测试	验证深拷贝与浅拷贝安全性
循环遍历随机修改节点类型/创建节点测试	动态扩展与类型切换能力

📊 手写的专项基础测试用例

测试类别	测试目标
文本解析 Json 测试	基础解析能力
创建 Json 节点树测试	节点生成与结构正确性
修改 Json 节点测试	删除、分离、修改
比较 Json 节点测试	节点比较与一致性
复制 Json 节点测试	深拷贝与浅拷贝验证
Json 循环测试	遍历与稳定性

4、代码质量与规范

✅ 工具链全面集成

工具	用途
Sanitizer	运行时捕获内存与线程安全问题
clang-tidy	静态分析潜在缺陷（空指针、资源泄漏等）
Cppcheck	深度扫描内存与资源问题
ClangFormat	统一代码风格
编译器警告	-Wall -Wextra（默认）、-Weffc++/-Weverything（Clang 可选，CI 强化时开启）

✅ 检查重点覆盖

• 内存安全：杜绝泄漏、越界、悬空指针
• 性能优化：减少冗余拷贝与低效算法
• 可读性：命名规范、注释完整、逻辑清晰

✅ 成果：实现接近语法级"零缺陷"，长期维护成本大幅降低

6、示例

测试代码和示例代码可在本项目根目录RyanJsonExample文件夹查看。

性能测试

请移步文末的 RyanDocs 文档中心查看，是基于 yyjson_benchmark 的测试结果

内存占用测试

*(20251222 linux平台，不考虑malloc头部空间)测试代码可在本项目根目录RyanJsonExample文件夹查看。新版本内存占用更低!*

*****************************************************************************
*************************** RyanJson / cJSON / yyjson 内存对比程序 **************************
*****************************************************************************

--------------------------- 混合类型json数据测试 --------------------------
json原始文本长度为 2265, 序列化后RyanJson内存占用: 3613, cJSON内存占用: 9160
比cJSON节省: 60.56% 内存占用

--------------------------- 对象占多json数据测试 --------------------------
json原始文本长度为 3991, 序列化后RyanJson内存占用: 5436, cJSON内存占用: 11633
比cJSON节省: 53.27% 内存占用

--------------------------- 数组占多json数据测试 --------------------------
json原始文本长度为 1205, 序列化后RyanJson内存占用: 2365, cJSON内存占用: 7340
比cJSON节省: 67.78% 内存占用

--------------------------- 小对象json 混合类型内存占用测试 --------------------------
json原始文本长度为 90, 序列化后RyanJson内存占用: 131, cJSON内存占用: 309
比cJSON节省: 57.61% 内存占用

--------------------------- 小对象json 纯字符串内存占用测试 --------------------------
json原始文本长度为 100, 序列化后RyanJson内存占用: 144, cJSON内存占用: 339
比cJSON节省: 57.52% 内存占用

RT-Thread平台考虑malloc头部空间12字节情况下

*****************************************************************************
*************************** RyanJson / cJSON / yyjson 内存对比程序 **************************
*****************************************************************************

--------------------------- 混合类型json数据测试 --------------------------
json原始文本长度为 2265, 序列化后RyanJson内存占用: 7993, cJSON内存占用: 13732
比cJSON节省: 41.79% 内存占用

--------------------------- 对象占多json数据测试 --------------------------
json原始文本长度为 3991, 序列化后RyanJson内存占用: 10668, cJSON内存占用: 19109
比cJSON节省: 44.17% 内存占用

--------------------------- 数组占多json数据测试 --------------------------
json原始文本长度为 1205, 序列化后RyanJson内存占用: 5449, cJSON内存占用: 10424
比cJSON节省: 47.73% 内存占用

--------------------------- 小对象json 混合类型内存占用测试 --------------------------
json原始文本长度为 90, 序列化后RyanJson内存占用: 287, cJSON内存占用: 477
比cJSON节省: 39.83% 内存占用

--------------------------- 小对象json 纯字符串内存占用测试 --------------------------
json原始文本长度为 100, 序列化后RyanJson内存占用: 300, cJSON内存占用: 567
比cJSON节省: 47.09% 内存占用

RFC 8295 标准测试，大部分嵌入式场景不会出现极为特殊的Unicode字符集

如果项目需要完全兼容Unicode字符集，可以考虑yyjson / json-c

*****************************************************************************
*************************** RyanJson / cJSON / yyjson RFC8259标准测试 **************************
*****************************************************************************
开始 RFC 8259 JSON 测试
--------------------------- RFC8259  RyanJson --------------------------
应该失败，但是成功: [1eE2], len: 6
应该成功，但是失败: [20e1], len: 6
应该成功，但是失败: [0e1], len: 5
RFC 8259 JSON: (319/322)

--------------------------- RFC8259  cJSON --------------------------
应该失败，但是成功: [1.], len: 4
应该失败，但是成功: [
                     ], len: 3
应该失败，但是成功: ["\uqqqq"], len: 10
应该失败，但是成功: [2.e-3], len: 7
应该失败，但是成功: [-2.], len: 5
应该失败，但是成功: [-.123], len: 7
应该失败，但是成功: 123, len: 4
应该失败，但是成功: [2.e+3], len: 7
应该失败，但是成功: [0.e1], len: 6
应该失败，但是成功: ["a, len: 7
应该失败，但是成功: [-012], len: 6
应该失败，但是成功: [, len: 3
应该失败，但是成功: [012], len: 5
应该失败，但是成功: ["new
line"], len: 12
应该失败，但是成功: ["  "], len: 5
应该失败，但是成功: [-01], len: 5
应该失败，但是成功: [2.e3], len: 6
RFC 8259 JSON: (305/322)
|||----------->>> area = 0, size = 0

4、局限性

• 使用int / double表示json中的number类型，精度有所丢失。建议64位的number类型最好用string字符串表示。
• 对象中允许有重复的key，RyanJson库采用单向链表，会访问到第一个对象。

5、文档

文档可在 Ryan文档中心获取

6、联系

Email：1831931681@qq.com