Go go/format.Node 怎样按标准格式输出语法树

用 Go 做代码生成、重构工具或源码检查器时，常见的一步是：程序已经拿到了 AST，怎样把某个节点重新写成格式统一的 Go 源码？答案是把同一个 token.FileSet 和 AST 节点交给 format.Node，让它把 canonical gofmt 风格的结果写入一个 io.Writer。

官方地址：https://pkg.go.dev/go/format

关键点有三个：parser.ParseFile 负责把源码解析成 *ast.File，token.FileSet 保存节点位置与文件集合，format.Node 只负责格式化并写出。它不会替你遍历语法树，也不会做类型检查或保证不同 Go 版本永远产生完全相同的文本。

先把解析、节点和格式化分成三层

这类工具最容易出现的设计误区，是把“能打印 AST”理解成一个函数包办全部工作。更稳的模式是把流程拆成三层：

• 输入层：parser.ParseFile 读取字符串或字节，生成 ast.File 等节点。
• 位置层：token.FileSet 记录文件名、偏移和行列位置，供 AST 节点的位置信息使用。
• 输出层：format.Node 将指定节点写到 io.Writer，输出格式化后的 Go 源码。

这种拆分带来的好处是：后续要替换节点、只打印函数、或者把结果写入文件时，不需要重新设计解析部分。图 1 用静态关系图展示了这条输入到输出的链路。

用 ParseFile 准备完整的 ast.File

如果目标是重新输出一个完整 Go 文件，通常从 parser.ParseFile 开始。下面的示例把源码放在内存中，用同一个 FileSet 解析，随后把文件节点交给格式化层。

package main

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

func main() {
    // 故意保留不统一的空格，观察格式化器如何整理源码。
    source := []byte(`package demo

func add(a int,b int)int{return a+b}
`)

    // FileSet 保存文件位置；解析和格式化必须使用同一份位置集合。
    fileSet := token.NewFileSet()
    file, err := parser.ParseFile(fileSet, "demo.go", source, parser.ParseComments)
    if err != nil {
        // 解析失败时不要把不完整的 AST 继续交给格式化器。
        panic(fmt.Errorf("parse Go source: %w", err))
    }

    var output bytes.Buffer
    // Node 负责按 canonical gofmt 风格写出指定 AST 节点。
    if err := format.Node(&output, fileSet, file); err != nil {
        // Writer 或节点位置异常时，必须把输出失败传回调用方。
        panic(fmt.Errorf("format AST node: %w", err))
    }

    fmt.Print(output.String())
}

这里的 file 是完整文件节点，所以输出包含包声明、函数声明和保留的注释。format.Node 的参数顺序是输出目标、文件集合和节点；把 FileSet 误换成另一个集合，容易让带位置的节点出现不符合预期的结果。

format.Node 的适用力是“按节点输出”，不是“替你改树”

format.Node 的价值在于它接受 ast.Node，因此输出范围可以比完整文件更小。例如代码生成器已经定位到一个函数声明，就可以只输出该函数。这个能力很适合生成补丁片段、调试重写后的节点，或者给编辑器返回局部文本。

// printFirstDecl 只输出文件中的第一个声明，不遍历整个 AST。
func printFirstDecl(fileSet *token.FileSet, file *ast.File) (string, error) {
    if file == nil || len(file.Decls) == 0 {
        // 空文件没有可供 format.Node 输出的声明，返回明确错误。
        return "", errors.New("file has no declaration")
    }

    var output bytes.Buffer
    // 复用解析文件时的 FileSet，保证节点位置仍然属于同一文件集合。
    if err := format.Node(&output, fileSet, file.Decls[0]); err != nil {
        return "", fmt.Errorf("format declaration: %w", err)
    }
    return output.String(), nil
}

这个片段展示的是设计边界，实际文件还要补上 bytes、errors、fmt、go/ast 和 go/format 等导入。它没有调用 ast.Inspect，因为遍历与输出是两个不同责任：需要筛选节点时先遍历，确定节点后再格式化。

错误处理决定工具能不能进入生产流水线

示例里不能省略 format.Node 的返回值。它写入的是任意 io.Writer，因此文件写入失败、网络流关闭或自定义 Writer 返回错误时，格式化过程就可能中断。对于命令行工具，建议把错误包上“正在格式化哪个文件或节点”的上下文；对于服务端，则应把失败交给调用方，而不是返回一段不完整源码。

还要先处理两个边界：

• 节点指针为空时不要调用格式化函数，先返回可识别的业务错误。
• 只输出局部声明时，结果可能没有包声明和导入上下文，不能直接当成一个完整 Go 文件编译。

图 2 把完整文件输出、局部节点输出和错误返回放到同一张静态边界图里，便于判断调用方应该接收“文件文本”还是“代码片段”。

什么时候用 format.Node，什么时候用 format.Source

如果手里只有一段源代码，没有修改 AST 的需求，format.Source 往往更直接：它接收字节并返回格式化后的字节。可是只要工具已经解析并改动了节点，继续从旧源文本格式化就会绕开 AST 变化，此时应使用 format.Node。

把它放进架构时要接受的代价

“解析—变换—格式化”是一个很实用的编译器式流水线模式。它的适用压力是：工具需要理解语法结构，并且希望输出仍然符合 Go 社区习惯。代价也很明确：你要维护节点选择逻辑、位置集合和错误传播；最终文本还可能受到当前 Go 版本格式规则影响。

因此，下面的判断清单比“凡是 AST 都调用 Node”更可靠：

1. 输入是否已经解析成 AST？没有的话先用 parser，而不是让 Node 处理原始字符串。
2. 是否修改或筛选了节点？是，就保留节点和对应的 FileSet，再调用 Node。
3. 调用方要完整文件还是局部片段？提前在接口里区分，避免下游误编译片段。
4. 是否要求跨 Go 版本字节级一致？如果要求，固定具体 gofmt 工具版本并把它纳入工具链。
5. Writer 是否可能失败？把错误向上传递，并附带文件名、节点类型等上下文。

常见问题

format.Node 能不能直接格式化字符串？

不能把字符串直接当成 AST 节点传入。原始源码应先通过 parser.ParseFile 或相关解析函数构造成节点；如果只是格式化源码字节，可以考虑 format.Source。

为什么局部节点输出没有 package 和 import？

因为你传给 Node 的就是局部节点，例如一个 ast.FuncDecl。格式化器不会自动补齐它的父级文件结构；需要完整文件时传入 *ast.File，需要片段时则由调用方明确片段语义。

format.Node 和 gofmt 的结果会永远一样吗？

它们遵循相同的标准格式方向，但官方文档明确提示格式会随 Go 版本演进。对长期存档、代码生成快照或跨环境门禁，应固定工具版本，不要只依赖当前运行环境的隐含版本。

总结一下：先用 parser 得到节点，再用同一个 FileSet 把节点交给 format.Node；把错误、输出范围和 Go 版本作为接口的一部分，AST 格式化工具才不会从一个方便函数变成隐藏的流水线耦合点。