【开源自荐】LJSON：全能、高性能、真流式的 C 语言 JSON 引擎和数值引擎

[lengjingzju]

LJSON：全能、高性能、真流式的 C 语言 JSON 引擎和数值引擎

0 项目地址

LJSON 支持 Windows 和 Linux ，项目地址位于：

• github: https://github.com/lengjingzju/json
• gitee: https://gitee.com/lengjingzju/json
• 设计讨论: 关于JSON解析性能 lengjingzju/json#2

1. 项目定位与设计初衷

LJSON 诞生于 2019 年 10 月，比 yyjson 早一年，初衷并非单纯追求基准测试中的极限解析速度，而是要在 性能、内存占用、可编辑性、流式能力、可维护性 之间找到最佳平衡。

它目前状态是：

• 能在多数场景下媲美甚至超越 yyjson 的性能
• 提供 yyjson 架构无法小改实现的真流式处理能力
• 保持代码可读性和可扩展性，适合长期演进

2. 核心能力

双重核心

全能 JSON 处理

• 完整支持 JSON5 规范（十六进制、注释、尾逗号、单引号等）
• DOM / SAX 双解析模式
• 真流式文件（边读边解析，边写边打印）

高性能数值转换引擎

• 独创 ldouble 算法
• 浮点 ↔ 字符串转换性能远超标准库和主流算法（sprintf、grisu2、dragonbox）
• 精度是16位，在边界处理时追求最短而不是偶数（标准是16位或17位，取决于二进制指数转换为十进制指数的乘子的分辨率）

3. 架构与模式设计

LJSON 提供 7 种解析模式 与 4 种打印模式，覆盖从内存到文件、从 DOM 到 SAX 的全场景需求：

解析模式

1. DOM 经典模式（malloc/free）
2. DOM 内存池模式
3. DOM 复用模式（可编辑，字符串原地复用）
4. DOM 文件流模式（真流式）
5. DOM 文件流内存池模式（真流式 + 内存池）
6. SAX 模式（回调处理）
7. SAX 文件流模式（真流式 + 回调）

打印模式

1. DOM → 字符串
2. DOM → 文件（真流式）
3. SAX → 字符串
4. SAX → 文件（真流式）

真流式：边读文件边解析，边打印边写文件，无需完整读入或生成中间大缓冲，内存占用可降至常数级，即使处理 1GB JSON 文件也仅需 KB 级内存。

yyjson ≈ LJSON 的 DOM 复用模式 + 激进只读优化

4. 与 yyjson 的设计差异

核心差异包括：

维度	LJSON	yyjson
模式设计	多模式（含真流式、可编辑复用）	单一复用模式（只读优化）
可编辑性	复用模式可编辑	只读与可编辑严格分离（val / mut_val）
字符串存储	标准 C 字符串（尾 1 个 \0）	非标准尾 4 个 \0（减少边界判断）
对象存储	key 与 value 一起存储	key 与 value 分开存储
内存策略	按需分配，尽量避免浪费	大块预分配，冗余度高
访问加速	json_items_t 缓存，数组 O(1)、对象 O(logN)	未知是否有缓存，可能 O(N)/O(2N)
优化手法	内联、分支预测、查表、缓存元信息；保持可读性	同类优化 + 大量宏循环展开，代码晦涩
流式处理	真流式解析/打印	不支持

5. 性能来源与权衡

优化技术对比

两者都使用：

• 内存池（块）优化
• 内联优化（inline）
• 分支预测优化（likely/unlikely）
• Cache 命中优化
• 查表优化
• 拷贝优化
• 信息记录优化（缓存字符串长度等）

差异：

• yyjson：大量宏进行循环手动展开，代码紧凑但晦涩，性能更激进；使用非标准特性（尾后 4 个 \0、非对齐访问等）。
• LJSON：追求易维护、可扩展、低占用、高性能的工程化平衡。保持可读性，宏进行手动循环展开。

性能对比

