AI 时代的利器 CLI 工具编写指南

在 AI 时代，命令行工具（CLI）正在经历一场复古潮流的复兴。为什么？因为 CLI 工具对 AI Agent 天然友好！

与图形界面相比，CLI 工具具有结构化的输入输出、清晰的帮助文档、可预测的行为模式——这些特性使 AI Agent 能够更容易地理解、学习和自动化使用 CLI 工具。

但你是否曾为编写一个功能完善的 CLI 工具而烦恼：

• 命令参数解析繁琐？
• 配置管理混乱？
• 帮助文档难以维护？
• 想要插件扩展却无从下手？

---

💡 在此之前，先介绍一下 jzero 模板市场

jzero 提供了丰富的官方模板和第三方模板，帮助你快速构建各种类型的项目：

🚀 内置模板：

• RPC 模板：基于 Protocol Buffers 的高性能 gRPC 微服务框架
• API 模板：基于 API 描述语言的轻量级 RESTful API 服务框架
• Gateway 模板：高性能 API 网关，同时支持 gRPC 和 HTTP 协议

📦 官方外置模板：

• CLI 模板：具有常见 CLI 模式的命令行应用程序模板（今天的主角！）
• API 模板：专为 Vercel 部署优化的 API 模板
• 文档模板：使用 VuePress Hope 主题的文档站点模板

🌍 第三方模板：

• 欢迎贡献你自己的模板，帮助更多开发者快速启动项目！

访问 jzero 模板市场 了解更多模板信息和使用指南。

---

今天，我们将介绍如何使用 jzero CLI 模板快速构建专业的命令行工具！

---

为什么选择 jzero CLI 模板？

jzero CLI 模板基于业界成熟的 Cobra 框架，提供了开箱即用的项目结构和最佳实践配置。相比从零开始搭建，使用 jzero CLI 模板能够：

✅ 快速启动：一键生成完整项目结构，无需繁琐配置
✅ 规范统一：遵循行业标准，命令结构清晰易懂
✅ 功能完备：内置配置管理、插件系统、调试模式等企业级特性
✅ 易于扩展：插件化架构，轻松添加新功能
✅ AI 友好：与 Claude、GPT 等 AI 工具完美配合，提升开发效率

---

快速开始：1 分钟创建你的第一个 CLI 工具

# 1. 安装 jzero（如果尚未安装）
go install github.com/jzero-io/jzero/cmd/jzero@latest

# 2. 创建新的 CLI 项目
jzero new mycli --branch cli

cd mycli

# 3. 安装依赖并构建
go mod tidy
go build

# 4. 测试运行
./mycli version

输出示例：

mycli version 1.0.0 darwin/amd64
Go version go1.21.0
Git commit abc123
Build date 2024-01-01 12:00:00 +0000 UTC

就这么简单！你已经拥有了一个功能完整的 CLI 工具框架。

---

核心概念：命令系统的三层结构

jzero CLI 模板基于 Cobra 框架，采用清晰的三层命令结构：

Root Command（根命令）
├── Command（命令）
│   └── Sub Command（子命令）

1. Root Command（根命令）

根命令是 CLI 工具的入口点，定义了工具的基本信息、全局配置和顶层命令。

// main.go
var rootCmd = &cobra.Command{
    Use:   "mycli",
    Short: "我的 CLI 工具",
    Long:  `一个功能强大的命令行工具，帮助你提高工作效率`,
}

根命令的特性：

• ✅ 定义全局标志（如 --debug、--config）
• ✅ 注册顶层命令
• ✅ 提供工具的整体帮助信息

2. Command（命令）

命令是根命令下的直接子命令，代表主要的功能模块。

mycli version      # 版本命令 - 显示版本信息
mycli config       # 配置命令 - 管理配置
mycli plugin       # 插件命令 - 管理插件
mycli server       # 服务器命令 - 启动服务

命令的特点：

• ✅ 直接挂载在根命令下
• ✅ 可以有独立的标志和参数
• ✅ 可以包含子命令，形成命令树

3. Sub Command（子命令）

