上周，OpenSauced 工程团队发布了 Pizza CLI，这是一个功能强大且可组合的命令行工具，用于生成 CODEOWNER 文件并与 OpenSauced 平台集成。构建强大的命令行工具可能看起来很简单，但如果没有仔细的规划和深思熟虑的范例，CLI 很快就会变成难以维护且充满错误的混乱代码。在这篇博文中，我们将深入探讨如何使用 Go 构建此 CLI、如何使用 Cobra 组织命令，以及我们的精益工程团队如何快速迭代以构建强大的功能。

使用 Go 和 Cobra

Pizza CLI 是一个 Go 命令行工具，利用多个标准库。 Go 的简单性、速度和系统编程重点使其成为构建 CLI 的理想选择。 Pizza-CLI 的核心是使用 spf13/cobra（Go 中的 CLI 引导库）来组织和管理整个命令树。

您可以将 Cobra 视为使命令行界面本身正常工作的脚手架，使所有标志能够一致地运行，并通过帮助消息和自动文档处理与用户的通信。

构建代码库

构建基于 Cobra 的 Go CLI 时的首要（也是最大）挑战之一是如何构建所有代码和文件。与普遍的看法相反，没有规定的方法可以在 Go 中做到这一点。 go build 命令和 gofmt 实用程序都不会抱怨您如何命名包或组织目录。这是 Go 最好的部分之一：它的简单性和强大功能使您可以轻松定义适合您和您的工程团队的结构！

最终，在我看来，最好将基于 Cobra 的 Go 代码库视为命令树：

├── Root command
│   ├── Child command
│   ├── Child command
│   │   └── Grandchild command

树的底部是根命令：这是整个 CLI 应用程序的锚点，并将获取 CLI 的名称。作为子命令附加，您将拥有一个分支逻辑树，它告知整个 CLI 流程如何工作的结构。

构建 CLI 时最容易忽略的事情之一就是用户体验。我通常建议人们在构建命令和子命令结构时遵循“根动词名词”范例，因为它逻辑流畅并带来出色的用户体验。

例如，在 Kubectl 中，您会随处看到这种范例：“kubectl get pods”、“kubectl apply …”或“kubectl label pods …”这确保了用户如何与命令行交互的合理流程应用程序，并且在与其他人谈论命令时有很大帮助。

最后，这个结构和建议可以告诉您如何组织文件和目录，但最终还是由您决定如何构建 CLI 并向最终用户呈现流程。

在 Pizza CLI 中，我们有一个定义良好的结构，子命令（以及这些子命令的后续子命令）所在的结构。在各自包的 cmd 目录下，每个命令都有自己的实现。 root 命令脚手架存在于 pkg/utils 目录中，因为将 root 命令视为 main.go 使用的顶级实用程序非常有用，而不是可能需要大量维护的命令。通常，在你的根命令 Go 实现中，你将有很多样板设置你不会接触太多的东西，所以最好把这些东西去掉。

这是我们目录结构的简化视图：

├── main.go
├── pkg/
│   ├── utils/
│   │   └── root.go
├── cmd/
│   ├── Child command dir
│   ├── Child command dir
│   │   └── Grandchild command dir

这种结构可以清晰地分离关注点，并且随着 CLI 的增长以及我们添加更多命令，更容易维护和扩展 CLI。

使用 go-git

我们在 Pizza-CLI 中使用的主要库之一是 go-git 库，它是 Go 中的一个纯 git 实现，具有高度可扩展性。在 CODEOWNERS 生成过程中，该库使我们能够迭代 git ref 日志、查看代码差异并确定哪些 git 作者与用户定义的配置属性相关联。

迭代本地 git repo 的 git ref 日志实际上非常简单：

// 1. Open the local git repository
repo, err := git.PlainOpen("/path/to/your/repo")
if err != nil {
        panic("could not open git repository")
}

// 2. Get the HEAD reference for the local git repo
head, err := repo.Head()
if err != nil {
        panic("could not get repo head")
}

// 3. Create a git ref log iterator based on some options
commitIter, err := repo.Log(&git.LogOptions{
        From:  head.Hash(),
})
if err != nil {
        panic("could not get repo log iterator")
}

defer commitIter.Close()

// 4. Iterate through the commit history
err = commitIter.ForEach(func(commit *object.Commit) error {
        // process each commit as the iterator iterates them
        return nil
})
if err != nil {
        panic("could not process commit iterator")
}

如果您正在构建基于 Git 的应用程序，我绝对推荐使用 go-git：它速度快，在 Go 生态系统中集成良好，并且可用于执行各种操作！

集成 Posthog 遥测技术

我们的工程和产品团队投入了大量资金，致力于为最终用户带来最佳的命令行体验：这意味着我们已采取措施集成匿名遥测技术，可以向 Posthog 报告实际使用情况和错误。这使我们能够首先修复最重要的错误，快速迭代流行的功能请求，并了解我们的用户如何使用 CLI。

Posthog 在 Go 中有一个第一方库支持这个确切的功能。首先，我们定义一个Posthog客户端：

import "github.com/posthog/posthog-go"

