Go 语言基于 flag 库开发命令行工具实战

原理：使用 flag 库解析参数

Go 标准库中的 flag 包提供了强大的命令行标志解析功能。要开发一个简单的命令行工具，首先需要明确需要接收哪些参数，并定义相应的变量来存储这些值。我们可以针对字符串（string）、整数（integer）和布尔值（bool）三种基础类型分别定义 flag，例如使用 flag.String()、flag.Int() 和 flag.Bool()。

以定义一个名为 -n 的选项为例，其默认值为 1234，提示信息为 help message for flag n，返回值是一个指向 int 类型的指针：

import "flag"
var nFlag = flag.Int("n", 1234, "help message for flag n")

除了上述直接赋值返回的方式，也可以将 flag 直接与已有变量绑定。只需在方法名前加上 Var（如 IntVar），首个参数传入变量的指针即可：

var flagvar int
func init() {
	flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
}

这两种方式的区别在于：Int 类方法返回一个新创建的指针，而 IntVar 则是将值写入已存在的指针指向的变量。签名结构相似，这里以 Int64Var 的定义参考为例：

在所有需要的 flag 都定义完毕后，调用 flag.Parse() 方法将命令行传入的数据解析并填充到对应的 flag 变量中。之后即可直接使用这些变量。

fmt.Println("ip has value ", *ip)
fmt.Println("flagvar has value ", flagvar)

如果不仅需要带值的 flag，还需要处理非标志位的一般参数，可以使用 flag.Args() 获取剩余的参数切片，或通过 flag.Arg(i) 按索引（从 0 开始）获取特定参数。

从开发者角度简化流程，建议统一使用 flag.XXXVar 进行绑定，最后统一调用 flag.Parse()。以下是一个完整的示例代码：

package main

import (
  "fmt"
  "flag"
)

var (
  intflag    int
  boolflag   bool
  stringflag string
)

func init() {
  flag.IntVar(&intflag, "intflag", 0, "int flag value")
  flag.BoolVar(&boolflag, "boolflag", false, "bool flag value")
  flag.StringVar(&stringflag, "stringflag", "default", "string flag value")
}

func main() {
  flag.Parse()

  fmt.Println("int flag:", intflag)
  fmt.Println("bool flag:", boolflag)
  fmt.Println("stringflag:", stringflag)
}

编译运行后，可以通过不同形式的参数传值：

$ ./main -intflag 12 -boolflag 1 -stringflag test

int flag: 12
bool flag: true
stringflag: test

若未设置某项 flag 的值，程序将自动采用定义的默认值。flag 支持多种参数书写格式：

• -flag：通常用于 bool 类型，存在即为 true
• --flag：双短横线前缀
• -flag=x：等号连接值
• -flag x：空格分隔值（bool 类型不适用此方式）

深入：FlagSet 与自定义配置

FlagSet 是 flag 库底层的核心结构体，用于封装一组 flag 定义及解析逻辑。其定义包含 Usage 函数字段，当解析 flag 出错时会被调用。

type FlagSet struct {
	Usage func()
	// 其他内部字段省略
}

默认的命令行解析（即直接调用 flag.Parse()）实际上是使用了全局唯一的 CommandLine FlagSet 实例：

// src/flag/flag.go
var CommandLine = NewFlagSet(os.Args[0], ExitOnError)

func Parse() {
  CommandLine.Parse(os.Args[1:])
}

当我们需要更灵活的控制（例如隔离不同子命令的 flag，或自定义错误处理方式）时，可以使用 NewFlagSet(name string, errorHandling int) 创建新的 FlagSet。第二个参数指定了错误处理策略，可选值包括：

• ContinueOnError：解析出错后继续，不会中断程序。默认的 CommandLine 实际上使用的是此模式但配合全局退出逻辑。
• ExitOnError：遇到错误时输出 Usage 信息并调用 os.Exit(2) 终止程序。
• PanicOnError：遇到错误时触发 panic。

具体参考如下：

实战需求拆解

为了演示完整流程，我们设定一个实际需求：编写一个命令行工具，用户通过传入“城市名称”参数，工具能自动获取并显示该城市的当前天气状况。

