注：上面篇首配图的底图由百度文心一格生成。

本文永久链接 – https://tonybai.com/2023/03/25/the-guide-of-developing-cli-program-in-go

近期在Twitter上看到一个名为“Command Line Interface Guidelines”的站点，这个站点汇聚了帮助大家编写出更好命令行程序的哲学与指南。这份指南基于传统的Unix编程原则，又结合现代的情况进行了“与时俱进”的更新。之前我还真未就如何编写命令行交互程序做系统的梳理，在这篇文章中，我们就来结合clig这份指南，(可能不会全面覆盖)整理出一份使用Go语言编写CLI程序的指南，供大家参考。

一. 命令行程序简介

命令行接口（Command Line Interface, 简称CLI）程序是一种允许用户使用文本命令和参数与计算机系统互动的软件。开发人员编写CLI程序通常用在自动化脚本、数据处理、系统管理和其他需要低级控制和灵活性的任务上。命令行程序也是Linux/Unix管理员以及后端开发人员的最爱。

2022年Q2 Go官方用户调查结果显示(如下图)：在使用Go开发的程序类别上，CLI类程序排行第二，得票率60%。

之所以这样，得益于Go语言为CLI开发提供的诸多便利，比如：

• Go语法简单而富有表现力；
• Go拥有一个强大的标准库，并内置的并发支持；
• Go拥有几乎最好的跨平台兼容性和快速的编译速度；
• Go还有一个丰富的第三方软件包和工具的生态系统。

这些都让开发者使用Go创建强大和用户友好的CLI程序变得容易。

容易归容易，但要用Go编写出优秀的CLI程序，我们还需要遵循一些原则，获得一些关于Go CLI程序开发的最佳实践和惯例。这些原则和惯例涉及交互界面设计、错误处理、文档、测试和发布等主题。此外，借助于一些流行的Go CLI程序开发库和框架，比如：cobra、Kingpin和Goreleaser等，我们可以又好又快地完成CLI程序的开发。在本文结束时，你将学会如何创建一个易于使用、可靠和可维护的Go CLI程序，你还将获得一些关于CLI开发的最佳实践和惯例的见解。

二. 建立Go开发环境

如果你读过《十分钟入门Go语言》或订阅学习过我的极客时间《Go语言第一课》专栏，你大可忽略这一节的内容。

在我们开始编写Go CLI程序之前，我们需要确保我们的系统中已经安装和配置了必要的Go工具和依赖。在本节中，我们将向你展示如何安装Go和设置你的工作空间，如何使用go mod进行依赖管理，以及如何使用go build和go install来编译和安装你的程序。

1. 安装Go

要在你的系统上安装Go，你可以遵循你所用操作系统的官方安装说明。你也可以使用软件包管理器，如homebrew（用于macOS）、chocolatey（用于Windows）或snap/apt（用于Linux）来更容易地安装Go。

一旦你安装了Go，你可以通过在终端运行以下命令来验证它是否可以正常工作。

$go version

如果安装成功，go version这个命令应该会打印出你所安装的Go的版本。比如说：

go version go1.20 darwin/amd64

2. 设置你的工作区(workspace)

Go以前有一个惯例，即在工作区目录中(\$GOPATH)组织你的代码和依赖关系。默认工作空间目录位于$HOME/go，但你可以通过设置GOPATH环境变量来改变它的路径。工作区目录包含三个子目录：src、pkg和bin。src目录包含了你的源代码文件和目录。pkg目录包含被你的代码导入的已编译好的包。bin目录包含由你的代码生成的可执行二进制文件。

Go 1.11引入Go module后，这种在\$GOPATH下组织代码和寻找依赖关系的要求被彻底取消。在这篇文章中，我依旧按照我的习惯在$HOME/go/src下放置我的代码示例。

为了给我们的CLI程序创建一个新的项目目录，我们可以在终端运行以下命令：

$mkdir -p $HOME/go/src/github.com/your-username/your-li-program
$cd $HOME/go/src/github.com/your-username/your-cli-program

注意，我们的项目目录名使用的是github的URL格式。这在Go项目中是一种常见的做法，因为它使得使用go get导入和管理依赖关系更加容易。go module成为构建标准后，这种对项目目录名的要求已经取消，但很多Gopher依旧保留了这种作法。

3. 使用go mod进行依赖管理

1.11版本后Go推荐开发者使用module来管理包的依赖关系。一个module是共享一个共同版本号和导入路径前缀的相关包的集合。一个module是由一个叫做go.mod的文件定义的，它指定了模块的名称、版本和依赖关系。

为了给我们的CLI程序创建一个新的module，我们可以在我们的项目目录下运行以下命令。

$go mod init github.com/your-username/your-cli-program

这将创建一个名为go.mod的文件，内容如下。

module github.com/your-username/your-cli-program

go 1.20

第一行指定了我们的module名称，这与我们的项目目录名称相匹配。第二行指定了构建我们的module所需的Go的最低版本。

为了给我们的模块添加依赖项，我们可以使用go get命令，加上我们想使用的软件包的导入路径和可选的版本标签。例如，如果我们想使用cobra作为我们的CLI框架，我们可以运行如下命令：

$go get github.com/spf13/cobra@v1.3.0

go get将从github下载cobra，并在我们的go.mod文件中把它作为一个依赖项添加进去。它还将创建或更新一个名为go.sum的文件，记录所有下载的module的校验和，以供后续验证使用。

我们还可以使用其他命令，如go list、go mod tidy、go mod graph等，以更方便地检查和管理我们的依赖关系。

4. 使用go build和go install来编译和安装你的程序

Go有两个命令允许你编译和安装你的程序：go build和go install。这两个命令都以一个或多个包名或导入路径作为参数，并从中产生可执行的二进制文件。

它们之间的主要区别在于它们将生成的二进制文件存储在哪里。

• go build将它们存储在当前工作目录中。
• go install将它们存储在\$GOPATH/bin或\$GOBIN（如果设置了）。

例如，如果我们想把CLI程序的main包（应该位于github.com/your-username/your-cli-program/cmd/your-cli-program）编译成一个可执行的二进制文件，称为your-cli-program，我们可以运行下面命令：

$go build github.com/your-username/your-cli-program/cmd/your-cli-program

或

$go install github.com/your-username/your-cli-program/cmd/your-cli-program@latest

三. 设计用户接口(interface)

要编写出一个好的CLI程序，最重要的环节之一是设计一个用户友好的接口。好的命令行用户接口应该是一致的、直观的和富有表现力的。在本节中，我将说明如何为命令行程序命名和选择命令结构(command structure)，如何使用标志(flag)、参数(argument)、子命令(subcommand)和选项(option)作为输入参数，如何使用cobra或Kingpin等来解析和验证用户输入，以及如何遵循POSIX惯例和GNU扩展的CLI语法。

1. 命令行程序命名和命令结构选择

你的CLI程序的名字应该是简短、易记、描述性的和易输入的。它应该避免与目标平台中现有的命令或关键字发生冲突。例如，如果你正在编写一个在不同格式之间转换图像的程序，你可以把它命名为imgconv、imago、picto等，但不能叫image、convert或format。

你的CLI程序的命令结构应该反映你想提供给用户的主要功能特性。你可以选择使用下面命令结构模式中的一种：

• 一个带有多个标志(flag)和参数(argument)的单一命令（例如：curl、tar、grep等)
• 带有多个子命令(subcommand)的单一命令（例如：git、docker、kubectl等)
• 具有共同前缀的多个命令（例如：aws s3、gcloud compute、az vm等)

命令结构模式的选择取决于你的程序的复杂性和使用范围，一般来说：

