go fix 执行前的模块范围与回滚准备

第一次运行 go fix，最容易犯的错不是选错 fixer，而是没有先确认“它到底会改哪里”。在项目根目录直接执行 go fix ./... 可能修改很多包；如果工作区本来就有未提交改动，回滚时很难分辨哪些是自动现代化、哪些是原有工作。更稳妥的做法是：先确认主模块和包模式，再用 -diff 预览，最后在一个独立 Git 检查点上执行。

官方地址：https://go.dev/cmd/go/

go fix 前的核心准备是把“扫描范围、构建配置、变更集”三件事分开确认。预览无误后再写入源码，并让这次修改拥有单独、可回退的提交边界。

先把 go fix 的扫描边界画出来

Go 的包模式和模块边界不是一回事。./... 会从当前目录展开匹配，但目录中存在另一个 go.mod 时，它不会自动把那个嵌套模块当作当前模块的一部分。若仓库包含多个服务或工具模块，应该分别进入各自模块根目录处理，不能把一次命令的输出当成全仓库覆盖证明。

另一个边界来自构建配置。go fix 一次只分析一个构建配置；带有平台文件、构建标签或不同生成代码的项目，需要为目标组合分别预览。

先预览差异，再决定是否写入

go fix -diff ./... 的价值在于把“可能修改什么”变成可审阅的文本。先查看差异中的文件数量、导入变化和语义改写，再决定是否启用全部 fixer。大仓库可以按子目录或具体 fixer 拆开，减少一次提交中混入无关变化。

# 先确认当前模块根目录和工作树状态
pwd
go env GOMOD
git status --short

# 只预览当前模块的修改，不写回源文件
go fix -diff ./...

# 需要时只查看一个 fixer 的说明，再决定是否启用
go tool fix help forvar

如果工作树已经有改动，先暂停并整理这些改动。官方建议从干净 Git 状态开始，是因为一次 go fix 可能涉及大量文件；干净状态能让评审和回退都只针对这次迁移。

用 Git 检查点把修改锁在可回退范围内

预览通过后，不要立刻把结果和其他重构一起提交。先创建一个语义明确的检查点，再执行 fix。这样出现编译错误、导入冲突或不符合团队风格的改写时，可以回退这一整个变更集，而不会误伤之前已经完成的工作。

# 检查没有未提交改动后，建立独立的迁移检查点
git status --short
git add -A
git commit -m "chore: checkpoint before go fix"

# 写入源码；大仓库也可以先从单个包开始
go fix ./...

# 立即查看本次变更，确认范围仍在预期内
git diff --stat
git diff -- go.mod '*.go'

这里的检查点不是为了掩盖修改，而是为了让自动改写拥有清晰的起点。若需要回退，优先使用版本控制的提交边界；不要用整目录覆盖命令抹掉同事后来加入的文件。

执行后按配置复查，不把成功退出当成迁移完成

go fix 的退出成功只说明工具完成了这次分析和写入，不代表所有目标平台都已经覆盖，也不代表改写后的行为一定符合业务预期。至少按文章开头记录的构建组合复查，并把格式、测试和人工 diff 作为同一变更集的验收项。

# 先格式化被改动的 Go 文件，保持差异可读
gofmt -w ./path/to/changed.go

# 在主平台上复查包和测试；失败时保留错误输出用于定位
go test ./...

# 对另一个发布目标重复预览或验证，按项目实际组合调整
GOOS=linux GOARCH=amd64 go fix -diff ./...
GOOS=darwin GOARCH=arm64 go fix -diff ./...

如果预览阶段发现某个平台仍有待处理文件，不能只凭主平台测试通过就提交。对于生成文件，go fix 会丢弃触及生成文件的修复；真正需要更新的是生成器或生成流程，不能把生成结果当成手工源文件继续改。

最终检查可以压缩成四项：变更文件是否都属于本模块；是否覆盖需要支持的构建配置；go test ./... 是否通过；Git diff 是否只包含本次现代化目的。四项都满足后再提交，回滚就只需要撤销这一条迁移提交。

常见问题

go fix ./... 会修改 go.mod 吗？

它主要改写 Go 源文件；模块依赖是否需要变化要由具体项目和其他 module-aware 命令决定。执行前仍应把 go.mod、go.sum 的差异列入人工检查。

仓库里有多个 go.mod，应该从哪里运行？

分别进入每个模块根目录运行，并为每个模块单独预览和建立检查点；不要假设仓库根目录的一次 ./... 会跨模块完成迁移。

预览没有差异，是否说明所有平台都完成了？

不一定。预览只对应当前构建配置；平台文件或 build tags 需要切换到目标组合后再次检查。