该需求分为两部分：

1. 参数解析：使用 flag 库接收并校验输入的城市名。
2. 数据获取与渲染：调用外部天气 API（如 wttr.in），并将返回的 HTML 内容转换为终端友好的文本格式。

访问 wttr.in/wuhan 可以看到返回的是网页格式的 HTML 内容，而非纯 JSON，因此我们需要额外的数据处理步骤。

第一步：实现 weather flag 解析

首先，利用 flag.NewFlagSet 创建一个独立的 FlagSet 实例，这样可以更好地控制报错信息和 Usage 提示，避免与主程序的其他 flag 冲突。

package main

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

type arguments struct {
    weatherCity string
}

func (a *arguments) parseArgs(args []string) error {
    // 创建一个新的 FlagSet，错误处理设为 ContinueOnError 以便后续自行捕获错误
    f := flag.NewFlagSet(os.Args[0], flag.ContinueOnError)

    // 定义 weather flag，类型为 String，默认为空
    f.StringVar(&a.weatherCity, "weather", "", "check weather of city")

    // 自定义 Usage 函数，优化帮助信息的展示
    f.Usage = func() {
        fmt.Fprintf(os.Stderr, `Usage of %s:\n`, os.Args[0])
        f.PrintDefaults()
        os.Exit(1)
    }

    // 执行解析
    if err := f.Parse(args[1:]); err != nil {
        return err
    }
    return nil
}

func Execute() error {
    args := &arguments{}
    if err := args.parseArgs(os.Args); err != nil {
        fmt.Println("Error parsing flags:", err)
        os.Exit(2)
    }

    // 仅当传入的天气城市参数不为空时，才执行查询
    if args.weatherCity != "" {
        // TODO: 在此处调用天气查询逻辑
        return handleWeatherQuery(args.weatherCity)
    }

    return nil
}

func main() {
    if err := Execute(); err != nil {
        // 处理全局错误
    }
}

第二步：获取并转换天气数据

在上面的 TODO 位置，我们需要实现 GetWeather(city string) 函数。由于源数据是 HTML，我们需要将其转换为 Markdown，再进一步渲染为适合 Terminal 显示的字符串。

1. 获取源数据

使用 http.Get 请求 wttr.in 接口：

import (
    "io/ioutil"
    "net/http"
)

注意：在新版 Go 中，ioutil.ReadAll 推荐使用 io.ReadAll。此处保留原意逻辑。

2. 数据转换链路

为了在终端优雅地展示天气，我们引入两个社区常用库：

• github.com/JohannesKaufmann/html-to-markdown：将 HTML 转为 Markdown 语法。
• github.com/MichaelMure/go-term-markdown：将 Markdown 渲染为适配终端宽度的纯文本。

整合后的核心逻辑如下：

package weather

import (
	"io/ioutil"
	"net/http"

	md "github.com/JohannesKaufmann/html-to-markdown"
	termmd "github.com/MichaelMure/go-term-markdown"
)

func GetWeather(city string) (string, error) {
	url := "https://wttr.in/" + city
	response, err := http.Get(url)
	if err != nil {
		return "", err
	}
	defer response.Body.Close()

	all, err := ioutil.ReadAll(response.Body)
	if err != nil {
		return "", err
	}

	htmlContent := string(all)
	
	// 将 HTML 转为 Markdown
	markdownText := convertHTMLToMarkdown(htmlContent)
	
	// 将 Markdown 渲染为终端文本
	result := termmd.Render(markdownText, 280, 6)
	return string(result), nil
}

func convertHTMLToMarkdown(html string) string {
	converter := md.NewConverter("", true, nil)
	markdown, err := converter.ConvertString(html)
	if err != nil {
		return ""
	}
	return markdown
}

运行效果验证

将上述逻辑整合进主程序后，编译工具并传入目标城市进行测试：

$ opb -weather beijing

程序将发起网络请求，解析响应，并在终端内打印出清晰的天气预报信息，包括温度、天气状况等。

至此，一个简单的基于 Go flag 库的 CLI 天气查询工具即告完成。通过组合标准库的参数解析能力和第三方库的内容转换能力，可以快速解决很多实际的终端交互需求。