CLI 开发基础与标准库

CLI（Command Line Interface，命令行界面）是开发者最常打交道的工具形态。从 git、docker、kubectl 到 go 本身，几乎所有基础设施工具都提供 CLI。Go 语言因其编译产物是单文件二进制、跨平台、启动极快，成为编写 CLI 工具的首选语言。本篇将系统讲解如何使用 Go 标准库开发 CLI 工具，从 os.Args 到 flag 包，再到子命令模式与 Unix 哲学。

一、CLI 概述

CLI 是一种通过文本命令与程序交互的界面。用户在终端输入命令，程序读取参数、执行逻辑、输出结果。与 GUI 相比，CLI 有以下优势：

可自动化：命令可以写入脚本，批量执行，这是 GUI 难以做到的。
可组合：通过管道（pipe）将一个程序的输出作为另一个程序的输入，实现复杂功能。
资源占用低：无需渲染图形界面，启动快、内存占用少。
远程友好：通过 SSH 即可使用，适合服务器管理场景。

一个典型的 CLI 命令结构如下：

myapp --flag value subcommand --subflag value positional_args

其中包含三个核心部分：

组成部分	说明	示例
命令名	程序名称	`git`、`docker`
标志（Flag）	以 `-` 或 `--` 开头的可选参数	`--verbose`、`-f`
位置参数	不以 `-` 开头的参数	`file.txt`、`add`
子命令	命令下的子操作	`git commit`、`git push`

二、为什么 Go 适合写 CLI

在众多编程语言中，Go 在 CLI 开发领域占据重要地位。原因如下：

1. 编译为单文件二进制

Go 编译后生成一个独立的二进制文件，不依赖任何动态链接库（除 libc）。这意味着用户无需安装运行时环境（如 Python 的解释器、Node.js 的运行时、Java 的 JVM），下载一个文件即可使用。这对 CLI 工具的分发至关重要——用户不需要 pip install 或 npm install，直接下载二进制就能跑。

2. 跨平台编译

Go 原生支持交叉编译，只需设置 GOOS 和 GOARCH 环境变量，就能在一台机器上编译出 Windows、Linux、macOS、ARM 等多种平台的二进制文件。这在其他语言中往往需要复杂的 CI 配置或第三方工具。

3. 启动速度极快

Go 编译为原生机器码，启动时间在毫秒级。相比之下，Python CLI 工具启动需要加载解释器（通常 100ms+），JVM 启动更慢。对于频繁调用的 CLI 工具，启动速度直接影响用户体验。

4. 标准库强大

Go 标准库自带 flag、os、io、fmt、bufio 等包，无需任何第三方依赖就能写出功能完整的 CLI 工具。go 命令本身就是用 Go 标准库写的。

5. 生态成熟

Go 拥有 Cobra、Viper、Bubbletea 等顶级 CLI 生态库，从命令解析到配置管理到终端 UI 一应俱全。kubectl、docker、hugo、gh（GitHub CLI）等知名工具都用 Go 编写。

三、os.Args 基础

os.Args 是 Go 中获取命令行参数最原始的方式。它是一个字符串切片，os.Args[0] 是程序本身路径，os.Args[1:] 是用户传入的参数。

package main

import (
	"fmt"
	"os"
)

func main() {
	// os.Args[0] 是程序名，os.Args[1:] 是实际参数
	args := os.Args[1:]

	if len(args) == 0 {
		fmt.Println("用法: myapp <name>")
		fmt.Println("示例: myapp world")
		os.Exit(1)
	}

	for i, arg := range args {
		fmt.Printf("参数 %d: %s\n", i, arg)
	}
}

运行示例：

bash

$ go run main.go hello world
参数 0: hello
参数 1: world

os.Args 的优点是简单直接，没有任何抽象。但缺点也很明显：

需要手动解析 -flag、--flag、-flag=value 等不同格式。
不支持自动生成帮助信息。
不支持默认值。
不支持类型转换（所有参数都是 string）。