• 如果你的程序只有一个主要功能或操作模式(operation mode)，你可以使用带有多个标志和参数的单一命令。
• 如果你的程序有多个相关但又不同的功能或操作模式，你可以使用一个带有多个子命令的单一命令。
• 如果你的程序有多个不相关或独立的功能或操作模式，你可以使用具有共同前缀的多个命令。

例如，如果你正在编写一个对文件进行各种操作的程序（如复制、移动、删除），你可以任选下面命令结构模式中的一种：

• 带有多个标志和参数的单一命令（例如，fileop -c src dst -m src dst -d src)
• 带有多个子命令的单个命令（例如，fileop copy src dst, fileop move src dst, fileop delete src)

2. 使用标志、参数、子命令和选项

标志(flag)是以一个或多个(通常是2个)中划线（-）开头的输入参数，它可以修改CLI程序的行为或输出。例如：

$curl -s -o output.txt https://example.com

在这个例子中：

• “-s”是一个让curl沉默的标志，即不输出执行日志到控制台；
• “-o”是另一个标志，用于指定输出文件的名称
• “output.txt”则是一个参数，是为“-o”标志提供的值。

参数(argument)是不以中划线（-）开头的输入参数，为你的CLI程序提供额外的信息或数据。例如：

$tar xvf archive.tar.gz

我们看在这个例子中：

• x是一个指定提取模式的参数
• v是一个参数，指定的是输出内容的详细(verbose)程度
• f是另一个参数，用于指定采用的是文件模式，即将压缩结果输出到一个文件或从一个压缩文件读取数据
• archive.tar.gz是一个参数，提供文件名。

子命令(subcommand)是输入参数，作为主命令下的辅助命令。它们通常有自己的一组标志和参数。比如下面例子：

$git commit -m "Initial commit"

我们看在这个例子中：

• git是主命令(primary command)
• commit是一个子命令，用于从staged的修改中创建一个新的提交(commit)
• “-m”是commit子命令的一个标志，用于指定提交信息
• “Initial commit”是commit子命令的一个参数，为”-m”标志提供值。

选项(option)是输入参数，它可以使用等号（=）将标志和参数合并为一个参数。例如:

$docker run --name=my-container ubuntu:latest

我们看在这个例子中“–name=my-container”是一个选项，它将容器的名称设为my-container。该选项前面的部分“–name”是一个标志，后面的部分“my-container”是参数。

3. 使用cobra包等来解析和验证用户输入的信息

如果手工来解析和验证用户输入的信息，既繁琐又容易出错。幸运的是，有许多库和框架可以帮助你在Go中解析和验证用户输入。其中最流行的是cobra。

cobra是一个Go包，它提供了简单的接口来创建强大的CLI程序。它支持子命令、标志、参数、选项、环境变量和配置文件。它还能很好地与其他库集成，比如：viper（用于配置管理）、pflag（用于POSIX/GNU风格的标志）和Docopt（用于生成文档）。

另一个不那么流行但却提供了一种声明式的方法来创建优雅的CLI程序的包是Kingpin，它支持标志、参数、选项、环境变量和配置文件。它还具有自动帮助生成、命令完成、错误处理和类型转换等功能。

cobra和Kingpin在其官方网站上都有大量的文档和例子，你可以根据你的偏好和需要选择任选其一。

4. 遵循POSIX惯例和GNU扩展的CLI语法

POSIX（Portable Operating System Interface）是一套标准，定义了软件应该如何与操作系统进行交互。其中一个标准定义了CLI程序的语法和语义。GNU（GNU’s Not Unix）是一个旨在创建一个与UNIX兼容的自由软件操作系统的项目。GNU下的一个子项目是GNU Coreutils，它提供了许多常见的CLI程序，如ls、cp、mv等。

POSIX和GNU都为CLI语法建立了一些约定和扩展，许多CLI程序都采用了这些约定与扩展。下面列举了这些约定和扩展中的一些主要内容：

• 单字母标志(single-letter flag)以一个中划线（-）开始，可以组合在一起（例如：-a -b -c 或 -abc )
• 长标志(long flag)以两个中划线（–）开头，但不能组合在一起（例如：–all、–backup、–color )
• 选项使用等号(=)来分隔标志名和参数值(例如：–name=my-container )
• 参数跟在标志或选项之后，没有任何分隔符（例如：curl -o output.txt https://example.com ）。
• 子命令跟在主命令之后，没有任何分隔符（例如：git commit -m “Initial commit” )
• 一个双中划线（–）表示标志或选项的结束和参数的开始（例如：rm — -f 表示要删除“-f”这个文件，由于双破折线的存在，这里的“-f”不再是标志)

遵循这些约定和扩展可以使你的CLI程序更加一致、直观，并与其他CLI程序兼容。然而，它们并不是强制性的，如果你有充分的理由，你也大可不必完全遵守它们。例如，一些CLI程序使用斜线（/）而不是中划线（-）表示标志（例如， robocopy /S /E src dst ）。

四. 处理错误和信号

编写好的CLI程序的一个重要环节就是优雅地处理错误和信号。

错误是指你的程序由于某些内部或外部因素而无法执行其预定功能的情况。信号是由操作系统或其他进程向你的程序发送的事件，以通知它一些变化或请求。在这一节中，我将说明一下如何使用log、fmt和errors包进行日志输出和错误处理，如何使用os.Exit和defer语句进行优雅的终止，如何使用os.Signal和context包进行中断和取消操作，以及如何遵循CLI程序的退出状态代码惯例。

1. 使用log、fmt和errors包进行日志记录和错误处理

Go标准库中有三个包log、fmt和errors可以帮助你进行日志和错误处理。log包提供了一个简单的接口，可以将格式化的信息写到标准输出或文件中。fmt包则提供了各种格式化字符串和值的函数。errors包提供了创建和操作错误值的函数。

要使用log包，你需要在你的代码中导入它：

import "log"

然后你可以使用log.Println、log.Printf、log.Fatal和log.Fatalf等函数来输出不同严重程度的信息。比如说：

log.Println("Starting the program...") // 打印带有时间戳的消息
log.Printf("Processing file %s...\n", filename) // 打印一个带时间戳的格式化信息
log.Fatal("Cannot open file: ", err) // 打印一个带有时间戳的错误信息并退出程序
log.Fatalf("Invalid input: %v\n", input) // 打印一个带时间戳的格式化错误信息，并退出程序。

为了使用fmt包，你需要先在你的代码中导入它：

import "fmt"

然后你可以使用fmt.Println、fmt.Printf、fmt.Sprintln、fmt.Sprintf等函数以各种方式格式化字符串和值。比如说：

fmt.Println("Hello world!") // 打印一条信息，后面加一个换行符
fmt.Printf("The answer is %d\n", 42) // 打印一条格式化的信息，后面是换行。
s := fmt.Sprintln("Hello world!") // 返回一个带有信息和换行符的字符串。
t := fmt.Sprintf("The answer is %d\n", 42) // 返回一个带有格式化信息和换行的字符串。

要使用错误包，你同样需要在你的代码中导入它：

import "errors"

然后你可以使用 errors.New、errors.Unwrap、errors.Is等函数来创建和操作错误值。比如说：

err := errors.New("Something went wrong") // 创建一个带有信息的错误值
cause := errors.Unwrap(err) // 返回错误值的基本原因（如果没有则为nil）。
match := errors.Is(err, io.EOF) // 如果一个错误值与另一个错误值匹配，则返回真（否则返回假）。

2. 使用os.Exit和defer语句实现CLI程序的优雅终止

