构建配置应放在cmd/下，因其属于编译期元信息，需按可执行入口隔离；internal/仅负责运行时功能实现，不可感知构建过程，避免将版本、时间等硬编码其中导致测试与CI行为不一致。
构建配置该放哪：cmd/ 和 internal/ 的边界必须划清
构建配置不是业务逻辑，也不是运行时参数，它属于“如何把代码变成二进制”的元信息。放在 cmd/ 下最合理，因为每个可执行入口（如 cmd/api/main.go、cmd/worker/main.go）可能需要不同的构建行为；而 internal/ 下的包只负责功能实现，不能感知构建过程。
常见错误是把版本号、编译时间等硬编码在 internal/config 或 pkg/version 里——这会导致测试时无法 mock 构建信息，CI 构建和本地构建行为不一致。
-
cmd/api/main.go中定义var Version, BuildTime string，不赋初值 - 用
go build -ldflags "-X main.Version=v1.2.0 -X main.BuildTime=2026-10-13T13:05:00Z"注入 - 避免在
internal/包中 importmain或直接读取这些变量
-ldflags 的坑：字符串拼接和空格处理要小心
-X 只支持 importpath.name=value 形式，且 value 中不能有未转义的双引号、换行或制表符。直接拼接 Git commit hash 或环境名容易出错。
比如想注入当前 Git 分支，写成 -X main.Branch=$(git rev-parse --abbrev-ref HEAD) 在 Makefile 里看似可行，但若分支名含斜杠（如 feature/login-v2），会被 shell 当作路径解析失败。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 安全做法：先用
printf %q转义，例如-X main.Branch=$(printf %q $(git rev-parse --abbrev-ref HEAD)) - 不要在
value中嵌套变量引用，-X main.Env=$ENV_NAME在 go build 中不会展开，得靠 shell 层处理 - 多个
-X参数之间用空格分隔，不能换行或用反斜杠续行
构建配置与运行时配置别混用：TOML 不负责编译期信息
有人把 version、build_time 写进 config.toml，再用 github.com/BurntSushi/toml 解析——这是典型错位。TOML 是运行时加载的配置，而构建信息应在编译时固化，二者生命周期完全不同。
后果是：每次发布都要手动生成并维护一个带版本号的 config 文件；灰度发布时无法区分二进制来源；容器镜像 tag 和内部版本号不一致。
- 构建期信息（版本、commit、时间、Go 版本）走
-ldflags - 运行时配置（数据库地址、超时、开关）走
configs/目录下的 TOML/YAML/环境变量 - 如果真要在程序里同时暴露两者，用两个独立结构体，比如
BuildInfo（由-ldflags填充）和Config（由 toml.DecodeFile 加载）
CI/CD 中统一构建入口：避免本地和流水线行为不一致
很多团队本地用 go build，CI 里用 docker build，结果发现 Docker 镜像里的 Version 是空字符串——因为 Dockerfile 没传 -ldflags。
关键点在于：构建命令必须收敛到一处，且所有环境都调用同一套逻辑。
- 在
scripts/build.sh里封装完整构建命令，包含git describe获取版本、date -u生成 ISO 时间 - Dockerfile 中用
ARG接收版本参数，再透传给go build，例如：ARG BUILD_VERSION; go build -ldflags "-X main.Version=${BUILD_VERSION}" - GitHub Actions 中用
env:传递BUILD_VERSION，而不是在run:里拼接字符串
-ldflags 注入的 Version 字段，在日志里显示为空，线上排查时根本分不清是哪个提交编译的二进制。 