对于超过 2-3 个参数的工具，手动解析会变得繁琐且容易出错。这时就需要 flag 包。

四、flag 包详解

flag 包是 Go 标准库提供的命令行参数解析工具。它支持类型安全的参数定义、默认值、自动生成帮助信息等功能。

1. flag.String、flag.Int、flag.Bool

flag 包为常用类型提供了便捷函数。每个函数接收三个参数：参数名、默认值、描述文本，返回对应类型的指针。

package main

import (
	"flag"
	"fmt"
)

func main() {
	// 定义字符串标志，默认值为 "localhost"
	host := flag.String("host", "localhost", "服务器地址")
	// 定义整数标志，默认值为 8080
	port := flag.Int("port", 8080, "服务器端口")
	// 定义布尔标志，默认值为 false
	verbose := flag.Bool("verbose", false, "是否输出详细日志")

	// 解析命令行参数，必须在所有 flag 定义之后调用
	flag.Parse()

	fmt.Printf("主机: %s\n", *host)
	fmt.Printf("端口: %d\n", *port)
	fmt.Printf("详细: %v\n", *verbose)
}

运行示例：

bash

$ go run main.go -host 127.0.0.1 -port 3000 -verbose
主机: 127.0.0.1
端口: 3000
详细: true

$ go run main.go -h
Usage of main:
  -host string
    	服务器地址 (default "localhost")
  -port int
    	服务器端口 (default 8080)
  -verbose
    	是否输出详细日志

flag 包支持三种参数格式：

-flag：用于布尔类型，等价于 -flag=true
-flag=value：所有类型通用
-flag value：仅用于非布尔类型

注意：Go 的 flag 包只支持单横杠 -flag，不支持 GNU 风格的双横杠 --flag。虽然写入 --flag 也能工作（flag 包会做兼容处理），但官方推荐使用单横杠。

2. flag.Var 自定义类型

当内置类型不够用时，可以实现 flag.Value 接口来自定义参数类型。接口定义如下：

type Value interface {
	String() string
	Set(string) error
}

下面实现一个可以接收多个值的字符串切片标志：

package main

import (
	"flag"
	"fmt"
	"strings"
)

// stringSlice 实现了 flag.Value 接口，支持逗号分隔的多值参数
type stringSlice []string

// String 返回当前值的字符串表示
func (s *stringSlice) String() string {
	return strings.Join(*s, ",")
}

// Set 将输入字符串解析并追加到切片中
func (s *stringSlice) Set(value string) error {
	parts := strings.Split(value, ",")
	for _, p := range parts {
		*s = append(*s, strings.TrimSpace(p))
	}
	return nil
}

func main() {
	var tags stringSlice
	flag.Var(&tags, "tag", "标签列表，逗号分隔，可多次指定")
	flag.Parse()

	fmt.Printf("标签数量: %d\n", len(tags))
	for i, t := range tags {
		fmt.Printf("  [%d] %s\n", i, t)
	}
}

运行示例：

bash

$ go run main.go -tag go,cli,tool
标签数量: 3
  [0] go
  [1] cli
  [2] tool

$ go run main.go -tag go -tag cli -tag tool
标签数量: 3
  [0] go
  [1] cli
  [2] tool

3. flag.Parse 的工作流程

flag.Parse() 解析命令行参数时遵循以下规则：

从 os.Args[1:] 开始扫描。
遇到 -flag 时，查找已注册的 flag 进行匹配。
遇到非 flag 参数（不以 - 开头）或 -- 时，停止解析。
停止解析后的剩余参数可通过 flag.Args() 获取，称为位置参数。

package main

import (
	"flag"
	"fmt"
)

