name: zig-best-practices description: 提供Zig语言中类型优先开发的模式，包括标签联合、显式错误集、编译时验证和内存管理。在读取或写入Zig文件时必须使用。

Zig 最佳实践

类型优先开发

类型在实现之前定义契约。遵循以下工作流程：

定义数据结构 - 首先定义结构体、联合体和错误集
定义函数签名 - 参数、返回类型和错误联合
实现以满足类型 - 让编译器指导完整性
在编译时验证 - 在编译期间捕获无效配置

使非法状态不可表示

使用Zig的类型系统在编译时防止无效状态。

标签联合用于互斥状态：

// 好：只允许有效组合
const RequestState = union(enum) {
    idle,
    loading,
    success: []const u8,
    failure: anyerror,
};

fn handleState(state: RequestState) void {
    switch (state) {
        .idle => {},
        .loading => showSpinner(),
        .success => |data| render(data),
        .failure => |err| showError(err),
    }
}

// 差：允许无效组合
const RequestState = struct {
    loading: bool,
    data: ?[]const u8,
    err: ?anyerror,
};

显式错误集用于故障模式：

// 好：准确记录可能失败的情况
const ParseError = error{
    InvalidSyntax,
    UnexpectedToken,
    EndOfInput,
};

fn parse(input: []const u8) ParseError!Ast {
    // 实现
}

// 差：anyerror隐藏故障模式
fn parse(input: []const u8) anyerror!Ast {
    // 实现
}

不同领域概念使用不同类别：

// 防止混淆不同类型的ID
const UserId = enum(u64) { _ };
const OrderId = enum(u64) { _ };

fn getUser(id: UserId) !User {
    // 编译器阻止在此处传递OrderId
}

fn createUserId(raw: u64) UserId {
    return @enumFromInt(raw);
}

编译时验证不变量：

fn Buffer(comptime size: usize) type {
    if (size == 0) {
        @compileError("缓冲区大小必须大于0");
    }
    if (size > 1024 * 1024) {
        @compileError("缓冲区大小超过1MB限制");
    }
    return struct {
        data: [size]u8 = undefined,
        len: usize = 0,
    };
}

非穷举枚举用于可扩展性：

// 可能获得变体的外部枚举
const Status = enum(u8) {
    active = 1,
    inactive = 2,
    pending = 3,
    _,
};

fn processStatus(status: Status) !void {
    switch (status) {
        .active => {},
        .inactive => {},
        .pending => {},
        _ => return error.UnknownStatus,
    }
}

模块结构

在Zig中，较大的内聚文件是惯用的。将相关代码放在一起：测试与实现一起，编译时泛型在文件作用域，公共/私有由pub控制。仅当文件处理真正独立的问题时才拆分。标准库通过像std/mem.zig这样的文件展示了这种模式，其中包含2000多行内聚的内存操作。

指令

使用错误联合（!T）返回带有上下文的错误；每个函数都返回一个值或一个错误。显式错误集记录故障模式。
在错误路径上使用errdefer进行清理；使用defer进行无条件清理。这可以防止资源泄漏，而无需try-finally样板。
处理switch语句中的所有分支；包括一个else子句，该子句返回错误或对真正不可能的情况使用unreachable。
将分配器显式传递给需要动态内存的函数；在测试中优先使用std.testing.allocator进行泄漏检测。
优先使用const而不是var；为了边界安全，优先使用切片而不是原始指针。不变性表示意图并启用优化。
避免anytype；优先使用显式的comptime T: type参数。显式类型记录意图并产生更清晰的错误消息。
使用std.log.scoped进行命名空间日志记录；定义模块级log常量以在整个文件中保持一致的命名空间。
为新逻辑添加或更新测试；使用std.testing.allocator自动捕获内存泄漏。

示例

未实现逻辑的显式失败：

fn buildWidget(widget_type: []const u8) !Widget {
    return error.NotImplemented;
}

使用try传播错误：

fn readConfig(path: []const u8) !Config {
    const file = try std.fs.cwd().openFile(path, .{});
    defer file.close();
    const contents = try file.readToEndAlloc(allocator, max_size);
    return parseConfig(contents);
}

使用errdefer进行资源清理：

fn createResource(allocator: std.mem.Allocator) !*Resource {
    const resource = try allocator.create(Resource);
    errdefer allocator.destroy(resource);

    resource.* = try initializeResource();
    return resource;
}

具有显式默认值的穷举switch：

fn processStatus(status: Status) ![]const u8 {
    return switch (status) {
        .active => "processing",
        .inactive => "skipped",
        _ => error.UnhandledStatus,
    };
}

具有内存泄漏检测的测试：

const std = @import("std");

test "widget creation" {
    const allocator = std.testing.allocator;
    var list: std.ArrayListUnmanaged(u32) = .empty;
    defer list.deinit(allocator);

    try list.append(allocator, 42);
    try std.testing.expectEqual(1, list.items.len);
}

内存管理

显式传递分配器；切勿使用全局状态进行分配。函数在参数中声明其分配需求。
获取资源后立即使用defer。将清理逻辑放在获取旁边以提高清晰度。
对于临时分配，优先使用竞技场分配器；当竞技场被销毁时，它们会一次性释放所有内容。
在测试中使用std.testing.allocator；它会报告泄漏，并显示分配来源的堆栈跟踪。

示例

分配器作为显式参数：

fn processData(allocator: std.mem.Allocator, input: []const u8) ![]u8 {
    const result = try allocator.alloc(u8, input.len * 2);
    errdefer allocator.free(result);

    // 将输入处理到结果中
    return result;
}

用于批处理操作的竞技场分配器：