子命令是命令的下一级，用于实现更细分的功能。

# 配置命令的子命令
mycli config init      # 初始化配置
mycli config set       # 设置配置项
mycli config get       # 获取配置项
mycli config list      # 列出所有配置

# 插件命令的子命令
mycli plugin install   # 安装插件
mycli plugin remove    # 卸载插件
mycli plugin list      # 列出插件
mycli plugin update    # 更新插件

子命令的优势：

• ✅ 功能模块化，逻辑清晰
• ✅ 支持多层嵌套（如 mycli config database connect）
• ✅ 每个子命令可以独立开发和维护

命令示例对比

# Root Command
mycli                    # 执行根命令

# Command（一级命令）
mycli config             # 执行配置命令
mycli plugin             # 执行插件命令

# Sub Command（二级命令）
mycli config init        # 执行配置初始化子命令
mycli plugin install     # 执行插件安装子命令

# 更深层次的子命令（三级命令）
mycli server start       # 启动服务器
mycli server stop        # 停止服务器
mycli server status      # 查看服务器状态

标志（Flags）的类型

标志用于配置命令的行为，分为三种类型：

局部标志（Local Flags）- 仅对当前命令有效：

Cmd.Flags().StringP("output", "o", "", "输出文件")

持久化标志（Persistent Flags）- 对当前命令及其所有子命令有效：

rootCmd.PersistentFlags().BoolP("verbose", "v", false, "详细输出模式")

全局标志（Global Flags）- 对所有命令有效：

mycli --debug          # 启用调试模式
mycli --config file.yaml  # 指定配置文件

---

配置管理：灵活的多层次配置方案

jzero CLI 模板提供了强大的配置管理系统，支持三种配置方式的灵活组合：

配置优先级

环境变量 > 命令行标志 > 配置文件

1. 配置文件（~/.YOUR_APP.yaml）

默认配置文件位置：~/.mycli.yaml

# 调试模式
debug: false

# 调试睡眠时间（秒）
debug-sleep-time: 0

# 自定义配置
database:
  host: localhost
  port: 5432
  name: mydb

2. 环境变量配置

jzero CLI 模板支持两种环境变量使用方式：

方式1：在 .mycli.env.yaml 中定义环境变量

# .mycli.env.yaml
# 这些环境变量会被设置到系统环境中
DATABASE_URL: postgres://localhost:5432/mydb
LOG_LEVEL: debug
API_KEY: sk-xxxxx

在主配置文件中引用：

# ~/.mycli.yaml
database:
  url: ${DATABASE_URL}          # 使用环境变量
  log:
    level: ${LOG_LEVEL}         # 使用环境变量

api:
  key: ${API_KEY}               # 使用环境变量

方式2：直接使用环境变量（自动映射）

jzero CLI 模板会自动将环境变量映射到配置字段，无需手动设置：

# 直接设置环境变量，自动映射到配置
export MYCLI_DEBUG=true
export MYCLI_DEBUG_SLEEP_TIME=5
export MYCLI_GREET_NAME="张三"

环境变量命名规则：

格式：{APP_PREFIX}_{CONFIG_PATH}

• {APP_PREFIX}：应用名前缀（大写），如 MYCLI、JZERO
• {CONFIG_PATH}：配置路径，. 和 - 替换为 _

映射示例：

配置字段	环境变量
config.C.Debug	MYCLI_DEBUG
config.C.DebugSleepTime	MYCLI_DEBUG_SLEEP_TIME
config.C.Greet.Name	MYCLI_GREET_NAME
config.C.Database.Host	MYCLI_DATABASE_HOST

3. 命令行标志

# 通过命令行覆盖配置
./mycli --debug
./mycli --config custom.yaml
./mycli --database.url postgres://localhost/mydb

---

统一配置管理：使用 internal/config/config.go

jzero CLI 模板的核心优势之一是统一的配置管理系统。所有配置都通过 internal/config/config.go 进行管理，确保配置的一致性和可维护性。

定义配置结构

在 internal/config/config.go 中定义配置：

package config

// C 全局配置变量（直接访问，不需要函数）
var C Config