// PosthogCliClient is a wrapper around the posthog-go client and is used as a
// API entrypoint for sending OpenSauced telemetry data for CLI commands
type PosthogCliClient struct {
    // client is the Posthog Go client
    client posthog.Client

    // activated denotes if the user has enabled or disabled telemetry
    activated bool

    // uniqueID is the user's unique, anonymous identifier
    uniqueID string
}

然后，在初始化一个新客户端后，我们可以通过我们定义的各种结构体方法来使用它。例如，登录OpenSauced平台时，我们捕获成功登录的具体信息：

// CaptureLogin gathers telemetry on users who log into OpenSauced via the CLI
func (p *PosthogCliClient) CaptureLogin(username string) error {
    if p.activated {
        return p.client.Enqueue(posthog.Capture{
            DistinctId: username,
            Event:      "pizza_cli_user_logged_in",
        })
    }

    return nil
}

在命令执行期间，会调用各种“捕获”函数来捕获错误路径、正常路径等。

对于匿名 ID，我们使用 Google 优秀的 UUID Go 库：

newUUID := uuid.New().String()

这些 UUID 以 JSON 形式本地存储在最终用户计算机的主目录下：~/.pizza-cli/telemtry.json。这为最终用户提供了完全的权限和自主权，可以根据需要删除此遥测数据（或通过配置选项完全禁用遥测！），以确保他们在使用 CLI 时保持匿名。

迭代开发和测试

我们的精益工程团队遵循迭代开发流程，专注于快速交付小型、可测试的功能。通常，我们通过 GitHub 问题、拉取请求、里程碑和项目来做到这一点。我们广泛使用 Go 的内置测试框架，为单个函数编写单元测试，为整个命令编写集成测试。

不幸的是，Go 的标准测试库没有现成的强大断言功能。使用“==”或其他操作数很容易，但大多数时候，当返回并阅读测试时，能够通过诸如“assert.Equal”或“assert.Nil”之类的断言来观察发生了什么是很好的”.

我们将优秀的 testify 库与其“断言”功能集成在一起，以实现更顺畅的测试实施：

config, _, err := LoadConfig(nonExistentPath)
require.Error(t, err)
assert.Nil(t, config)

仅使用

我们大量使用 Just at OpenSauced，这是一个命令运行程序实用程序，很像 GNU 的“make”，可以轻松执行小脚本。这使我们能够快速将新的团队成员或社区成员引入我们的 Go 生态系统，因为构建和测试就像“仅构建”或“仅测试”一样简单！

例如，要在 Just 文件中创建一个简单的构建实用程序，我们可以：

build:
  go build main.go -o build/pizza

这将在 build/ 目录中构建 Go 二进制文件。现在，本地构建就像执行“just”命令一样简单。

但是我们已经能够将更多功能集成到 Just 中，并使其成为我们整个构建、测试和开发框架执行方式的基石。例如，要使用注入的构建时间变量（例如构建二进制文件的 sha、版本、日期时间等）为本地架构构建二进制文件，我们可以使用本地环境并在脚本中运行额外的步骤在执行“go build”之前：

build:
    #!/usr/bin/env sh
  echo "Building for local arch"

  export VERSION="${RELEASE_TAG_VERSION:-dev}"
  export DATETIME=$(date -u  "%Y-%m-%d-%H:%M:%S")
  export SHA=$(git rev-parse HEAD)

  go build \
    -ldflags="-s -w \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Version=${VERSION}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Sha=${SHA}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Datetime=${DATETIME}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.writeOnlyPublicPosthogKey=${POSTHOG_PUBLIC_API_KEY}'" \
    -o build/pizza

我们甚至扩展了它以支持跨架构和操作系统构建：Go 使用 GOARCH 和 GOOS 环境变量来了解要针对哪个 CPU 架构和操作系统进行构建。要构建其他变体，我们可以为此创建特定的 Just 命令：

# Builds for Darwin linux (i.e., MacOS) on arm64 architecture (i.e. Apple silicon)
build-darwin-arm64:
  #!/usr/bin/env sh

  echo "Building darwin arm64"

  export VERSION="${RELEASE_TAG_VERSION:-dev}"
  export DATETIME=$(date -u  "%Y-%m-%d-%H:%M:%S")
  export SHA=$(git rev-parse HEAD)
  export CGO_ENABLED=0
  export GOOS="darwin"
  export GOARCH="arm64"

  go build \
    -ldflags="-s -w \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Version=${VERSION}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Sha=${SHA}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.Datetime=${DATETIME}' \
    -X 'github.com/open-sauced/pizza-cli/pkg/utils.writeOnlyPublicPosthogKey=${POSTHOG_PUBLIC_API_KEY}'" \
    -o build/pizza-${GOOS}-${GOARCH}

结论

使用 Go 和 Cobra 构建 Pizza CLI 是一段激动人心的旅程，我们很高兴与您分享。 Go 的性能和简单性与 Cobra 强大的命令结构相结合，使我们能够创建一个不仅健壮、功能强大，而且用户友好且可维护的工具。

我们邀请您探索 Pizza CLI GitHub 存储库，试用该工具，并让我们知道您的想法。您的反馈和贡献非常宝贵，因为我们致力于让世界各地的开发团队更轻松地进行代码所有权管理！