编译期计算与元编程

Zig 的 comptime 让一部分代码在编译阶段执行，从而把类型生成、约束检查、代码选择和预计算提前完成。它不是宏系统或 DSL，而是用普通 Zig 代码参与编译阶段的计算与决策——编译期检查和运行时逻辑共享同一套表达方式，泛型和普通函数风格一致。本章聚焦于 comptime 的机制——语法、内建函数、能力边界。泛型设计模式将在泛型编程中展开。

编译期和运行时：核心区分

只有编译期已知的值和类型信息才能参与 comptime 计算。类型参数、常量、结构体字段信息属于编译期已知；用户输入、文件内容、网络请求则属于运行时。

comptime 参数

这是最基础也最常用的机制——函数参数标记为 comptime，调用者必须在编译期提供值。

const std = @import("std");

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

pub fn main() void {
    const a = max(i32, 10, 20);
    const b = max(f64, 3.14, 2.72);

    std.debug.print("int max: {}\n", .{a});
    std.debug.print("float max: {d}\n", .{b});
}

要点：

• T 必须在编译期已知，不能由运行时值决定
• 编译器会为每个不同的 T 生成一份特化实现
• 这就是 Zig 泛型的底层机制——详见泛型编程

comptime 参数不限于 type，也可以是整数、枚举等编译期值：

const std = @import("std");

fn repeat(comptime n: u32, value: u8) [n]u8 {
    return [_]u8{value} ** n;
}

pub fn main() void {
    const buf = repeat(5, 'A');
    std.debug.print("{s}\n", .{&buf}); // AAAAA
}

inline fn vs comptime 参数

两者都涉及“编译器在调用处展开代码“，容易混淆。但 inline 只是生成优化建议，不会把参数变成编译期值——comptime 参数才真正约束调用者必须在编译期提供值。

inline 不等于编译期——它只是建议编译器在调用处展开函数体，不会让参数变成编译期值。

comptime T: type vs anytype

两者都能让函数接受不同类型，但机制不同：

const std = @import("std");

// comptime T: type — 类型有名，可反射
fn printTypeInfo(comptime T: type) void {
    std.debug.print("size of {} = {}\n", .{ T, @sizeOf(T) });
}

// anytype — 适合"我只是把值转发出去"的场景
fn double(x: anytype) @TypeOf(x) {
    return x + x;
}

pub fn main() void {
    printTypeInfo(i32);                          // size of i32 = 4
    std.debug.print("{d}\n", .{double(21)});     // 42
}

anytype 的本质是“推迟类型推导“——编译器在调用处根据实参类型生成一份特化函数，但函数体内无法直接引用这个类型。如果需要在函数体内做类型判断、构造该类型的值、或者返回该类型的指针，comptime T: type 更合适。

comptime 块

comptime { } 块用于显式写出“一段代码必须在编译期执行“。典型用法是在类型定义中写编译期检查：

const std = @import("std");

const Block = struct {
    data: [block_size]u8 = undefined,

    const block_size = 4096;

    comptime {
        // 编译期断言：block_size 必须是 2 的幂
        std.debug.assert(block_size > 0 and (block_size & (block_size - 1)) == 0);
    }
};

pub fn main() void {
    var b: Block = .{};
    b.data[0] = 42;
    std.debug.print("first byte: {}\n", .{b.data[0]});
}

如果断言不成立，错误会在编译阶段直接暴露出来。

comptime var

comptime 参数和 comptime 块处理的都是编译期已知的固定值。但如果编译期计算需要循环累积中间结果，就需要一个能在编译期被修改的变量——这正是 comptime var 的设计意图：声明一个只存在于编译期的可变变量。

const std = @import("std");

fn fibonacci(comptime n: u32) u32 {
    comptime var a: u32 = 0;
    comptime var b: u32 = 1;
    inline for (0..n) |_| {
        const tmp = a + b;
        a = b;
        b = tmp;
    }
    return a;
}

test "fibonacci at comptime" {
    // fibonacci(10) == 55，编译期计算完毕
    try std.testing.expectEqual(55, comptime fibonacci(10));
}

comptime var 只能在编译期执行的代码中修改——包括 comptime 函数体、comptime 块和 inline for / inline while 循环体。普通运行时 for 不能修改 comptime var，因为运行时代码执行时编译期变量已不存在。inline for 之所以可以，是因为它在编译期展开：每次迭代生成一份独立的编译期语句，所有语句都在编译期执行完毕后才进入运行时。

@typeInfo 与 @compileError

@typeInfo 返回一个类型的结构化描述，可以在编译期根据类型信息做分支决策：

const std = @import("std");

fn zeroValue(comptime T: type) T {
    return switch (@typeInfo(T)) {
        .int => 0,
        .float => 0.0,
        .bool => false,
        else => @compileError("unsupported type for zeroValue"),
    };
}

test "zeroValue" {
    try std.testing.expectEqual(@as(i32, 0), zeroValue(i32));
    try std.testing.expectEqual(@as(f64, 0.0), zeroValue(f64));
    try std.testing.expectEqual(false, zeroValue(bool));
}

读取结构体字段信息：

const std = @import("std");

fn fieldCount(comptime T: type) usize {
    return switch (@typeInfo(T)) {
        .@"struct" => |info| info.fields.len,
        else => @compileError("expected struct type"),
    };
}

const User = struct {
    id: u32,
    name: []const u8,
    active: bool,
};

test "fieldCount" {
    try std.testing.expectEqual(3, fieldCount(User));
}

.@"struct" => |info| 捕获的 info 是一个 std.builtin.Type.Struct，包含：

