1. 项目概述为什么我们需要一个C JSON库在C的世界里处理JSON数据一直是个“甜蜜的烦恼”。JSON作为一种轻量级的数据交换格式几乎成了现代前后端通信、配置文件、日志存储的通用语。然而C标准库直到C17才姗姗来迟地引入了std::variant和std::optional等工具为构建一个优雅的JSON库提供了部分基础但一个完整的、符合直觉的JSON库仍然需要我们自己动手。我之所以投入时间构建这个“CJson项目”核心驱动力源于实际开发中的痛点。无论是从网络API接收数据还是解析复杂的配置文件亦或是需要将内存中的结构化数据序列化后持久化你都会发现一个好用、高效、类型安全的JSON库能极大提升开发效率和代码质量。市面上的库如nlohmann/json固然优秀但有时我们需要的不仅仅是“能用”而是“透彻理解”。自己动手实现一遍从null、boolean、number、string、array到object这六种基本类型的封装到递归解析、内存管理、移动语义优化这整个过程是对C现代特性如RAII、模板、移动语义、异常安全一次绝佳的实战演练。它不仅仅是一个工具库更是一个深入理解C核心机制的练功房。这个项目笔记就是记录我从零开始构建一个简易但功能完整的JSON解析器与序列化器的全过程。目标读者是那些已经掌握C基础希望深入理解数据序列化、内存管理并渴望通过一个综合性项目来巩固技能的开发者。通过这篇笔记你不仅能获得一个可用的JSON库代码更重要的是你将理解每一个设计决策背后的“为什么”以及在实际编码中如何规避那些教科书上不会写的“坑”。2. 核心设计思路与架构选型2.1 数据模型设计用std::variant承载多态JSON数据的核心是它的值这个值可能是六种类型之一。在C中传统的做法可能是设计一个基类JsonValue然后派生出JsonNumber、JsonString等子类。这种方式可行但会引入虚函数开销和复杂的内存管理需要手动new/delete或使用智能指针。现代C提供了更优雅的解决方案std::variant。它可以安全地存储一组指定类型中的某一个就像一个类型安全的联合体union。这正是我们需要的。#include variant #include string #include vector #include unordered_map #include optional namespace my_json { // 前向声明因为JsonValue中需要包含JsonArray和JsonObject struct JsonValue; using JsonNull std::monostate; // 表示null类型 using JsonBool bool; using JsonNumber double; // JSON标准不区分整型和浮点这里用double涵盖 using JsonString std::string; using JsonArray std::vectorJsonValue; using JsonObject std::unordered_mapstd::string, JsonValue; // 核心数据容器 struct JsonValue { std::variantJsonNull, JsonBool, JsonNumber, JsonString, JsonArray, JsonObject value; // 构造函数们方便创建各种类型的JsonValue JsonValue() : value(JsonNull{}) {} JsonValue(bool b) : value(b) {} JsonValue(double d) : value(d) {} JsonValue(int i) : value(static_castdouble(i)) {} // 方便整数初始化 JsonValue(const char* s) : value(std::string(s)) {} JsonValue(const std::string s) : value(s) {} JsonValue(const JsonArray arr) : value(arr) {} JsonValue(const JsonObject obj) : value(obj) {} // 移动构造版本... }; }为什么选择std::variant类型安全编译器能确保我们访问的是当前实际存储的类型如果访问错误类型会抛出std::bad_variant_access异常我们可以用std::holds_alternative或std::get_if来安全检查。值语义JsonValue对象可以像普通值一样被拷贝、移动存储在容器里管理起来非常直观符合C“资源获取即初始化”RAII的理念。零开销抽象在大多数情况下std::variant的内存布局和手写的联合体加类型标签类似没有虚函数表指针的开销。与标准库算法兼容因为它是一个普通的结构体可以轻松用在各种STL容器和算法中。注意使用std::variant需要C17或更高标准。这是现代C项目的一个合理基线。如果你的环境必须使用C11/14那么可能需要回退到基于继承和std::unique_ptr的方案但这会复杂得多。2.2 解析器设计手写递归下降 vs. 第三方库解析Parsing是将JSON格式的字符串如{name: Alice, age: 30}转换为我们内存中JsonValue对象树的过程。这里有两个主流选择使用现成的解析器生成器如ANTLR或者手写一个递归下降解析器。对于学习项目和轻量级库我强烈推荐手写递归下降解析器。原因如下控制力强你可以完全控制错误处理、内存分配和解析细节。依赖少项目不引入庞大的第三方库更轻便。学习价值高编写解析器是理解编译原理中词法分析、语法分析的绝佳入门实践。递归下降解析器的核心是将解析过程分解为一系列相互递归调用的函数每个函数对应JSON语法中的一个非终结符如parse_value,parse_object,parse_array,parse_string。基本工作流程词法分析Lexing虽然我们可以边解析边识别字符但先做一个简单的词法分析器Tokenizer会让逻辑更清晰。它负责将输入字符串分解成一个个有意义的“词法单元”Token如{、}、:、“name”、30、true、null等。语法分析Parsing解析器消费这些Token根据JSON的语法规则递归地构建出JsonValue树。class JsonParser { public: explicit JsonParser(const std::string jsonText) : m_input(jsonText), m_index(0) {} JsonValue parse() { skipWhitespace(); return parseValue(); } private: std::string m_input; size_t m_index; // 辅助函数查看当前字符跳过空白等 char peek() const { return m_index m_input.size() ? m_input[m_index] : \0; } char advance() { return m_input[m_index]; } void skipWhitespace(); // 核心解析函数 JsonValue parseValue(); JsonValue parseNull(); JsonValue parseBool(); JsonValue parseNumber(); JsonValue parseString(); JsonValue parseArray(); JsonValue parseObject(); };2.3 序列化器设计递归遍历与字符串构建序列化Serialization是解析的逆过程将内存中的JsonValue对象树转换回符合JSON标准的字符串。这个过程相对直接核心是一个深度优先的递归遍历。我们需要为每种类型实现其字符串表示null-nullboolean-true或falsenumber- 直接使用std::to_string但要注意浮点数的精度和格式避免输出像1.200000这样的形式可以考虑使用std::ostringstream并设置精度。string- 需要处理转义字符如、\、\n、\t等输出时要在两侧加上双引号。array- 输出为[elem1, elem2, ...]递归序列化每个元素。object- 输出为{key1: value1, key2: value2, ...}递归序列化每个键值对。性能考量在序列化时频繁的字符串拼接operator会产生大量临时对象影响性能。一个常见的优化是使用std::ostringstream来累积结果或者预先估算所需字符串长度使用reserve预留空间。class JsonSerializer { public: static std::string serialize(const JsonValue val, bool pretty false, int indentLevel 0) { std::ostringstream oss; serializeValue(oss, val, pretty, indentLevel); return oss.str(); } private: static void serializeValue(std::ostringstream oss, const JsonValue val, bool pretty, int indent); static void serializeString(std::ostringstream oss, const std::string str); // ... 其他类型的序列化函数 };3. 关键实现细节与避坑指南3.1 内存管理与移动语义我们的JsonValue使用了STL容器std::string,std::vector,std::unordered_map它们都管理着自己的内存。因此JsonValue的默认拷贝构造函数、移动构造函数、析构函数和赋值运算符通常由编译器自动生成并且是正确的遵循“零规则”。但是我们需要显式提供移动构造函数和移动赋值运算符来优化性能特别是在解析大型JSON或进行赋值操作时。struct JsonValue { std::variant... value; // 移动构造函数 JsonValue(JsonValue other) noexcept : value(std::move(other.value)) { // 移动后将other置于一个有效但明确的状态例如null other.value JsonNull{}; } // 移动赋值运算符 JsonValue operator(JsonValue other) noexcept { if (this ! other) { value std::move(other.value); other.value JsonNull{}; } return *this; } // 拷贝构造和拷贝赋值使用编译器生成的即可 };避坑点确保noexcept。移动操作通常不应该抛出异常标记为noexcept有助于标准库容器如std::vector在重新分配内存时使用移动而非拷贝从而提升性能。3.2 数字解析的精度与边界问题JSON数字的解析看似简单std::stod实则暗藏玄机。整数溢出JSON数字没有范围限制但C的double有。虽然double范围很大但对于极端大的整数可能会丢失精度。一个健壮的解析器应该考虑使用std::stoll先尝试解析为long long如果失败或超出范围再回退到std::stod。对于我们的学习项目直接用std::stod通常可以接受但心里要明白这个限制。非数字NaN和无穷大InfinityJSON标准不支持NaN和Infinity。但std::stod在解析类似“NaN”的字符串时会生成NaN值。我们需要在解析阶段就检测并拒绝这类字符串或者在后期的序列化阶段进行特殊处理但最好在解析时就报错遵循标准。本地化问题std::stod依赖于当前C环境的区域设置locale。在某些区域设置下小数点可能是逗号,。JSON标准明确规定小数点必须是点.。因此在解析前最好将C和C的locale都设置为“C”经典 locale以确保解析行为一致。JsonValue parseNumber() { size_t startPos m_index; // 消耗数字字符0-9, -, , ., e, E while (std::isdigit(peek()) || peek() . || peek() e || peek() E || peek() || peek() - || (m_index startPos (peek() - || peek() ))) { advance(); } std::string numStr m_input.substr(startPos, m_index - startPos); try { // 临时切换locale以确保解析正确 // 注意实际项目中应使用更鲁棒的方法如自定义字符遍历转换 char* endPtr; double val std::strtod(numStr.c_str(), endPtr); if (endPtr numStr.c_str() numStr.length()) { return JsonValue(val); } else { throw JsonParseError(Invalid number format); } } catch (const std::exception) { throw JsonParseError(Invalid number: numStr); } }3.3 字符串处理与Unicode转义JSON字符串必须处理转义序列。这在解析和序列化时都是必须的。需要处理的转义字符\-\\-\\/-/(虽然JSON允许但通常不必要)\b- 退格\f- 换页\n- 换行\r- 回车\t- 制表符\uXXXX- Unicode码点需要解码为UTF-8字符这是最复杂的部分。Unicode转义\uXXXX的实现要点\u后跟4个十六进制数字例如\u4F60表示汉字“你”。需要将这4个十六进制数字转换为一个16位的Unicode码点code point。对于基本多文种平面BMP U0000 到 UFFFF的字符这个码点可以直接转换为1-3个字节的UTF-8序列。对于辅助平面如表情符号JSON使用代理对Surrogate Pair\uD83D\uDE00两个\u转义表示一个码点U1F600。你需要检测到高位代理0xD800-0xDBFF和紧随其后的低位代理0xDC00-0xDFFF然后将它们组合计算得到真实的码点0x10000 (high - 0xD800) * 0x400 (low - 0xDC00)再将其编码为4字节的UTF-8。std::string decodeUnicodeEscape() { // 假设已经读到了 \u advance(); // 跳过 u if (m_index 4 m_input.size()) throw JsonParseError(Incomplete Unicode escape); std::string hex m_input.substr(m_index, 4); m_index 4; unsigned int codePoint; try { codePoint std::stoul(hex, nullptr, 16); } catch (...) { throw JsonParseError(Invalid Unicode escape: \\u hex); } // 处理代理对 if (codePoint 0xD800 codePoint 0xDBFF) { // 高位代理 if (peek() ! \\ || (m_index m_input.size() - 1 m_input[m_index 1] ! u)) { throw JsonParseError(Missing low surrogate in Unicode surrogate pair); } advance(); // 跳过 \ advance(); // 跳过 u std::string lowHex m_input.substr(m_index, 4); m_index 4; unsigned int lowSurrogate std::stoul(lowHex, nullptr, 16); if (lowSurrogate 0xDC00 || lowSurrogate 0xDFFF) { throw JsonParseError(Invalid low surrogate in Unicode surrogate pair); } codePoint 0x10000 ((codePoint - 0xD800) 10) (lowSurrogate - 0xDC00); } else if (codePoint 0xDC00 codePoint 0xDFFF) { // 单独出现的低位代理是错误 throw JsonParseError(Lone low surrogate in Unicode escape); } // 将codePoint编码为UTF-8字节序列 return codePointToUtf8(codePoint); }实操心得Unicode处理是JSON解析中最容易出错的部分之一。在项目初期可以暂时只支持\uXXXX表示BMP字符忽略代理对这能覆盖绝大多数用例。等核心功能稳定后再回来完善代理对的支持。测试时务必使用包含非ASCII字符尤其是中文、emoji的JSON字符串。3.4 错误处理与异常安全一个健壮的库必须有清晰的错误处理机制。对于解析错误如格式错误、未预期的字符、未终止的字符串抛出异常是最直接的方式。我们可以定义自己的异常类class JsonException : public std::runtime_error { public: using std::runtime_error::runtime_error; }; class JsonParseError : public JsonException { public: explicit JsonParseError(const std::string msg, size_t pos std::string::npos) : JsonException(msg (pos ! std::string::npos ? at position std::to_string(pos) : )) {} };在解析函数中一旦检测到错误立即抛出JsonParseError并尽可能附上出错的位置信息m_index这对调试至关重要。异常安全要确保即使在解析中途抛出异常也不会造成资源泄漏如内存泄漏。由于我们大量使用RAII对象std::string,std::vector等它们会在栈展开时自动清理所以基本保证了强异常安全。唯一需要小心的是在parseObject或parseArray中如果向容器insert或push_back失败可能抛出std::bad_alloc已经插入的元素会被容器的析构函数正确清理。4. 完整实现流程与核心代码解析4.1 词法分析器Tokenizer实现虽然可以边解析边识别但一个独立的词法分析器能让语法分析逻辑更干净。它负责将输入流切分成Token。enum class TokenType { BEGIN_OBJECT, // { END_OBJECT, // } BEGIN_ARRAY, // [ END_ARRAY, // ] COLON, // : COMMA, // , STRING, NUMBER, BOOLEAN, NULL_TOKEN, END_OF_INPUT }; struct Token { TokenType type; std::string value; // 对于STRING、NUMBER类型存储原始文本 size_t position; Token(TokenType t, size_t pos) : type(t), position(pos) {} Token(TokenType t, std::string val, size_t pos) : type(t), value(std::move(val)), position(pos) {} }; class Tokenizer { public: explicit Tokenizer(const std::string input) : m_input(input), m_index(0) {} Token nextToken(); private: std::string m_input; size_t m_index; void skipWhitespace(); Token parseStringToken(); Token parseNumberToken(); Token parseKeywordToken(); // 解析 true, false, null };nextToken()是主函数它跳过空白查看下一个字符然后分发给具体的解析函数。4.2 递归下降解析器核心逻辑有了Tokenizer解析器Parser的逻辑就清晰多了。class Parser { public: explicit Parser(const std::string jsonText) : m_tokenizer(jsonText), m_currentToken(TokenType::END_OF_INPUT, 0) { advance(); // 读取第一个token } JsonValue parse(); private: Tokenizer m_tokenizer; Token m_currentToken; void advance() { m_currentToken m_tokenizer.nextToken(); } void expect(TokenType expected, const std::string msg); JsonValue parseValue(); JsonValue parseObject(); JsonValue parseArray(); JsonValue parseString(); // 从STRING token构造JsonString JsonValue parseNumber(); // 从NUMBER token构造JsonNumber JsonValue parseBoolean(); JsonValue parseNull(); }; JsonValue Parser::parseValue() { switch (m_currentToken.type) { case TokenType::BEGIN_OBJECT: return parseObject(); case TokenType::BEGIN_ARRAY: return parseArray(); case TokenType::STRING: return parseString(); case TokenType::NUMBER: return parseNumber(); case TokenType::BOOLEAN: return parseBoolean(); case TokenType::NULL_TOKEN: return parseNull(); default: throw JsonParseError(Unexpected token at start of value, m_currentToken.position); } } JsonValue Parser::parseObject() { expect(TokenType::BEGIN_OBJECT, Expected {); JsonObject obj; advance(); // 跳过 { skipWhitespaceIfNeeded(); if (m_currentToken.type ! TokenType::END_OBJECT) { while (true) { // 1. 解析key (必须是STRING token) if (m_currentToken.type ! TokenType::STRING) { throw JsonParseError(Expected string key in object, m_currentToken.position); } std::string key m_currentToken.value; advance(); // 2. 解析冒号 expect(TokenType::COLON, Expected : after object key); advance(); // 3. 解析value JsonValue val parseValue(); obj.emplace(std::move(key), std::move(val)); // 4. 解析逗号或结束符 if (m_currentToken.type TokenType::COMMA) { advance(); skipWhitespaceIfNeeded(); // 检查尾随逗号JSON标准不允许 { a:1, } if (m_currentToken.type TokenType::END_OBJECT) { throw JsonParseError(Trailing comma in object, m_currentToken.position); } continue; } else if (m_currentToken.type TokenType::END_OBJECT) { break; } else { throw JsonParseError(Expected , or } in object, m_currentToken.position); } } } expect(TokenType::END_OBJECT, Expected }); advance(); // 跳过 } return JsonValue(std::move(obj)); }parseArray的实现与parseObject类似只是键变成了数组索引。4.3 用户友好API设计底层解析和序列化实现后我们需要提供一个简洁的API给用户。namespace my_json { class Json { public: // 静态解析函数 static Json parse(const std::string jsonText); static Json parseFile(const std::string filePath); // 构造工厂函数 static Json object(); static Json array(); static Json null(); // ... 其他 // 数据访问 (类型安全) bool isNull() const; bool isBool() const; bool isNumber() const; bool isString() const; bool isArray() const; bool isObject() const; // 值获取 (带类型检查失败抛异常或返回std::optional) bool asBool() const; double asDouble() const; int asInt() const; // 注意精度丢失 const std::string asString() const; const JsonArray asArray() const; const JsonObject asObject() const; // 操作API (针对Object和Array) // 对于Object bool contains(const std::string key) const; Json operator[](const std::string key); // 非const版本用于修改/添加 const Json operator[](const std::string key) const; // const版本用于访问 Json at(const std::string key); // 带边界检查 // 对于Array Json operator[](size_t index); const Json operator[](size_t index) const; void push_back(const Json value); void push_back(Json value); size_t size() const; // 序列化 std::string serialize(bool prettyPrint false) const; void serializeToFile(const std::string filePath, bool prettyPrint false) const; private: JsonValue m_value; // 私有构造函数用户通过静态工厂或parse创建 Json(JsonValue val) : m_value(std::move(val)) {} }; }这样用户就可以用非常直观的方式操作JSON了auto config my_json::Json::parseFile(config.json); std::string name config[user][name].asString(); int port config[server][port].asInt(); my_json::Json response; response[status] 200; response[data][items] my_json::Json::array(); response[data][items].push_back(item1); std::string jsonStr response.serialize(true); // 漂亮打印5. 常见问题、调试技巧与性能优化5.1 解析阶段常见错误与排查“Unexpected token”错误这是最常见的错误。通常是因为JSON格式不正确比如缺少逗号、冒号或者字符串引号不匹配。排查在错误信息中输出出错的位置索引。可以写一个辅助函数打印出错位置附近的一小段文本并用^标记位置这样能快速定位。void printErrorContext(const std::string input, size_t pos) { size_t start (pos 20) ? pos - 20 : 0; size_t end std::min(pos 20, input.length()); std::cerr Context: ... input.substr(start, end - start) ... std::endl; std::cerr std::string(pos - start 9, ) ^ here std::endl; }内存访问越界在解析字符串或数字时m_index可能超过字符串长度。每次advance()或peek()前都要检查。技巧将peek()和advance()函数实现为内联函数并在其中加入边界断言assert(m_index m_input.size())在Debug模式下能快速发现问题。递归深度过大JSON可以嵌套如[[[[...]]]]递归下降解析器可能因递归太深导致栈溢出。优化对于特别深的嵌套可以考虑将递归改为显式栈迭代方式但这会大大增加代码复杂度。对于绝大多数实际JSON数据深度很少超过1000层递归是足够安全的。5.2 使用与API设计中的陷阱类型误用用户可能尝试将Json对象当作数组访问或反之。防御在asXxx()和operator[]中必须进行严格的类型检查。asXxx()可以在类型不匹配时抛出清晰的异常。operator[]对于Object如果键不存在是应该插入一个null值像std::unordered_map::operator[]一样还是应该抛出异常这需要根据设计哲学决定。我倾向于提供一个at()方法用于安全访问抛异常而operator[]用于已知存在或用于插入。浮点数精度丢失与比较JSON数字被解析为double。进行相等比较是危险的因为浮点数有精度误差。应避免直接比较或使用误差范围epsilon。建议在库的API层面不提供operator直接比较double或者提供一个带有误差容限的比较函数。5.3 性能优化考量解析性能避免拷贝在解析字符串时如果原输入字符串生命周期足够长可以考虑使用std::string_view来避免复制子字符串。但这需要仔细管理生命周期。SIMD加速在跳过空白字符、扫描字符串结尾等简单循环中可以使用SIMD指令如SSE、AVX进行加速。但这属于高级优化仅在对性能有极致要求时考虑。内存池频繁创建小的JsonValue对象尤其在解析大型数组时可能导致堆碎片。可以考虑使用自定义分配器或内存池来批量分配。序列化性能预留空间在序列化前可以递归遍历整个JsonValue树估算出最终字符串的大致长度然后在std::string或std::ostringstream中预留reserve空间减少多次重新分配。直接写入流提供直接序列化到std::ostream的接口避免在内存中生成完整的字符串对于网络传输或写入大文件很有用。访问模式优化缓存哈希值如果JsonObject使用std::unordered_map键std::string的哈希计算在频繁访问时可能成为瓶颈。如果键是固定的如配置文件可以在解析后计算并缓存哈希值但这增加了复杂性。最后的建议在项目初期优先追求正确性、清晰度和完整的特性。性能优化应该在有了可靠的基准测试Benchmark证明瓶颈所在之后再进行。一个正确但稍慢的库远比一个快但充满Bug的库更有价值。你可以使用像google-benchmark这样的库来对比你的实现和nlohmann/json在解析特定文件时的速度找到真正的热点。