Go有两个功能可以帮助你优雅地终止CLI程序：os.Exit和defer。os.Exit函数立即退出程序，并给出退出状态代码。defer语句则会在当前函数退出前执行一个函数调用，它常用来执行清理收尾动作，如关闭文件或释放资源。

要使用os.Exit函数，你需要在你的代码中导入os包：

import "os"

然后你可以使用os.Exit函数，它的整数参数代表退出状态代码。比如说

os.Exit(0) // 以成功的代码退出程序
os.Exit(1) // 以失败代码退出程序

要使用defer语句，你需要把它写在你想后续执行的函数调用之前。比如说

file, err := os.Open(filename) // 打开一个文件供读取。
if err != nil {
    log.Fatal(err) // 发生错误时退出程序
}
defer file.Close() // 在函数结束时关闭文件。

// 对文件做一些处理...

3. 使用os.signal和context包来实现中断和取消操作

Go有两个包可以帮助你实现中断和取消长期运行的或阻塞的操作，它们是os.signal和context包。os.signal提供了一种从操作系统或其他进程接收信号的方法。context包提供了一种跨越API边界传递取消信号和deadline的方法。

要使用os.signal，你需要先在你的代码中导入它。

import (
  "os"
  "os/signal"
)

然后你可以使用signal.Notify函数针对感兴趣的信号(如下面的os.Interrupt信号)注册一个接收channel(sig)。比如说：

sig := make(chan os.Signal, 1) // 创建一个带缓冲的信号channel。
signal.Notify(sig, os.Interrupt) // 注册sig以接收中断信号（例如Ctrl-C）。

// 做一些事情...

select {
case <-sig: // 等待来自sig channel的信号
    fmt.Println("被用户中断了")
    os.Exit(1) // 以失败代码退出程序。
default: //如果没有收到信号就执行
    fmt.Println("成功完成")
    os.Exit(0) // 以成功代码退出程序。
}

要使用上下文包，你需要在你的代码中导入它：

import "context"

然后你可以使用它的函数，如context.Background、context.WithCancel、context.WithTimeout等来创建和管理Context。Context是一个携带取消信号和deadline的对象，可以跨越API边界。比如说：

ctx := context.Background() // 创建一个空的背景上下文（从不取消）。
ctx, cancel := context.WithCancel(ctx) // 创建一个新的上下文，可以通过调用cancel函数来取消。
defer cancel() // 在函数结束前执行ctx的取消动作

// 将ctx传递给一些接受它作为参数的函数......

select {
case <-ctx.Done(): // 等待来自ctx的取消信号
    fmt.Println("Canceled by parent")
    return ctx.Err() // 从ctx返回一个错误值
default: // 如果没有收到取消信号就执行
    fmt.Println("成功完成")
    return nil // 不返回错误值
}

4. CLI程序的退出状态代码惯例

退出状态代码是一个整数，表示CLI程序是否成功执行完成。CLI程序通过调用os.Exit或从main返回的方式返回退出状态值。其他CLI程序或脚本可以可以检查这些退出状态码，并根据状态码值的不同执行不同的处理操作。

业界有一些关于退出状态代码的约定和扩展，这些约定被许多CLI程序广泛采用。其中一些主要的约定和扩展如下：。

• 退出状态代码为0表示程序执行成功（例如：os.Exit(0) )
• 非零的退出状态代码表示失败（例如：os.Exit(1) ）。
• 不同的非零退出状态代码可能表示不同的失败类型或原因（例如：os.Exit(2)表示使用错误，os.Exit(3)表示权限错误等等）。
• 大于125的退出状态代码可能表示被外部信号终止（例如，os.Exit(130)为被信号中断）。

遵循这些约定和扩展可以使你的CLI程序表现的更加一致、可靠并与其他CLI程序兼容。然而，它们不是强制性的，你可以使用任何对你的程序有意义的退出状态代码。例如，一些CLI程序使用高于200的退出状态代码来表示自定义或特定应用的错误（例如，os.Exit(255)表示未知错误）。

五. 编写文档

编写优秀CLI程序的另一个重要环节是编写清晰简洁的文档，解释你的程序做什么以及如何使用它。文档可以采取各种形式，如README文件、usage信息、help flag等。在本节中，我们将告诉你如何为你的程序写一个README文件，如何为你的程序写一个有用的usage和help flag等。

1. 为你的CLI程序写一个清晰简洁的README文件

README文件是一个文本文件，它提供了关于你的程序的基本信息，如它的名称、描述、用法、安装、依赖性、许可证和联系细节等。它通常是用户或开发者在源代码库或软件包管理器上首次使用你的程序时会看到的内容。

如果你要为Go CLI程序编写一个优秀的README文件，你应该遵循一些最佳实践，比如：

• 使用一个描述性的、醒目的标题，反映你的程序的目的和功能。
• 提供一个简短的介绍，解释你的程序是做什么的，为什么它是有用的或独特的。
• 包括一个usage部分，说明如何用不同的标志、参数、子命令和选项来调用你的程序。你可以使用代码块或屏幕截图来说明这些例子。
• 包括一个安装(install)部分，解释如何在不同的平台上下载和安装你的程序。你可以使用go install、go get、goreleaser或其他工具来简化这一过程。
• 指定你的程序的发行许可，并提供一个许可全文的链接。你可以使用SPDX标识符来表示许可证类型。
• 为想要报告问题、请求新功能、贡献代码或提问的用户或开发者提供联系信息。你可以使用github issue、pr、discussion、电子邮件或其他渠道来达到这个目的。

以下是一个Go CLI程序的README文件的示例供参考：

2. 为你的CLI程序编写有用的usage和help标志

usage信息是一段简短的文字，总结了如何使用你的程序及其可用的标志、参数、子命令和选项。它通常在你的程序在没有参数或输入无效的情况下运行时显示。

help标志是一个特殊的标志（通常是-h或–help），它可以触发显示使用信息和一些关于你的程序的额外信息。

为了给你的Go CLI程序写有用的usage信息和help标志，你应该遵循一些准则，比如说：

• 使用一致而简洁的语法来描述标志、参数、子命令和选项。你可以用方括号“[ ]”表示可选元素，使用角括号“< >”表示必需元素，使用省略号“…”表示重复元素，使用管道“|”表示备选，使用中划线“-”表示标志(flag)，使用等号“=”表示标志的值等等。
• 对标志、参数、子命令和选项应使用描述性的名称，以反映其含义和功能。避免使用单字母名称，除非它们非常常见或非常直观（如-v按惯例表示verbose模式）。
• 为每个标志、参数、子命令和选项提供简短而清晰的描述，解释它们的作用以及它们如何影响你的程序的行为。你可以用圆括号“（ ）”来表达额外的细节或例子。
• 使用标题或缩进将相关的标志、参数、子命令和选项组合在一起。你也可以用空行或水平线（—）来分隔usage的不同部分。
• 在每组中按名称的字母顺序排列标志。在每组中按重要性或逻辑顺序排列参数。在每组中按使用频率排列子命令。

git的usage就是一个很好的例子：

$git
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]

结合上面的准则，大家可以细心体会一下。

六. 测试和发布你的CLI程序

编写优秀CLI程序的最后一个环节是测试和发布你的程序。测试确保你的程序可以按预期工作，并符合质量标准。发布可以使你的程序可供用户使用和访问。

在本节中，我将说明如何使用testing、testify/assert、mock包对你的代码进行单元测试，如何使用go test、coverage、benchmark工具来运行测试和测量程序性能以及如何使用goreleaser包来构建跨平台的二进制文件。