func main() {
	mode := flag.String("mode", "default", "运行模式")
	flag.Parse()

	// flag.Args() 返回未解析的位置参数
	// flag.NArg() 返回位置参数的数量
	// flag.Arg(i) 返回第 i 个位置参数
	fmt.Printf("模式: %s\n", *mode)
	fmt.Printf("位置参数数量: %d\n", flag.NArg())
	for i, arg := range flag.Args() {
		fmt.Printf("  位置参数[%d]: %s\n", i, arg)
	}
}

运行示例：

bash

$ go run main.go -mode test file1.txt file2.txt
模式: test
位置参数数量: 2
  位置参数[0]: file1.txt
  位置参数[1]: file2.txt

4. 子命令模式：flag.NewFlagSet

当 CLI 工具功能增多时，子命令模式成为更好的选择。git 就是一个典型例子：git add、git commit、git push 是不同的子命令，每个有自己的参数。

flag.NewFlagSet 允许为每个子命令创建独立的 flag 集合：

package main

import (
	"flag"
	"fmt"
	"os"
)

func main() {
	// 检查是否提供了子命令
	if len(os.Args) < 2 {
		printUsage()
		os.Exit(1)
	}

	// 根据第一个参数分发到不同的子命令
	switch os.Args[1] {
	case "add":
		addCommand(os.Args[2:])
	case "delete":
		deleteCommand(os.Args[2:])
	case "list":
		listCommand(os.Args[2:])
	default:
		fmt.Printf("未知子命令: %s\n", os.Args[1])
		printUsage()
		os.Exit(1)
	}
}

func printUsage() {
	fmt.Println("用法: myapp <command> [options]")
	fmt.Println("命令:")
	fmt.Println("  add     添加条目")
	fmt.Println("  delete  删除条目")
	fmt.Println("  list    列出所有条目")
}

func addCommand(args []string) {
	// 为 add 子命令创建独立的 FlagSet
	fs := flag.NewFlagSet("add", flag.ExitOnError)
	name := fs.String("name", "", "条目名称 (必填)")
	force := fs.Bool("force", false, "强制添加，跳过确认")
	fs.Parse(args)

	if *name == "" {
		fmt.Println("错误: --name 是必填的")
		fs.Usage()
		os.Exit(1)
	}

	fmt.Printf("添加条目: %s (force=%v)\n", *name, *force)
}

func deleteCommand(args []string) {
	fs := flag.NewFlagSet("delete", flag.ExitOnError)
	id := fs.Int("id", 0, "条目 ID (必填)")
	fs.Parse(args)

	if *id == 0 {
		fmt.Println("错误: --id 是必填的")
		fs.Usage()
		os.Exit(1)
	}

	fmt.Printf("删除条目 ID: %d\n", *id)
}

func listCommand(args []string) {
	fs := flag.NewFlagSet("list", flag.ExitOnError)
	all := fs.Bool("all", false, "显示所有条目包括已删除的")
	fs.Parse(args)

	fmt.Printf("列出条目 (all=%v)\n", *all)
}

运行示例：

bash

$ go run main.go add --name "hello" --force
添加条目: hello (force=true)

$ go run main.go delete --id 42
删除条目 ID: 42

$ go run main.go list --all
列出条目 (all=true)

子命令模式的核心思路是：将 os.Args 切分，第一个参数作为子命令名，剩余参数传给子命令自己的 FlagSet 进行解析。每个子命令有独立的参数定义和帮助信息。

五、标准库 CLI 的局限

flag 包虽然够用，但在复杂场景下有明显不足：

屗限性	说明
不支持双横杠	虽然兼容 `--flag`，但帮助信息只显示 `-flag`
不支持短标志缩写	无法定义 `-v` 作为 `--verbose` 的缩写
子命令较繁琐	需要手动写 switch 分发逻辑
无嵌套子命令	不支持 `docker container list` 这样的多级子命令
帮助信息较简单	无法添加示例、分组等
无自动补全	不支持生成 shell 自动补全脚本
无 man page	不支持生成 man 手册页

当工具复杂度超过 3-4 个子命令时，建议使用第三方框架（如 Cobra），它提供了更完善的子命令管理、自动补全、帮助生成等功能。这将在下一篇中详细讲解。

