6、实现版本号打印功能

5、实现版本号打印功能

go项目中，为了方便排障等，需要知道某个线上应用的具体版本。另外，在开发命令行工具的时候，也需要支持-v / --version 之类的命令行参数。这时候就需要给应用添加版本号打印功能。

如何添加版本号？

实际开发中国，当完成一个应用特性开发后，会编译 应用源码并发布到生产环境。为了定位问题或出于安全考虑（确认发布的是正确的版本），开发者通常需要了解应用的版本信息及一些编译时的详细信息，例如编译时使用的go版本、git目录是否干净，以及哪个git提交id进行的编译。在一个编译好的可执行程序中，通常可以通过类似/appname -v 的方式来获取版本信息。

可以将这些信息写入版本号配置文件中，程序运行时从版本号配置文件中读取并显示。然而，在程序部署时，除了二进制文件外，还需要额外的版本号配置文件，这种方式既不方便，又面临版本号配置文件被篡改的风险，另一种方式是将这些信息直接写入代码，这样无需额外的版本号配置文件，但每次编译时都需要修改代码以更新版本号，这种方式同样不够优雅。

Go官方提供了一种更优的方式：通过编译时指定-ldflags -X importpath.name=value参数，来为程序自动注入版本信息。

实际开发中，绝大多数情况是使用git进行源码版本管理，因此fastgo的版本功能也基于git实现。

给fg-apiserver 组件添加版本号功能

可以通过以下步骤添加

1. 创建一个version包用于保存版本信息
2. 将版本信息注入到version包中
3. fg-apiserver应用添加--version命令行选项

创建一个version包

创建一个pkg/version/version.go 文件

package version

import (
	"encoding/json"
	"fmt"
	"github.com/gosuri/uitable"
	"runtime"
)

var (
	// semantic version, derived by build scripts (see
	// https://github.com/kubernetes/community/blob/master/contributors/design-proposals/release/versioning.md
	// for a detailed discussion of this field)
	//
	// TODO: This field is still called "gitVersion" for legacy
	// reasons. For prerelease versions, the build metadata on the
	// semantic version is a git hash, but the version itself is no
	// longer the direct output of "git describe", but a slight
	// translation to be semver compliant.

	// NOTE: The $Format strings are replaced during 'git archive' thanks to the
	// companion .gitattributes file containing 'export-subst' in this same
	// directory.  See also https://git-scm.com/docs/gitattributes
	gitVersion   = "v0.0.0-master+$Format:%H$"
	gitCommit    = "$Format:%H$" // sha1 from git, output of $(git rev-parse HEAD)
	gitTreeState = ""            // state of git tree, either "clean" or "dirty"

	buildDate = "1970-01-01T00:00:00Z" // build date in ISO8601 format, output of $(date -u +'%Y-%m-%dT%H:%M:%SZ')
)

// Info contains versioning information.
type Info struct {
	GitVersion   string `json:"gitVersion"`
	GitCommit    string `json:"gitCommit"`
	GitTreeState string `json:"gitTreeState"`
	BuildDate    string `json:"buildDate"`
	GoVersion    string `json:"goVersion"`
	Compiler     string `json:"compiler"`
	Platform     string `json:"platform"`
}

// String returns info as a human-friendly version string.
func (info Info) String() string {
	return info.GitVersion
}

// ToJSON returns the JSON string of version information.
func (info Info) ToJSON() string {
	s, _ := json.Marshal(info)

	return string(s)
}

// Text encodes the version information into UTF-8-encoded text and
// returns the result.
func (info Info) Text() string {
	table := uitable.New()
	table.RightAlign(0)
	table.MaxColWidth = 80
	table.Separator = " "
	table.AddRow("gitVersion:", info.GitVersion)
	table.AddRow("gitCommit:", info.GitCommit)
	table.AddRow("gitTreeState:", info.GitTreeState)
	table.AddRow("buildDate:", info.BuildDate)
	table.AddRow("goVersion:", info.GoVersion)
	table.AddRow("compiler:", info.Compiler)
	table.AddRow("platform:", info.Platform)

	return table.String()
}