1. 使用testing、testify的assert及mock包对你的代码进行单元测试

单元测试是一种验证单个代码单元（如函数、方法或类型）的正确性和功能的技术。单元测试可以帮助你尽早发现错误，提高代码质量和可维护性，并促进重构和调试。

要为你的Go CLI程序编写单元测试，你应该遵循一些最佳实践：

• 使用内置的测试包来创建测试函数，以Test开头，后面是被测试的函数或方法的名称。例如：func TestSum(t *testing.T) { … }；
• 使用*testing.T类型的t参数，使用t.Error、t.Errorf、t.Fatal或t.Fatalf这样的方法报告测试失败。你也可以使用t.Log、t.Logf、t.Skip或t.Skipf这样的方法来提供额外的信息或有条件地跳过测试。
• 使用Go子测试(sub test)，通过t.Run方法将相关的测试分组。例如：

func TestSum(t *testing.T) {
    t.Run("positive numbers", func(t *testing.T) {
        // test sum with positive numbers
    })
    t.Run("negative numbers", func(t *testing.T) {
        // test sum with negative numbers
    })
}

• 使用表格驱动(table-driven)的测试来运行多个测试用例，比如下面的例子：

func TestSum(t *testing.T) {
    tests := []struct{
        name string
        a int
        b int
        want int
    }{
        {"positive numbers", 1, 2, 3},
        {"negative numbers", -1, -2, -3},
        {"zero", 0, 0 ,0},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := Sum(tt.a , tt.b)
            if got != tt.want {
                t.Errorf("Sum(%d , %d) = %d; want %d", tt.a , tt.b , got , tt.want)
            }
        })
    }
}

• 使用外部包，如testify/assert或mock来简化你的断言或对外部的依赖性。比如说：

import (
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/mock"
)

type Calculator interface {
    Sum(a int , b int) int
}

type MockCalculator struct {
    mock.Mock
}

func (m *MockCalculator) Sum(a int , b int) int {
    args := m.Called(a , b)
    return args.Int(0)
}

2. 使用Go的测试、覆盖率、性能基准工具来运行测试和测量性能

Go提供了一套工具来运行测试和测量你的代码的性能。你可以使用这些工具来确保你的代码按预期工作，检测错误或bug，并优化你的代码以提高速度和效率。

要使用go test、coverage、benchmark工具来运行测试和测量你的Go CLI程序的性能，你应该遵循一些步骤，比如说。

• 将以_test.go结尾的测试文件写在与被测试代码相同的包中。例如：sum_test.go用于测试sum.go。
• 使用go测试命令来运行一个包中的所有测试或某个特定的测试文件。你也可以使用一些标志，如-v，用于显示verbose的输出，-run用于按名字过滤测试用例，-cover用于显示代码覆盖率，等等。例如：go test -v -cover ./…
• 使用go工具cover命令来生成代码覆盖率的HTML报告，并高亮显示代码行。你也可以使用-func这样的标志来显示函数的代码覆盖率，用-html还可以在浏览器中打开覆盖率结果报告等等。例如：go tool cover -html=coverage.out
• 编写性能基准函数，以Benchmark开头，后面是被测试的函数或方法的名称。使用类型为*testing.B的参数b来控制迭代次数，并使用b.N、b.ReportAllocs等方法控制报告结果的输出。比如说

func BenchmarkSum(b *testing.B) {
    for i := 0; i < b.N; i++ {
        Sum(1 , 2)
    }
}

• 使用go test -bench命令来运行一个包中的所有性能基准测试或某个特定的基准文件。你也可以使用-benchmem这样的标志来显示内存分配的统计数据，-cpuprofile或-memprofile来生成CPU或内存profile文件等等。例如：go test -bench . -benchmem ./…

• 使用pprof或benchstat等工具来分析和比较CPU或内存profile文件或基准测试结果。比如说。

# Generate CPU profile
go test -cpuprofile cpu.out ./...

# Analyze CPU profile using pprof
go tool pprof cpu.out

# Generate two sets of benchmark results
go test -bench . ./... > old.txt
go test -bench . ./... > new.txt

# Compare benchmark results using benchstat
benchstat old.txt new.txt

3. 使用goreleaser包构建跨平台的二进制文件

构建跨平台二进制文件意味着将你的代码编译成可执行文件，可以在不同的操作系统和架构上运行，如Windows、Linux、Mac OS、ARM等。这可以帮助你向更多的人分发你的程序，使用户更容易安装和运行你的程序而不需要任何依赖或配置。

为了给你的Go CLI程序建立跨平台的二进制文件，你可以使用外部软件包，比如goreleaser等 ，它们可以自动完成程序的构建、打包和发布过程。下面是使用goreleaser包构建程序的一些步骤。

• 使用go get或go install命令安装goreleaser。例如： go install github.com/goreleaser/goreleaser@latest
• 创建一个配置文件（通常是.goreleaser.yml），指定如何构建和打包你的程序。你可以定制各种选项，如二进制名称、版本、主文件、输出格式、目标平台、压缩、校验和、签名等。例如。

# .goreleaser.yml
project_name: mycli
builds:
  - main: ./cmd/mycli/main.go
    binary: mycli
    goos:
      - windows
      - darwin
      - linux
    goarch:
      - amd64
      - arm64
archives:
  - format: zip
    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
    files:
      - LICENSE.txt
      - README.md
checksum:
  name_template: "{{ .ProjectName }}_checksums.txt"
  algorithm: sha256

运行goreleaser命令，根据配置文件构建和打包你的程序。你也可以使用-snapshot用于测试，-release-notes用于从提交信息中生成发布说明，-rm-dist用于删除之前的构建，等等。例如：goreleaser –snapshot –rm-dist。

检查输出文件夹（通常是dist）中生成的二进制文件和其他文件。你也可以使用goreleaser的发布功能将它们上传到源代码库或软件包管理器中。

七. clig.dev指南要点

通过上述的系统说明，你现在应该可以设计并使用Go实现出一个CLI程序了。不过本文并非覆盖了clig.dev指南的所有要点，因此，在结束本文之前，我们再来回顾一下clig.dev指南中的要点，大家再体会一下。

前面说过，clig.dev上的cli指南是一个开源指南，可以帮助你写出更好的命令行程序，它采用了传统的UNIX原则，并针对现代的情况进行了更新。

遵循cli准则的一些好处是：

• 你可以创建易于使用、理解和记忆的CLI程序。
• 你可以设计出能与其他程序进行很好配合的CLI程序，并遵循共同的惯例。
• 你可以避免让用户和开发者感到沮丧的常见陷阱和错误。
• 你可以从其他CLI设计者和用户的经验和智慧中学习。

下面是该指南的一些要点：

• 理念

这一部分解释了好的CLI设计背后的核心原则，如人本设计、可组合性、可发现性、对话性等。例如，以人为本的设计意味着CLI程序对人类来说应该易于使用和理解，而不仅仅是机器。可组合性意味着CLI程序应该通过遵循共同的惯例和标准与其他程序很好地协作。

• 参数和标志

这一部分讲述了如何在你的CLI程序中使用位置参数(positional arguments )和标志。它还解释了如何处理默认值、必传参数、布尔标志、多值等。例如，你应该对命令的主要对象或动作使用位置参数，对修改或可选参数使用标志。你还应该使用长短两种形式的标志（如-v或-verbose），并遵循常见的命名模式（如–help或–version）。

• 配置

这部分介绍了如何使用配置文件和环境变量来为你的CLI程序存储持久的设置。它还解释了如何处理配置选项的优先级、验证、文档等。例如，你应该使用配置文件来处理用户很少改变的设置，或者是针对某个项目或环境的设置。对于特定于环境或会话的设置（如凭证或路径），你也应该使用环境变量。

