xpack基础用法详解：XPACK宏与encode/decode手把手教学

xpack基础用法详解：XPACK宏与encode/decode手把手教学

【免费下载链接】xpackconvert json/xml/bson to c++ struct项目地址: https://gitcode.com/gh_mirrors/xp/xpack

一句话认识 xpack：它是一个纯头文件的 C++ 库，帮你轻松实现 JSON/XML/BSON 与 C++ 结构体之间的互相转换。本文围绕xpack 基础用法展开，手把手教你使用XPACK 宏绑定结构体字段，再通过encode/decode完成序列化与反序列化，让新手也能快速上手。无论你是做网络通信、配置文件解析，还是数据存储，这套C++ 序列化方案都能显著减少你的样板代码。

📦 xpack 是什么？C++ 程序员为什么需要它？

在 C++ 项目里，把结构体转成 JSON 或把 JSON 转回结构体，通常需要手写大量解析代码，字段一多就非常痛苦。xpack的出现正是为了解决这个痛点：

• ✅纯头文件，无需编译库文件、无需 Makefile，拷进去就能用
• ✅ 支持JSON / XML / YAML / BSON，还支持 MySQL、SQLite 数据源
• ✅ 只需在结构体末尾加一行XPACK 宏，即可自动生成编解码逻辑
• ✅ 容器友好：vector、list、set、map、shared_ptr开箱即用

核心源码入口不多，看这几个文件就够了：入口头文件 json.h、宏定义核心 xpack.h，以及完整的官方文档 README.md。

🚀 快速上手：三分钟搭建你的第一个 xpack 项目

一键安装：纯头文件库的引入方法

xpack 无需安装，只要把整个项目目录放到你的工程中，并在源码里包含对应头文件即可：

#include "xpack/json.h" // 操作 JSON 包含它 #include "xpack/xml.h" // 操作 XML 则包含它

编译时加上头文件路径-I指向项目根目录即可，参考示例工程 example/makefile：

g++ -o demo demo.cpp -std=c++11 -I ../../xpack

最简示例：XPACK 宏与 encode/decode 的第一次亲密接触

下面这段代码就是 xpack 的全部核心，强烈建议亲手跑一遍：

#include <iostream> #include "xpack/json.h" using namespace std; struct User { int id; string name; XPACK(O(id, name)); // XPACK 宏绑定字段 }; int main() { User u; string data = "{\"id\":12345, \"name\":\"xpack\"}"; xpack::json::decode(data, u); // JSON -> 结构体 cout << u.id << ';' << u.name << endl; string json = xpack::json::encode(u); // 结构体 -> JSON cout << json << endl; return 0; }

输出结果一目了然：decode把字符串解析进结构体，encode再把它序列化回 JSON 字符串。完整可运行代码见 example/encoder.cpp。

🔧 XPACK 宏详解：结构体字段绑定的核心语法

XPACK 宏是 xpack 的灵魂。它的写法是XPACK(字母(字段...))，其中字母代表不同功能：

字母	含义	示例
O	普通字段，无特殊标记	XPACK(O(id, name))
X	带 FLAG 的字段	XPACK(X(F(OE), id))
M	必填字段（缺失抛异常）	XPACK(M(id))
A	别名，字段名与 key 不同	XPACK(A(uid, "id"))
B	位域字段	XPACK(B(F(0), ver, len))
I	继承的父类	XPACK(I(Base1, Base2))
E	枚举（非 C++11 环境）	XPACK(E(F(0), e))
C	自定义编解码	XPACK(C(mycodec, F(0), b))

O 与 X：最常用的两种写法

• O(a, b)等价于X(F(0), a, b)，表示字段无特殊 FLAG，日常最常用
• X(F(flag...), ...)适合需要给单个字段附加 FLAG 的场景

常用 FLAG 速查表

FLAG	作用
OE	encode 时值为 0/空串/false 则不输出该字段
EN	encode 时空值输出为null（仅 JSON）
M	decode 时字段缺失则抛异常，适合 id 等关键字段
ATTR	XML encode 时输出为属性（attribute）
SL	JSON encode 时数组字段单行输出

🔄 encode/decode 手把手进阶：从 JSON 到 XML 的通用玩法

玩法一：嵌套结构体与容器

xpack 支持结构体嵌套和标准容器，这是业务中最常见的需求：

struct Score { int math; int english; XPACK(O(math, english)); }; struct Student { string name; vector<int> scores; map<string, string> attrs; XPACK(O(name, scores, attrs)); };

vector、map、list、set、shared_ptr等都直接支持，无需额外配置。

玩法二：一行代码切换 XML

xpack 的接口设计高度统一，换格式只需换头文件和命名空间：

#include "xpack/xml.h" Student s; xpack::xml::decode(xmlStr, s); // XML -> 结构体 string xml = xpack::xml::encode(s); // 结构体 -> XML

同样地，BSON 支持见 bson.h，YAML 支持见 yaml.h。

玩法三：格式化输出，让人读的 JSON

默认encode输出无缩进，适合程序间传输；如果需要给人看，可以指定缩进参数：

// 参数：indentCount 缩进字符数，indentChar 缩进字符（空格/制表符） string json = xpack::json::encode(u, 0, 2, ' ');

玩法四：别名让字段名与 key 解耦

接口返回的字段名和结构体变量名不一致是常态，用A别名轻松解决：

struct Test { long uid; string name; XPACK(A(uid, "id"), O(name)); // 结构体 uid 对应 JSON 中的 "id" };

更进阶的用法（如json:_id类型级别名、XML 数组标签控制等）都收录在官方文档 README.md 的「别名」章节。

🧩 进阶特性速览：继承、枚举与自定义编解码

• 继承：用I(P1, P2)声明父类，父类同样需要 XPACK 宏，参考 example/inherit.cpp
• 枚举：C++11 下枚举可直接放进O/X/A；老编译器用E，参考 example/enum.cpp
• 自定义编解码：两种方式——类型级xtype（参考 example/xtype.cpp）和字段级C(...)（参考 example/custom.cpp），可实现时间格式化为字符串、union 处理等高级需求
• 不定类型：JSON schema 不确定时，用xpack::JsonData动态接收，参考 example/json-data.cpp

❓ 常见问题 FAQ

Q1：xpack 需要 C++11 吗？基础功能不强制，但shared_ptr、unordered_map等容器需要 C++11 支持；MSVC 建议使用 2019 及以上版本。

Q2：能处理第三方库的结构体吗？可以。用XPACK_OUT宏在全局命名空间声明即可，官方示例就是用它对struct timeval做的扩展，详见 README.md 的「第三方类和结构体」章节。

Q3：变量名有什么讲究？避免使用__x_pack开头的变量名，以免与库内部实现冲突。

🎯 总结

xpack 用极低的成本解决了 C++ 中最繁琐的结构化数据序列化问题：一行XPACK 宏完成字段绑定，encode/decode统一处理多格式转换。从今天的xpack 基础用法出发，你已经掌握了 90% 的日常场景，剩下的高级玩法都可以在 example 示例目录里找到答案。赶紧动手试一下吧！🚀

【免费下载链接】xpackconvert json/xml/bson to c++ struct项目地址: https://gitcode.com/gh_mirrors/xp/xpack