11# RyanJson
2- ### * 欢迎试用并反馈问题与建议*
2+ > 面向资源受限设备的嵌入式通用 JSON 库
3+ >
4+ > 🎯 内存占用降低 ** 50%** | 🛡️ ** 100%** 模糊测试覆盖 | 🚀 ** 零递归** 栈依赖
35
4- 📢 ** 使用中遇到问题,欢迎提交 Issue 或在 [ RT-Thread 社区] ( https://club.rt-thread.org/index.html ) 提问。**
6+ 📢 ** 使用中遇到问题,欢迎提交 Issue 或在 [ RT-Thread 社区] ( https://club.rt-thread.org/index.html ) 提问。**
57
6- ** 一句话简介:** 面向资源受限设备的嵌入式 JSON 组件库,强调极小内存占用与高可靠性。
78** 快速入口:** ` example/ ` 、` ./run_local_base.sh ` 、` AGENTS.md `
89
910### 1、介绍
1011
11- - ** 定位:** 面向嵌入式平台深度优化的 C 语言 JSON 解析器。
12- - ** 目标:** 在保证高可靠与高可控的前提下,持续压缩内存占用。
13- - ** 动机:** 项目重构后 JSON 结构复杂度提升,cJSON 内存占用过高,难以满足嵌入式场景需求。
14-
1512#### ✅ 特性亮点
1613
17- - 💡 ** 极致内存优化:** 通过动态内存扩展与紧凑布局( 兼容未对齐访问) ,相较 cJSON 内存占用约降低 ** 50%** (详见 [ 内存占用对比报告] ( memoryUsageCompareQemu.md ) )。
14+ - 💡 ** 极致内存优化:** 通过动态内存扩展 + 紧凑布局, 兼容未对齐访问,相较 cJSON 内存占用约降低 ** 50%** (详见 [ 内存占用对比报告] ( memoryUsageCompareQemu.md ) )。
1815- 💡 ** 适配 malloc 头部与对齐策略:** 通过配置匹配不同平台的分配器特性,平衡内联阈值与内存占用。
19- - 💡 ** 零递归栈依赖:** 关键路径采用线索化链表 + 迭代 DFS,避免递归栈依赖,深层嵌套时栈占用可控 。
20- - 🔍 ** 模糊测试护城河:** 基于 [ LLVM LibFuzzer] ( https://llvm.org/docs/LibFuzzer.html ) 进行高强度随机用例生成与回归,覆盖率以在线报告为准(见下文链接)。
16+ - 🧱 ** 零递归栈依赖:** 采用线索化链表 + 迭代 DFS,避免递归栈依赖,深层嵌套栈占用可控 。
17+ - 🔍 ** 模糊测试护城河:** 基于 [ LLVM LibFuzzer] ( https://llvm.org/docs/LibFuzzer.html ) 进行上亿纪随机用例生成与回归,分支覆盖率100%。 ** [ 点击在线查看覆盖率信息 ] ( https://ryan-cw-code.github.io/RyanJson/ ) **
2118- 🧪 ** 单元测试矩阵与 QEMU 语义验证一体化:** 覆盖 double、重复 key、深层嵌套、链表稳定性等路径,并在 Cortex-M 语义下校验未对齐访问与 HardFault,核心语义宏组合覆盖。
2219- 🛡️ ** 运行时安全分析验证:** 使用 ** [ Sanitizer] ( https://clang.llvm.org/docs/index.html#sanitizers ) ** 系列工具,捕获内存越界、Use-after-free、数据竞争、未定义行为、内存泄漏等问题,提升代码健壮性与安全性。
2320- 📐 ** 高质量代码保障:** 引入 ** [ clang-tidy] ( https://clang.llvm.org/extra/clang-tidy/#clang-tidy ) ** 与 ** [ Cppcheck] ( https://cppcheck.sourceforge.io/ ) ** 进行静态分析,目标是接近语法级“零缺陷”。
@@ -175,24 +172,17 @@ typedef struct RyanJsonNode *RyanJson_t;
175172- ** 组成:** 单元测试矩阵 + 模糊测试 + QEMU 语义验证
176173- ** 目标:** 将稳定性验证前置到研发阶段
177174
178- #### ✅ 本地测试入口(脚本)
179- | 脚本 | 说明 |
180- | --- | --- |
181- | ` ./run_local_base.sh ` | 单元测试矩阵(Unity) |
182- | ` ./run_local_fuzz.sh ` | LibFuzzer 模糊测试 |
183- | ` ./run_local_ci.sh ` | 本地 CI(单元 + quick fuzz) |
184- | ` ./run_local_qemu.sh ` | QEMU 语义验证(嵌入式路径) |
185- | ` ./run_local_format.sh --check ` | 格式检查 |
186- | ` ./run_local_skills.sh ` | skills 同步与校验 |
187-
188- #### ✅ 覆盖率与日志说明
189- - unit 覆盖率目录:` localLogs/unitMatrix `
190- - fuzz 覆盖率目录:` test/fuzzer/coverage `
191- - fuzz 运行日志:默认覆盖写入 ` ./fuzz.log `
175+ #### ✅ 本地测试脚本
176+ | 脚本 | 用途 | 推荐场景 |
177+ | --- | --- | --- |
178+ | ` ./run_local_base.sh ` | 单元测试矩阵 | 修改测试用例后 |
179+ | ` ./run_local_fuzz.sh ` | LibFuzzer 模糊测试 | 解析/打印/内存路径改动 |
180+ | ` ./run_local_qemu.sh ` | QEMU 语义验证 | 嵌入式语义/对齐相关改动 |
181+ | ` ./run_local_ci.sh ` | 完整 CI 验证 | 提交前对齐 |
182+ | ` ./run_local_format.sh --check ` | 格式检查 | 代码风格调整 |
183+ | ` ./run_local_skills.sh ` | skills 同步与校验 | 更新文档后 |
192184
193- #### 🧪 专项基础功能测试(单元测试分层与覆盖域)
194-
195- 单元测试以“语义正确 + 资源安全 + 场景一致性”为主线,按目录分层组织覆盖范围与职责(见 ` test/unityTest/cases ` )。
185+ #### 🧪 专项功能单元测试覆盖域
196186
197187| 分组目录 | 说明 |
198188| --- | --- |
@@ -206,8 +196,6 @@ typedef struct RyanJsonNode *RyanJson_t;
206196| ` utils ` | 工具函数与辅助路径的正确性验证 |
207197| ` RFC8259 ` | RFC8259 标准样例与一致性检验 |
208198
209- fuzz 目标覆盖 ` parse/create/modify/replace/detach/delete/duplicate/minify ` 等路径(见 ` test/fuzzer/cases ` ),用于补充随机与异常输入下的鲁棒性与崩溃防御验证。
210-
211199#### 🛰️ QEMU 语义验证(嵌入式硬件语义)
212200- 通过 QEMU 模拟 Cortex-M 语义路径,覆盖未对齐访问与 HardFault 处理等硬件级关键行为(` UNALIGN_TRP=1 ` 强制触发未对齐异常)。
213201- 面向嵌入式场景的“语义级一致性”保障,不仅是“能跑通”,更是“语义正确”。
@@ -236,7 +224,7 @@ LLVM LibFuzzer 模糊测试是 RyanJson 的 **稳定性护城河**,用于持
236224| ** 随机压力复制安全测试** | 覆盖大规模深拷贝的内存池利用效率与拓扑安全 |
237225| ** 动态类型切换压力测试** | 覆盖运行期类型切换与动态扩展的内存安全 |
238226
239- #### 🛡️ 工具链全面集成
227+ #### 🛡️ 工具链集成
240228
241229运行时、静态分析与格式化三位一体,形成持续质量防线。
242230
@@ -263,60 +251,38 @@ LLVM LibFuzzer 模糊测试是 RyanJson 的 **稳定性护城河**,用于持
263251
264252
265253#### 内存占用测试
266- RyanJson 支持按平台配置 ` malloc ` 头部空间与对齐粒度(见 ` RyanJson/RyanJsonConfig.h ` ),内存对比结果已独立输出为 Markdown 文档,避免 README 过长。
254+ RyanJson 支持按平台配置 ` malloc ` 头部空间与对齐粒度(见 ` RyanJson/RyanJsonConfig.h ` )
267255
268256- Host 报告:[ memoryUsageCompareHost.md] ( memoryUsageCompareHost.md )
269257- QEMU 报告:[ memoryUsageCompareQemu.md] ( memoryUsageCompareQemu.md )
270258
271- 生成方式(默认同时生成 host + qemu) :
259+ 生成方式:
272260
273- ``` bash
274- bash run_local_memory.sh
275261```
262+ 测试用例代码:`test/unityTest/cases/performance/testMemory.c`
276263
277- 如需仅主机侧结果:
278-
279- ``` bash
280- MEM_PLATFORM=host bash run_local_memory.sh
264+ bash run_local_memory.sh # 同时生成 host + qemu
265+ MEM_PLATFORM=host bash run_local_memory.sh # 仅主机侧
266+ MEM_PLATFORM=qemu bash run_local_memory.sh # 仅 QEMU
281267```
282268
283- 如需仅 QEMU 结果:
284-
285- ``` bash
286- MEM_PLATFORM=qemu bash run_local_memory.sh
287- ```
288-
289- 测试用例代码:` test/unityTest/cases/performance/testMemory.c ` 。示例数据参考 ` example/ ` 。
290-
291-
292-
293269#### [ RFC 8259] ( https://github.com/nst/JSONTestSuite ) 标准符合性测试
294270RFC8259 测试结果已独立输出为 Markdown 文档,避免 README 过长。
295271
296272- Host 报告:[ rfc8259ReportHost.md] ( rfc8259ReportHost.md )
297273- QEMU 报告:[ rfc8259ReportQemu.md] ( rfc8259ReportQemu.md )
298274
299- 生成方式(默认同时生成 host + qemu):
300-
301- ``` bash
302- bash run_local_rfc8259.sh
303- ```
304-
305- 如需仅主机侧结果:
275+ 生成方式:
306276
307- ``` bash
308- RFC_PLATFORM=host bash run_local_rfc8259.sh
309277```
278+ 测试代码入口:`test/unityTest/cases/RFC8259/testRfc8259.c`。
310279
311- 如需仅 QEMU 结果:
312-
313- ``` bash
314- RFC_PLATFORM=qemu bash run_local_rfc8259.sh
280+ bash run_local_rfc8259.sh # 同时生成 host + qemu
281+ RFC_PLATFORM=host bash run_local_rfc8259.sh # 仅主机侧
282+ RFC_PLATFORM=qemu bash run_local_rfc8259.sh # 仅 QEMU
315283```
316284
317- 测试代码入口:` test/unityTest/cases/RFC8259/testRfc8259.c ` 。
318-
319- ### 5、局限性与注意事项
285+ ### 5、使用限制与注意事项
320286
321287- ** 数值精度** :内部使用 ` int ` / ` double ` 存储 Number。对于超过 double 精度的 64 位整数或高精度浮点数,内部使用 snprintf 打印;如果平台不支持科学计数法,建议使用 String 类型存储以避免精度丢失。
322288- ** 重复 Key** :严格模式下解析阶段拒绝重复 key;非严格模式允许重复 key,` GetObjectByKey ` /` DetachByKey ` 命中首个重复项,` DeleteByKey ` 每次删除一个,` Compare ` 在非严格模式按同 key 的出现序号对齐比较。
@@ -326,7 +292,7 @@ RFC_PLATFORM=qemu bash run_local_rfc8259.sh
326292- 📖 文档中心:RyanDocs
327293- 📧 联系与支持:如有任何疑问或商业合作需求,请联系:` 1831931681@qq.com `
328294
329- ### 7、快速开始(集成视角)
295+ ### 7、快速开始
330296
331297#### ✅ 编译工具链需要加入的文件
332298- ` RyanJson/*.c ` (核心源码)
0 commit comments