RapidJSON v1.1.0 发布简介
时隔 15.6 个月，终于发布了一个新版本 v1.1.0。
新版本除了包含了这些日子收集到的无数的小改进及 bug fixes，也有一些新功能。本文尝试从使用者的角度，简单介绍一下这些功能和沿由。
JSON Pointer
也许 RapidJSON 一直最为人垢病的地方，是它奇怪的 API 设计。例如，对 DOM 加添数据要给于 allocator 参数：
#include "rapidjson/document.h"
using namespace rapidjson;
// ...
Document d(kObjectType);
Value a(kArrayType);
for (int i = 1; i <= 4; i++)
a.PushBack(i, d.GetAllocator());
d.AddMember("a", a, d.GetAllocator());
// { a : [1, 2, 3, 4] }
这是由于 RapidJSON 的 DOM 使用局部的分配器，以避免全局分配器的问题。而为了节省内存，每个 Value 不会存储分配器的指针，所以必须从外部提供。
此设计也导致另一种问题。我们看看一个例子，使用 DOM API 访问以下这个 JSON：
{
"widget": {
"window": {
"title": "Sample Konfabulator Widget"
}
}
}
要访问 title，最直觉想到的应该是这样：
Document d;
d.Parse(json);
std::cout << d["widget"]["window"]["title"].GetString();
如果 widget、window 或 title 不存在呢？以标准库 std::map::operator[] 的做法来说，当找不到键，它会自动加入一个键值对，并返回该值（所以 map::operator[] 必须是 non-const 函数）。然而，RapidJSON 创建值的时候需要 allocator，所以不可能自动加入键值对。因此，RapidJSON 规定以 operator[] 访问时，必须确保键存在（找不到时直接断言失败）。若不能确保，应先用 HasMember() 判断，或更好的是使用 FindMember()，因为它可以告之键是否存在的同时，能通过迭代器取得该值。可是，使用 FindMember() 去访问多层对象，代码非常冗长：
Value::ConstMemberIterator itr1 = d.FindMember("widget");
if (itr1 != d.MemberEnd()) {
const Value& widget = itr1->value;
if (widget.IsObject()) {
Value::ConstMemberIterator itr2 = widget.FindMember("window");
if (itr2 != widget.MemberEnd()) {
const Value& window = itr2->value;
if (window.IsObject()) {
Value::ConstMemberIterator itr3 = window.FindMember("title");
if (itr3 != window.MemberEnd()) {
const Value& title = itr3->value;
if (title.IsString()) {
std::cout << title.GetString();
}
}
}
}
}
}
这坨代码也许是最快最直接的方式。但一般业务代码写成这样，可读性太低，也容易出错。
大家都可以写一些辅助函数来解决这个问题。而我选择了实现 RFC6901 ── JSON Pointer。先看看使用后的结果：
#include "rapidjson/pointer.h"
// ...
if (const Value* title = GetValueByPointer(d, "/widget/window/title")) {
if (title->IsString()) {
std::cout << title->GetString();
}
}
这个版本简单得多吧，"/widget/window/title" 是一个 JSON Pointer 的字符串形式，然后 GetValueByPointer() 在 d 上解引用，如果失败就返回空指针。
在逻辑上是和上面的冗长版本是一模一样的，只是增加了一些解析 JSON Pointer 的运行时间及空间成本。对大多数人来说，应该更会接受这个版本。
有时候，业务逻辑还会是这样的：「如果键不存在，就使用缺省值。」RapidJSON 的 JSON Pointer 也提供此功能：
Value& title = GetValueByPointerWithDefault(
d, "/widget/window/title", "untitled");
当解引用失败时，它会创建整个路径，并把预设值复制成新值，并返回该值。由于它总能返回一个值，此函数的返回类型为引用而不是指针。
在此也简单介绍一下 JSON Pointer 的语法。它以 ‘/’ 分隔多个 token，而每个 token 可以是 JSON object 的键，也可以是 JSON array 的下标。还有一种特殊 token 是负号 -，它可以指 JSON array 最后元素的下一个元素。使用这种特性能实现 PushBack() 的效果：
Document d;
CreateValueByPointer(d, "/a").SetArray();
for (int i = 1; i <= 4; i++)
SetValueByPointer(d, "/a/-", i);
// { a : [1, 2, 3, 4] }
使用 JSON Pointer 的另一优点在于，它本身也是一个字符串，可以放置在 JSON 或其他文本格式之中。那么，我们便有一个标准方式去引用 JSON 中的值。
希望 JSON Pointer 能减轻使用者的负担，同时也提供一种数据驱动的弹性。新功能 JSON Pointer 简单介绍至此，更多信息可参考 RapidJSON 使用手册：Pointer。
JSON Schema
上面我们也谈到一个问题，JSON 里的组织方式、类型可能和预期的不同，我们可能要写很多代码去校验一个 JSON 的格式是否乎合预期。特别是后台服务器可能接收到不正常的JSON，甚至是恶意编写的 JSON 以图攻击。
在 XML 的世界中，可使用 XML DTD 或 XML Schema 去描述 XML 的结构。在 JSON 的世界中，已经有相关草案，称为 JSON Schema。
RapidJSON 实现了 JSON Schema v4 draft，并正式纳入了 v1.1.0。先看看用法：
#include "rapidjson/schema.h"
// ...
Document sd;
if (!sd.Parse(schemaJson).HasParseError()) {
// 此 schema 不是合法的 JSON
}
SchemaDocument schema(sd); // 把一个 Document 编译至 SchemaDocument
// 之后不再需要 sd
Document d;
if (!d.Parse(inputJson).HasParseError()) {
// 输入不是一个合法的 JSON
}
SchemaValidator validator(schema);
if (!d.Accept(validator)) {
// 输入的 JSON 不合乎 schema
}
以我所知，现时所有 JSON Schema 实现都是校验一个 DOM 是否合乎 Schema。RapidJSON 做了一个创新的尝试，以事件流（SAX 风格）的方式去做校验。上面的例子利用 Document::Accept() 产生事件流，然后送交 SchemaValidator 校验。也许读者会问：「这也是在校验一个 DOM 是否合乎 Schema，有什么特别吗？」
这实际意味着，RapidJSON 的 JSON Schema 校验器除了可以校验 DOM，也可以校验更底层的 SAX。例如，我们可以用 SAX 解析 JSON 时，同时进行 JSON Schema 校验。如果中途不合乎 JSON Schema，就能直接中止解析。
SchemaValidator validator(schema);
Reader reader;
if (!reader.Parse(stream, validator)) {
if (!validator.IsValid()) {
// 输入的 JSON 不合乎 schema
}
}
也可以同时把事件转发至一个自定义 handler：
MyHandler handler;
GenericSchemaValidator<SchemaDocument, MyHandler> validator(schema, handler);
Reader reader;
if (!reader.Parse(stream, validator)) {
if (!validator.IsValid()) {
// 输入的 JSON 不合乎 schema
}
}
由于 DOM 解析 JSON 时，底层也是使用 SAX，所以也可以同时做 Schema 校验。其实除了解析，在生成时也可以进行校验，以确保输出的 JSON 也是乎合 Schema 的。这些用法都可参考 RapidJSON 使用手册：Schema。要学习 JSON Schema 的写法，笔者推荐 Understanding JSON Schema 这个英文网站。
C++11 范围 for 循环
此版本还加入了 Array 和 Object 辅助类型（包裹类），可分别通过 Value::GetArray()、Value::GetObject() 获取。这两个辅助类型提供该 JSON 类型专门的接口，例如 Array::PushBack()、Object::AddMember() 等。更重要的是，为了令 C++11 用户使用得更顺手，它们可做范围 for 循环（range-based for loop）：
// C++03
for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr)
printf("%d ", itr->GetInt());
// C++11
for (auto& v : a.GetArray())
printf("%d ", v.GetInt());
// C++03
for (Value::ConstMemberIterator itr = document.MemberBegin();
itr != document.MemberEnd(); ++itr)
{
printf("Type of member %s is %s\n",
itr->name.GetString(), kTypeNames[itr->value.GetType()]);
}
// C++11
for (auto& m : document.GetObject())
printf("Type of member %s is %s\n",
m.name.GetString(), kTypeNames[m.value.GetType()]);
其他相关详情可参阅 RapidJSON 使用手册：教程。
结语
这个 RapidJSON 版本对我而言是一个挑战。
JSON Schema 实际上也需要 JSON Pointer，所以 JSON Pointer 可算是一举两得的新功能。但实现 JSON Schema 时有两个难点。一个是 JSON Schema 需要正则引擎，在 C++11 下能直接使用 std::regex；而为了 C++03，我还实现了一个 500 行代码的 Thompson NFA 正则引擎。另一个难点在于，事件流的校验不容易实现 allOf、anyOf、oneOf、not 等关键字，需要多个校验器同时检验事件流。
新功能 JSON Schema 和 JSON Pointer 都是附加功能，完全不影响 v1.0.x 的 API。
除新功能外，此版本含有一个重要的内存优化。在 x86-64 架构下，64 位指针只使用到 48 位，我重新设计了 Value 的排布，使每个值的内存开销从 24 字节缩减至 16 字节。虽然存储指针时会有时间开销，但因大量缩减内存，更好的缓存一致性应该可以厘补损失，甚至能进一步提升整体性能。
屈指一算，RapidJSON 已快近 5 个年头了，最近一年我转部门后，更少机会在工作上使用 RapidJSON，所以我可能较少机会发现问题和新需求。虽然是这样，我仍然会继续维护这个项目，也要靠大家去发现问题和新需求，希望能得到大家的意见。
P.S. 可能大家会关心性能，我会尽快更新 nativejson-benchmark。
Milo Yip
RAPIDJSON