云原生小技巧 : 如何自動化發布 CLI 工具？

作者：Cloud Native 101 2023-12-04 08:26:42

在自動化構建的世界中，編寫一個穩定且跨平臺兼容的構建腳本是關鍵。Golang 提供了強大的跨平臺構建能力，而 go build 命令是實現這一目標的核心。

在云原生時代，CLI 工具已成為開發者日常工作中不可或缺的一部分。然而，將開發好的 CLI 工具分享給大家使用，如果僅依賴手動發布，不僅效率低，且易出錯，特別是在處理多架構和多平臺兼容性時尤為明顯。

那么，我們如何才能實現 CLI 工具的自動化發布呢？本文旨在探討這一問題，并提出一套實用的解決方案。

在接下來的分享中，我將主要以 Golang 舉例。需要指出的是，我們將討論的自動化構建和發布的原則是通用的，適用于所有編程語言。因此，無論大家使用哪種語言編寫工具，這些實踐都將具有重要的參考價值。

編寫構建腳本

在自動化構建的世界中，編寫一個穩定且跨平臺兼容的構建腳本是關鍵。Golang 提供了強大的跨平臺構建能力，而 go build 命令是實現這一目標的核心。例如：

CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o fooctl-darwin-amd64 -v

這個命令示例突顯了 Golang 在生成特定平臺和架構二進制文件方面的靈活性。在構建腳本中，我們需要進一步擴展這種靈活性，以支持多平臺構建需求。

參數化和默認值設置：

OUTPUT_DIR 和 BINARY_NAME 的設定允許用戶自定義輸出目錄和二進制文件的名稱，加強了腳本的通用性。

BUILDPATH 變量用于指定構建路徑，是腳本運行的必需參數，保證了構建過程的穩定性。

跨平臺和架構支持：

通過設置 BUILD_GOOS 和 BUILD_GOARCH 變量，腳本能夠靈活地處理不同操作系統和架構的構建需求，增加了適用性。
這些變量的默認值通過 go env 獲取，但也可以通過參數覆蓋，提供了靈活性。

動態輸出路徑：

OUT 變量根據是否為發布版（IS_RELEASE），動態調整輸出文件的命名和路徑。這樣的設計使得腳本能夠根據不同的使用場景（如開發測試或正式發布）輸出不同格式的文件名。

特殊情況處理：

對 Windows 平臺的特殊處理（.exe 擴展名）是必要的，因為 Windows 系統下的可執行文件通常需要這個擴展名。

gobuild.sh 腳本

下面的 gobuild.sh 腳本是對上述原則的實踐，將跨平臺構建的復雜性轉化為簡單的命令行操作：

OUTPUT_DIR=${4:-"bin"}
BINARY_NAME=$(basename ${1})
BUILDPATH=./${1:?"path to build"}

BUILD_GOOS=${GOOS:-$(go env GOOS)}
BUILD_GOARCH=${GOARCH:-$(go env GOARCH)}
GOBINARY=${GOBINARY:-go}
LDFLAGS=$(version::ldflags)