yyjson 相当于只实现了 LJSON 的DOM复用模式，并且转换可编辑模式时对象和字符串都存储在内存块里，和LJSON的内存池原理一致。

• yyjson 只读复用模式 性能略高于 LJSON，来源于：
  • 模式单一
  • 激进资源使用（预分配冗余内存）
  • 非标准特性（尾后 4 个 \0、非对齐访问）
  • 宏循环展开
• yyjson 只读模式 性能和 LJSON 很接近，两者互有胜负
• yyjson 可编辑模式 性能可能大幅落后于 LJSON（大文件解析 yyjson 比 LJSON 内存占用多约一倍，速度慢约一倍）

注：如果 LJSON 放弃流式、标准字符串、可编辑性，采用更晦涩代码，可达到 yyjson 只读复用模式 性能，但那将不再是 LJSON 的设计哲学。

6. 优化机制亮点

• 零堆分配：首次分配后循环复用，避免频繁 malloc/free。
• 原地字符串复用：直接引用输入缓冲区，减少拷贝与内存带宽消耗。
• json_items 加速器：数组 O(1) 访问，对象 O(logN) 查找。
• 真流式管线：解析与 I/O 并行，消除峰值内存与额外拷贝。
• ldouble 数值引擎：浮点转字符串性能领先 sprintf 10~70 倍。

7. 多维度对比（可编辑模式）

对比维度	LJSON	yyjson	RapidJSON	cJSON
解析性能	高（547ms，可编辑复用）	中高（1011ms，可编辑）	较高	中等
打印性能	高（真流式+ldouble）	高（全缓冲）	中等	低
内存占用	可常数级（流式）	较高	较高	较高
CPU 特性依赖	低	低	中	低
可扩展性	高	低	中	高
代码可读性	高	极低	中	高
关键机制	零堆分配、内存池复用、原地字符串、json_items、ldouble	原地复用、内存块、非标准字符串尾、循环展开	模板+分配器	malloc/free

8. 适用场景

• 大文件处理：GB 级 JSON 格式化/压缩，内存占用可常数级。
• 嵌入式系统：低内存、高性能需求。
• 高频读写：实时数据流解析与生成。
• 跨平台开发：Linux / Windows / 嵌入式 RTOS。

9. 设计哲学总结

yyjson：以极致性能为第一目标，通过激进优化手段和单一模式深耕，适合极限只读解析场景。
LJSON：追求易维护、可扩展、低占用、高性能的工程化平衡，适合通用、可编辑、流式处理、大文件低内存占用的场景。纯 C 实现，零第三方依赖，跨平台编译，接口设计参考 cJSON，逻辑清晰，编译速度快，易于二次开发。

LJSON 的价值不仅在于跑分，更在于它能在真实工程环境中，以极低的内存占用和高性能，稳定支撑多样化的 JSON 处理需求。

[lengjingzju]

yyjson ≠ 万能王者：它只是 LJSON DOM 复用模式的一个特化版本

——一场关于 JSON 引擎架构哲学的深度对话

引言：性能之外，还有架构的边界

在 C 语言 JSON 库的世界里，yyjson 凭借惊人的解析速度成为众多 benchmark 的常客。但如果你是一位系统级工程师，追求的不只是跑分，而是架构的可控性、可维护性和真实场景下的适应力，那么你会发现：

yyjson 本质上只是 LJSON 所提供的 DOM 复用模式的一个特化版本。 (首次提交时间，yyjson 为 2020.10，LJSON 为 2019.10 )

这不是贬低，而是一次架构哲学的澄清。本文将从模式设计、性能策略、内存行为、流式能力等多个维度，深入剖析 yyjson 与 LJSON 的本质差异。

一、DOM 复用模式：性能的起点，不是终点

所谓 DOM 复用模式，是指解析 JSON 时复用输入缓冲区中的字符串，避免额外拷贝与堆分配，从而提升性能、降低内存占用。

LJSON 的 DOM 复用模式具备：

