Tokamak CLI模块教程:让命令行工具与Web服务共享同一套依赖注入
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 });
}
发生了什么?
tk.app.run用多模块系统构建同一个依赖容器:App里的db、config被自动解析初始化tk.cli.run作为被调用函数,其参数(包括Cli模块里的cmds)全部由容器注入- 每条命令的 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。
与本教程相关的核心文件一览:
- CLI 模块源码:src/cli.zig
- 应用运行器(DI + 入口函数粘合层):src/app.zig
- 完整 CLI 示例:examples/hello_cli/src/main.zig
- Web 服务对照示例:examples/hello_app/src/main.zig
- 依赖注入指南:docs/guide/dependency-injection.md
🚀 总结:Tokamak CLI 模块的价值不在"多了一个 CLI 框架",而在于命令 handler 与 Web 路由 handler 使用同一套依赖注入协议。写迁移脚本、数据导入、备份工具时,把服务声明为函数参数即可,配置与服务生命周期由 DI 容器统一管理——这正是它让命令行工具与 Web 服务共享同一套依赖注入的方式。