如何把Ziggy文档反序列化为Zig结构体:Deserializer API完整教程
如何把Ziggy文档反序列化为Zig结构体:Deserializer API完整教程
Ziggy 是一款面向 API 消息、配置文件等场景的数据序列化语言。本教程围绕 Ziggy 的 Deserializer API,手把手教你把一份 Ziggy 文档反序列化为 Zig 结构体,从 30 秒上手的完整示例,到选项配置、错误处理和自定义行为,一篇讲透。
一、Ziggy 文档长什么样?先认识一下
在写代码之前,先花 10 秒钟认识 Ziggy 文档(Ziggy Document)的两种常见写法,它们都能直接映射到 Zig 的 struct:
// 无大括号写法:字段名带一个前导点
.foo = "bar",
.bar = false,
// 大括号写法:类似 JSON 的字典
{
"foo": "bar",
"bar": false,
}
反序列化(deserialize) 就是把上面这种文本文档转换成内存中的 Zig 值,例如 struct { foo: []const u8, bar: bool }。Ziggy 的特色在于:不需要先构建 AST,解析和类型转换一步完成,性能更好,错误位置信息依然完整。
📖 项目简介见 README.md,核心入口在 src/root.zig,
deserialize和deserializeLeaky两个便捷函数就在这里导出。
二、一键获取源码:准备工作
Ziggy 是一个纯 Zig 库,克隆仓库即可作为依赖使用:
git clone https://gitcode.com/gh_mirrors/zig/ziggy
在你的项目中把它声明为模块后,就可以这样引入:
const ziggy = @import("ziggy");
这样就能直接访问 ziggy.deserialize、ziggy.deserializeLeaky 等 API。
三、最快上手:30 秒完成一次反序列化
下面是最小可用示例:把一份 Ziggy 文档解析进一个 Zig 结构体。
const std = @import("std");
const ziggy = @import("ziggy");
const Config = struct {
foo: []const u8,
bar: bool,
};
pub fn main() !void {
const doc =
\\.foo = "bar",
\\.bar = false,
;
var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
defer arena.deinit();
var meta: ziggy.Deserializer.Meta = .init;
const config = try ziggy.deserializeLeaky(
Config, // 目标 Zig 类型
arena.allocator(), // 分配器
doc, // Ziggy 文档字符串([:0]const u8)
&meta, // 错误元信息
.{}, // 选项,空 = 全部默认
);
std.debug.print("foo={s} bar={any}\n", .{ config.foo, config.bar });
}
输出:foo=bar bar=false。🎉
几个要点:
- 目标类型
T在编译期已知,字段名必须与文档字段一一对应; src是[:0]const u8(带终止符的切片),文件读取结果通常天然满足;- 文档支持注释(
//开头),会被自动忽略; - 除了 struct,Ziggy 还支持整数、浮点(含
inf/nan)、布尔、null、可选类型?T、enum、union(.date("...")这种联合分支写法)、数组<a href="https://link.gitcode.com/i/440304b7179d6867ac303dd94efc2719" target="_blank">1, 2, 3]等,完整行为可见 [src/Deserializer.zig 中的deserializeOne。
官方测试里的最小示例对(文档 + 类型)可以直接参考:
- 文档:tests/ziggy/type-driven/errors/struct.ziggy
- 类型:tests/ziggy/type-driven/errors/struct.zig
- 完整调用流程:tests/type_driven.zig
四、API 详解:deserialize 与 deserializeLeaky 怎么选?
两个函数参数完全相同,区别只在内存管理方式,这是新手最容易困惑的地方。
| 函数 | 返回值 | 内存管理 | 适用场景 |
|---|---|---|---|
deserializeLeaky |
直接返回 T |
调用者自行释放 | 长驻程序、传入 arena 分配器 |
deserialize |
返回 Value(T) |
内置 arena,调用 deinit() 一次释放全部 |
短生命周期、不想手动追踪内存 |
deserializeLeaky:名字里的 "Leaky" 提示你——由于类型可能含默认值,正确释放并不容易,所以官方建议长驻程序直接传 arena 分配器,统一回收。定义见 src/Deserializer.zig。deserialize:把返回值和 arena 打包成Value(T),用完调用deinit()即可,取数据用.value。定义见 src/Deserializer.zig。
// 用非 Leaky 版本的完整生命周期
var result = try ziggy.deserialize(Config, gpa, doc, &meta, .{});
// ... 使用 result.value.foo ...
result.deinit(); // 一次性释放所有内部分配
四个实用选项(Options)速查
Options 结构体(src/Deserializer.zig)目前有两个选项,都支持 .{} 省略:
| 选项 | 默认值 | 作用 |
|---|---|---|
copy_strings |
.to_unescape |
字符串拷贝策略。.always 表示总是拷贝;.to_unescape 只在字符串含转义序列时拷贝,无转义的 const 字符串直接指向原文,零拷贝、更快,但要求 src 的生命周期长于解析结果 |
delimiter |
.none |
支持解析嵌入在其他文件中的 Ziggy 文档(如 SuperMD/HTML),取值为 Tokenizer.Delimiter,可指定 dashes(Markdown frontmatter)或 backticks(代码块)作为结束定界符,成功后 meta.doc 会记录文档长度和行数 |
五、错误处理:reportErrors 与常见错误速查表
⚠️ 这是 Deserializer API 的精髓:deserializeLeaky 不构建 AST,因此它的错误不应直接展示给用户。官方推荐的两步流程是:
- 构建 AST,先把语法级解析错误报给用户;
- AST 无解析错误时,再报告 Deserializer 返回的语义级错误。
官方已把这个流程封装成便捷函数 Meta.reportErrors 及其格式化版本 reportErrorsFmt,一行代码就能生成带行列号和高亮下划线的报错,例如(真实快照见 missing_field_snap.txt):
missing_field.ziggy:2:1 missing field 'bar'
| .foo = "bar",
Meta 结构体(src/Deserializer.zig)在失败时还会填充 error_loc(错误位置)和 missing_field_name(缺失字段名)。
常见错误类型一览
完整错误集定义在 src/Deserializer.zig:
| 错误 | 含义 | 触发示例 |
|---|---|---|
MissingField |
文档缺少某必填字段 | 文档里没有 .bar |
UnknownField |
文档出现了 struct 中不存在的字段 | 文档多了 .baz = 1 |
DuplicateField |
同一字段出现两次 | .foo 写了两遍 |
UnexpectedToken / UnexpectedValue |
位置或值不符合预期 | 该是 = 的地方出现了其他 token |
Overflow |
整数溢出 | u8 字段收到 300 |
InvalidEscapeSequence |
字节串含非法转义序列 | 由解析器自动检测 |
OutOfMemory |
分配失败 | 需手动处理 |
每个错误都附带精确的行列位置,这对调试配置文件类场景非常友好。💡 更多报错样例可浏览 tests/ziggy/type-driven/errors/ 目录下的 *_snap.txt 快照文件。
六、进阶:用 ziggy_options 自定义反序列化行为
当 Zig 容器类型(struct/union/enum)内部定义了一个名为 ziggy_options 的公开声明,类型就可以定制 (de)serialize 行为。可用项见 root.zig:
| 选项 | 作用 |
|---|---|
skip_fields |
列出这些字段后,反序列化时直接忽略(deserialize 为 null 时它们必须有默认值) |
loc_field |
把该 struct 在文档中的源码位置写入指定字段(需同时列入 skip_fields,类型为 Tokenizer.Token.Loc) |
deserialize |
完全接管某个类型的解析逻辑,函数内可通过 d.deserializeOne 复用默认行为 |
serialize / roles |
序列化侧的对应定制项 |
典型用途:字段改名兼容、给错误信息带上来源位置、包装第三方类型等。自定义解析函数中还能调用 d.unexpected、d.duplicateField、d.missingField 等辅助函数(src/Deserializer.zig)来正确记录错误位置。
七、小结:核心知识点回顾
✅ 三步走:定义与文档字段对应的 struct → 调用 ziggy.deserialize(省心)或 ziggy.deserializeLeaky(高性能)→ 出错时用 Meta.reportErrorsFmt 报告。
✅ 零 AST 开销:直接 token 流驱动的类型转换,字符串默认零拷贝。
✅ 完整错误位置:8 类语义错误全部带行列号,报错质量高。
✅ 可定制:ziggy_options 让你在不 fork 源码的情况下改变解析行为。
延伸阅读
- 序列化(反向操作):src/Serializer.zig
- AST 与格式渲染:src/Ast.zig
- Ziggy Schema 校验体系:src/schema.zig 与 src/schema/
- 类型驱动测试入口:tests/type_driven.zig
- 动态类型(解析任意文档):src/dynamic.zig
掌握以上内容,你就可以在配置加载、API 消息解析等场景中自由使用 Ziggy Deserializer API 了。🚀