• 原地字符串复用（零拷贝）
• 内存池分配结构体（避免频繁 malloc/free）
• 可编辑性（支持修改 key/value）

yyjson 的核心模式与此高度重合，但它进一步做了激进的只读优化。

二、yyjson 的极限优化：只读复用场景的王者

yyjson 在 DOM 复用基础上，采取了以下策略以追求极致性能：

• 非标准字符串尾部：使用 \0\0\0\0 替代标准 C 字符串尾部，减少边界判断。
• 宏展开循环：大量使用宏手动展开解析循环，压榨 CPU 指令流水。
• 预分配冗余内存：一次性分配大块内存（冗余度较高）存储对象结构，避免频繁 realloc 。
• 只读不可编辑：解析后的结构不可修改（对象结构可以更小，16字节可对齐到cache刷新线），牺牲灵活性换取速度（可编辑需要再次转换）。

这些手段确实让 yyjson 在只读场景下表现惊艳，但也限制了它的适用边界。

注：yyjson 仅仅是只读复用原始字符串模式比 LJSON 快；只读模式和 LJSON 互有胜负；可编辑模式可能大幅度落后于 LJSON 。

分析1：yyjson 只读模式为什么和 LJSON 互有胜负？yyjson 不支持标准字符串，标准字符串时需要复制一份原始数据（尾后添4个0）再解析；LJSON 支持标准字符串，少了 yyjson 单一模式的激进优化和宏手动展开循环优化。

分析2：yyjson 可编辑模式为什么比 LJSON 慢？ yyjson 需要复制转换一份数据到可编辑对象，且内存要翻倍；LJSON 复用模式原始就是可编辑的。

三、LJSON 的架构通用性：不仅仅是快

LJSON 提供了多达 7 种解析模式 与 4 种打印模式，覆盖从内存到文件、从 DOM 到 SAX 的全场景需求：

解析模式包括：

1. DOM 经典模式（malloc/free）
2. DOM 内存池模式
3. DOM 复用模式（可编辑，字符串原地复用）
4. DOM 文件流模式（真流式）
5. DOM 文件流内存池模式（真流式 + 内存池）
6. SAX 模式（回调处理）
7. SAX 文件流模式（真流式 + 回调）

真流式解析（chunked 文件边读边解析，无需完整读完文件到缓冲再解析）

打印模式包括：

1. DOM → 字符串
2. DOM → 文件（真流式）
3. SAX → 字符串
4. SAX → 文件（真流式）

真流式打印（边打印边写文件，无需先打印到字符串完后再写文件）

这种架构设计使得 LJSON 能在以下场景中游刃有余：

• 大文件处理：支持 GB 级 JSON 文件的常数级内存解析
• 嵌入式系统：低内存占用，无堆分配
• 高频读写：支持可编辑 DOM 和高性能打印
• 跨平台开发：纯 C 实现，无第三方依赖

四、设计哲学的分野：深度 vs 单点突破

维度	yyjson	LJSON
核心模式	DOM 复用（只读）	多模式（DOM/SAX/流式）
可编辑性	❌ 不支持（可转换为可编辑）	✅ 支持（不用额外转换）
流式处理	❌ 不支持（需要完整读取再解析）	✅ 真流式
内存策略	内存块 + 原地复用	内存池 + 原地复用
代码可读性	极低（宏密集）（约2万行代码）	高（结构清晰）（约1万行代码）
适用场景	极限只读解析	通用 JSON 处理

yyjson 是一把锋利的手术刀，专注于只读解析的极限性能；而 LJSON 是一套完整的工具箱，兼顾性能、灵活性和可维护性。

五、结语：选型的本质，是理解架构边界

yyjson 的成功在于它对单一模式的深度打磨，但它的架构本质上只是 LJSON 多模式体系中的一个特化版本（yyjson ≈ LJSON 的 DOM 复用模式 + 激进只读优化）。LJSON 的真正价值，在于它能在真实工程环境中，以极低的内存占用和高性能，稳定支撑多样化的 JSON 处理需求。