type Config struct {
    // 根命令的持久化标志
    Debug bool `mapstructure:"debug"`
    DebugSleepTime int `mapstructure:"debug-sleep-time"`
    
    // 在这里添加你的自定义配置字段
    // Database DatabaseConfig `mapstructure:"database"`
    // Server   ServerConfig   `mapstructure:"server"`
}

// 配置初始化由 jzero 模板自动处理
// InitConfig() 函数会自动读取配置文件、环境变量和命令行标志

关键字段说明：

• mapstructure 标签：映射配置文件中的字段名
• 全局变量 C：直接访问配置，不需要调用函数
• 配置初始化：由模板自动处理，无需手动编写

配置优先级

jzero CLI 模板遵循以下配置优先级（从高到低）：

环境变量 > 命令行标志 > 配置文件

配置使用示例

1. 使用配置文件 (~/.mycli.yaml)

# ~/.mycli.yaml
debug: false
debug-sleep-time: 0

2. 使用环境变量文件 (.mycli.env.yaml)

# .mycli.env.yaml
MYCLI_DEBUG: "true"
MYCLI_DEBUG_SLEEP_TIME: "5"

3. 使用命令行标志

./mycli --debug
./mycli --debug-sleep-time 10

4. 组合使用（优先级示例）

# 配置文件设置 debug=false
# 环境变量设置 MYCLI_DEBUG=true
# 命令行不设置

# 结果：debug=true（环境变量优先级最高）

在命令中使用配置

jzero CLI 模板使用全局变量 config.C 来访问配置：

// internal/command/example/example.go
package example

import (
	"fmt"
	"mycli/internal/config"
	"github.com/spf13/cobra"
)

var Cmd = &cobra.Command{
	Use:   "example",
	Short: "示例命令",
	Run: func(cmd *cobra.Command, args []string) {
		// 直接使用全局配置变量
		if config.C.Debug {
			fmt.Printf("调试模式已启用\n")
			fmt.Printf("调试睡眠时间: %d 秒\n", config.C.DebugSleepTime)
		}
		
		// 你的业务逻辑...
	},
}

// 如果需要命令特定的标志，在 init() 中添加
func init() {
	// 命令特定的标志会自动绑定到 config.C
	// 例如：Cmd.Flags().String("output", "", "输出文件")
}

添加自定义配置字段

在 Config 结构体中添加字段，支持嵌套结构：

type Config struct {
    Debug bool `mapstructure:"debug"`
    DebugSleepTime int `mapstructure:"debug-sleep-time"`

    // 添加自定义配置
    Database DatabaseConfig `mapstructure:"database"`
    Server   ServerConfig   `mapstructure:"server"`
}

然后在配置文件中对应使用：

# ~/.mycli.yaml
debug: false
database:
  host: localhost
  port: 5432
server:
  host: 0.0.0.0
  port: 8080

统一配置的优势

✅ 自动优先级处理：Viper 自动处理配置优先级
✅ 类型安全：使用 Go 结构体和 mapstructure 标签
✅ 环境变量支持：自动将环境变量映射到配置字段
✅ 灵活扩展：添加新配置字段非常简单
✅ 全局访问：通过 config.C 全局变量在任何地方访问
✅ 命令特定配置：支持为不同命令设置独立配置

---

添加自定义命令：三步即可完成

第一步：在配置中添加字段（如需要）

如果命令需要配置，在 internal/config/config.go 中添加嵌套结构：

type Config struct {
    Debug bool `mapstructure:"debug"`
    DebugSleepTime int `mapstructure:"debug-sleep-time"`

    // 添加 greet 命令的配置
    Greet GreetConfig `mapstructure:"greet"`
}

type GreetConfig struct {
    Name string `mapstructure:"name"`
}

第二步：创建命令文件

在 internal/command/ 下创建新目录和命令文件：

// internal/command/greet/greet.go
package greet

import (
    "fmt"
    "mycli/internal/config"
    "github.com/spf13/cobra"
)