if [ $# -ge 2 ] && [ -n $2 ]; then
  BUILD_GOOS=$2
fi

if [ $# -ge 3 ] && [ -n $3 ]; then
  BUILD_GOARCH=$3
fi

OUT=${OUTPUT_DIR}/${1:?"output path"}
if [ "${IS_RELEASE:-0}" == "1" ]; then
    OUT="${OUTPUT_DIR}/${BINARY_NAME}-${BUILD_GOOS}-${BUILD_GOARCH}"
    if [ "${BUILD_GOOS}" == "windows" ]; then
        OUT="${OUTPUT_DIR}/${BINARY_NAME}-${BUILD_GOOS}-${BUILD_GOARCH}.exe"
    fi
fi

CGO_ENABLED=0 GOOS=${BUILD_GOOS} GOARCH=${BUILD_GOARCH}${GOBINARY} build \
    -ldflags="${LDFLAGS}" \
    -o "${OUT}" \
    "${BUILDPATH}"

這個腳本不僅適應了多平臺和多架構的需要，還提供了足夠的靈活性和可配置性，以適應不同的構建場景。

配合 Makefile 實現全自動化構建

進一步的，結合 Makefile 可以將構建過程自動化，提升效率：

.PHONY: build-binaries

BUILD_SCRIPT_PATH := ./hack/gobuild/gobuild.sh
# 列出了需要構建的所有二進制文件，可管理多個項目的構建過程
BINARIES := cmd/fooctl cmd/barctl

# 通過 ALLPLATFORMS 變量，我們定義了一系列目標平臺和架構組合
ALLPLATFORMS := linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64

# 構建所有組合
build-binaries: $(foreach bin,$(BINARIES),$(foreach plat,$(ALLPLATFORMS),build-$(bin)-$(plat)))

# 構建規則模板
# 這個模板可以生成特定于每個二進制文件和平臺組合的構建規則。
define BUILD_template
build-$(1)-$(2):
    IS_RELEASE=1 $$(BUILD_SCRIPT_PATH) $(1) $$(subst /, ,$$(word 1,$$(subst -, ,$(2)))) $$(subst /, ,$$(word 2,$$(subst -, ,$(2))))
endef

# 生成構建規則
# 我們自動為每個二進制文件和平臺組合生成了具體的構建規則。
$(foreach bin,$(BINARIES),$(foreach plat,$(ALLPLATFORMS),$(eval $(call BUILD_template,$(bin),$(plat)))))

通過這個 Makefile，即使同時構建 fooctl 和 barctl 這兩個 CLI Tool 也變得異常簡單。一條簡單的命令 make build-binaries 就能觸發整個構建流程，大大減少了人工干預，確保了構建過程的一致性和可靠性。

小結

通過上述詳細的構建腳本和 Makefile 配置，我們可以看到，現代軟件開發中自動化構建的強大功能和必要性。這種方法不僅提升了構建效率，也增強了軟件的質量和穩定性。在云原生時代，自動化構建已成為提高開發團隊效率和產品可靠性的關鍵策略。

Release CLI tool on GitLab CI/CD

在構建腳本準備完畢后，接下來我們就可以將其集成到 CI 系統了，下面我以 GitLab CI/CD 為例。

在 GitLab CI/CD 的核心，是一系列定義明確的作業（Jobs），它們在代碼提交時自動執行。對于完整的持續集成來說，這些作業通常包括構建（build）、測試（test）、代碼審查（lint）等步驟。但在本文中，我們將重點關注自動發布流程。

觸發自動發布的條件

自動發布流程是基于 Git 標簽創建的。當開發者推送一個新標簽到倉庫時，GitLab CI/CD 會捕捉到這一事件，并啟動預定義的發布流程。

rules:
  - if: $CI_COMMIT_TAG

這個條件確保只有在創建新標簽時，才會啟動后續的構建、上傳和發布作業。

Release Jobs

步驟一：構建二進制文件，在 build-binaries 階段，CI 會構建針對不同平臺和架構的 CLI 工具二進制文件，確保構建過程的一致性和可重復性。

步驟二：上傳構建產物，待構建完成后，upload 階段負責將二進制文件上傳到 GitLab 的包管理器或其他存儲位置。這為后續的發布提供了必要的資源。

步驟三：發布到 GitLab，最后，在 release 階段，CI 使用 release-cli 工具自動創建發布，并將構建的二進制文件作為發布的資產。

Create releases from .gitlab-ci.yml

下面的 .gitlab-ci.yml 腳本是對上述發布流程的實踐：

stages:
  ...
  - build-binaries
  - upload
  - release
  
build-binaries:
  stage: build-binaries
  image: golang:1.21.1
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - echo "Building binaries for all platforms and architectures..."
    - make build-binaries
  artifacts:
    paths:
      - bin

upload:
  stage: upload
  image: curlimages/curl:latest
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - echo "Uploading binaries..."
    - >
      for binary in ./bin/*; do
        curl --header "JOB-TOKEN: $CI_JOB_TOKEN" \
             --upload-file $binary \
             "${PACKAGE_REGISTRY_URL}/$(basename $binary)";
      done
    
release:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - echo "Creating a release for $CI_COMMIT_TAG"
    - |
      ASSET_LINKS=""
      for binary in ./bin/*; do
        LINK="{\"name\":\"$(basename $binary)\", \"url\":\"${PACKAGE_REGISTRY_URL}/$(basename $binary)\"}"
        ASSET_LINKS="${ASSET_LINKS},${LINK}"
      done
      ASSET_LINKS="[${ASSET_LINKS:1}]"
    - >
      release-cli create \
        --name "Release $CI_COMMIT_TAG" \
        --tag-name $CI_COMMIT_TAG \
        --description "Created using the release-cli: $CI_COMMIT_REF_NAME-$CI_JOB_ID" \
        --ref $CI_COMMIT_SHA \
        --assets-link "$ASSET_LINKS"

以上示例將會構建 CLI 工具二進制文件，并將其上傳到 Gitlab Release 頁面。用戶從 Gitlab Release 頁面查找并下載適合其平臺的二進制包即可。

圖片

有關詳細的 GitLab CI 流程，可以參考項目：https://gitlab.com/lqshow/clireleaseautomator

小結

這個流程大大簡化了 CLI 工具的發布過程，使得開發者能夠專注于代碼開發，而不是后續的構建和發布環節。自動化這些步驟意味著每次發布都是快速、一致且無誤的，從而提高了軟件的整體質量和可靠性。

Release CLI tool use GoReleaser

不難發現，上述整個流程相對來說還是比較繁瑣的，準備腳本的過程也比較復雜，現在我將介紹一個讓這個過程不那么痛苦的工具 GoReleaser[1]。

它是一個變革性的工具，特別是對于以 Golang 編寫的項目。相比于傳統的手動配置和腳本編寫，GoReleaser 提供了一種更高效和簡潔的自動化發布方法。

GoReleaser 的優勢

GoReleaser 的設計理念是“一次配置，處處運行”，它通過一個單一的配置文件，即可控制整個發布流程。這個配置文件定義了如何構建二進制文件、如何打包它們、如何處理版本信息以及如何發布到各種平臺。具體來說，GoReleaser 的優勢包括：

簡化的構建過程：通過預定義的模板，GoReleaser 能夠自動構建針對不同平臺和架構的二進制文件，無需編寫復雜的腳本。
靈活的打包和發布：支持多種格式的打包選項，以及與主要代碼托管平臺的無縫集成。
高度可配置：從構建選項到發布設置，GoReleaser 允許高度定制化，以滿足不同項目的需求。

配置和使用 GoReleaser

使用 GoReleaser 的第一步是在項目的根目錄下創建 .goreleaser.yml 配置文件。通過 goreleaser init 命令可快速生成初始配置。這個文件涵蓋了構建、打包和發布的全過程。

在配置好 .goreleaser.yml 之后，我們需要調整 .gitignore 加上 dist，因為 goreleaser 會默認把編譯編譯好的文件輸出到 dist 目錄中。

接下來我們看個例子：

# .goreleaser.yml 示例
builds:
  - id: fooctl
    binary: fooctl
    main: ./cmd/fooctl
    ldflags:
    - -s -w
    - -X gitlab.com/lqshow/clireleaseautomator-with-goreleaser/version.gitVersinotallow={{.Version}}
    - -X gitlab.com/lqshow/clireleaseautomator-with-goreleaser/version.gitCommit={{.ShortCommit}}
    goos:
      - linux
      - darwin
      - windows
    goarch:
      - amd64
      - arm64
  - id: barctl
    binary: barctl
    main: ./cmd/barctl
    ldflags:
    - -s -w
    - -X gitlab.com/lqshow/clireleaseautomator-with-goreleaser/version.gitVersinotallow={{.Version}}
    - -X gitlab.com/lqshow/clireleaseautomator-with-goreleaser/version.gitCommit={{.ShortCommit}}
    goos:
      - linux
      - darwin
      - windows
    goarch:
      - amd64
      - arm64

這個簡單清晰的配置文件，事實上包含了我之前介紹的兩個模塊，相當于省去了寫 shell 腳本和 Makefile 文件，使整個過程更加靈活和高效。

GitLab CI 中的 GoReleaser 集成

在 .gitlab-ci.yml 文件中，我們只需要定義一個簡單的 release 作業，對了，別忘了還需要在 CI/CD 里配置一個 GTILAB_TOKEN 變量：

stages:
  - release

release:
  stage: release
  image:
    name: goreleaser/goreleaser
    entrypoint: ['']
  only:
    - tags
  variables:
    GIT_DEPTH: 0
    GITLAB_TOKEN: $GITLAB_TOKEN
  script:
    - goreleaserrelease--clean

只要查看運行日志，其實我們就會發現，GoReleaser 自動執行后，它包含了構建、上傳和發布的整個流程。

具體詳情：https://gitlab.com/lqshow/clireleaseautomator-with-goreleaser/-/jobs/5669211977

責任編輯：武曉燕來源： Cloud Native 101

CLI 工具