在选型时，开发者应根据实际场景权衡：是只读解析的极限速度，还是通用处理的架构弹性？理解这两者的本质差异，才能做出真正工程化的决策。

[lengjingzju]

LJSON 高性能优化的平衡之道：哲学思维与工程实践

项目地址

• github: https://github.com/lengjingzju/json
• gitee: https://gitee.com/lengjingzju/json

引言：与计算本质的深度对话

性能优化既不是纯粹的技术堆砌，也不是形而上的抽象思辨，而是一场与计算本质的深刻对话。它要求开发者在有限资源与无限可能性之间、在时间与空间之间、在理想与现实之间，寻找动态平衡的艺术。LJSON 项目的优化实践立足于“尊重数据本质、拥抱硬件特性、精简热路径决策”三大基石，将哲学性思考与工程可行性有机融合。

真正的性能突破源于对数据本质的洞察、硬件特性的顺应，以及对工程规律的尊重。LJSON 通过创新的架构设计与算法优化，在 JSON 处理领域实现了突破性的性能提升，这一切都建立在深刻的工程哲学基础之上。

一、算法与框架：多维解析模式的智慧平衡

哲学思考

一切优化的终极边界，由算法和框架所划定。这关乎选择——在无限的解空间中，找到与需求约束最契合的路径；这也关乎约束——承认资源的有限性，并在此前提下构建秩序。高性能的基石，始于对问题本质的洞察，而非对细枝末节的修补。一个优雅的算法，建立在对问题的深刻抽象之上；一个强大的框架，源于对复杂性的成功封装。

优秀的开发者懂得在问题空间的无限可能性中，识别出与硬件特性、数据特征和业务需求最匹配的解决方案，在“问题规模—时间复杂度—空间复杂度”构成的三维空间中寻找最优解释。这种选择不仅是技术决策，更是对问题本质的深刻洞察。

LJSON 的设计哲学，是在提供丰富功能的同时，确保每种场景都能匹配最优的解析路径。

实践原则

LJSON 框架提供多达 7 种解析模式 与 4 种打印模式，形成了一套完整的解决方案体系：

解析模式包括：

1. DOM 经典模式（malloc/free）——通用场景的基础选择
2. DOM 内存池模式——减少内存碎片，提升分配效率
3. DOM 复用模式（可编辑，字符串原地复用）——最大化内存利用率
4. DOM 文件流模式（真流式）——大文件处理的利器
5. DOM 文件流内存池模式（真流式 + 内存池）——流式处理与内存管理的结合
6. SAX 模式（回调处理）——高效的事件驱动解析
7. SAX 文件流模式（真流式 + 回调）——大文件事件处理的终极方案

打印模式包括：

1. DOM → 字符串——标准序列化输出
2. DOM → 文件（真流式）——大JSON文件生成
3. SAX → 字符串——事件流到字符串的高效转换
4. SAX → 文件（真流式）——事件流到文件的高效输出

这种多模式架构体现了“没有绝对最优，只有最适合”的工程哲学，使开发者能依据具体场景选择最合适的处理策略。

独创算法优势

LJSON 采用自研的 ldouble 算法实现数字与字符串间的相互转换，带来显著性能提升：

• 浮点 ↔ 字符串转换性能远超标准库及主流算法（如 sprintf、grisu2、dragonbox）
• 精度设定为16位，边界处理追求最短表示而非机械的偶数舍入
• 在保证精度的前提下最大化转换效率，体现精度与性能间的精细平衡

二、查表法：有限域内的极致优化

哲学思考

查表法体现了时空转换的基本哲学：用空间确定性换取时间不确定性。通过预先计算并存储可能的结果，将运行时的复杂计算转换为高效的内存访问。其精髓在于识别那些输入域有限但计算代价高昂的操作，以空间换时间，实现性能跃升。

实践原则

LJSON 在多个关键路径应用查表优化：

