xpack 开源库使用指南：C++ 结构体与多格式数据的无缝转换

一款零依赖、仅头文件的 C++ 序列化神器，让 JSON/XML/YAML/BSON/MySQL/SQLite 转换如呼吸般自然。

一、xpack 是什么？

xpack 是一款轻量级 C++ 开源库，专为解决一个痛点而生：

C++ 结构体 ↔ JSON / XML / YAML / BSON / MySQL / SQLite 之间的双向转换。

它的设计哲学极其克制——仅包含头文件，无需编译任何库文件，把.h丢进项目就能用。支持 STL 容器、位域、继承、枚举、自定义编解码，几乎覆盖了数据序列化的所有主流场景。

• 📦 项目地址：https://gitcode.com/gh_mirrors/xp/xpack
• 📄 许可证：MIT

二、快速安装

2.1 安装系统依赖

根据你需要支持的格式，安装对应的第三方库：

Ubuntu/Debian 一键安装：

sudo apt-get install libbson-1.0 libmysqlclient-dev libsqlite3 yaml-cpp libxml2-dev

2.2 引入项目

git clone https://gitcode.com/gh_mirrors/xp/xpack.git

​​将xpack/目录下的头文件复制到你的项目中，或者直接#include "xpack/json.h"。

三、3 分钟上手：JSON 与结构体互转

3.1 定义结构体 + XPACK 宏

#include <iostream> #include "xpack/json.h" using namespace std; struct User { int id; string name; XPACK(O(id, name)); // O = 普通字段，无特殊 FLAG };

核心就一行：XPACK(O(id, name))。宏会自动生成编解码逻辑，零侵入。

3.2 结构体 → JSON（序列化）

User u{12345, "xpack"}; string json = xpack::json::encode(u); cout << json << endl; // 输出: {"id":12345,"name":"xpack"}

支持格式化输出，便于人工调试：

string json = xpack::json::encode(u, xpack::JSON_INDENT(4)); // 输出带 4 空格缩进的美观 JSON

3.3 JSON → 结构体（反序列化）

string data = R"({"id":12345,"name":"xpack"})"; User u; xpack::json::decode(data, u); cout << u.id << " " << u.name << endl; // 12345 xpack

四、高级特性：5 个隐藏大招

4.1 别名（A）：字段名与 Key 名不一致

JSON key 是class，但 C++ 关键字不能用？别名一招解决：

struct Config { int port; string class_; // C++ 关键字冲突 XPACK(O(port), A(class_, "class_name")); }; // 序列化结果: {"port":8080,"class_name":"server"}

4.2 位域（B）：节省带宽的利器

硬件寄存器、协议解析场景的神器：

struct Flags { unsigned int enable : 1; unsigned int mode : 3; XPACK(B(F(0), enable, mode)); // B = 位域处理 };

自动打包为紧凑二进制表示，传输效率拉满。

4.3 继承（I）：复用基类序列化逻辑

struct Base { string mail; XPACK(O(mail)); }; struct Derived : public Base { long uid; string name; XPACK(I(Base), O(uid, name)); // I = 继承支持 };

父类也要定义XPACK宏，子类用I()引入。

4.4 枚举（E）：智能枚举转换

enum Status { OK = 0, ERROR = 1, PENDING = 2 }; struct Task { string name; Status st; XPACK(O(name), E(F(0), st)); // E = 枚举处理 };

编译器支持 C++11 时，枚举也可直接放在O()中。

4.5 自定义编解码（C / xtype）：搞定第三方类型

以 Qt 的QDateTime为例：

namespace xpack { template<> struct Codec<QDateTime> { void encode(Encoder& e, const QDateTime& dt) { e.Value(dt.toString(Qt::ISODate).toStdString()); } void decode(const Decoder& d, QDateTime& dt) { dt = QDateTime::fromString(d.Value().GetString(), Qt::ISODate); } }; }

现在QDateTime可以直接参与序列化。

五、STL 容器全面支持

xpack 对主流 STL 容器开箱即用：

示例：

struct Data { vector<int> nums; map<string, string> tags; XPACK(O(nums, tags)); };

六、FLAG 系统速查表

XPACK宏的第一个字母决定行为：

七、多格式同时使用

同一个结构体，同时输出 JSON 和 XML：

#include "xpack/json.h" #include "xpack/xml.h" vector<int> vi = {1, 2, 3}; xpack::JsonWriter jw; xpack::XEncoder<xpack::JsonWriter> je(jw); je.ob(NULL).add("vv", vi).add("i", 10).add("s", "hello").oe(); xpack::XmlWriter xw; xpack::XEncoder<xpack::XmlWriter> xe(xw); xe.ob("root").add("vv", vi).add("i", 10).add("s", "hello").oe(); cout << je.String() << endl; // JSON 输出 cout << xe.String() << endl; // XML 输出

八、性能对比（10 万次序列化基准测试）

Protobuf 为二进制格式，与 JSON 不具直接可比性，仅作参考。

结论：xpack 在保持接近二进制协议性能的同时，提供了文本格式的可读性，特别适合需要人工调试的数据交互场景。

九、错误处理

解码时务必包裹try-catch：

try { xpack::json::decode(data, u); } catch (const exception& e) { cout << "解析失败: " << e.what() << endl; }

十、典型应用场景

十一、快速总结

一句话总结：如果你的 C++ 项目需要和任何数据格式打交道，xpack 是目前最优雅的零成本方案。没有之一。