六、CLI 设计原则：Unix 哲学

好的 CLI 工具遵循 Unix 哲学。这些原则由 Doug McIlroy 在 1978 年总结，至今仍然适用。

1. 一个程序只做一件事

每个工具应该专注解决一个问题，做到极致。grep 只做文本搜索，sort 只做排序，uniq 只做去重。不要试图写一个"万能工具"。

反面案例：一个 CLI 工具既能压缩文件、又能发送邮件、还能管理数据库——这违反了"只做一件事"原则。正确做法是拆分为三个独立工具。

2. 输出纯文本，可作为管道

程序输出应该是纯文本（或 JSON 等结构化文本），以便其他程序通过管道消费。这是 Unix 工具链的基石。

package main

import (
	"bufio"
	"fmt"
	"os"
	"strings"
)

// 这个程序从 stdin 读取文本，转为大写后输出到 stdout
// 可以与其他工具配合使用：cat file.txt | go run main.go | grep ERROR
func main() {
	scanner := bufio.NewScanner(os.Stdin)
	for scanner.Scan() {
		line := scanner.Text()
		fmt.Println(strings.ToUpper(line))
	}

	if err := scanner.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "读取错误: %v\n", err)
		os.Exit(1)
	}
}

管道组合示例：

bash

# 将文件转为大写，筛选包含 ERROR 的行，统计行数
cat log.txt | go run main.go | grep ERROR | wc -l

3. 组合优于集成

不要在一个程序里集成所有功能。通过管道、子进程等方式组合多个小工具，才能产生强大的合力。kubectl 就是组合哲学的典范——它本身只做 API 调用，日志查看、数据过滤交给 jq、grep 等工具。

4. 其他重要原则

沉默是金：成功时不输出多余信息，只在出错时报告。
失败要响亮：错误信息输出到 stderr，带明确的错误描述。
退出码有意义：成功返回 0，不同类型的失败返回不同的非零码。
配置友好：支持配置文件、环境变量、命令行参数，且有合理的默认值。
文档完备：提供 --help 输出和 man page。

七、完整示例：文件处理工具

下面用一个完整的文件处理工具来综合演示标准库 CLI 开发。该工具支持读取输入文件、转换内容、写入输出文件，并支持详细日志模式。

package main

import (
	"bufio"
	"flag"
	"fmt"
	"io"
	"os"
	"strings"
)

// 版本信息，可在编译时通过 ldflags 注入
var version = "1.0.0"

func main() {
	// 定义命令行标志
	inputFile := flag.String("input", "", "输入文件路径 (必填，使用 - 表示从 stdin 读取)")
	outputFile := flag.String("output", "", "输出文件路径 (必填，使用 - 表示输出到 stdout)")
	verbose := flag.Bool("verbose", false, "输出详细处理日志到 stderr")
	uppercase := flag.Bool("upper", false, "将文本转为大写")
	lowercase := flag.Bool("lower", false, "将文本转为小写")
	lineNum := flag.Bool("number", false, "为每行添加行号")
	showVersion := flag.Bool("version", false, "显示版本信息")

	flag.Usage = printUsage
	flag.Parse()

	// 处理版本标志
	if *showVersion {
		fmt.Printf("fileproc %s\n", version)
		os.Exit(0)
	}

	// 校验必填参数
	if *inputFile == "" || *outputFile == "" {
		fmt.Fprintln(os.Stderr, "错误: --input 和 --output 是必填的")
		flag.Usage()
		os.Exit(1)
	}

	// 校验互斥选项
	if *uppercase && *lowercase {
		fmt.Fprintln(os.Stderr, "错误: --upper 和 --lower 不能同时使用")
		os.Exit(1)
	}

	// 设置日志输出：verbose 模式输出到 stderr，否则静默
	logger := newLogger(*verbose)

	// 打开输入源
	reader, closeInput, err := openInput(*inputFile)
	if err != nil {
		fmt.Fprintf(os.Stderr, "打开输入失败: %v\n", err)
		os.Exit(1)
	}
	defer closeInput()
	logger.log("输入源已打开: %s", *inputFile)

	// 打开输出目标
	writer, closeOutput, err := openOutput(*outputFile)
	if err != nil {
		fmt.Fprintf(os.Stderr, "打开输出失败: %v\n", err)
		os.Exit(1)
	}
	defer closeOutput()
	logger.log("输出目标已打开: %s", *outputFile)

	// 执行处理
	processed, err := process(reader, writer, *uppercase, *lowercase, *lineNum, logger)
	if err != nil {
		fmt.Fprintf(os.Stderr, "处理失败: %v\n", err)
		os.Exit(1)
	}

	logger.log("处理完成，共处理 %d 行", processed)
}