• 输出

这部分介绍了如何格式化和展示你的CLI程序的输出。它还解释了如何处理输出verbose级别、进度指示器、颜色、表格等。例如，你应该使用标准输出（stdout）进行正常的输出，这样输出的信息可以通过管道输送到其他程序或文件。你还应该使用标准错误（stderr）来处理不属于正常输出流的错误或警告。

• 错误

这部分介绍了如何在你的CLI程序中优雅地处理错误。它还解释了如何使用退出状态码、错误信息、堆栈跟踪等。例如，你应该使用表明错误类型的退出代码（如0代表成功，1代表一般错误）。你还应该使用简洁明了的错误信息，解释出错的原因以及如何解决。

• 子命令

这部分介绍了当CLI程序有多种操作或操作模式时，如何在CLI程序中使用子命令。它还解释了如何分层构建子命令，组织帮助文本，以及处理常见的子命令（如help或version）。例如，当你的程序有不同的功能，需要不同的参数或标志时（如git clone或git commit），你应该使用子命令。你还应该提供一个默认的子命令，或者在没有给出子命令时提供一个可用的子命令列表。

业界有许多精心设计的CLI工具的例子，它们都遵循cli准则，大家可以通过使用来深刻体会一下这些准则。下面是一些这样的CLI工具的例子：

• httpie：一个命令行HTTP客户端，具有直观的UI，支持JSON，语法高亮，类似wget的下载，插件等功能。例如，Httpie使用清晰简洁的语法进行HTTP请求，支持多种输出格式和颜色，优雅地处理错误并提供有用的文档。

• git：一个分布式的版本控制系统，让你管理你的源代码并与其他开发者合作。例如，Git使用子命令进行不同的操作（如git clone或git commit），遵循通用的标志（如-v或-verbose），提供有用的反馈和建议（如git status或git help），并支持配置文件和环境变量。

• npm：一个JavaScript的包管理器，让你为你的项目安装和管理依赖性。例如，NPM使用一个简单的命令结构（npm [args]），提供一个简洁的初始帮助信息，有更详细的选项（npm help npm），支持标签完成和合理的默认值，并允许你通过配置文件（.npmrc）自定义设置。

八. 小结

在这篇文章中，我们系统说明了如何编写出遵循命令行接口指南的Go CLI程序。

你学习了如何设置Go环境、设计命令行接口、处理错误和信号、编写文档、使用各种工具和软件包测试和发布程序。你还看到了一些代码和配置文件的例子。通过遵循这些准则和最佳实践，你可以创建一个用户友好、健壮和可靠的CLI程序。

最后我们回顾了clig.dev的指南要点，希望你能更深刻理解这些要点的含义。

我希望你喜欢这篇文章并认为它很有用。如果你有任何问题或反馈，请随时联系我。编码愉快！

注：本文系与New Bing Chat联合完成，旨在验证如何基于AIGC能力构思和编写长篇文章。文章内容的正确性经过笔者全面审校，可放心阅读。

“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群！高品质首发Go技术文章，“三天”首发阅读权，每年两期Go语言发展现状分析，每天提前1小时阅读到新鲜的Gopher日报，网课、技术专栏、图书内容前瞻，六小时内必答保证等满足你关于Go语言生态的所有需求！2023年，Gopher部落将进一步聚焦于如何编写雅、地道、可读、可测试的Go代码，关注代码质量并深入理解Go核心技术，并继续加强与星友的互动。欢迎大家加入！

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

程序员步入“大龄”，写代码的节奏也会受到影响。以前是长时间持续地写，现在写代码的节奏变成了“波浪形”：即写一段时间，歇一段时间。当然这里的“歇”并不是真的歇，而是做其他事情了，比如：回顾、整理与总结。

平时写Go代码，时不时就遇到一些问题，或是写出一些让自己还算满意的代码，这里全部列为“问题”行列。这些“问题”(以及其解决方法)往往比较“小”、比较“碎片”，不适合以自己“擅长”的“长篇”风格写出来分享，也不知道以什么样的“题目”去分享更好，但这样的“问题”在日常又总是会遇到。考量来考量去，赶脚还是用一系列的文章去分享比较合适，即每隔一段时间，积累了一些问题后，就写一篇文章分享一下。

这是第一篇，后续不确定时间地(注意：这不是weekly的哦)发布新篇，直到没啥可写了或不写Go代码了^0^。

一、Go包管理

首当其冲的是Go包管理。

1. vendor的“传染性”带来的问题

Go从1.5版本开始引入vendor机制以辅助Go的包管理。随着vendor机制的应用日益广泛，我们会发现：有些时候你要是不用vendor（在不借助第三方包管理工具的前提下），很多编译问题是解决不了的，或者说vendor机制有一定的传染性。比如下面这个例子：

如上图所示：app_c包直接调用lib_a包中函数，并使用了lib_b包(v0.2版本)中的类型，lib_a包vendor了lib_b包(v0.1版本)。在这样的情况下，当我们编译app_c包时，是否会出现什么问题呢？我们一起来看一下这个例子：

在$GOPATH/src路径下面我们查看当前示例的目录结构：

$tree
├── app_c
    ├── c.go
├── lib_a
    ├── a.go
    └── vendor
        └── lib_b
            └── b.go
├── lib_b
    ├── b.go

各个源文件的示例代码如下：

//lib_a/a.go
package lib_a

import "lib_b"

func Foo(b lib_b.B) {
    b.Do()
}

//lib_a/vendor/lib_b/b.go

package lib_b

import "fmt"

type B struct {
}

func (*B) Do() {
    fmt.Println("lib_b version:v0.1")
}

// lib_b/b.go
package lib_b

import "fmt"

type B struct {
}

func (*B) Do() {
    fmt.Println("lib_b version:v0.2")
}

// app_c/c.go
package app_c

import (
    "lib_a"
    "lib_b"
)

func main() {
    var b lib_b.B
    lib_a.Foo(b)
}

进入app_c目录，执行编译命令：

$go build c.go
# command-line-arguments
./c.go:10:11: cannot use b (type "lib_b".B) as type "lib_a/vendor/lib_b".B in argument to lib_a.Foo

我们看到go compiler认为：app_c包main函数中定义的变量b的类型(lib_b.B)与lib_a.Foo的参数b的类型(lib_a/vendor/lib_b.B)是不同的类型，不能相互赋值。

2. 通过手工vendor解决上述问题

这个例子非常有代表性，那么怎么解决这个问题呢？我们需要在app_c中也使用vendor机制，即将app_c所需的lib_a和lib_b都vendor到app_c中。

按照上述思路解决后的示例的目录结构：

$tree
├── app_c
    ├── c.go
    └── vendor
        ├── lib_a
        │   └── a.go
        └── lib_b
            └── b.go
├── lib_a
    ├── a.go
    └── vendor
        └── lib_b
            └── b.go
├── lib_b
    ├── b.go

不过要注意的是：app_c/vendor下面的库中的vendor目录要被删除掉的，我们只保留顶层vendor。现在我们再来编译c.go就可以顺利编译通过了。

3. 使用dep

对于demo或规模不大、依赖不多的小项目，手工进行vendor还是蛮有效的。一个可行的手工vendor步骤：

• 在项目顶层创建vendor；
• 通过go list -json ./…查看项目依赖 “deps”;
• 逐一下载各个依赖，并确定要使用的版本(tag or branch)，将特定版本cp到顶层的vendor目录下，至少要做到vendor所有直接依赖包；
• 可以在顶层vendor下创建dependencies.list文件，手工记录vendor的依赖包列表以及版本信息。

