Go printer.CommentedNode 怎样让生成源码保留指定注释

我在做 Go 源码生成时遇到过一个很容易误判的问题：AST 节点已经拿到了，为什么输出结果里的注释却不见了？关键在于 printer.Fprint 打印的是你传入的节点；如果要把指定注释一起交给打印器，需要用 printer.CommentedNode 把目标节点和注释组明确绑定。

CommentedNode 只有两个核心字段：Node 是要输出的 AST 节点，Comments 是要考虑的 []*ast.CommentGroup。它不会自动复制整个文件的所有注释，也不会替你决定哪些注释属于业务对象。

CommentedNode 的两个字段分别负责什么

官方文档对它的定义很直接：它把一个 AST 节点和对应的注释绑定起来，并且可以作为 Fprint 的参数。这里的“对应”不是一个自动搜索结果，而是你放进 Comments 切片里的那些 *ast.CommentGroup。

因此，想保留“指定注释”的动作可以拆成两部分：先从解析结果里拿到注释组，再把筛选结果放进 CommentedNode.Comments。如果把 Comments 留空，打印器没有理由凭空恢复注释。

解析时先打开注释信息

parser.ParseFile 默认面向 AST 解析；要让文件对象保留注释，需要传入 parser.ParseComments。解析成功后，文件级的 ast.File.Comments 就能提供注释组。下面的例子只选择包含“保留”字样的注释，并打印对应的函数声明。

package main

import (
	"bytes"
	"errors"
	"fmt"
	"go/ast"
	"go/parser"
	"go/printer"
	"go/token"
	"strings"
)

func printSelectedComment() (string, error) {
	src := `package demo

// 保留：生成器需要把这个说明带回输出源码
func greet() string {
	return "hello"
}

// 丢弃：这段注释不属于本次输出对象
var unused = 1
`

	// ParseComments 让 ast.File 收集源文件中的注释组。
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "demo.go", src, parser.ParseComments)
	if err != nil {
		return "", fmt.Errorf("解析 Go 源码失败: %w", err)
	}

	// 这里只取第一个函数声明，真实生成器应按名称或位置选择目标节点。
	var fn *ast.FuncDecl
	for _, decl := range file.Decls {
		if candidate, ok := decl.(*ast.FuncDecl); ok && candidate.Name.Name == "greet" {
			fn = candidate
			break
		}
	}
	if fn == nil {
		return "", errors.New("没有找到 greet 函数")
	}

	// 注释组由调用方筛选，未放入 keep 的注释不会随 CommentedNode 输出。
	keep := make([]*ast.CommentGroup, 0, 1)
	for _, group := range file.Comments {
		if strings.Contains(group.Text(), "保留") {
			keep = append(keep, group)
		}
	}
	if len(keep) == 0 {
		return "", errors.New("没有找到需要保留的注释")
	}

	var out bytes.Buffer
	// Node、Comments 与 fset 来自同一次解析，位置关系可以被打印器使用。
	err = printer.Fprint(&out, fset, &printer.CommentedNode{
		Node:     fn,
		Comments: keep,
	})
	if err != nil {
		return "", fmt.Errorf("打印源码失败: %w", err)
	}
	return out.String(), nil
}

这段代码的重点不是“按文本搜索”本身，而是把注释选择权留在调用方。项目也可以按照注释位置、声明名称或自定义元数据选择 CommentGroup；只要最终交给 CommentedNode 的是对应的注释组，打印器就有机会按它们的位置信息排版。

节点和注释要共享同一个位置上下文

AST 里的位置不是脱离上下文的整数。token.Pos 需要结合 token.FileSet 才能映射到文件和行列。因而，最稳妥的做法是让目标节点、注释组和传给 Fprint 的 FileSet 都来自同一次解析。

如果把一个 AST 节点从 A 文件的解析结果拿出来，却用 B 文件的注释组，或者用完全不匹配的 FileSet 去打印，注释和节点的相对位置就没有可靠语义。生成器里常见的错误是只保存了节点指针，却丢掉了它对应的文件集。

这也是为什么示例里把 fset 一直保留到最后：parser.ParseFile 返回的 file、file.Comments、函数声明和 fset 是一组位置相关的数据，应该一起传递到输出阶段。

只输出节点时，未选注释不会自动跟随

printer.Fprint 可以打印整个 *ast.File，也可以打印一个声明或语句。当输出范围缩小到函数声明时，文件中其他声明附近的注释并不属于这个输出对象。即使你传入了 CommentedNode，也只是显式允许指定的 Comments 参与排版，不是把全文件注释做一次全量合并。

可以把输出策略理解成下面的关系：

• 输出整个文件：把 *ast.File 交给打印器，文件范围内的 AST 与注释由文件结构共同决定。
• 输出单个声明：把声明作为 Node，只把属于该声明的注释组放入 Comments。
• 输出合成节点：除了构造 AST，还要为节点和注释建立可用的位置关系，不能只拼一个没有位置信息的对象。

这里的“属于”需要由生成器的业务规则判断。CommentedNode 提供的是传递通道和打印入口，不是注释归属分析器；它也不负责重排、合并或推断注释语义。

生成源码时的三个边界

我通常会在生成器里保留下面三个检查点，避免把“注释没了”误判成 printer 的 bug。

1. 解析边界：确认调用 parser.ParseFile 时包含 parser.ParseComments，否则后面没有可筛选的 CommentGroup。
2. 对象边界：确认 Node 真的是希望输出的 AST 类型，例如函数声明，而不是整个文件或另一个声明。
3. 位置边界：确认 Node、Comments 和 FileSet 来自同一位置上下文；合成 AST 则要显式设计位置。

这三个检查点比盯着最终字符串更有效，因为每一个都对应一个独立的数据来源。只要注释没有解析进来、没有放进 Comments，或者位置上下文错配，最后的文本自然不会符合预期。

结论：把注释保留当成显式绑定

Go 的 printer.CommentedNode 适合做“节点级源码输出”：Node 指定输出对象，Comments 指定允许一起打印的注释组，FileSet 提供位置解释。正确顺序是解析时保留注释、按业务规则筛选、保持位置上下文一致，最后把包装后的节点交给 printer.Fprint。

如果只是想把原文件完整格式化，直接打印 *ast.File 通常更自然；如果只想输出某个声明并保留其中几条注释，才使用 CommentedNode。它解决的是“把哪些注释交给打印器”的接口问题，不替代注释归属和重排策略。

相关问题

CommentedNode 会自动保留所有文件注释吗？

不会。只有解析得到且被放入 Comments 的注释组才进入这个包装对象的打印范围。

为什么传入了注释，位置仍然不对？

优先检查节点、注释组和 FileSet 是否来自同一解析上下文；然后检查合成节点是否有可用的位置信息。

是否必须输出 CommentedNode？

不必须。它是传给 printer.Fprint 的一种节点形态，完整文件或不需要附加注释的 AST 可以直接传普通节点。

资料来源：https://pkg.go.dev/go/printer#CommentedNode、https://pkg.go.dev/go/printer#Fprint、https://pkg.go.dev/go/parser#ParseFile、https://pkg.go.dev/go/ast#CommentGroup