• fields — []const StructField，每个字段含 name（名称）、type（类型）、default_value_ptr（默认值指针）、is_comptime、alignment
• decls — []const Declaration，类型内部的声明（函数、常量）
• layout — ContainerLayout，结构体布局方式（.auto / @"packed"）
• is_tuple — 是否为元组（匿名结构体）

这组信息使得编译期代码可以遍历字段、按名称查找、根据字段类型做条件分支，是系列化、配置映射和代码生成的基础。inline for 一节将展示如何遍历 fields。

@compileError 在 @typeInfo 的 else 分支中用于阻止不支持的用法，也可单独用于类型前置校验：

const std = @import("std");

fn safeDiv(comptime T: type, a: T, b: T) T {
    switch (@typeInfo(T)) {
        .int => {},
        .float => {},
        else => @compileError("safeDiv only supports integer and float types"),
    }
    if (b == 0) return 0;
    return a / b;
}

test "safeDiv" {
    try std.testing.expectEqual(@as(i32, 3), safeDiv(i32, 10, 3));
    try std.testing.expectEqual(@as(f64, 2.5), safeDiv(f64, 5.0, 2.0));
    try std.testing.expectEqual(@as(i32, 0), safeDiv(i32, 10, 0));
}

inline for：编译期循环展开

inline for 在编译期展开循环，每次迭代的捕获值都是编译期已知的，可在循环体内做编译期类型推导：

const std = @import("std");

fn printFieldNames(comptime T: type) void {
    const fields = @typeInfo(T).@"struct".fields;
    inline for (fields) |field| {
        std.debug.print("{s}\n", .{field.name});
    }
}

const Config = struct { host: []const u8, port: u16, debug: bool };

pub fn main() void {
    printFieldNames(Config);
}

输出：host / port / debug

@hasDecl 与 @hasField：编译期鸭子类型

const std = @import("std");

fn canSerialize(comptime T: type) bool {
    return @hasDecl(T, "serialize");
}
fn hasNameField(comptime T: type) bool {
    return @hasField(T, "name");
}

const S = struct {
    data: u32,
    pub fn serialize(_: @This()) []const u8 { return "ok"; }
};
const P = struct { name: []const u8, value: u32 };

test "@hasDecl and @hasField" {
    try std.testing.expect(canSerialize(S));
    try std.testing.expect(!canSerialize(P));
    try std.testing.expect(hasNameField(P));
    try std.testing.expect(!hasNameField(S));
}

@hasDecl 检查命名空间声明，@hasField 检查数据字段。详见泛型编程。

@embedFile：编译期嵌入文件

@embedFile 在编译期将文件内容嵌入为 *const [N:0]u8 字节数组常量：

// const version = @embedFile("data/version.txt");
// 返回 *const [N:0]u8，NUL 结尾

典型场景：嵌入配置文件、模板、shader 源码、静态资源、版本号或构建信息。

类型构造内建函数

从 @typeInfo 结果构造类型的能力由一组专用内建函数提供：

这些内建函数与 @typeInfo 形成拆解—组装的对应关系：@typeInfo 把一个类型拆成结构化信息（std.builtin.Type 标签联合的某个 variant），内建函数把这些信息重新组装成类型。例如 @typeInfo(i32) 返回 .int = .{ .signedness = .signed, .bits = 32 }，@Int(.signed, 32) 则用同样的信息构造出 i32。下面的 DoubleWidth 就是这个模式的最好示范——读出、修改、重建。

根据需求选择最小整数类型：

fn SmallestUint(comptime max_val: comptime_int) type {
    if (max_val < (1 << 8)) return u8;
    if (max_val < (1 << 16)) return u16;
    if (max_val < (1 << 32)) return u32;
    return u64;
}

使用 @Int 构造精确位宽：

fn DoubleWidth(comptime T: type) type {
    const info = @typeInfo(T).int;
    return @Int(info.signedness, info.bits * 2);
}

@Struct 可在编译期重建结构体：

// 5 个参数：layout, backing_integer, 字段名数组, 类型数组, 默认值属性数组
const MyStruct = @Struct(
    .auto,                    // layout
    null,                     // backing_integer（packed 时使用）
    &.{ "x", "y" },          // field names
    &.{ u8, u8 },            // field types
    &.{                      // field default attributes
        .{ .@"comptime" = false, .@"align" = null, .default_value_ptr = null },
        .{ .@"comptime" = false, .@"align" = null, .default_value_ptr = null },
    },
);

编译期的硬性限制

comptime 能力强大，但有明确的边界：

const std = @import("std");

comptime {
    // 编译期可以做的：
    var x: u32 = 0;
    for (0..10) |i| {
        x += @as(u32, @intCast(i));
    }
    std.debug.assert(x == 45);

    // 编译期不能做的（取消注释会产生编译错误）：
    // _ = std.heap.page_allocator;     // 运行时分配器
    // _ = @import("std").Io.Dir.cwd(); // 编译期不能访问文件系统
}

本章小结

边界与常见陷阱

• 别把运行时问题硬塞进编译期——用户输入、文件、网络数据天然属于运行时。
• 编译期 ≠ 免费——编译期计算会增加编译时间，不要为省下微不足道的运行时开销而大幅拖慢编译。
• 先学稳基础再玩反射——推荐顺序：comptime 参数 → 编译期条件分支 → 类型构造 → @typeInfo 反射。跳过前面直接沉迷复杂反射，代码往往自己也看不清。

注意：如果需要运行时切换实现、类型擦除或 VTable，那更适合运行时抽象而非 comptime。完整对比见接口与设计模式章节。

相关阅读：泛型编程