zig-best-practices

Zig 最佳实践

遵循 CLAUDE.md 中的类型优先、函数式和错误处理模式。本技能仅涵盖 Zig 特有的惯用法。

类型系统模式

用带标签联合表示互斥状态——防止出现包含多个可空字段的结构体所允许的无效组合：

const RequestState = union(enum) {
    idle,
    loading,
    success: []const u8,
    failure: anyerror,
};

显式错误集——准确说明可能发生的错误；anyerror 会隐藏错误类型：

const ParseError = error{ InvalidSyntax, UnexpectedToken, EndOfInput };
fn parse(input: []const u8) ParseError!Ast { ... }

为领域 ID 定义独立类型——编译器可防止混淆不同的 ID 类型：

const UserId = enum(u64) { _ };
const OrderId = enum(u64) { _ };

编译时验证——在编译时而非运行时捕获无效配置：

fn Buffer(comptime size: usize) type {
    if (size == 0) @compileError("buffer size must be greater than 0");
    return struct { data: [size]u8 = undefined, len: usize = 0 };
}

内存管理

• 将分配器显式传递给每个进行分配的函数；不要使用全局分配器状态。
• 获取资源后立即放置 defer resource.deinit()——让清理代码与创建代码位于同一处。
• 错误路径上使用 errdefer 清理；无条件清理使用 defer。
• 批量或临时工作使用 arena 分配器；它们会一次性释放所有内容。
• 在测试中使用 std.testing.allocator——它会通过堆栈跟踪报告内存泄漏。

fn createResource(allocator: std.mem.Allocator) !*Resource {
    const resource = try allocator.create(Resource);
    errdefer allocator.destroy(resource);  // runs only on error
    resource.* = try initializeResource();
    return resource;
}

主要约定

• 优先使用 const 而非 var；优先使用切片而非裸指针。
• 优先使用 comptime T: type 而非 anytype；显式类型能产生更清晰的错误。仅在确实需要多态的情况下（如回调、std.debug.print 风格）使用 anytype。
• switch 必须穷尽：对于确实不可能发生的情况，添加返回错误或 unreachable 的 else 分支。
• 使用 std.log.scoped(.module_name) 进行命名空间日志记录；定义模块级 const log 常量。
• 较大的整体性文件符合惯用风格——测试与实现并列，comptime 泛型位于文件作用域。

高级主题

• 泛型容器（队列、栈、树）：参见 GENERICS.md
• C 库互操作（raylib、SDL、curl）：参见 C-INTEROP.md
• 调试内存泄漏（GPA、堆栈跟踪）：参见 DEBUGGING.md

工具

zigdoc——浏览标准库和依赖项文档：

zigdoc std.mem.Allocator   # std lib symbol
zigdoc vaxis.Window        # project dependency
zigdoc @init               # create AGENTS.md with API patterns

ziglint——使用 .ziglint.zon 配置进行静态分析：

ziglint                    # lint current directory
ziglint --ignore Z001      # suppress specific rule

参考资料

• 语言参考：https://ziglang.org/documentation/0.15.2/
• 标准库：https://ziglang.org/documentation/0.15.2/std/
• Zig 指南：https://zig.guide/