Go format.Node 怎样格式化带注释 AST

如果 AST 经过改写后需要重新输出 Go 源码，format.Node 的关键不是“把节点传进去”这么简单：解析时要启用 parser.ParseComments，格式化时要继续使用解析同一份源码得到的 token.FileSet。完整文件直接传入 *ast.File；只输出局部声明或表达式时，则用 printer.CommentedNode 明确携带注释集合。

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

想保留注释，先在解析阶段保留注释；想让注释位置稳定，解析、节点和输出必须共享同一个 FileSet。format.Node 负责格式化，不负责从已经丢失的 AST 信息中猜回注释。

完整文件为什么能保留注释

format.Node 支持 *ast.File，而完整文件的注释会保存在 ast.File.Comments 中。下面的最小示例包含包注释、声明前的文档注释和字段行尾注释，重点是 ParseComments 与 FileSet 的创建位置。

package main

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

func main() {
    src := `package demo

// Config 保存渲染配置。
type Config struct {
    Name string // 输出名称
}
`

    // FileSet 记录源码位置，后续格式化必须复用这一个实例。
    fset := token.NewFileSet()
    // ParseComments 让文档注释和行尾注释进入 AST。
    file, err := parser.ParseFile(
        fset, "config.go", src,
        parser.ParseComments|parser.SkipObjectResolution,
    )
    if err != nil {
        log.Fatal(err)
    }

    var buf bytes.Buffer
    // 完整 ast.File 自带 Comments，format.Node 会按位置排版。
    if err := format.Node(&buf, fset, file); err != nil {
        log.Fatal(err)
    }
    fmt.Print(buf.String())
}

这里的 SkipObjectResolution 只是跳过已经废弃的标识符对象解析，不影响注释保存。真正决定注释是否存在的是 ParseComments。如果解析时传入默认模式，后面即使调用 format.Node，也没有可供它输出的完整注释集合。

同一个 FileSet 为什么重要

注释和 AST 节点都使用 token.Pos 表示位置，FileSet 负责把这些位置解释为文件、行和列。常见的安全路径是：创建一次 fset，用它解析源码，再把它原样传给 format.Node。

不要在解析后随意新建另一个空的 FileSet 来格式化原 AST。节点仍然携带旧位置，新集合却没有对应的文件区间，注释排序、行号解释和输出边界就可能失去依据。这个问题尤其容易出现在“解析函数返回 AST，调用方稍后自行格式化”的封装里；可以把 fset 与 AST 放在同一个结果结构中一起返回。

type ParsedFile struct {
    File *ast.File
    Fset *token.FileSet
}

func parseSource(src string) (ParsedFile, error) {
    // AST 和 FileSet 成对返回，避免调用者误用新的位置集合。
    fset := token.NewFileSet()
    file, err := parser.ParseFile(
        fset, "input.go", src,
        parser.ParseComments|parser.SkipObjectResolution,
    )
    if err != nil {
        return ParsedFile{}, err
    }
    return ParsedFile{File: file, Fset: fset}, nil
}

这个片段需要额外导入 go/ast、go/parser 和 go/token。它展示的是接口边界：谁持有 AST，谁就应同时持有解释 AST 位置的 FileSet。

局部 AST 如何把注释一起带走

如果只想输出一个声明，直接把 file.Decls[0] 传给 format.Node，格式化器拿到的是局部节点。此时应使用 printer.CommentedNode 把相关 ast.CommentGroup 一起交给打印器。它不是截图或运行时证据，而是一个明确的“节点 + 注释集合”数据边界。

import (
    "bytes"
    "go/format"
    "go/parser"
    "go/printer"
    "go/token"
    "log"
)

func formatFirstDecl(src string) ([]byte, error) {
    // 使用同一份 FileSet，让局部节点的位置仍可解释。
    fset := token.NewFileSet()
    file, err := parser.ParseFile(
        fset, "input.go", src,
        parser.ParseComments|parser.SkipObjectResolution,
    )
    if err != nil {
        return nil, err
    }
    if len(file.Decls) == 0 {
        return nil, fmt.Errorf("源码没有声明")
    }

    // CommentedNode 将局部声明和注释列表绑定为一个输出对象。
    node := &printer.CommentedNode{
        Node:     file.Decls[0],
        Comments: file.Comments,
    }
    var buf bytes.Buffer
    if err := format.Node(&buf, fset, node); err != nil {
        return nil, err
    }
    return buf.Bytes(), nil
}

示例中的 fmt.Errorf 需要补充 fmt 导入。实际项目还可以先按照声明的 Pos 和 End 筛选相关注释，再放入 Comments，避免把整个文件的无关注释带进局部输出。printer.CommentedNode 会依据节点的位置范围处理传入的注释列表。

format.Node 和 format.Source 怎么选

两者都输出接近 gofmt 风格的代码，但输入边界不同：

官方文档特别提醒：对局部源文件或局部节点，导入不会像完整 *ast.File 那样排序。不要把“局部输出保留了注释”误认为“局部输出等同于整个 gofmt 文件”；输入类型决定了格式化器能处理的范围。

几个容易踩到的边界

• 先格式化再想恢复注释：如果解析时没有开启 ParseComments，后续通常没有完整的注释位置可恢复。
• 把 FileSet 当成全局单例：FileSet 不必全局共享，但必须和当前 AST 的位置来源匹配。
• 把局部节点当完整文件：局部节点可以输出，但完整文件才具备整文件导入排序等上下文。
• 把错误当成验证失败：format.Node 可能在输出未完成前返回格式化错误，调用方应检查返回值，不要把不完整缓冲区当成功结果。

速查结论

需要格式化带注释的完整 Go 文件时，使用 parser.ParseFile(fset, ..., parser.ParseComments|parser.SkipObjectResolution)，再调用 format.Node(&buf, fset, file)。需要格式化局部声明时，使用同一个 fset，并用 printer.CommentedNode 明确带上相关评论组。只有在手里没有 AST、只想把源码字节格式化时，才优先考虑 format.Source。

相关问题

format.Node 会修改 AST 吗？官方接口说明它不会修改传入节点；格式化器只把结果写入目标 io.Writer。

为什么局部节点的 import 没有排序？因为它不是完整 *ast.File，格式化器没有完整文件的导入上下文。

只有表达式时还需要 FileSet 吗？仍应传入与节点位置匹配的 FileSet；如果表达式来自 parser.ParseExpr，其位置语义与真实文件不同，适合把它当作独立表达式输出。