简介这份源码包面向需要高性能 JSON 处理的 C 开发者适合有一定 C 基础并关注性能与跨平台适配的人群核心是 RapidJSON 的完整实现可用于服务端接口数据解析、客户端配置文件读写及大规模 JSON 序列化等场景。它在内存管理与算法层面做了针对性优化实际测试速度优于 jsoncpp 和 lib_json并兼顾多字节编码与 Unicode 兼容便于在 Qt 等使用 Unicode 字符串的项目中集成。压缩包共 366 个文件约 1.91MB以 json 测试数据、cpp 源文件与 h 头文件为主辅以 md 说明文档、CMake/Makefile 构建配置及少量图片资源目录结构完整适合直接纳入工程或按需裁剪。已有 927 人学习读者可获得可编译的库源码、配套测试用例与构建脚本既能快速替换现有 JSON 库验证性能也能通过阅读实现与测试代码理解解析器设计、编码处理和定制优化思路。1. 从一个绕不开的性能热点说起服务端跑着跑着 CPU 打满火焰图最顶上那一大坨经常不是业务逻辑而是 JSON 解析入口先 parse 一遍业务层再拷一份 Value落盘前又序列化一遍同一份数据被处理三次。这时候选型就变得很直接——RapidJSON 这个 C 的 JSON 序列化解析器几万行代码全塞在头文件里DOM 和 SAX 两套接口并存多字节字符和 Unicode 编码UTF-8 / UTF-16 / UTF-32都能直接处理在和其他 JSON 库的反复对比测试中它的解析速度常年优于 jsoncpp 和 lib_json 这类老牌库。这份源码包适合两类人被解析性能拖慢过、想知道快在哪儿的后端开发以及要在客户端或资源受限环境里塞一个体积小、可裁剪 JSON 库的人。下面按「能干什么 → 怎么跑 → 怎么改」的顺序拆一遍。2. 目录结构与选型header-only 到底省掉了哪一层开销2.1 include/rapidjson 里的头文件分工把源码包解开第一层几乎只有include/和test/、thirdparty/、CMakeLists.txt。真正要读的是include/rapidjson/这一层头文件的划分本身就暗示了作者的设计意图一个文件对应一个能力用不到就别 include编译期自然也不会展开。头文件职责什么时候会用到rapidjson.h全局宏、断言、版本宏想改默认解析行为时document.hDocument/ValueDOM 入口需要随机读字段reader.hReaderSAX 解析器只需提取少数几个字段writer.h/prettywriter.h紧凑输出 / 带缩进输出序列化、调试打印stringbuffer.h内存输出缓冲配合 Writer 拿结果allocators.hMemoryPoolAllocator/CrtAllocator换分配策略encodings.hUTF8/UTF16/UTF32/AutoUTF非 UTF-8 输入error/en.h错误码转英文描述打日志定位filereadstream.h/istreamwrapper.hFILE* 与 std::istream 适配大文件流式解析pointer.hJSON Pointer 按路径取值路径式配置读取schema.hJSON Schema 校验报文结构校验internal/*dtoa、itoa、strfunc、stack、diyfp 等调性能时才翻internal/才是性能真正落地的地方。internal/strfunc.h里的SkipWhitespace在开了RAPIDJSON_SSE2/RAPIDJSON_SSE42/RAPIDJSON_NEON之后会走指令集批量扫描空白字符这就是「解析快」最直观的一段internal/dtoa.h实现的是 Grisu2 浮点转字符串internal/itoa.h负责整数分支。第一次读源码时容易一头扎进document.h的模板里出不来我的建议是先看reader.h的ParseValue主循环再看strfunc.h的跳过逻辑剩下的都是配套设施。2.2 header-only 换来了什么又付出了什么RapidJSON 的解析器不是继承体系Reader::Parse的 Handler 是模板参数编译期静态分发调用点直接展开成内联代码一次StartObject就是一次函数调用没有虚表间接跳转。这一点和 jsoncpp 的思路完全不同jsoncpp 的Json::Value内部用std::mapstd::string, Value存对象每个节点一次堆分配、每个 key 一次std::string构造解析一万个对象就是几万次 malloc。RapidJSON 的Value在 64 位下是 16 字节的紧凑结构字符串和数组元素全部从MemoryPoolAllocator的大块内存里线性切出来默认按 64KB 一块向后申请。代价也很实在。模板全展开意味着编译时间明显变长一个把document.h引进公共头文件的工程增量编译经常从 2 秒变成十几秒模板报错信息动辄几百行第一次踩坑会怀疑人生二进制体积也会涨。所以工程上的常规做法是业务代码里只 include 必要的那几个头再包一层自己的小接口把rapidjson的名字挡在实现文件里公共头文件里一个字都不出现。接入方式极其简单因为它没有需要编译链接的源文件# 直接把 include 目录加到搜索路径即可不需要链接任何库 g -stdc11 -O2 -I third_party/rapidjson/include demo.cpp -o demo用 CMake 的项目一般这么写把它做成 INTERFACE 目标谁用谁target_link_librariesadd_library(rapidjson INTERFACE) target_include_directories(rapidjson INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/third_party/rapidjson/include) target_compile_features(rapidjson INTERFACE cxx_std_11)INTERFACE库不产出任何二进制target_include_directories后面的INTERFACE关键字表示「用我的人才会拿到这个路径」自己的工程不会被污染。cxx_std_11是硬要求没有 C11 就没有移动语义后面AddMember那一堆.Move()会写得非常难受。有个隐蔽的坑要提前说rapidjson.h里有一批RAPIDJSON_*宏比如RAPIDJSON_HAS_STDSTRING打开后Value才能和std::string互转。这类宏必须在所有引用 rapidjson 的编译单元里保持一致否则同一个Document在不同 TU 里布局不同链接期不报错运行期直接崩属于典型的玄学问题。要么统一写在 CMake 的target_compile_definitions里要么谁也别开。3. DOM 上手Document、Value 与分配器的生命周期3.1 最小可跑示例与错误定位DOM 是最容易上手的一层Document继承自Value解析完就当成一个巨大的树来读。下面这段是能直接编译运行的完整例子重点看错误处理那几行——很多人第一次用会把HasParseError忘掉结果报文格式一错后面全是空指针。#include rapidjson/document.h #include rapidjson/error/en.h #include cstdio #include string int main() { const char* json R({id:1024,name:张三,score:97.5, tags:[cpp,json],vip:true}); rapidjson::Document doc; // 默认使用 MemoryPoolAllocator doc.Parse(json); // 复制模式字符串会被拷进 doc 自己的内存池 if (doc.HasParseError()) { // 一定要判否则后面全是未定义行为 std::printf(parse error: %s at offset %zu\n, rapidjson::GetParseError_En(doc.GetParseError()), doc.GetErrorOffset()); return 1; } if (!doc.IsObject() || !doc.HasMember(id) || !doc[id].IsInt()) return 2; std::printf(id%d name%s score%.2f tags%u\n, doc[id].GetInt(), doc[name].GetString(), doc[score].GetDouble(), doc[tags].Size()); return 0; }Parse返回的是Document本身不带成功标志判断全靠HasParseError()GetParseError()拿到的是枚举GetParseError_En()把它转成人能读的英文GetErrorOffset()给出出错字节偏移。线上排查报文问题时把 offset 和原始字符串一起打到日志里能省掉大量来回对包的时间。IsXxx()先行、GetXxx()后取是这一层的铁律。doc[id]用的是operator[]key 不存在时会触发RAPIDJSON_ASSERTRelease 下断言被关掉就变成越界读。所以要么先HasMember要么用FindMember// FindMember 返回迭代器找不到时等于 MemberEnd()比 operator[] 安全 auto it doc.FindMember(name); if (it ! doc.MemberEnd() it-value.IsString()) { const char* name it-value.GetString(); // 注意指向 doc 内部内存 rapidjson::SizeType len it-value.GetStringLength(); // 中间可能含 \0 }GetString()拿到的是裸指针它指向Document内部内存池Document一析构指针立刻失效。这是我见过最多的翻车方式把const char*塞进结构体缓存起来等下一帧再用结果读到一片已经被复用的内存日志里全是乱码。要留就立刻std::string(str, len)拷走GetStringLength()不能省因为 JSON 字符串里允许出现\u0000用strlen会截断。3.2 in-situ 解析与零拷贝的边界Parse默认是把字符串拷进内存池的安全但有拷贝成本。体积大的报文可以用ParseInsitu直接在你给的缓冲区上就地改写把转义字符原地处理掉字符串指针指回原缓冲区一次拷贝都不做std::string buf(json); // 必须可写 doc.ParseInsitu(buf[0]); // C11 起 buf[0] 可写不要用 c_str() // 此后 buf 的内容已被修改doc 里的字符串全部指向 buf // buf 不能重新赋值、不能析构直到 doc 用完这里的约束比想象中严缓冲区必须以\0结尾RapidJSON 靠它判断结束不额外传长度解析过程中内容会被改写解析完原来的 JSON 文本就没了。所以千万别对同一个 buffer 调两次ParseInsitu第二次解析的是被改坏的数据报错位置还莫名其妙。另外std::string::c_str()在 C11 之后虽然返回const char*但buf[0]的语义更明确别在这上面省事。3.3 内存池与字符串写入要自己构造Value往外输出时分配器必须显式带上。这是新手最容易卡住的地方AddMember的第二个参数如果是含字符串的Value它需要分配器来拷字符串不传就编译不过。rapidjson::MemoryPoolAllocator alloc(4096); // 每块 4KB按需增长 rapidjson::Document doc(alloc); doc.SetObject(); rapidjson::Value key(name, alloc); // key 也走同一个池 rapidjson::Value val(张三, alloc); // 字符串被拷进池里 doc.AddMember(key, val, alloc); // 第三个参数是分配器 doc.AddMember(id, 1024, alloc); // 字面量 key 有重载可省一次构造MemoryPoolAllocator的模板参数是底层分配器默认CrtAllocator也就是malloc/free。它只在块用完时申请新块析构时统一释放所以单个Value的销毁是空操作这也是 DOM 树析构几乎不花时间的原因。反过来池只在Document析构时统一归还中途删掉某个成员并不会把内存还给池——解析超大文档时如果只留一小部分字段内存峰值依然是整棵树。需要跨Document搬数据时用CopyFrom同样要带分配器rapidjson::Document dst; dst.SetObject(); dst.CopyFrom(src, dst.GetAllocator()); // 深拷贝字符串重新分配在 dst 的池里顺带提一句RAPIDJSON_HAS_STDSTRING1之后可以直接doc.AddMember(name, std::string(张三), alloc)省掉手写Value(...)的啰嗦但记得前面说的宏一致性问题。4. SAX 与 Writer把解析链路的开销压到最低4.1 Reader Handler 的事件流只要几十个字段里的三五个构造整棵 DOM 纯属浪费。SAX 模式下你写一个 Handler解析器每遇到一个 token 就回调一次全程不建树。Handler 不需要继承什么基类只要提供Null/Bool/Int/Uint/Int64/Uint64/Double/String/StartObject/Key/EndObject/StartArray/EndArray这些方法缺的用BaseReaderHandler的默认空实现补上就行。#include rapidjson/reader.h #include rapidjson/stringbuffer.h #include cstring #include string #include vector // 只收集所有 name 字段的值其余 token 一律忽略 struct NameCollector : rapidjson::BaseReaderHandlerrapidjson::UTF8, NameCollector { std::vectorstd::string names; bool expect_name false; bool Key(const char* str, rapidjson::SizeType len, bool /*copy*/) { expect_name (len 4 std::memcmp(str, name, 4) 0); return true; // 返回 false 会立刻中止解析 } bool String(const char* str, rapidjson::SizeType len, bool /*copy*/) { if (expect_name) { names.emplace_back(str, len); // 按长度构造兼容 \u0000 expect_name false; } return true; } }; // 调用侧 rapidjson::Reader reader; rapidjson::StringStream ss(json); // 也可以是 FileReadStream NameCollector h; rapidjson::ParseResult ok reader.Parserapidjson::kParseIterativeFlag(ss, h); if (!ok) { /* ok.Code() / ok.Offset() 可直接取错误码和偏移 */ }Key的第三个参数copy在 SAX 模式下恒为false字符串指针指向源缓冲区回调返回后就失效所以必须当场拷走。ParseResult比 DOM 那套更友好ok.IsError()、ok.Code()、ok.Offset()一步到位。kParseIterativeFlag值得单独说默认的解析器是递归下降的JSON 嵌套几百层就会爆栈遇到恶意构造的深嵌套报文直接被拉挂。加上这个 flag 后改用显式栈internal/stack.h那个自带的栈实现接管了递归深度只受内存限制。线上服务接口一律带上这是血泪经验。4.2 Writer 输出与浮点位数控制序列化这边Writer是紧凑输出PrettyWriter带缩进和换行调试打印或者生成人读配置文件时用后者。两者都写到一个StringBuffer里最后GetString()/GetSize()取结果。#include rapidjson/prettywriter.h #include rapidjson/stringbuffer.h rapidjson::StringBuffer sb; rapidjson::PrettyWriterrapidjson::StringBuffer w(sb); w.SetIndent( , 2); // 两空格缩进 w.SetMaxDecimalPlaces(4); // double 最多保留 4 位小数默认是 324 w.StartObject(); w.Key(id); w.Int(1024); w.Key(name); w.String(张三); w.Key(score);w.Double(97.5); w.Key(tags); w.StartArray(); w.String(cpp); w.String(json); w.EndArray(); w.EndObject(); std::fwrite(sb.GetString(), 1, sb.GetSize(), stdout);SetMaxDecimalPlaces的默认值极大意味着0.1 0.2这种浮点误差会原样吐出来前端同学看到一长串0.30000000000000004会来问你是不是有 bug。业务上一般按字段语义设成 26 位。另外 Writer 默认把非有限值NaN、Inf当非法处理需要输出时得在解析侧开kParseNanAndInfFlag写出侧用w.Nan()/w.Inf()两边都要开只开一边照样对不上。Writer还有个RawValue(json, len, type)可以把一段已经序列化好的 JSON 原样嵌进去避免「字符串里套字符串」再解析一次。用它的时候一定要保证那段的类型标注kObjectType之类和实际内容一致标错了生成的 JSON 结构就乱了而且这种错误在解析侧才会暴露。4.3 多字节与 Unicode 编码的三种处理方式RapidJSON 的编码设计是把「源编码」和「目标编码」拆成两个模板参数默认都是UTF8。处理中文这类多字节字符时有三种典型写法第一种输入本来就是 UTF-8什么都不用做ReaderUTF8, UTF8是默认值。中文在 UTF-8 里是 3 字节解析器不解释字符语义只按字节处理转义和边界所以性能不受影响。第二种输入是 UTF-16Windows 侧或者某些协议常见显式指定源编码// 源数据是 UTF-16LE目标 DOM 仍用 UTF-8 存储 rapidjson::GenericDocumentrapidjson::UTF8 doc; doc.Parserapidjson::kParseDefaultFlags, rapidjson::UTF16LE(u16str);模板参数顺序是parseFlags, SourceEncoding容易写反写反了不报错但解析结果全是乱码——这是我在一个跨平台模块上排查了半天的坑。第三种输入编码不确定用AutoUTFInputStream读 BOM 自动判定配合AutoUTF作为源编码using AutoStream rapidjson::AutoUTFInputStreamunsigned, rapidjson::FileReadStream; FILE* fp std::fopen(data.json, rb); char buf[65536]; rapidjson::FileReadStream fs(fp, buf, sizeof(buf)); AutoStream as(fs); // 读 BOM决定 UTF-8 / UTF-16LE / UTF-16BE rapidjson::Reader reader; NameCollector h; reader.Parserapidjson::kParseDefaultFlags, rapidjson::AutoUTFunsigned(as, h);AutoUTF的代价是每个字符多一次分支判断比写死编码慢一截只在输入来源不确定时用。另外\uXXXX转义的处理是统一的解析器会把它解码成 UTF-8 序列写进结果遇到代理对\uD83D\uDE00这种会合并成一个码点不需要自己拼。但如果自己手动String()写入包含代理对的裸 UTF-16那就要自己保证序列合法。4.4 大文件流式读取几百 MB 的 JSON 一次性读进内存再解析内存曲线会很难看。FileReadStream配合ParseStream增量喂数据ParseStream内部会维护跨块的 token 状态FILE* fp std::fopen(big.json, rb); char buf[65536]; // 缓冲区大小自己调64KB 起步 rapidjson::FileReadStream fs(fp, buf, sizeof(buf)); rapidjson::Document doc; doc.ParseStream(fs); // 只读一遍缓冲区会被反复复用 std::fclose(fp);缓冲区是复用的所以不能指望解析完还能从buf里读原文ParseStream之后buf里只剩最后一小段。如果是std::ifstream用IStreamWrapper包一层接口一模一样。再往上kParseStopWhenDoneFlag可以让解析器在第一个完整 JSON 值结束时停下处理「一行一个 JSON」的日志文件时非常有用配合GetErrorOffset()就能按行切分。5. 避坑与排查几个真会让人加班到深夜的坑5.1 编译与集成类现象代码在自己机器上编过到 CI 上链接报undefined reference指向某个rapidjson::符号。原因多半是某个 TU 里定义了RAPIDJSON_HAS_STDSTRING之类的宏另一些 TU 没定义同一个内联函数展开出不同实现ODR 被破坏。解决所有RAPIDJSON_*宏统一放 CMake 的target_compile_definitions(... PUBLIC ...)不要写在某个 .cpp 文件顶上。现象MSVC 下编译时间爆炸或者模板报错几千行定位不到自己写的哪一行错了。原因document.h被公共头文件 include模板在每个引用点都完整展开一遍。解决公共头里只前置声明自己的封装类型rapidjson的头全部挪进 .cpp必要时开RAPIDJSON_NOMEMBERITERATORCLASS牺牲一点遍历便利换编译速度。5.2 内存与生命周期类现象接口偶发返回乱码重启后正常压测一段时间必现。原因把Value::GetString()返回的const char*存进了缓存或结构体Document析构后指针悬空那块内存被内存池复用。解决出作用域前一律std::string(str, GetStringLength())拷走需要长期持有就别存指针。这类问题用 ASan 跑一遍基本都能抓出来。现象用ParseInsitu之后同一个 buffer 再解析一次报错位置完全对不上。原因in-situ 是就地改写第一次解析完原文本已经被破坏第二次解析的是残缺数据。解决in-situ 只用于「解析一次就丢」的场景需要重复解析就保留一份原始副本或者干脆用普通Parse。5.3 数值与解析行为类现象一个 19 位的订单号解析出来末几位变成了 0。原因数字被当成double处理。RapidJSON 会根据字面量自动判断整数还是浮点但超过int64范围或者带小数点时仍是double超过 2^53 就丢精度。解决ID 类字段在协议层就用字符串传必须用数字时开kParseNumbersAsStringsFlag全当字符串收自己按需转浮点比对场景再叠kParseFullPrecisionFlag。现象本地解析结果和线上差最后一位小数怀疑解析器有问题。原因默认的浮点转换走 Grisu2 快速路径不保证和strtod逐位一致。解决需要严格一致时开kParseFullPrecisionFlag代价是慢一些。做数据比对、写单测断言时这个 flag 要常开。现象报文里带\u0000的字符串取出来被截断了。原因用strlen(GetString())算长度遇到\0就停。解决永远用GetStringLength()写出去的时候也别用%s用fwrite或std::string(ptr, len)。6. 二次开发裁剪、封装与验证的一套做法真正把 RapidJSON 接进项目改造点通常不在「加功能」而在「把它的灵活性收窄」。我的习惯是先建一个json_util.hjson_util.cpp的两文件层头文件里一个rapidjson的类型都不出现这样上层业务换库、或者以后想换string_view版本只改这两个文件。裁剪先从宏开始常用的几个开关如下宏作用建议RAPIDJSON_HAS_STDSTRINGValue与std::string互转开了省事但要全局一致RAPIDJSON_HAS_CXX11_RVALUE_REFS启用移动语义C11 以上默认开RAPIDJSON_PARSE_DEFAULT_FLAGS全局默认解析 flag把kParseIterativeFlag焊死在这里RAPIDJSON_WRITE_DEFAULT_FLAGS全局默认写出 flag统一浮点行为RAPIDJSON_ASSERT替换断言实现换成写日志 上报别直接 abortRAPIDJSON_SSE42/RAPIDJSON_NEON指令集加速空白跳过部署环境确定支持再开RAPIDJSON_PARSE_DEFAULT_FLAGS这个宏特别值得用把防爆栈的 flag 写死在编译选项里比每个调用点都记得传要可靠得多。封装层的接口我一般只留三四个函数返回值统一成一个带错误码和偏移的结构// json_util.h —— 不暴露任何 rapidjson 类型 #pragma once #include cstddef #include string namespace jsonutil { struct Status { bool ok false; std::string message; // 已经是人可读的英文描述 std::size_t offset 0; }; // 从扁平对象里取一个字符串字段找不到或类型不符都返回非 ok Status GetString(const std::string text, const char* key, std::string out); // 序列化字段少的时候直接拼字段多再走 Writer Status Dump(const std::string key, const std::string value, std::string out); } // namespace jsonutil实现侧的关键是把两个 flag 固定住解析用kParseIterativeFlag | kParseStopWhenDoneFlag避免深嵌套爆栈也让「尾部有多余字符」不再静默通过出错时把GetParseError_En和 offset 一起塞进Status::message上层只管透传给调用方。这套东西写完业务侧看到的就只是if (!st.ok) { log(st.message); }不需要知道底下发生了什么。验证方式我推荐一步到位写一个只用 20 行左右的冒烟用例喂进去五种输入——正常对象、截断的 JSON、深嵌套 500 层、超长整数、含\u0000的字符串——断言前两个成功、中间两个报错且 offset 合理、最后两个能原样取回。这五个用例跑通基本可以认定接入姿势没问题后面每次升级源码包重跑一遍就知道有没有行为变化。这个习惯是被坑出来的曾经有次换了编译选项RAPIDJSON_ASSERT被NDEBUG关掉原本断言拦住的越界访问变成了静默读脏数据问题飘到业务层才炸查了两天。从那以后我每次把这个库接进新工程都先把这五个用例跑一遍再接业务代码。希望帮到你。本文还有配套的精品资源点击获取