// Get returns the overall codebase version. It's for detecting
// what code a binary was built from.
func Get() Info {
	// These variables typically come from -ldflags settings and in
	// their absence fallback to the settings in pkg/version/base.go
	return Info{
		GitVersion:   gitVersion,
		GitCommit:    gitCommit,
		GitTreeState: gitTreeState,
		BuildDate:    buildDate,
		GoVersion:    runtime.Version(),
		Compiler:     runtime.Compiler,
		Platform:     fmt.Sprintf("%s/%s", runtime.GOOS, runtime.GOARCH),
	}
}

version包用于记录版本号信息，而版本号功能几乎是所有Go应用都会用到的通用功能。因此，需要考虑将version包提供给其他外部应用程序使用。根据目录规范，应将version包放在pkg/目录下，以便其他项目可以导入并使用version包。鱿鱼version包需要是面向第三方应用的包，因此需要确保version包的功能稳定、完善并且能够独立对外提供预期的功能。

上面代码定义了一个Info结构体，用于统一保存版本信息。Info结构体记录了比较详细的构建信息，包括git版本号、git提交id、git仓库状态、应用构建时间、go版本、用到的编译器和构建平台。此外，Info结构体还实现了以下方法，用于展示不同格式的版本信息

• Get方法：返回详尽的代码库版本信息
• String方法：以更友好、可读的形式展示构建信息
• ToJSON方法：以Json格式输出版本信息
• Text方法：展示格式化的版本信息

pkg/version/flag.go文件

package version

import (
	"fmt"
	flag "github.com/spf13/pflag"
	"os"
	"strconv"
)

type versionValue int

const (
	// 未设置版本.
	VersionNotSet versionValue = 0
	// 启用版本.
	VersionEnabled versionValue = 1
	// 原始版本.
	VersionRaw versionValue = 2
)

const strRawVersion string = "raw"

func (v *versionValue) IsBoolFlag() bool {
	return true
}

func (v *versionValue) Get() any {
	return *v
}

func (v *versionValue) Set(s string) error {
	if s == strRawVersion {
		*v = VersionRaw
		return nil
	}
	boolVal, err := strconv.ParseBool(s)
	if boolVal {
		*v = VersionEnabled
	} else {
		*v = VersionNotSet
	}
	return err
}

func (v *versionValue) String() string {
	if *v == VersionRaw {
		return strRawVersion
	}
	return fmt.Sprintf("%v", bool(*v == VersionEnabled))
}

// The type of the flag as required by the pflag.Value interface.
func (v *versionValue) Type() string {
	return "version"
}

func VersionVar(p *versionValue, name string, value versionValue, usage string) {
	*p = value
	flag.Var(p, name, usage)
	// "--version" will be treated as "--version=true"
	flag.Lookup(name).NoOptDefVal = "true"
}

func Version(name string, value versionValue, usage string) *versionValue {
	p := new(versionValue)
	VersionVar(p, name, value, usage)
	return p
}

const versionFlagName = "version"

var versionFlag = Version(versionFlagName, VersionNotSet, "Print version information and quit")

// AddFlags registers this package's flags on arbitrary FlagSets, such that they point to the
// same value as the global flags.
func AddFlags(fs *flag.FlagSet) {
	fs.AddFlag(flag.Lookup(versionFlagName))
}

// PrintAndExitIfRequested will check if the -version flag was passed
// and, if so, print the version and exit.
func PrintAndExitIfRequested() {
	// 检查版本标志的值并打印相应的信息
	if *versionFlag == VersionRaw {
		fmt.Printf("%s\n", Get().Text())
		os.Exit(0)
	} else if *versionFlag == VersionEnabled {
		fmt.Printf("%s\n", Get().String())
		os.Exit(0)
	}
}

将版本信息注入到version包中

接下来，可以通过 -ldflags -X “importpath.name=value” 构建参数将版本信息注入到version包中。

由于需要解析当前Git仓库的状态、CommitID、tag等信息，为了方便在编译时将版本号信息注入到version包中，这里将这些注入操作统一封装到build.sh 脚本中，这样在编译fg-apiserver组件的时候，只需要执行build.sh脚本就可以。

#!/bin/bash

# 获取脚本所在目录作为项目根目录
PROJ_ROOT_DIR=$(dirname "${BASH_SOURCE[0]}")

# 定义构建产物的输出目录为项目根目录下的_output文件夹
OUTPUT_DIR=${PROJ_ROOT_DIR}/_output

