源码格式化

Go 源码格式化先看手里的输入是什么：如果拿到的是完整源码或声明、语句片段，直接调用 go/format.Source；如果已经有 ast.Node，或者需要把格式化结果写进一个 io.Writer，使用 go/format.Node。两者都输出 gofmt 风格，但入口、错误位置和导入排序边界不同。

官方文档：https://pkg.go.dev/go/format

一句话判断：源码是字节，选 Source；源码已经被解析成语法树，选 Node。需要先改写 AST，再把节点输出到缓冲区或文件时，也选 Node。

先判断输入：源码字节还是 AST 节点

可以把格式化工作拆成三个边界：输入形态、格式化入口和输出对象。Source 把 []byte 当作源码处理，调用者拿回新的字节切片；Node 接受允许的 AST 节点，并把结果写到调用者提供的 Writer。它不会修改传入的节点。

完整源码格式化：优先使用 Source

Source 的输入是 []byte，返回格式化后的 []byte 和错误。它适合代码生成器、模板渲染器或接收上传源码后做统一排版的场景。不要把错误忽略掉：语法不完整时，返回的错误就是调用方判断“不能继续发布或保存”的依据。

package main

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

func main() {
	// 这里模拟生成器交付的一段完整 Go 源文件。
	src := []byte("package main\nimport \"fmt\"\nfunc main(){fmt.Println(\"ok\")}\n")

	// Source 返回新的格式化结果，不会原地改写 src。
	formatted, err := format.Source(src)
	if err != nil {
		// 语法错误应在格式化边界返回，避免保存半成品。
		log.Fatal(err)
	}
	fmt.Print(string(formatted))
}

如果输入是文件内容，读取文件后同样可以交给 Source。如果只是声明或语句片段，文档也允许直接传入；但片段没有完整文件上下文，导入排序行为不能按完整 *ast.File 推断。

AST 节点格式化：用 Node 接住输出

当需求已经进入语法树层面，重复把 AST 转回字符串、再调用 Source 会丢掉调用者手里的节点边界。更直接的做法是用 parser.ParseFile 得到 *ast.File 和 token.FileSet，改完节点后，把它交给 format.Node。

package main

import (
	"bytes"
	"fmt"
	"go/ast"
	"go/format"
	"go/parser"
	"go/token"
	"log"
)

func main() {
	// parser 同时返回语法树和节点位置所依赖的 FileSet。
	src := `package demo

import "fmt"

func Hello(name string) { fmt.Println(name) }
`
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "demo.go", src, parser.ParseComments)
	if err != nil {
		// 解析失败时没有可安全输出的 AST，直接结束当前处理。
		log.Fatal(err)
	}

	// 只演示静态遍历；实际改写可以替换 file.Decls 中的节点。
	ast.Inspect(file, func(node ast.Node) bool {
		return node != nil
	})

	var buf bytes.Buffer
	// Node 将完整 ast.File 按 gofmt 风格写入指定 Writer。
	if err := format.Node(&buf, fset, file); err != nil {
		// Writer 或格式化阶段出错时保留错误，不发布不完整结果。
		log.Fatal(err)
	}
	fmt.Print(buf.String())
}

Node 支持 *ast.File、printer.CommentedNode、声明和语句切片，以及可赋值给表达式、声明、规格或语句的节点。fset 负责把节点位置与源码文件对应起来，尤其是在节点来自真实文件、还需要保留注释或位置关系时不要随手换成一个无关的空集合。

三个容易误判的边界

部分源码不等于完整文件

Source 接受声明或语句列表，但片段的前后空白和首行缩进有自己的处理规则；部分源码的导入不会像完整文件那样自动排序。因此，如果任务是“重排完整文件的 import”，要解析完整文件并把 *ast.File 交给 Node，不要把几行 import 当成孤立片段。

格式化不等于语法修复

输入有语法错误时，Source 或 Node 都不是修复器。调用方应该把错误留在边界层，记录文件名或生成阶段，再决定回滚、提示用户或保留原文。

稳定构建要固定工具版本

Go 官方文档明确提醒，源码格式化结果会随 Go 版本变化。若预提交检查、生成文件哈希或跨机器快照要求长期一致，固定具体版本的 gofmt 工具链比直接依赖当前编译器版本下的 go/format 更稳。

源码格式化速查表

• 手里是 []byte：调用 format.Source，检查返回错误，使用返回的新字节。
• 手里是 AST：准备匹配的 token.FileSet，调用 format.Node 写到 bytes.Buffer 或其他 Writer。
• 需要改写语法结构：先解析和修改 AST，再格式化，不要通过字符串替换代替节点操作。
• 需要导入排序：优先处理完整 *ast.File，不要把部分声明片段当成完整文件。
• 需要跨版本稳定：固定 gofmt 版本，并把工具版本纳入构建环境。

常见问题

format.Node 会改变 AST 吗？

不会。它读取节点并把格式化结果写入 Writer；需要改名或增删声明时，应在调用 Node 之前显式修改 AST。

只有一个表达式时能用 Node 吗？

可以。先用解析器得到表达式节点，再提供与节点匹配的 FileSet 和 Writer。若只是已有文本，直接使用 Source 通常更简单。

Source 和 gofmt 命令输出一定永远一致吗？

它们都遵循 gofmt 风格，但格式化行为会随 Go 版本变化。对一致性敏感的自动化任务应固定工具链版本，不要把不同版本的输出混在同一份快照中。