nlohmannjson：一个头文件，C++ JSON 处理不再折腾

nlohmann/json：一个头文件，C++ JSON 处理不再折腾

nlohmann/json 在 GitHub 上已经拿到 49.7K Star 了。

德国开发者 Niels Lohmann 从 2013 年开始维护这个库，目标很明确：让 C++ 里操作 JSON 跟操作 std::vector 一样顺手。一个头文件，拖进项目就用，没有子依赖，不需要调编译器选项。

1、 这玩意儿解决了什么

C++ 里的 JSON 库很多，但问题集中在两点：集成重、API 设计跟 C++ 标准库不一致。习惯了 std::map 和 std::vector 接口的人，换个 JSON 库往往要学一套新的访问方式。

nlohmann/json 的设计方向不一样。它利用运算符重载和 C++11 特性，让 JSON 值在 C++ 里表现得像一个标准容器：用 [] 访问字段，用迭代器遍历，用 push_back 加元素，结构体可以一键序列化。你不需要学这个库，你知道 STL 就会用它。

2、 集成只有一个文件

这个库就是一个 json.hpp。没有 .cpp，没有 .a/.so，没有子项目。

#include <nlohmann/json.hpp>
using json = nlohmann::json;

两行写完，-std=c++11 就能编译。同时被 Homebrew、vcpkg、Conan、Conda、NuGet、xmake 等十几个包管理器收录，CMake 里有 nlohmann_json::nlohmann_json 目标直接用，或者 FetchContent 远程拉取。

3、 用起来什么样

创建 JSON 对象：

json j = {
  {"pi", 3.141},
  {"happy", true},
  {"name", "Niels"},
  {"answer", {{"everything", 42}}},
  {"list", {1, 0, 2}}
};

读写跟 STL 容器一样：

std::string name = j["name"];
j["new_key"] = "value";
std::cout << j.dump(4);   // 格式化输出

for (auto& [key, value] : j.items()) {
  std::cout << key << " : " << value << '\n';
}

流式 I/O 也支持：

json j;
std::cin >> j;            // 从输入流解析
std::cout << std::setw(4) << j;  // 格式化输出到输出流

4、 自定义类型序列化，几行搞定

项目里重复率最高的代码是什么？把 struct 字段一个个映射到 JSON，再一个个读回来。写一次还好，十个 struct 写十遍，改一个字段漏一个映射。

这个库的做法：在类型的命名空间里实现两个函数（to_json 和 from_json）。之后 json j = myStruct 和 auto s = j.get<MyStruct>() 直接可用。

struct Person { std::string name; int age; };

void to_json(json& j, const Person& p) {
  j = json{{"name", p.name}, {"age", p.age}};
}
void from_json(const json& j, Person& p) {
  j.at("name").get_to(p.name);
  j.at("age").get_to(p.age);
}

还有一种写法：NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(Person, name, age) 一行宏，替代上面全部。对枚举也有关键宏：NLOHMANN_JSON_SERIALIZE_ENUM 指定枚举到字符串的映射。

5、 五种二进制格式 + 三套 RFC

除了标准 JSON 文本，库内置了 BSON、CBOR、MessagePack、UBJSON、BJData 五种二进制格式的转换。调用 json::to_msgpack(j) 输出 vector<uint8_t>，json::from_cbor(v) 读回来，接口一致。

协议层面直接支持 JSON Pointer（RFC 6901）做路径访问、JSON Patch（RFC 6902）做 diff 和增量更新、JSON Merge Patch（RFC 7386）做结构化合并。有 SAX 接口做流式解析。做配置中心或协同编辑功能时，这些协议实现能直接用。

6、 怎么验证它可靠

单元测试覆盖率 100%。Google OSS-Fuzz 7x24 小时模糊测试。Valgrind 查内存，Clang Sanitizers 查 UB。CI 矩阵覆盖 GCC 4.8 到 14.2、Clang 3.4 到 21.0、Apple Clang、MSVC 2015 到 2022、Intel C++ 编译器和 Nvidia CUDA 编译器。CII 最佳实践认证，OpenSSF Scorecard 评分可查。

7、 适合哪些人用

• C++ 后端开发，接口对接需要频繁 JSON 解析和生成
• 游戏引擎或嵌入式环境，不想拖一条依赖链进来
• 有一堆 struct 需要序列化到 JSON，想省掉手写映射代码
• 网络协议用了 MessagePack 或 CBOR，需要 C++ 端解析支持
• 做配置下发、增量更新，需要 Patch 协议支持的场景