# 指定版本信息包的路径，后续会通过-ldflags参数将版本信息注入到这个包的变量中
VERSION_PACKAGE=gitlab.com/onexstack/fastgo/pkg/version

# 确定VERSION值：如果环境变量中没有设置VERSION，则使用git标签作为版本号
# git describe --tags --always --match='v*'命令会获取最近的v开头的标签，如果没有则使用当前commit的短哈希
if [[ -z "${VERSION}" ]];then
  VERSION=$(git describe --tags --always --match='v*')
fi

# 检查代码仓库状态：判断工作目录是否干净
# 默认状态设为"dirty"（有未提交更改）
GIT_TREE_STATE="dirty"
# 使用git status检查是否有未提交的更改
is_clean=$(git status --porcelain 2>/dev/null)
# 如果is_clean为空，说明没有未提交的更改，状态设为"clean"
if [[ -z ${is_clean} ]];then
  GIT_TREE_STATE="clean"
fi

# 获取当前git commit的完整哈希值
GIT_COMMIT=$(git rev-parse HEAD)

# 构造链接器标志（ldflags）
# 通过-X选项向VERSION_PACKAGE包中注入以下变量的值：
# - gitVersion: 版本号
# - gitCommit: 构建时的commit哈希
# - gitTreeState: 代码仓库状态(clean或dirty)
# - buildDate: 构建日期和时间(UTC格式)
GO_LDFLAGS="-X ${VERSION_PACKAGE}.gitVersion=${VERSION} \
  -X ${VERSION_PACKAGE}.gitCommit=${GIT_COMMIT} \
  -X ${VERSION_PACKAGE}.gitTreeState=${GIT_TREE_STATE} \
  -X ${VERSION_PACKAGE}.buildDate=$(date -u +'%Y-%m-%dT%H:%M:%SZ')"

# 执行Go构建命令
# -v: 显示详细编译信息
# -ldflags: 传入上面定义的链接器标志
# -o: 指定输出文件路径和名称
# 最后参数是入口文件路径
go build -v -ldflags "${GO_LDFLAGS}" -o ${OUTPUT_DIR}/fg-apiserver -v cmd/fg-apiserver/main.go

fg-apiserver 添加 --version 命令行选项

前面的步骤，在编译fg-apiserver 之后，所需的版本信息已经成功注入version包中。接下来还需要再fg-apiserver 主程序中调用version包打印版本信息。

编辑cmd/fg-apiserver/app/server.go 在run函数添加代码

package app

import (
    ...
   "gitlab.com/onexstack/fastgo/pkg/version"

)
...
// NewFastGOCommand 创建一个 *cobra.Command 对象，用于启动应用程序.
func NewFastGOCommand() *cobra.Command {
    ...
    // 添加 --version 标志
    version.AddFlags(cmd.PersistentFlags())

    return cmd
}

// run 是主运行逻辑，负责初始化日志、解析配置、校验选项并启动服务器。
func run(opts *options.ServerOptions) error {
    // 如果传入 --version，则打印版本信息并退出
    version.PrintAndExitIfRequested()
    ...
}   

version.AddFlags(cmd.PersistentFlags()) 用来给fg-apiserver 命令添加-v / --version 命令行选项

version.PrintAndExitIfRequested() 用来指定当fg-apiserver 命令执行并传入 -v / --version 命令行选项时，应用会打印版本号信息并退出

测试fg-apiserver 版本号打印

执行以下命令编译fg-apiserver 组件源码，打印版本信息

(base) dujie@MacBook-Pro fastgo % git tag -a v0.0.2 -m "release: v0.0.2"
(base) dujie@MacBook-Pro fastgo % sh build.sh
(base) dujie@MacBook-Pro fastgo % ./_output/fg-apiserver --version=raw 
/Users/dujie/.fastgo/fg-apiserver.yaml
  gitVersion: v0.0.2                                  
   gitCommit: 61f41c6b84add6906b2811a16ad13f14661a416f
gitTreeState: dirty                                   
   buildDate: 2025-04-02T04:46:06Z                    
   goVersion: go1.24.0                                
    compiler: gc                                      
    platform: darwin/arm64       

可以看到fg-apiserver 程序根据 –version 的值输出了不同格式且内容详尽的版本信息。通过这些版本信息，可以精确定位当前应用所使用的代码及编译环境，为日后的故障排查鉴定了坚实的基础。