• 字符类型判断：使用紧凑查找表快速识别字符类型（如空白符、数字等），避免昂贵分支
• 转义字符处理：预计算转义序列与特殊字符映射，加速字符串序列化与反序列化
• 数字解析与序列化：为浮点、大数、除法等运算设计专用查找表，减少实时计算

这些优化严格限定于有限域，确保表结构精简、缓存友好。LJSON 的查表策略始终坚持“小而精”，每张表都经精心设计，以适配 L1/L2 缓存高效运行。

三、减少数据拷贝：秩序的保持与熵减

哲学思考

不必要的拷贝是软件系统中的“熵增”过程，导致资源浪费与能效下降。优化之道，在于践行熵减——通过传递引用（本质）而非副本（表象），维持系统的简洁与有序。珍视数据的形态与流向，避免无谓的搬运与复制。零拷贝正是这一哲学的理想体现，它让数据沿固有轨道自然流动，如河流沿河道奔涌。

实践原则

LJSON 通过多项技术实现数据拷贝最小化：

1. 原地字符串复用：在 DOM 复用模式下，字符串数据直接于原缓冲区重用，避免复制
2. 直接缓冲区操作：解析/打印结果直接在目标缓冲区中生成，省去中间环节
3. 指针优化策略：对大结构体使用指针而非值拷贝，减少内存移动开销
4. 零拷贝解析：在支持场景中直接引用输入数据，无需复制

这些措施共同构成 LJSON 高效内存管理的核心，确保在各类场景下实现最小数据移动开销。

四、信息记录优化：预计算与智能预判

哲学思考

优化的智慧不在于避免计算，而在于避免重复计算。LJSON 通过精细的信息记录机制，将单次计算结果保存并多次使用，体现对计算资源的深刻尊重。

实践原则

LJSON 在多个层面实施信息记录优化：

1. 字符串元数据记录：
   • 记录字符串长度，避免重复执行 strlen
   • 记录转义状态，优化序列化性能
   • 缓存哈希值，加速字典查找
2. 资源预计算：
   • 根据文件大小预分配内存资源
   • 提前分配充足缓冲区，避免频繁 malloc
3. 状态持久化：
   • 记录解析与打印的存储缓冲区状态
   • 通过缓冲区复用实现零堆分配模式，杜绝运行时内存分配

该策略使 LJSON 在多数场景中实现确定性性能表现，避免运行时计算带来的不确定性。

五、批量操作：化零为整的性能提升

哲学思考

现代系统的瓶颈常源于处理海量碎片化操作所产生的开销。批量操作是对碎片化的反抗，它倡导整合与批处理，将随机请求转化为平稳流，遵循耗散结构理论，以有序对抗混乱。

实践原则

LJSON 通过多项批处理技术提升性能：

1. 内存池管理：
   • 提供可选内存池分配器，替代频繁 malloc/free，减少碎片，提升缓存局部性
   • 一次性预估并分配大块内存，内部实施精细管理
2. 缓冲IO优化：
   • 文件流模式采用大块读取策略，减少系统调用次数
   • 写入时先缓冲、后批量写入，最大化 IO 吞吐
3. 批量内存操作：
   • 使用 memcpy/memmove 替代逐字节拷贝
   • 设计便于编译器向量化的代码结构，发挥现代 CPU 优势

这些技术使 LJSON 在处理大规模数据时仍保持优异性能。

六、精度与工程平衡：ldouble 算法的创新实践

哲学思考

对绝对精度的执着是理想主义的完美论，而工程本质是关于权衡的艺术。现实中，我们追求的常非数学最优解，而是约束下的满意解——主动放弃微不足道的精度，可换来计算、带宽与能耗的极大节省。

实践原则

LJSON 自研的 ldouble 算法体现精度与性能的精细平衡：

1. 精度策略：
   • 采用16位十进制精度，满足绝大多数场景
   • 边界处理追求最短表示，非机械偶数舍入