fn processBatch(items: []const Item) !void {
    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
    defer arena.deinit();
    const allocator = arena.allocator();

    for (items) |item| {
        const processed = try processItem(allocator, item);
        try outputResult(processed);
    }
    // 当竞技场销毁时，所有分配都被释放
}

日志记录

使用std.log.scoped创建命名空间日志记录器；每个模块应定义自己的作用域日志记录器以进行过滤。
在文件顶部定义模块级const log；在整个模块中一致使用它。
使用适当的日志级别：err用于失败，warn用于可疑条件，info用于状态更改，debug用于跟踪。

示例

模块的作用域日志记录器：

const std = @import("std");
const log = std.log.scoped(.widgets);

pub fn createWidget(name: []const u8) !Widget {
    log.debug("创建小部件: {s}", .{name});
    const widget = try allocateWidget(name);
    log.debug("已创建小部件 id={d}", .{widget.id});
    return widget;
}

pub fn deleteWidget(id: u32) void {
    log.info("删除小部件 id={d}", .{id});
    // 清理
}

代码库中的多个作用域：

// 在 src/db.zig 中
const log = std.log.scoped(.db);

// 在 src/http.zig 中
const log = std.log.scoped(.http);

// 在 src/auth.zig 中
const log = std.log.scoped(.auth);

编译时模式

对泛型函数使用comptime参数；类型信息在编译时可用，运行时成本为零。
尽可能使用编译时验证而不是运行时检查。在编译期间捕获错误，而不是在生产中。
对应该导致构建失败的无效配置使用@compileError。

示例

具有编译时类型的泛型函数：

fn max(comptime T: type, a: T, b: T) T {
    return if (a > b) a else b;
}

编译时验证：

fn createBuffer(comptime size: usize) [size]u8 {
    if (size == 0) {
        @compileError("缓冲区大小必须大于0");
    }
    return [_]u8{0} ** size;
}

避免 anytype

优先使用comptime T: type而不是anytype；显式类型参数记录预期约束并产生更清晰的错误。
仅当函数真正接受任何类型（如std.debug.print）或用于回调/闭包时才使用anytype。
使用anytype时，添加描述预期接口或约束的文档注释。

示例

优先使用显式编译时类型（好）：

fn sum(comptime T: type, items: []const T) T {
    var total: T = 0;
    for (items) |item| {
        total += item;
    }
    return total;
}

当类型已知时避免anytype（差）：

// 不清楚哪些类型有效；错误消息会令人困惑
fn sum(items: anytype) @TypeOf(items[0]) {
    // ...
}

回调的可接受anytype：

/// 为每个项目调用`callback`。回调必须接受(T)并返回void。
fn forEach(comptime T: type, items: []const T, callback: anytype) void {
    for (items) |item| {
        callback(item);
    }
}

当anytype必要时使用@TypeOf：

fn debugPrint(value: anytype) void {
    const T = @TypeOf(value);
    if (@typeInfo(T) == .Pointer) {
        std.debug.print("ptr: {*}
", .{value});
    } else {
        std.debug.print("val: {}
", .{value});
    }
}

错误处理模式

为函数定义特定的错误集；尽可能避免anyerror。特定错误记录故障模式。
使用带有块的catch进行错误恢复或日志记录；仅当错误确实不可能时才使用catch unreachable。
当组合可能以不同方式失败的操作时，使用||合并错误集。

示例

特定错误集：

const ConfigError = error{
    FileNotFound,
    ParseError,
    InvalidFormat,
};

fn loadConfig(path: []const u8) ConfigError!Config {
    // 实现
}

带有catch块的错误处理：

const value = operation() catch |err| {
    std.log.err("操作失败: {}", .{err});
    return error.OperationFailed;
};

配置

在启动时从环境变量加载配置；在使用前验证所需值。缺少配置应导致带有描述性消息的干净退出。
将Config结构定义为单一事实来源；避免std.posix.getenv分散在整个代码中。
为开发使用合理的默认值；为生产机密要求显式值。

示例

类型化配置结构：

const std = @import("std");

pub const Config = struct {
    port: u16,
    database_url: []const u8,
    api_key: []const u8,
    env: []const u8,
};

pub fn loadConfig() !Config {
    const db_url = std.posix.getenv("DATABASE_URL") orelse
        return error.MissingDatabaseUrl;
    const api_key = std.posix.getenv("API_KEY") orelse
        return error.MissingApiKey;
    const port_str = std.posix.getenv("PORT") orelse "3000";
    const port = std.fmt.parseInt(u16, port_str, 10) catch
        return error.InvalidPort;

    return .{
        .port = port,
        .database_url = db_url,
        .api_key = api_key,
        .env = std.posix.getenv("ENV") orelse "development",
    };
}

可选类型

使用orelse为可选类型提供默认值；仅当null是程序错误时才使用.?。
优先使用if (optional) |value|模式进行安全解包并访问值。

示例

安全可选类型处理：

fn findWidget(id: u32) ?*Widget {
    // 查找实现
}

fn processWidget(id: u32) !void {
    const widget = findWidget(id) orelse return error.WidgetNotFound;
    try widget.process();
}

使用if解包的可选类型：

if (maybeValue) |value| {
    try processValue(value);
} else {
    std.log.warn("没有值存在", .{});
}

高级主题

参考以下指南以获取专门模式：

构建自定义容器（队列、堆栈、树）：参见GENERICS.md
与C库接口（raylib、SDL、curl、系统API）：参见C-INTEROP.md
调试内存泄漏（GPA、堆栈跟踪）：参见DEBUGGING.md

参考

语言参考：https://ziglang.org/documentation/0.15.2/
标准库：https://ziglang.org/documentation/0.15.2/std/
代码示例：https://ziglang.org/learn/samples/
Zig指南：https://zig.guide/