但是对于稍大一点的项目，手工vendor就会费时费力，有时仅能顾及到“直接依赖包”的vendor，“数不清”的间接依赖/传递依赖会让你头疼不已。这个时候我们会想到使用第三方的包管理工具。在现在这个时间点，如果你再和我提godep、glide等，那你就out了，dep是首选。

在《初窥dep》一文中，我们对当时的dep进行了较为详细的工作机制分析，如今dep已经演化到0.3.2版本了，并且commandline交互接口已经稳定了。dep init默认采用network mode，即到各个依赖包的upstream上查找版本信息并下载；dep init也支持-gopath模式，即在本地$GOPATH下获取依赖包的元信息并分析。

不过，对于在国内的gopher，dep init的过程依然是一道很难逾越的“坎”。问题多出在：第三方包特别喜欢依赖的golang.org/x下的那些包，常见的包有：net、text、crypto等。golang.org/x/{package_name}仅仅是canonical import path，真正的代码存储在go.googlesource.com上，而在国内get这些包，我们会得到如下错误：

$go get -u golang.org/x/net
package golang.org/x/net: unrecognized import path "golang.org/x/net" (https fetch: Get https://golang.org/x/net?go-get=1: dial tcp 216.239.37.1:443: i/o timeout)

这将导致dep init命令长期阻塞，给国内gopher带来极为糟糕的体验。更为糟糕的是，即便是采用了一些fan qiang方式，有些时候go.googlesource.com依旧无法连接。因此，我一般的作法是在国外的主机上进行dep init，然后将vendor checkin到代码仓库中。这样其他人在得到你的代码后，也不需dep ensure(也要下载依赖包)即可实现reproducable build。

有些朋友可能会将从github.com/golang上下载的net包来代替golang.org/x/net，并使用dep init -v -gopath=true的模式。但这种替换会被dep分析出来，因为dep会尝试去读取代码库的元信息，结果依然会是失败。

二. 非容器化应用的本地日志管理

在微服务、容器化大行其道的今天，单个应用的日志处理变得简单化了，应用只需要将要输出的信息输出到stdout、stderr上即可。logging基础设施会收集容器日志，并做后续归档、分析、过滤、查找、展示等处理。但是在非容器环境、在没有统一的logging基础设施的前提下，日志的管理就又交还给应用自身了。浅显的日志管理至少要包含日志的rotate(轮转)、压缩归档以及历史归档文件的处理吧。这里我们就来探讨一下这个问题的几种解决方法。

1. 托管给logrotate

在主流的Linux发行版上都有一个logrotate工具程序，应用程序可以借助该工具对应用输出的日志进行rotate、压缩、归档和删除历史归档日志，这样可大幅简化应用的日志输出逻辑，应用仅需要将日志输出到一个具名文件中即可，其余都交给logrotate处理。

我们建立一个输出log的demo app:

//testlogrotate.go

package main

import (
    "log"
    "os"
    "time"
)

func main() {
    file, err := os.OpenFile("./app.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
    if err != nil {
        log.Fatalln("Failed to open log file:", err)
    }
    defer file.Close()

    logger := log.New(file,
        "APP_LOG_PREFIX: ",
        log.Ldate|log.Ltime|log.Lshortfile)

    for {
        logger.Println("test log")
        time.Sleep(time.Second * 1)
    }
}

该程序每隔1s向app.log文件写入一行日志。

# tail -f app.log
APP_LOG_PREFIX: 2018/01/12 19:14:43 testlogrotate.go:22: test log
APP_LOG_PREFIX: 2018/01/12 19:14:44 testlogrotate.go:22: test log
APP_LOG_PREFIX: 2018/01/12 19:14:45 testlogrotate.go:22: test log
APP_LOG_PREFIX: 2018/01/12 19:14:46 testlogrotate.go:22: test log
APP_LOG_PREFIX: 2018/01/12 19:14:47 testlogrotate.go:22: test log
... ..

接下来，我们就要用logrotate对该app.log文件进行定期的rotate、压缩归档以及历史归档清理了，我们需要为app.log定制一个配置。logrotate读取配置的目录是/etc/logrotate.d，我们在/etc/logrotate.d下面建立applog文件(当然你也可以在任意其他目录下建立配置文件，不过其他目录下的配置文件无法被logrotate的cron任务感知到，不过这样的配置文件可以手工与logrotate程序结合使用)，文件内容如下：

# cat /etc/logrotate.d/applog

/data/tonybai/test/go/app.log {
  rotate 7
  daily
  size=10M
  compress
  dateext
  missingok
  copytruncate
}

这个配置的大致含义是：
* 每天rotate一次
* 日志保留7天(rotate=7, daily rotate)
* 归档日志采用压缩形式
* 归档日志带有时间戳
* 当当前日志size > 10M时，会进行一次rotate
* 最重要的是copytruncate这个配置，这个配置的含义是将app.log当前日志copy到一个归档文件后，对app.log进行truncate操作，这样app.log的open file fd并不改变，不会影响到原app继续写日志。当然这个copy的过程中可能会有少量日志lost。

如果你觉得logrotate在时间粒度和精确度上依旧无法满足你的要求，你可以结合crontab自己定时执行logrotate(crontab -e编辑crontab的配置)：

# logrotate -f /etc/logrotate.d/applog

下面是rotate时，tail -f中看到的情况：

APP_LOG_PREFIX: 2018/01/12 20:25:59 testlogrotate.go:21: test log
APP_LOG_PREFIX: 2018/01/12 20:26:00 testlogrotate.go:21: test log
tail: app.log: file truncated
APP_LOG_PREFIX: 2018/01/12 20:26:01 testlogrotate.go:21: test log
APP_LOG_PREFIX: 2018/01/12 20:26:02 testlogrotate.go:21: test log
APP_LOG_PREFIX: 2018/01/12 20:26:03 testlogrotate.go:21: test log

可以看到tail可以检测到file truncate事件。

2. 使用自带rotate功能log包

在go技术栈中众多的logging包中，logrus是使用较为广泛的一个包，支持与std库 log API兼容的结构化日志、支持logging level设置、支持安全地并发写日志以及hook等。但logrus自身并不具备auto rotate功能，需要结合其他工具才能实现。这里用nate finch的lumberjack，我们来看一个简单的例子：

// testlogrusAndlumberjack.go

package main

import (
    "time"

    "github.com/natefinch/lumberjack"
    log "github.com/sirupsen/logrus"
)

func main() {
    logger := log.New()
    logger.SetLevel(log.DebugLevel)
    logger.Formatter = &log.JSONFormatter{}

    logger.Out = &lumberjack.Logger{
        Filename:   "./app.log",
        MaxSize:    1, // megabytes
        MaxBackups: 3,
        MaxAge:     1,    //days
        Compress:   true, // disabled by default
        LocalTime:  true,
    }

    for {
        logger.Debug("this is an app log")
        time.Sleep(2 * time.Millisecond)
    }
}

从代码里，我们看到：通过设置logger.Out为一个lumberjack.Logger的实例，将真正的Write交给了lumberjack.Logger，而后者实现了log的rotate功能，与logrotate的配置有些类似，这里也包括日志最大size设定、保留几个归档日志、是否压缩、最多保留几天的日志。不过当前lumberjack实现的rotate判断条件仅有一个：MaxSize，而没有定时rotate的功能。

我们执行一下该程序，等待一会，并停止程序。可以看到目录下的日志文件发生了变化：

$ls -lh
-rw-r--r--  1 tony  staff   3.7K Jan 12 21:03 app-2018-01-12T21-03-42.844.log.gz
-rw-r--r--  1 tony  staff   3.7K Jan 12 21:04 app-2018-01-12T21-04-15.017.log.gz
-rw-r--r--  1 tony  staff   457K Jan 12 21:04 app.log

lumberjack每发现app.log大于MaxSize就会rotate一次，这里已经有了两个归档压缩文件，并被lumberjack赋予了时间戳和序号，便于检索和查看。

3. 关于对日志level的支持以及loglevel的热更新

对日志level的支持是logging包选项的一个重要参考要素。logrus支持设置六个log level：

    PanicLevel
    FatalLevel
    ErrorLevel
    WarnLevel
    InfoLevel
    DebugLevel

并且对不同的leve的日志，logrus支持设定hook分别处理，比如：放到不同的日志文件中。通过logrus.Logger.SetLevel方法可以运行时更新logger实例的loglevel，这个特性可以让我们在生产环境上通过临时打开debuglevel日志对程序进行更细致的观察，以定位问题，快速定位bug，非常实用。

结合系统Signal机制，我们可以通过USR1和USR2两个signal来运行时调整程序的日志级别，我们来看一个示例：

从上面图片可以看到，日志级别从高到低分别为：Panic, Fatal, Error, Warn，Info和Debug。如果要调高log level，我们向程序发送USR1来调高日志级别，相反，发送USR2来调低日志级别：

我们在testlogrusAndlumberjack.go上面做些修改：增加对signal: USR1和USR2的监听处理，同时循环打印各种级别日志，以后续验证日志级别的动态调整：

// testloglevelupdate.go

import (
    log "github.com/sirupsen/logrus"
    ... ...
)

func main() {
    logger := log.New()
    logger.SetLevel(log.DebugLevel)
    logger.Formatter = &log.JSONFormatter{}

    logger.Out = &lumberjack.Logger{
        Filename:   "./app.log",
        MaxSize:    1, // megabytes
        MaxBackups: 3,
        MaxAge:     1,    //days
        Compress:   true, // disabled by default
        LocalTime:  true,
    }

    c := make(chan os.Signal, 1)
    signal.Notify(c, syscall.SIGUSR1, syscall.SIGUSR2)
    go watchAndUpdateLoglevel(c, logger)

    for {
        logger.Debug("it is debug level log")
        logger.Info("it is info level log")
        logger.Warn("it is warning level log")
        logger.Error("it is warning level log")
        time.Sleep(5 * time.Second)
    }
}

watchAndUpdateLoglevel函数用于监听程序收到的系统信号，并根据信号类型调整日志级别：

// testloglevelupdate.go
func watchAndUpdateLoglevel(c chan os.Signal, logger *log.Logger) {
    for {
        select {
        case sig := <-c:
            if sig == syscall.SIGUSR1 {
                level := logger.Level
                if level == log.PanicLevel {
                    fmt.Println("Raise log level: It has been already the most top log level: panic level")
                } else {
                    logger.SetLevel(level - 1)
                    fmt.Println("Raise log level: the current level is", logger.Level)
                }

            } else if sig == syscall.SIGUSR2 {
                level := logger.Level
                if level == log.DebugLevel {
                    fmt.Println("Reduce log level: It has been already the lowest log level: debug level")
                } else {
                    logger.SetLevel(level + 1)
                    fmt.Println("Reduce log level: the current level is", logger.Level)
                }

            } else {
                fmt.Println("receive unknown signal:", sig)
            }
        }
    }
}

运行该程序后，你可以通过如下命令向程序发送信号：

$ kill -s USR1|USR2 程序的进程号

通过日志的输出，可以判断出日志级别调整是否生效，这里就不细说了。

不过这里还要提一点的是logrus目前对于输出的日志中双引号内的一些字符（比如双引号自身）会做转义处理，即在前面加上“反斜杠”，比如：

{"level":"debug","msg":"receive a msg: {\"id\":\"000002\",\"ip\":\"201.108.111.117\"}","time":"2018-01-11T20:42:31+08:00"}

这个问题让日志可读性大幅下降，但这个问题似乎尚处于无解状态

三. json marshal json string时的转义问题

之前写过这样一个function，用于统一marshal内部组件通信的应答消息：

func marshalResponse(code int, msg string, result interface{}) (string, error) {
    m := map[string]interface{}{
        "code":   0,
        "msg":    "ok",
        "result": result,
    }

    b, err := json.Marshal(&m)
    if err != nil {
        return "", err
    }

    return string(b), nil
}

不过当result类型为json string时，这个函数的输出带有转义反斜线：

//testmarshaljsonstring.go
... ...
func main() {
    s, err := marshalResponse(0, "ok", `{"name": "tony", "city": "shenyang"}`)
    if err != nil {
        fmt.Println("marshal response error:", err)
        return
    }
    fmt.Println(s)
}

运行这个程序输出：

{"code":0,"msg":"ok","result":"{\"name\": \"tony\", \"city\": \"shenyang\"}"}

怎么解决掉这个问题呢？json提供了一种RawMessage类型，本质上就是[]byte，我们将json string转换成RawMessage后再传给json.Marshal就可以解决掉这个问题了：

//testmarshaljsonstring.go
func marshalResponse1(code int, msg string, result interface{}) (string, error) {
    s, ok := result.(string)
    var m = map[string]interface{}{
        "code": 0,
        "msg":  "ok",
    }

    if ok {
        rawData := json.RawMessage(s)
        m["result"] = rawData
    } else {
        m["result"] = result
    }

    b, err := json.Marshal(&m)
    if err != nil {
        return "", err
    }

    return string(b), nil
}

func main() {
    s, err = marshalResponse1(0, "ok", `{"name": "tony", "city": "shenyang"}`)
    if err != nil {
        fmt.Println("marshal response1 error:", err)
        return
    }
    fmt.Println(s)
}

再运行这个程序的输出结果就变成了我们想要的结果了：

{"code":0,"msg":"ok","result":{"name":"tony","city":"shenyang"}}

四. 如何在main包之外使用flag.Parse后的命令行flag变量

我们在使用Go开发交互界面不是很复杂的command-line应用时，一般都会使用std中的flag包进行命令行flag解析，并在main包中校验和使用flag.Parse后的flag变量。常见的套路是这样的：

//testflag1.go
package main

import (
    "flag"
    "fmt"
)

var (
    endpoints string
    user      string
    password  string
)

func init() {
    flag.StringVar(&endpoints, "endpoints", "127.0.0.1:2379", "comma-separated list of etcdv3 endpoints")
    flag.StringVar(&user, "user", "", "etcdv3 client user")
    flag.StringVar(&password, "password", "", "etcdv3 client password")
}

func usage() {
    fmt.Println("flagdemo-app is a daemon application which provides xxx service.\n")
    fmt.Println("Usage of flagdemo-app:\n")
    fmt.Println("\t flagdemo-app [options]\n")
    fmt.Println("The options are:\n")

    flag.PrintDefaults()
}

func main() {
    flag.Usage = usage
    flag.Parse()

   // ... ...
   // 这里我们可以使用endpoints、user、password等flag变量了
}

在这样的一个套路中，我们可以在main包中直接使用flag.Parse后的flag变量了。但有些时候，我们需要在main包之外使用这些flag vars(比如这里的：endpoints、user、password)，怎么做呢，有几种方法，我们逐一来看看。

1. 全局变量法

我想大部分gopher第一个想法就是使用全局变量，即建立一个config包，包中定义全局变量，并在main中将这些全局变量绑定到flag的Parse中：

$tree globalvars
globalvars
├── config
│   └── config.go
├── etcd
│   └── etcd.go
└── main.go

// flag-demo/globalvars/config/config.go

package config

var (
    Endpoints string
    User      string
    Password  string
)

// flag-demo/globalvars/etcd/etcd.go
package etcd

import (
    "fmt"

    "../config"
)

func EtcdProxy() {
    fmt.Println(config.Endpoints, config.User, config.Password)
    //... ....
}

// flag-demo/globalvars/main.go
package main

import (
    "flag"
    "fmt"
    "time"

    "./config"
    "./etcd"
)

func init() {
    flag.StringVar(&config.Endpoints, "endpoints", "127.0.0.1:2379", "comma-separated list of etcdv3 endpoints")
    flag.StringVar(&config.User, "user", "", "etcdv3 client user")
    flag.StringVar(&config.Password, "password", "", "etcdv3 client password")
}

.... ...

func main() {
    flag.Usage = usage
    flag.Parse()

    go etcd.EtcdProxy()

    time.Sleep(5 * time.Second)
}

可以看到，我们在绑定cmdline flag时使用的是config包中定义的全局变量。并且在另外一个etcd包中，使用了这些变量。

我们运行这个程序：

./main -endpoints 192.168.10.69:2379,10.10.12.36:2378 -user tonybai -password xyz123
192.168.10.69:2379,10.10.12.36:2378 tonybai xyz123

不过这种方法要注意这些全局变量值在Go包初始化过程的顺序，比如：如果在etcd包的init函数中使用这些全局变量，那么你得到的各个变量值将为空值，因为etcd包的init函数在main.init和main.main之前执行，这个时候绑定和Parse都还未执行。

2. 传参法

第二种比较直接的想法就是将Parse后的flag变量以参数的形式、以某种init的方式传给其他要使用这些变量的包。

$tree parampass
parampass
├── etcd
│   └── etcd.go
└── main.go

// flag-demo/parampass/etcd/etcd.go
package etcd
... ...

func EtcdProxy(endpoints, user, password string) {
    fmt.Println(endpoints, user, password)
}

// flag-demo/parampass/main.go
package main

import (
    "flag"
    "fmt"
    "time"

    "./etcd"
)

var (
    endpoints string
    user      string
    password  string
)

func init() {
    flag.StringVar(&endpoints, "endpoints", "127.0.0.1:2379", "comma-separated list of etcdv3 endpoints")
    flag.StringVar(&user, "user", "", "etcdv3 client user")
    flag.StringVar(&password, "password", "", "etcdv3 client password")
}

... ...

func main() {
    flag.Usage = usage
    flag.Parse()

    go etcd.EtcdProxy(endpoints, user, password)

    time.Sleep(5 * time.Second)
}

这种方法非常直观，这里就不解释了。但注意：一旦使用这种方式，一定需要在main包与另外的包之间建立某种依赖关系，至少main包会import那些使用flag变量的包。

3. 配置中心法

全局变量法直观，而且一定程度上解除了其他包与main包的耦合。但是有一个问题，那就是一旦flag变量发生增减，config包就得相应添加或删除变量定义。是否有一种方案可以在flag变量发生变化时，config包不受影响呢？我们可以用配置中心法。所谓的配置中心法，就是实现一个与flag变量类型和值无关的通过配置存储结构，我们在main包中向该结构注入parse后的flag变量，在其他需要flag变量的包中，我们使用该结构得到flag变量的值。

$tree configcenter
configcenter
├── config
│   └── config.go
└── main.go

//flag-demo/configcenter/config/config.go
package config

import (
    "log"
    "sync"
)

var (
    m  map[string]interface{}
    mu sync.RWMutex
)

func init() {
    m = make(map[string]interface{}, 10)
}

func SetString(k, v string) {
    mu.Lock()
    m[k] = v
    mu.Unlock()
}

func SetInt(k string, i int) {
    mu.Lock()
    m[k] = i
    mu.Unlock()
}

func GetString(key string) string {
    mu.RLock()
    defer mu.RUnlock()
    v, ok := m[key]
    if !ok {
        return ""
    }
    return v.(string)
}

func GetInt(key string) int {
    mu.RLock()
    defer mu.RUnlock()
    v, ok := m[key]
    if !ok {
        return 0
    }
    return v.(int)
}

func Dump() {
    log.Println(m)
}

// flag-demo/configcenter/main.go

package main

import (
    "flag"
    "fmt"
    "time"

    "./config"
)

var (
    endpoints string
    user      string
    password  string
)

func init() {
    flag.StringVar(&endpoints, "endpoints", "127.0.0.1:2379", "comma-separated list of etcdv3 endpoints")
    flag.StringVar(&user, "user", "", "etcdv3 client user")
    flag.StringVar(&password, "password", "", "etcdv3 client password")
}
... ...
func main() {
    flag.Usage = usage
    flag.Parse()

    // inject flag vars to config center
    config.SetString("endpoints", endpoints)
    config.SetString("user", user)
    config.SetString("password", password)

    time.Sleep(5 * time.Second)
}

我们在main中使用config的SetString将flag vars注入配置中心。之后，我们在其他包中就可以使用：GetString、GetInt获取这些变量值了，这里就不举例了。

4、“黑魔法”: flag.Lookup

flag包中提供了一种类似上述的”配置中心”的机制，但这种机制不需要我们显示注入“flag vars”了，我们只需按照flag提供的方法在其他package中读取对应flag变量的值即可。

$tree flaglookup
flaglookup
├── etcd
│   └── etcd.go
└── main.go

// flag-demo/flaglookup/main.go
package main

import (
    "flag"
    "fmt"
    "time"

    "./etcd"
)

var (
    endpoints string
    user      string
    password  string
)

func init() {
    flag.StringVar(&endpoints, "endpoints", "127.0.0.1:2379", "comma-separated list of etcdv3 endpoints")
    flag.StringVar(&user, "user", "", "etcdv3 client user")
    flag.StringVar(&password, "password", "", "etcdv3 client password")
}

......

func main() {
    flag.Usage = usage
    flag.Parse()

    go etcd.EtcdProxy()

    time.Sleep(5 * time.Second)
}

// flag-demo/flaglookup/etcd/etcd.go
package etcd

import (
    "flag"
    "fmt"
)

func EtcdProxy() {
    endpoints := flag.Lookup("endpoints").Value.(flag.Getter).Get().(string)
    user := flag.Lookup("user").Value.(flag.Getter).Get().(string)
    password := flag.Lookup("password").Value.(flag.Getter).Get().(string)

    fmt.Println(endpoints, user, password)
}

运行该程序：

$go run main.go -endpoints 192.168.10.69:2379,10.10.12.36:2378 -user tonybai -password xyz123
192.168.10.69:2379,10.10.12.36:2378 tonybai xyz123

输出与我们的预期是一致的。

5、对比

我们用一幅图来对上述几种方法进行对比：

很显然，经过简单包装后，“黑魔法”flaglookup应该是比较优异的方案。main包、other packages只需import flag即可。

注意：在main包中定义exported的全局flag变量并被其他package import的方法是错误的，很容易造成import cycle问题。并且任何其他package import main包都是不合理的。

五. 小结

以上是这段时间遇到的、收集的一些Go问题以及solution。注意：这些solution不一定是最优方案哦！如果您有更好方案，欢迎批评指正和互动交流。

本文章中涉及到的所有源码和配置文件在这里可以下载到。

微博：@tonybai_cn
微信公众号：iamtonybai
github.com: https://github.com/bigwhite

微信赞赏：