Skip to content

Commit 9819f03

Browse files
committed
docs: 更新readme
1 parent 5a67d66 commit 9819f03

1 file changed

Lines changed: 31 additions & 65 deletions

File tree

README.md

Lines changed: 31 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,20 @@
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) 标准符合性测试
294270
RFC8259 测试结果已独立输出为 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

Comments
 (0)