Go gofmt 处理生成代码时如何稳定空白和导入顺序

代码生成器最容易失控的地方，不是模板能不能拼出一段 Go，而是同一份输入在不同分支下留下不同的空格、缩进和 import 顺序。处理方式很明确：让生成器只输出语法正确的完整 Go 文件，写盘后统一调用固定版本的 gofmt，最后用 gofmt -d 检查是否还会变化。这样模板不需要复制一套排版规则，审查时也能把真正的逻辑变化从空白噪声里分离出来。

先让生成器输出完整且可解析的 Go 文件

不要在模板里手工计算 tab 数量，也不要让每个字段分支决定 import 的排列。生成阶段只关心包名、声明和依赖是否正确；格式阶段再交给 gofmt。完整文件至少应有 package 声明，import 和声明之间的关系也要满足 Go 语法。若模板可能生成空文件、重复 import 或未闭合的复合字面量，gofmt 会报告语法错误，它不会替你修复生成逻辑。

一个稳定的调用顺序可以写成下面这样：

# 先生成完整的 .go 文件，再交给固定工具统一格式
go generate ./...

# -w 原地写回；目录参数会递归处理其中的 .go 文件
gofmt -w internal/generated

# 只检查是否仍有格式差异，不修改文件
gofmt -d internal/generated

用 gofmt 统一空白，导入分组要由模板明确表达

gofmt 使用 tab 处理缩进、用空白做对齐，最终排版取决于 Go 语法结构，而不是模板作者手写的列宽。对完整 Go 文件，它也会稳定整理同一导入组中的路径顺序。但空行形成的导入组仍然是源码的语义提示：标准库、第三方包和内部包是否分组，必须由生成器输出对应的空行。

因此，生成器应当维护“需要哪些 import”的集合，但不必维护最终的字母顺序。若某个模板分支加入了新依赖，先把路径写入正确的 import 组，再由 gofmt 完成组内排序。这样新增字段不会因为手工空格不同而制造大范围 diff。

格式化代码片段时，完整文件和片段不是一回事

如果生成器使用 go/format 而不是启动命令行工具，要先区分输入形态。format.Source 可以处理完整源文件，也可以处理声明、语句或表达式片段；片段会保留首尾空白和首行缩进，但官方文档明确说明，部分源文件不会执行 import 排序。想稳定处理 import，优先把内容放入完整的 ast.File 或完整源码上下文中。

package main

import (
	"fmt"
	"go/format"
	"log"
)

func main() {
	// format.Source 适合把完整 Go 源码转成标准 gofmt 形态。
	src := []byte("package demo\n\nimport (\"fmt\"; \"log\")\n\nfunc Run(){fmt.Println(log.Prefix())}\n")
	formatted, err := format.Source(src)
	if err != nil {
		// 格式化失败通常意味着生成器输出不是合法 Go 源码。
		log.Fatal(err)
	}
	fmt.Print(string(formatted))
}

这个边界很关键：如果你只把一段声明或表达式送进格式化函数，却又希望它替你推断整个文件的 import 分组，结果就会和命令行 gofmt 不同。生成器可以选择“先拼完整文件再格式化”，这是最容易复现的路径；只有确实需要 AST 级操作时，才把节点类型和输入范围写进设计说明。

把版本固定和 diff 检查放进生成流水线

格式化结果会随工具实现变化。官方 go/format 文档建议依赖一致格式的工具直接执行特定版本的 gofmt 二进制；否则开发者使用不同 Go 版本时，预提交检查可能出现脆弱的差异。工程上可以把生成器和 Go 工具链版本一起记录，在同一环境依次执行：

# 输出当前工具链版本，便于定位生成结果漂移
go version

# -l 只列出需要格式化的文件；-d 适合在 CI 中展示差异
gofmt -l internal/generated
gofmt -d internal/generated

# 本地需要修复时再显式写回
gofmt -w internal/generated

检查结果的判断也要分层：gofmt -d 有 diff，说明文件尚未处于该 gofmt 版本的规范形态；它不等于代码编译失败。若 gofmt 直接报错，优先回到生成模板检查语法、字符串转义和 import 拼接，而不是继续调整缩进。

常见问题

gofmt 会自动删除未使用的 import 吗？

不要把这个责任交给 gofmt。它主要格式化源码；依赖增删和未使用 import 的处理应由生成器逻辑、编译器反馈或专门的导入工具负责。

为什么 import 还是没有按我想要的三组排列？

检查模板里的空行。gofmt 会稳定处理已有导入组，但不会根据“标准库、第三方、内部包”的组织习惯替你创建业务分组。

只格式化一段字符串时为什么顺序不一致？

因为片段格式化保留输入范围和缩进，并不等同于完整文件格式化。把片段放回完整 Go 文件上下文后再执行 gofmt，结果更容易复现。

参考：https://pkg.go.dev/cmd/gofmt、https://pkg.go.dev/go/format。