// printUsage 打印自定义帮助信息
func printUsage() {
	fmt.Fprintf(os.Stderr, `fileproc %s - 文件处理工具

用法:
  fileproc [flags]

示例:
  fileproc -input data.txt -output result.txt --upper --number
  cat log.txt | fileproc -input - -output - --lower
  fileproc -input config.yaml -output stdout.txt --verbose

选项:
`, version)
	flag.PrintDefaults()
}

// logger 是一个可控制的日志器，verbose 为 false 时静默
type logger struct {
	verbose bool
}

func newLogger(verbose bool) *logger {
	return &logger{verbose: verbose}
}

func (l *logger) log(format string, args ...interface{}) {
	if l.verbose {
		fmt.Fprintf(os.Stderr, "[fileproc] "+format+"\n", args...)
	}
}

// openInput 打开输入源，支持文件路径和 "-" (stdin)
func openInput(path string) (io.Reader, func(), error) {
	if path == "-" {
		return os.Stdin, func() {}, nil
	}
	file, err := os.Open(path)
	if err != nil {
		return nil, nil, err
	}
	return file, func() { file.Close() }, nil
}

// openOutput 打开输出目标，支持文件路径和 "-" (stdout)
func openOutput(path string) (io.Writer, func(), error) {
	if path == "-" {
		return os.Stdout, func() {}, nil
	}
	file, err := os.Create(path)
	if err != nil {
		return nil, nil, err
	}
	return file, func() { file.Close() }, nil
}

// process 逐行读取、转换并写入
func process(reader io.Reader, writer io.Writer, upper, lower, num bool, log *logger) (int, error) {
	scanner := bufio.NewScanner(reader)
	bufWriter := bufio.NewWriter(writer)
	defer bufWriter.Flush()

	count := 0
	for scanner.Scan() {
		line := scanner.Text()

		// 应用转换
		if upper {
			line = strings.ToUpper(line)
		}
		if lower {
			line = strings.ToLower(line)
		}
		if num {
			line = fmt.Sprintf("%6d\t%s", count+1, line)
		}

		fmt.Fprintln(bufWriter, line)
		count++

		if count%1000 == 0 {
			log.log("已处理 %d 行", count)
		}
	}

	if err := scanner.Err(); err != nil {
		return count, err
	}

	return count, nil
}

运行示例：

bash

# 基本用法：转换为大写并添加行号
$ echo -e "hello\nworld" | go run main.go -input - -output - --upper --number
     1	HELLO
     2	WORLD

# 文件到文件，带详细日志
$ go run main.go -input data.txt -output result.txt --lower --verbose
[fileproc] 输入源已打开: data.txt
[fileproc] 输出目标已打开: result.txt
[fileproc] 处理完成，共处理 5 行

# 查看版本
$ go run main.go -version
fileproc 1.0.0

# 查看帮助
$ go run main.go -h

这个示例体现了 CLI 设计的最佳实践：

