核心结论：用 actions/setup-go@v4 + go test -race + golangci-lint 三件套打底，再按需加构建、镜像、缓存，基本覆盖 90% 的微服务场景；必须显式声明 go 版本、启用模块缓存、强制竞态检测与静态检查，避免环境不一致和并发隐患。
直接上手就能跑通的 GitHub Actions CI 流水线，对 Golang 微服务来说不是“要不要做”，而是“怎么避免踩坑”。核心结论：用 actions/setup-go@v4 + go test -race + golangci-lint 三件套打底，再按需加构建、镜像、缓存，基本覆盖 90% 的微服务场景。
为什么不能直接用默认 Go 版本？
GitHub Actions 默认 Ubuntu runner 不带 Go，且版本滞后。硬写 go version 可能报错或触发旧版行为（比如 go mod 默认行为变化）。必须显式声明版本，并启用缓存。
-
actions/setup-go@v4是目前最稳的版本，v5在某些矩阵构建中会因check-latest: true拉取 beta 版本导致失败 - 建议固定
go-version: '1.22'（或项目实际使用的 LTS 版本），避免 nightly 或 patch 自动升级引发不兼容 - 加上
cache: true能让go mod download缓存复用，二次构建快 3–5 秒；但注意它只缓存GOROOT和go mod，不缓存build输出
测试阶段必须加 -race 吗？
对微服务必须加。Golang 微服务天然多 goroutine，漏掉数据竞争在生产环境可能表现为偶发 panic 或状态不一致，CI 阶段不暴露，上线后难复现。
-
go test -v -race ./...是最低要求；./...比./更安全，能覆盖internal/和pkg/下的包 - 如果测试超时，别急着删
-race—— 先检查是否在测试里启了没 shutdown 的 HTTP server 或 goroutine leak - 覆盖率可选，但建议加
go test -coverprofile=coverage.out ./...，后续传给 codecov 或 sonarqube；注意coverprofile文件路径要统一，否则上传失败
静态检查为什么推荐 golangci-lint 而非 go vet？
go vet 只查语法和基础逻辑错误，而微服务代码常含并发、HTTP handler、config 注入等模式，golangci-lint 能覆盖更多真实风险点。
- 配置文件
.golangci.yml必须存在，否则 Action 会跳过检查；常见误操作是只在本地装了 linter，但没提交配置 - 推荐启用
errcheck（检查 error 是否被忽略）、govet（增强版 vet）、staticcheck（找过期 API 和逻辑漏洞） - CI 中加
only-new-issues: true，避免历史债阻塞新 PR；但主干分支（如main）建议关掉该选项，强制清旧债
构建二进制和 Docker 镜像要不要放同一个 job？
不要。构建二进制和打包镜像应拆开，尤其当你要支持多架构（ARM64 / AMD64）或不同部署目标（K8s vs Serverless）时。
- 二进制构建 job 用
go build -ldflags="-s -w" -o bin/app ./cmd/app，-s -w减小体积且去调试符号，适合微服务轻量部署 - Docker 构建 job 单独定义，用
docker/build-push-action@v5，指定platforms: linux/amd64,linux/arm64；别用docker build原生命令，它不支持跨平台原生构建 - 关键陷阱：Docker job 必须显式
checkout且setup-go—— 因为多阶段 Dockerfile 里可能有go build步骤，没 Go 环境会直接失败
真正容易被忽略的，是环境变量和 secrets 的传递链路。比如 DOCKER_PASSWORD 传进镜像推送步骤前，得确认它没被 if: ${{ !startsWith(github.ref, 'refs/tags/') }} 这类条件过滤掉；微服务往往依赖多个 secret（DB URL、JWT key、K8s token），漏一个就卡在 deploy 阶段，但日志里只报 “unauthorized”，根本看不出是哪个 secret 没配对。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
