Tokamak CLI模块教程:让命令行工具与Web服务共享同一套依赖注入

原创2026-11-09 17:47:411,956 阅读

Tokamak CLI模块教程:让命令行工具与Web服务共享同一套依赖注入

Tokamak 是一个基于 Zig 的 Web 框架,其 CLI 模块(tk.cli)最大的亮点是:命令行工具可以与你的 Web 服务共享同一套依赖注入容器。这意味着数据库连接、配置文件、HTTP 客户端等服务只需定义一次,Web 服务和 CLI 命令(如数据库迁移、数据导入导出、备份脚本)都能直接注入使用,无需重复初始化代码。本教程将带你快速上手 Tokamak CLI,掌握命令定义、参数解析与输出格式三大核心能力。

为什么需要 CLI 模块?

🤔 做过 Web 开发的读者都会遇到这样的场景:

  • 上线前要跑一次数据库迁移
  • 需要导入/导出一批数据
  • 定期执行备份、统计、清理等维护任务

传统做法是再写一个独立脚本,手动打开数据库、重新读取配置——结果服务里改了一处逻辑,脚本却忘了同步。

Tokamak CLI 的设计思路(见 src/cli.zig 头部注释)非常直接:它不是一个"又一个 CLI 框架",而是为现有 Web 应用提供配套的命令行工具。你只需把应用的 DI 模块原样传给 CLI 入口,任何服务都能以函数参数形式注入到命令里。

快速上手:三步创建你的第一条命令

第 1 步:安装 Tokamak

git clone https://gitcode.com/gh_mirrors/tokam/tokamak

然后在你的 build.zig 中引入:

const tokamak = @import("tokamak");
tokamak.setup(exe, .{});

第 2 步:定义命令

使用 tk.cli.Command 的工厂方法定义命令,cmd0 到 cmd3 分别对应 0~3 个参数(依赖不算参数):

const commands = &[_]tk.cli.Command{
    .usage,                        // 内置帮助命令
    .cmd0("version", "Show version", version),
    .cmd1("hello", "Greet someone", hello),
};

fn hello(arena: std.mem.Allocator, name: []const u8) ![]const u8 {
    return std.fmt.allocPrint(arena, "Hello, {s}!", .{name});
}

注意 hello 的参数:arena 是被注入的依赖,name 才是从命令行解析的参数。

第 3 步:启动 CLI

var injector = tk.Injector.init(&.{}, null);
try tk.cli.run(&injector, gpa.allocator(), commands);

运行效果:

$ myapp version
1.0.0

$ myapp hello World
Hello, World!

💡 小贴士:不带参数或命令名拼错时,Tokamak 会自动打印 usage 帮助信息,列出所有命令及其参数签名。

核心机制:Web 服务与 CLI 共享 DI 模块

这才是 Tokamak CLI 真正的威力所在。借助 Tokamak 的多模块系统(详见 docs/guide/dependency-injection.md),你只需要两个模块结构体:

// App 模块:Web 服务和 CLI 共享的服务
const App = struct {
    db: Database,
    config: Config,
};

// Cli 模块:仅 CLI 二进制使用的命令定义
const Cli = struct {
    cmds: []const tk.cli.Command = &.{
        .usage,
        .cmd0("migrate", "Run database migrations", migrate),
        .cmd1("find-user", "Find user by email", findUser),
    };
};

入口函数只需一行(原理见 src/app.zig):

pub fn main(init: std.process.Init) !void {
    try tk.app.run(init, tk.cli.run, &.{ App, Cli });
}

发生了什么?

  1. tk.app.run 用多模块系统构建同一个依赖容器:App 里的 db、config 被自动解析初始化
  2. tk.cli.run 作为被调用函数,其参数(包括 Cli 模块里的 cmds)全部由容器注入
  3. 每条命令的 handler 执行时,框架再从容器里取出它声明的依赖

完整的实战示例可以查看 examples/hello_cli/src/main.zig——它把 HTTP 客户端同时共享给 Web 路由和 scrape、grep 等 CLI 命令。

🎯 结果:migrate(db: *Database) 里的 db 与 Web 服务里注入的是同一个连接,配置、生命周期管理完全一致,零重复代码。

参数解析:类型安全,无需手写转换

Tokamak CLI 的另一个省心之处:参数类型直接写在函数签名里,框架自动完成字符串到类型的转换。

以 hello_cli 示例中的命令为例:

.cmd1("gh", "List GitHub repos", gh_repos),
.cmd2("scrape", "Scrape a URL with optional CSS selector", scrape),

fn scrape(http_client: *tk.http.Client, arena: std.mem.Allocator,
          url: []const u8, qs: ?[]const u8) ![]const u8 { ... }

参数解析规则(实现见 src/parse.zig):

类型 示例输入 说明
u32 / i32 / f32 42 / -3 / 3.14 整数与浮点数
bool true 布尔值
enum 标签 json 枚举成员名
?T 可选类型 缺省或 null 命令尾部的可选参数可以省略
[]const u8 切片 a,b,c 逗号分隔转成数组
自定义类型 — 若类型声明了 T.parse 函数则优先使用

⚠️ 约定:handler 的前段参数是注入的依赖,后段参数是命令行参数,框架按位置区分。少传必填参数会返回 MissingArg 错误并打印用法。

输出格式:一键切换 YAML 与 JSON

CLI 命令的返回值会被自动序列化输出,这让命令天然适合管道串联:

  • 字符串:原样打印
  • 结构体/数组:默认输出 YAML
$ myapp find-user john@example.com
id: 123
name: John Doe
email: john@example.com

需要机器可读的 JSON?在命令名前加 --json(YAML 可显式用 --yaml):

$ myapp --json find-user john@example.com
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

实现位于 src/cli.zig,序列化复用了 Tokamak 的 serde 模块,因此任何实现了 T.serialize 的类型都能直接作为命令返回值。命令执行失败时,错误信息也会按同样格式输出,方便 CI 脚本判断。

延伸阅读与相关文件

想深入了解更多终端工具(包括交互式 TUI 应用),官方文档有专门章节:docs/guide/terminal.md。

与本教程相关的核心文件一览:

🚀 总结:Tokamak CLI 模块的价值不在"多了一个 CLI 框架",而在于命令 handler 与 Web 路由 handler 使用同一套依赖注入协议。写迁移脚本、数据导入、备份工具时,把服务声明为函数参数即可,配置与服务生命周期由 DI 容器统一管理——这正是它让命令行工具与 Web 服务共享同一套依赖注入的方式。

登录后查看全文
tokamak