支持 stdin/stdout：使用 - 作为特殊值，让工具能接入管道。
verbose 日志输出到 stderr：不污染 stdout 上的正常输出。
互斥参数校验：--upper 和 --lower 不能同时使用。
自定义帮助信息：包含用法、示例、选项列表。
版本信息：通过 -version 查看，且支持编译时注入。
退出码：成功返回 0，失败返回 1。
defer 关闭资源：确保文件句柄正确释放。
缓冲写入：使用 bufio.Writer 提升写入性能。

八、小结

本篇介绍了 Go CLI 开发的基础知识：

CLI 概述：理解了 CLI 的基本结构和优势，包括命令名、标志、位置参数、子命令。
Go 的优势：单文件二进制、跨平台编译、启动快、标准库强大、生态成熟。
os.Args：最原始的参数获取方式，适合简单场景，但手动解析容易出错。
flag 包：标准库的参数解析方案，支持类型安全、默认值、自动帮助生成。
- flag.String/Int/Bool：内置类型的便捷函数。
- flag.Var：通过实现 flag.Value 接口支持自定义类型。
- flag.Parse：解析参数，flag.Args() 获取位置参数。
- flag.NewFlagSet：实现子命令模式的基础。
标准库的局限：不支持缩写、子命令管理繁琐、无自动补全等。
Unix 哲学：只做一件事、输出纯文本、组合优于集成、沉默是金。
完整示例：文件处理工具综合演示了参数定义、校验、I/O 处理、日志控制等实践。

标准库 flag 包足以应对简单到中等复杂度的 CLI 工具。当工具规模增长、需要更完善的子命令管理和用户体验时，Cobra 框架是下一站。下一篇我们将深入学习 Cobra——Go 生态中最流行的 CLI 框架。

入门篇

进阶篇

资深篇

CLI 开发基础与标准库

一、CLI 概述

二、为什么 Go 适合写 CLI

1. 编译为单文件二进制

2. 跨平台编译

3. 启动速度极快

4. 标准库强大

5. 生态成熟

三、os.Args 基础

四、flag 包详解

1. flag.String、flag.Int、flag.Bool

2. flag.Var 自定义类型

3. flag.Parse 的工作流程

4. 子命令模式：flag.NewFlagSet

五、标准库 CLI 的局限

六、CLI 设计原则：Unix 哲学

1. 一个程序只做一件事

2. 输出纯文本，可作为管道

3. 组合优于集成

4. 其他重要原则

七、完整示例：文件处理工具

八、小结

CLI 开发基础与标准库 ​

一、CLI 概述 ​

二、为什么 Go 适合写 CLI ​

1. 编译为单文件二进制 ​

2. 跨平台编译 ​

3. 启动速度极快 ​

4. 标准库强大 ​

5. 生态成熟 ​

三、os.Args 基础 ​

四、flag 包详解 ​

1. flag.String、flag.Int、flag.Bool ​

2. flag.Var 自定义类型 ​

3. flag.Parse 的工作流程 ​

4. 子命令模式：flag.NewFlagSet ​

五、标准库 CLI 的局限 ​

六、CLI 设计原则：Unix 哲学 ​

1. 一个程序只做一件事 ​

2. 输出纯文本，可作为管道 ​

3. 组合优于集成 ​

4. 其他重要原则 ​

七、完整示例：文件处理工具 ​

八、小结 ​

CLI 开发基础与标准库

一、CLI 概述

二、为什么 Go 适合写 CLI

1. 编译为单文件二进制

2. 跨平台编译

3. 启动速度极快

4. 标准库强大

5. 生态成熟

三、os.Args 基础

四、flag 包详解

1. flag.String、flag.Int、flag.Bool

2. flag.Var 自定义类型

3. flag.Parse 的工作流程

4. 子命令模式：flag.NewFlagSet

五、标准库 CLI 的局限

六、CLI 设计原则：Unix 哲学

1. 一个程序只做一件事

2. 输出纯文本，可作为管道

3. 组合优于集成

4. 其他重要原则

七、完整示例：文件处理工具

八、小结