C++ Rapidjson 完全指南 - 高效 JSON 解析与性能优化

2025-02-05

2025-04-24

Rapidjson 是一款 C++ 的 json 库. 支持处理 json 格式的文档. 其设计风格是头文件库, 包含头文件即可使用, 小巧轻便并且性能强悍. 本文结合在线样例来介绍 Rapidjson 一些常见的用法.

作者提了一个 PR 将 Rapidjson 集成到 Compiler Explorer 上. 目前可以使用 Compiler Explorer 来体验 Rapidjson 的功能. 如果想要本地安装, 请参考最后一节 .

基础用法

解析 json

        auto input = R"({"name": "华安", "id": 9527})";
rapidjson::Document doc;
doc.Parse(input);
if (doc.HasParseError()) {
  return -1;
}
       

访问元素

检查并获取

HasMember 查询 key 是否存在, 然后使用 Is 方法来判断类型是否兼容, 最后用 Get 方法来获取对应的值.

        // HasMember + IsType + Get
if (doc.HasMember("name") && doc["name"].IsString()) {
  std::string name = doc["name"].GetString();
  std::cout << "name is: " << name << std::endl;
if (doc.HasMember("id") && doc["id"].IsInt()) {
  int id = doc["id"].GetInt();
  std::cout << "id is: " << id << std::endl;
}
       

使用 `FindMember` 减少查询开销

上述示例中, doc["name"] 被使用了两次, 相当于创建了两个临时变量. 使用 FindMember 方法则可以减少这种额外开销.

        // FindMember + IsType + Get
if (auto it = doc.FindMember("name");
    it != doc.MemberEnd() && it->value.IsString()) {
  std::string name = it->value.GetString();
  std::cout << "name is: " << name <<




    
 std::endl;
if (auto it = doc.FindMember("id");
    it != doc.MemberEnd() && it->value.IsInt()) {
  auto id = it->value.GetInt();
  std::cout << "id is: " << id << std::endl;
}
       

访问对象(Object)

现在假定我们有下面的 json:

        {
  "code": 200,
  "data": {
    "total": 200,
    "curr": [12345, 23456, 34564]
}
       

查询方法与前面的基础类型相似. 需要注意的是, GetObject() 方法返回的是一个 const 引用. Rapidjson 为了提高效率, 接口的设计上避免使用对象拷贝.

        if (auto it = doc.FindMember("data");
    it != doc.MemberEnd() && it->value.IsObject()) {
  const auto& data = it->value.GetObject();
  // ...
}
       

访问数组(Array)

我们用 IsArray() 和 GetArray() 来判断和获取对应的数据.

需要注意的是: json 中的数组是允许多个不同类型的, 如下是一个合法的 json:

        {
  "array": ["string", true, null, [], {}, 123]
}
       

但是 C++ 的数组或者容器 vector 仅支持相同的元素, 所以我们在获取数组元素时需要注意判断元素类型.

          for (auto it = array.Begin(); it != array.End(); ++it) {
    if (it->IsInt()) {
      std::cout << it->GetInt() << std::endl;
  }
       

由于 rapidjson 支持 range based for , 我们可以这样写:

          // range based for
  for (const auto& item : array) {
    if (item.IsInt()) {
      std::cout << item.GetInt() << std::endl;
  }
       

序列化 json 对象

下面的函数用来将 json 对象序列化成字符串. 后续的示例中将会用到这个函数

        #include <rapidjson/document.h>
#include <rapidjson/filewritestream.h>
#include <rapidjson/writer.h>
std::string ToString(rapidjson::Value& value) {
  rapidjson::StringBuffer buffer;
  rapidjson::Writer<rapidjson::StringBuffer> writer(buffer);
  value.Accept




    
(writer);
  return buffer.GetString();
}
       

生成 json 对象

基础类型

对于基础类型(整型, 布尔值, 浮点数)我们可以直接使用 AddMember 添加, 需要注意的是接口中需要指定一个 Allocator .

        rapidjson::Document doc(rapidjson::kObjectType);
doc.AddMember("name", "华安", doc.GetAllocator());
doc.AddMember("id", 9527, doc.GetAllocator());
doc.AddMember("is_intern", true, doc.GetAllocator());
std::cout << ToString(doc) << std::endl;
       

此时 doc 的内容为:

        { "name": "华安", "id": 9527, "is_intern": true }
       

为了减少对 GetAllocator() 的调用, 可以使用一个变量保存该结果, 见后续代码.

刚开始使用 Rapidjson 时会遇到如下场景下的编译失败:

value 类型为 std::string
key 类型为 std::string

接下来详述其解决办法.

解决 value 为 std::string 类型的问题

        rapidjson::Document doc(rapidjson::kObjectType);
std::string name{"唐伯虎"};
// 默认情况下都会失败, 无法编译
doc.AddMember("name", name, doc.GetAllocator());
       

编译器错误:

        error: no matching function for call to 'rapidjson::GenericDocument<rapidjson::UTF8<> >::AddMember(const char [5], const char*, rapidjson::MemoryPoolAllocator<rapidjson::CrtAllocator>&)'
       

也就是没有匹配的 AddMember 可以接受 std::string 类型. 这是因为 Rapidjson 默认没有打开 std::string 支持. 解决办法是在项目中增加 RAPIDJSON_HAS_STDSTRING 宏定义. 可以在编译时增加 -DRAPIDJSON_HAS_STDSTRING 参数.

手动增加编译器参数: g++ -DRAPIDJSON_HAS_STDSTRING

在 CMakeLists.txt 中增加如下代码:

          add_compile_definitions(RAPIDJSON_HAS_STDSTRING)
         

代码中在 include 之前增加如下代码: #define RAPIDJSON_HAS_STDSTRING 1

         1#define RAPIDJSON_HAS_STDSTRING 1
 2#include <rapidjson/document.h>
 3#include <string>
 5int main() {
 6  rapidjson::Document doc(rapidjson::kObjectType);
 8  std::string name{"唐伯虎"};
 9  doc.AddMember("name", name, doc.GetAllocator());
10}
       

解决 key 为 std::string 类型的问题

        rapidjson::Document doc(rapidjson::kObjectType);
std::string key{"dynamic-key"};
doc.AddMember(key, "some-value", doc.GetAllocator());
       

编译器错误:

        error: no matching function for call to 'rapidjson::GenericDocument<rapidjson::UTF8<> >::AddMember(std::string&, const char [11], rapidjson::MemoryPoolAllocator<rapidjson::CrtAllocator>&)'

解决办法为创建一个 rapidjson::Value 对象, 并对其赋给动态值.

        rapidjson::Document doc(rapidjson::kObjectType);
std::string key{"dynamic-key"};
// 创建一个rapidjson::Value对象
rapidjson::Value json_key;
// 从string赋值
json_key.SetString(key.data(), key.size());
doc.AddMember(json_key, "some-value", doc.GetAllocator());
       

添加对象

一个 Object 对象可以用 rapidjson::Value 表示. 其添加成员的方法是 AddMember ( rapidjson::Document 是 rapidjson::Value 的衍生类).

对于特殊值 null , 我们可以使用 SetNull() 方法或者在构造函数中指定 rapidjson::kNullType 来实现.

        rapidjson::Document doc(rapidjson::kObjectType);
auto& allocator = doc.GetAllocator();
// 添加对象类型的成员
rapidjson::Value contact(rapidjson::kObjectType);
rapidjson::Value email;
email.SetNull();  // 设置为null
contact.AddMember("email", email, allocator);
contact.AddMember("twitter", rapidjson::Value(rapidjson::kNullType),
                  allocator);
doc.AddMember("contact", contact, allocator);
std::cout << ToString(doc) << std::endl;
       

此时的 doc 为:

        {
  "contact": { "email": null, "twitter": null }
}
       

添加数组

Array 类型的创建和添加如下所示.

        rapidjson::Document doc(rapidjson::kObjectType);
auto& allocator = doc.GetAllocator();
// 添加数组类型的成员
rapidjson::Value friends(rapidjson::kArrayType);
friends.PushBack("祝枝山", allocator);
friends.PushBack("文征明", allocator);
friends.PushBack("徐祯卿", allocator);
doc.AddMember("friends", friends, allocator);
std::cout << ToString(doc) << std::endl;
       

此时 doc 为:

        {
  "friends": ["祝枝山", "文征明", "徐祯卿"]
}
       

进阶用法

使用函数模板简化解析

从前面解析的例子我们可以看到, 对每一个字段的解析都有:查找是否存在, 判断类型是否匹配, 然后获取值, 代码接近只是字段和类型有区别, 这会导致大量的冗余代码. 可以通过模板函数来实现一个通用的解析代码.

模板签名为:
```
template <typename... T>
bool Parse(rapidjson::Value& data, const char* name,
          std::variant<T...>& target);
```
其中:
- data 是需要解析的 json 数据
- name 是字段名
- target 是存储解析结果的变量, 我们用 std::variant 来存储不同的解析类型, 比如: int* , double* , std::string* 等.

在实现中, 先查找字段中是否存在字段, 如果不存在则报错.

          auto it = data.FindMember(name);
if (it == data.MemberEnd()) {
  std::cerr << "key not found: " << name << std::endl;
  return false;  // 字段不存在
}
         

接着判断字段值的类型是否与 target 预期一致. 我们用 std::visit 来访问 std::variant , 针对不同类型做不同的解析, 对目前尚不支持的类型则报错.

          return std::visit(
  [&](auto value) {
    // 获取字段类型
    using ValueType = std::remove_pointer_t<decltype(value)>;
    // 按照字段类型分类处理, 此处判断值类型是否为string
    if constexpr (std::is_same_v<ValueType, std::string>) {
      if (!it->value.IsString()) {
        std::cerr << "string not match: " << name << std::endl;
        return false;  // 类型不匹配
      *value = std::string(it->value.GetString(), it->value.GetStringLength());
    } else if constexpr (std::is_integral_v<ValueType> ||
                          std::is_floating_point_v<ValueType>) {
      if (!it->value.Is<ValueType>()) {
        std::cerr << "integer not found: " << name << std::endl;
        return false;  // 类型不匹配
      *value = it->value.Get<ValueType>();
    } else {
      std::cerr << "unsupported type\n";
      return false;  // 不支持的类型
    return true;  // 解析成功
  target);
         

下面以解析一个结构体为例展示如何使用. 页面中仅仅展示了一部分关键代码. 点击下面的运行或者访问 parse.cpp 可以获取到完整代码.

        struct Person {
  bool married = false;
  int




    
 id = 0;
  int age = 0;
  double point = 0;
  std::string name;
  std::string email;
bool ParsePerson(Person* person, rapidjson::Value& json) {
  std::vector<
      std::tuple<const char*, std::variant<int*, std::string*, double*, bool*>>>
      list = {
          {"id", &person->id},           {"age", &person->age},
          {"name", &person->name},       {"email", &person->email},
          {"married", &person->married}, {"point", &person->point},
  for (auto& [name, variant] : list) {
    if (!Parse(json, name, variant)) {
      return false;  // 解析失败
  return true;  // 解析成功
}
       

处理多重嵌套

在工作中我们有时候会遇到嵌套很深的 json 文档. 比如给定这样一个 json 文档, 现在我们要获取 /data/avatar/image/thumbnail 如何操作?

        {
  "code": 200,
  "data": {
    "avatar": {
      "image": {
        "medium": "https://image.com/hua.an.jpg",
        "thumbnail": "https://image.com/hua.an-thumbnail.jpg"
}
       

如果按照之前的写法层层解析, 那么必然是个很深的嵌套.

但是现在有个更好的解决办法, 就是 JSONPath , 在 rapidjson 里面就是 Pointer 类, 可以轻松获取到嵌套很深的值.

        rapidjson::Document doc;
if (doc.Parse(response).HasParseError()) {
  std::cerr << "JSON parse error!" << std::endl;
  return -1;
// 使用 RapidJSON 的 Pointer 解析 JSONPath
const char* jsonpath = "/data/avatar/image/thumbnail";
rapidjson::Pointer pointer(jsonpath);
// 获取 JSONPath 对应的值
if (rapidjson::Value* value = pointer.Get(doc)) {
  if (value->IsString()) {
    std::cout << "Thumbnail URL: " << value->GetString() << std::endl;
  } else {
    std::cerr << "Thumbnail is not a string!" << std::endl;
} else {
  std::cerr << "Thumbnail not found!" << std::endl;
}
       

完整的代码请参考: jsonpath.cpp

安装集成

有如何的几种方法可以将 Rapidjson 集成到您的项目中.

Vcpkg 安装: 使用 vcpkg install rapidjson 即可. 如果不熟悉 vcpkg 请参考我的文章: Vcpkg 使用全攻略: 支持 VS Code, Visual Studio 和 CLion .

CMake 的 FetchContent_Declare 方法.

          # 引入 FetchContent 模块
include(FetchContent)
# 设置 Rapidjson 编译选项
set(RAPIDJSON_BUILD_TESTS OFF CACHE INTERNAL "")
set(RAPIDJSON_BUILD_DOC OFF CACHE INTERNAL "")
set(RAPIDJSON_BUILD_EXAMPLES OFF CACHE INTERNAL "")
set(RAPIDJSON_BUILD_CXX20 ON CACHE INTERNAL "")
FetchContent_Declare(
    rapidjson
    URL https://github.com/Tencent/rapidjson/archive/refs/tags/v1.1.0.zip
FetchContent_MakeAvailable(rapidjson)
         

源码安装: 下载源码并将其路径加入 include 目录列表中: gcc -I /path/to/rapidjson

参考链接

Tags:

Rapidjson Best Practice