var Cmd = &cobra.Command{
    Use:   "greet",
    Short: "问候命令",
    Long:  `向用户发送友好的问候`,
    Run: func(cmd *cobra.Command, args []string) {
        // 从统一配置获取名字（映射到 greet.name）
        name := config.C.Greet.Name
        if name == "" {
            name = "世界"
        }
        fmt.Printf("你好，%s！\n", name)
    },
}

func init() {
    // 添加标志，会自动绑定到 config.C.Greet.Name
    Cmd.Flags().StringP("name", "n", "", "指定问候对象的名字")
}

第三步：注册命令

在 main.go 中导入并注册命令：

import (
    "mycli/internal/command/greet"
    // 其他导入...
)

func init() {
    rootCmd.AddCommand(greet.Cmd)
}

第三步：测试使用

go build

# 方式1：使用默认值
./mycli greet
# 输出：你好，世界！

# 方式2：使用命令行标志
./mycli greet --name 张三
# 输出：你好，张三！

# 方式3：使用配置文件
echo "greet:" >> ~/.mycli.yaml
echo "  name: 李四" >> ~/.mycli.yaml
./mycli greet
# 输出：你好，李四！

# 方式4：使用环境变量
export MYCLI_GREET_NAME="王五"
./mycli greet
# 输出：你好，王五！

---

调试模式：开发者的好帮手

jzero CLI 模板内置了完善的调试支持：

启用调试的三种方式

方式一：配置文件

# ~/.mycli.yaml
debug: true
debug-sleep-time: 5  # 调试睡眠时间（秒）

方式二：环境变量

export MYCLI_DEBUG=true
./mycli

方式三：命令行标志

./mycli --debug
./mycli --debug --debug-sleep-time 5

调试功能特性

• 详细日志输出：显示详细的执行过程和中间状态
• 睡眠时间控制：在关键步骤间暂停，方便观察
• 错误堆栈追踪：清晰的错误信息和调用栈

---

插件系统：无限扩展可能

jzero CLI 模板支持强大的插件系统，让你的工具能够动态扩展功能。

插件命名规则

插件可执行文件以 YOUR_APP- 为前缀，例如：

• mycli-git
• mycli-docker
• mycli-deploy

插件自动发现

系统会自动从 PATH 中搜索以 mycli- 开头的可执行文件。

插件使用示例

# 安装插件到 PATH
sudo cp mycli-git /usr/local/bin/

# 直接使用插件
./mycli git status
./mycli docker build
./mycli deploy production

多级命令命名

插件支持多级命令结构：

# 插件文件：mycli-k8s-pod
./mycli k8s pod list

# 插件文件：mycli-k8s-service
./mycli k8s service list

---

构建版本信息：专业的发布流程

在构建时注入版本信息，让你的工具更加专业：

go build \
  -ldflags="-X 'main.version=1.0.0' \
            -X 'main.commit=$(git rev-parse HEAD)' \
            -X 'main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)'" \
  -o mycli

构建后的版本信息示例：

mycli version 1.0.0 darwin/amd64
Go version go1.21.0
Git commit 8f7a3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8
Build date 2024-01-15T08:30:00Z

---

项目结构：清晰的代码组织

jzero CLI 模板提供了清晰的项目结构：

mycli/
├── main.go                    # 入口文件
├── internal/
│   ├── command/              # 命令实现
│   │   ├── version/          # 版本命令
│   │   │   └── version.go
│   │   └── greet/            # 自定义命令
│   │       └── greet.go
│   └── config/               # 配置管理
│       └── config.go
├── go.mod
└── go.sum

这种结构清晰分离了不同功能的代码，便于维护和扩展。

---

相关资源

• jzero GitHub: https://github.com/jzero-io/jzero
• jzero 文档: https://docs.jzero.io
• CLI 模板: https://templates.jzero.io/external/cli/
• Cobra 文档: https://github.com/spf13/cobra
• Viper 文档: https://github.com/spf13/viper

---

让 jzero CLI 模板成为你 AI 时代的得力助手！ 🚀

觉得有用？请给 jzero 一个 ⭐ Star，支持我们继续改进！