TFRSManager 版本管理规范¶

概述¶

项目采用语义化版本（SemVer），通过 Go 的 -ldflags -X 在编译时注入版本信息，运行时可被遥测、日志等消费。使用 bump-my-version 管理版本号和 git tag。

版本包¶

internal/shared/version/version.go

三个变量通过 -ldflags 注入：

变量	说明	默认值
`Version`	语义化版本号（来自 `git describe --tags`）	`dev`
`GitCommit`	构建时 commit SHA 短哈希	`unknown`
`BuildTime`	构建时间（UTC ISO 8601）	`unknown`

编译时注入¶

本地构建（Makefile）¶

VERSION ?= $(shell git describe --tags --always --dirty)
COMMIT  := $(shell git rev-parse --short HEAD)
BUILD_TIME := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
LDFLAGS := -s -w \
  -X TFRSManager/internal/shared/version.Version=$(VERSION) \
  -X TFRSManager/internal/shared/version.GitCommit=$(COMMIT) \
  -X TFRSManager/internal/shared/version.BuildTime=$(BUILD_TIME)

make build-user / make build-admin 自动携带版本信息。

Docker 构建¶

Dockerfile 通过 ARG 接收版本参数：

docker build -f Dockerfile.user \
  --build-arg VERSION=v1.0.1 \
  --build-arg COMMIT=abc1234 \
  --build-arg BUILD_TIME=2025-01-01T00:00:00Z \
  .

CI/CD（CNB）¶

.cnb.yml 中 docker build 阶段自动从 git 获取版本信息并传入 --build-arg。

版本消费¶

启动日志：两个服务的 main.go 在启动时输出 version、commit、build_time
OpenTelemetry：config.go 中 OTEL_SERVICE_VERSION 默认值读取 version.Version（替代硬编码 "1.0.0"）

bump-my-version 工作流¶

配置文件：.bumpversion.toml，初始版本 1.0.0。

发布流程¶

# 补丁版本：1.0.0 → 1.0.1
bump-my-version bump patch

# 次版本：1.0.1 → 1.1.0
bump-my-version bump minor

# 主版本：1.1.0 → 2.0.0
bump-my-version bump major

# 预发布：1.0.0 → 1.0.1-alpha.0 → 1.0.1-beta.0 → 1.0.1-rc.0 → 1.0.1
bump-my-version bump pre_n   # 递增预发布号
bump-my-version bump pre_l   # 提升预发布阶段（dev→alpha→beta→rc→final）

每次 bump 会： 1. 更新 .bumpversion.toml 中的 current_version 2. 创建 commit：Bump version: 1.0.0 → 1.0.1 3. 创建 git tag：v1.0.1

预发布标签顺序¶

dev → alpha → beta → rc → final（final 表示正式版，不显示后缀）

常用命令¶

make version          # 显示当前版本信息
make build-all        # 构建并注入版本

文件清单¶

文件	作用
`internal/shared/version/version.go`	版本变量定义
`.bumpversion.toml`	bump-my-version 配置
`Makefile`	LDFLAGS 注入 + `version` target
`Dockerfile.user` / `Dockerfile.admin`	Docker 构建时 ARG 注入
`.cnb.yml`	CI/CD 构建传入版本 build-arg
`internal/shared/config/config.go`	OTEL 版本默认值
`cmd/user-service/main.go`	启动日志输出版本
`cmd/admin-service/main.go`	启动日志输出版本