2. 性能优化：
   • 避免昂贵除法、大数与浮点运算
   • 优化常见数字处理路径

该算法在显著提升性能的同时，仍保障足够的精度与可靠性。

七、分支预测优化：与不确定性共舞

哲学思考

CPU 流水线渴望确定性，而条件分支是其挑战。分支预测优化是人类将概率与模式注入硬件，教其“猜测”，从而与不确定性共舞。likely/unlikely 宏是人类向编译器传递的“先验知识”，是对执行概率的一种预言。

实践原则

LJSON 在分支预测优化方面采取多类策略：

1. 热路径优先：最常见条件前置，提高预测准确性
2. 分支消除：使用位运算和数学恒等式替代分支
3. 数据驱动：将条件判断转为查表操作，减少分支数量
4. 循环优化：简化循环条件，提升预测效率
5. 分支选择：在 switch-case 与 if-else 间审慎选择

这些优化确保 LJSON 在关键路径上充分释放现代 CPU 流水线的潜力。

八、缓存命中优化：数据局部性的艺术

哲学思考

缓存优化建立在对时空局部性原理的应用之上：时间局部性（近期再访）和空间局部性（访问邻近），是驾驭存储层次的关键。优化缓存命中，是一场精心策划的数据布局艺术，它要求以 CPU 视角——而非人类视角——组织信息，塑造高效且契合硬件的“空间美学”。

实践原则

LJSON 采用多种缓存优化技术：

1. 数据结构优化：
   • 压缩对象体积，如将 JSON Object 从 48 字节优化至 32 字节（64位系统）
   • 字段重排减少填充字节，提高缓存行利用率
2. 代码布局优化：
   • 热点代码集中放置，提升指令缓存效率
   • 冷代码分离至独立区域，减少缓存污染
3. 循环优化：
   • 保持循环结构紧凑
   • 优化访问模式，增强数据局部性
4. 内存访问优化：
   • 优先顺序访问，最大化缓存行利用
   • 减少随机访问，提高硬件预取效果

这些优化共同保障 LJSON 在内存访问层面达到近乎最优的性能。

九、内联与函数重排：代码的时空编织术

哲学思考

内联（Inlining）打破函数物理边界，是一种空间编织术——将代码段织入调用上下文，以消除调用开销。函数重排（PGO）则是一种时间编织术——依据实际运行剖面（Profile），将频繁连续执行的函数在物理地址上紧密排列。

二者共同指向一点：代码的物理布局应呼应其执行脉络，达到时空的高效统一。

实践原则

• 选择性内联：仅内联小型热点函数，减小调用开销
• PGO 优化：借助剖析反馈优化函数布局
• 模块化内联：保持函数职责单一，便于编译器决策
• 避免过度内联：防止代码膨胀与指令缓存污染

结语：优化作为持续平衡的艺术

LJSON 的优化实践揭示了一条深刻的工程真理：高性能并非源于单一技术的极致追求，而是来自多维度间最佳平衡的艺术。真正优秀的系统优化，需在微观与宏观、短期与长期、人与机器之间找到和谐统一。

• 在算法选择上，LJSON 不追求理论最优复杂度，而是寻找实际场景中的最实用解；
• 在内存管理中，不追求绝对零拷贝，而是权衡拷贝代价与实现复杂度；
• 在精度处理上，不追求数学完美，而是立足需求平衡精度与效率。

这种平衡哲学使 LJSON 既在极端场景中表现卓越，也在一般应用中维持易用与可维护。它告诉我们，真正的优化大师并非追求极端指标之人，而是懂得在约束中做出恰当权衡的工程师。

“优化的最高境界，不是让某个指标臻于极致，而是让整个系统在真实环境中达到和谐高效的状态。”——这正是 LJSON 带给我们的宝贵启示。

注：本文针对 LJSON 的实践，不含针对特定环境和芯片的优化（例如SIMD、汇编）,针对系统级的优化（例如并行、异步、通知）。