Go ast.CommentGroup.Text 为什么会移除注释指令

如果你用 Go 的 go/ast 提取注释，发现 ast.CommentGroup.Text() 的结果里少了 //go:noinline、//line 或 //export，这不是解析丢数据，而是 API 的设计。Text() 产出的是适合文档和示例使用的规范化文本；需要保留源文件原样时，应读取 Comment.Text。

本文按“升级范围—差异表—旧代码风险—新写法—回归检查—迁移清单”的方式，把这两个字段的职责拆开。先记住一句话：文档提取用 CommentGroup.Text()，源码保真用 Comment.Text，两者都依赖 parser.ParseComments。

官方资料：https://pkg.go.dev/go/ast#CommentGroup.Text

一、升级范围：先确认注释进入了 AST

parser.ParseFile 默认不会把注释加入 AST。调用时要把 parser.ParseComments 放进模式参数，否则 ast.File.Comments 为空，后续没有任何 CommentGroup 可以读取。

package main

import (
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
)

func main() {
	src := `package demo

// ExportedName 用来演示注释会进入 AST。
//go:noinline
func ExportedName() {}
`

	fset := token.NewFileSet()
	file, err := parser.ParseFile(
		fset,
		"demo.go",
		src,
		parser.ParseComments, // 只有设置该模式，file.Comments 才会保存注释组
	)
	if err != nil {
		panic(err) // 示例输入固定；真实工具应把文件名和解析错误一起返回
	}

	for _, group := range file.Comments {
		fmt.Printf("原始条数: %d，文档文本: %q\\n", len(group.List), group.Text())
		for _, comment := range group.List {
			fmt.Printf("原始 Comment.Text: %q\\n", comment.Text) // 逐条读取可保留指令
		}
	}

	_ = ast.CommentGroup{} // 仅用于说明 file.Comments 的元素类型是 *ast.CommentGroup
}

这里的 file.Comments 是按源文件顺序保存的注释组。一个 CommentGroup 表示中间没有其他 token、也没有空行分隔的一串注释；它的 List 则保存每一条 *ast.Comment。

二、变更表：Comment.Text 与 CommentGroup.Text 的职责不同

三、旧代码风险：Text 为什么会移除注释指令

CommentGroup.Text() 的目标不是复制源文件，而是把注释转换成更适合文档消费的文本。当前实现会先去掉 //、/*、*/ 等标记和行注释后的第一个空格，再识别指令行；匹配到的指令不会加入结果。

官方实现把以下形式视为指令：

• 以 line 、extern 或 export 开头的行，例如 //line 10 "generated.go"；
• 符合“小写字母或数字 + 冒号 + 小写字母或数字”开头规则的行，例如 //go:noinline、//go:linkname。

这层过滤是为了避免编译器、链接器、cgo 或源码位置相关控制语句混进面向读者的文档。它只影响 Text() 的返回值，不会修改 group.List 里的 Comment 节点。

package main

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

func main() {
	src := `package demo

// 这是普通说明。
//go:noinline
// 说明仍然属于同一组。
//line 50 "virtual.go"
func Run() {}
`

	file, err := parser.ParseFile(token.NewFileSet(), "demo.go", src, parser.ParseComments) // 开启注释保留
	if err != nil {
		panic(err) // 生产代码应根据调用方约定返回错误
	}

	group := file.Comments[0]
	fmt.Printf("Text() = %q\\n", group.Text()) // 指令行不会出现在这里
	for _, c := range group.List {
		fmt.Printf("Comment.Text = %q\\n", c.Text) // 原始节点仍能看到每一条指令
	}
}

因此，遇到“注释明明在源文件里，Text() 却为空或少了一行”的现象，先看它是不是指令行，再看它是否因为空行和规范化规则被合并。不要先把问题归因于 AST 遍历失败。

四、新写法：按任务选择原始字段或文档方法

1. 生成文档、摘要或示例说明

如果产物是 Markdown、帮助页或 API 文档，使用 group.Text() 更合适。它会移除注释外壳、收敛连续空行、裁剪行尾空白，并在非空结果末尾补换行，调用方不需要重复实现这些规则。

func docText(group *ast.CommentGroup) string {
	if group == nil {
		return "" // 没有关联文档时返回空字符串
	}
	return group.Text() // 这里明确接受指令被过滤的语义
}

2. 扫描编译指令、保留源文件或做格式化工具

如果需要判断 //go:noinline 是否存在，或者要把注释原样写回文件，就遍历 group.List，读取每个 Comment.Text。不要用 strings.Contains(group.Text(), "go:noinline")，因为这个字符串可能已经被 Text() 删除。

func hasDirective(group *ast.CommentGroup, want string) bool {
	if group == nil {
		return false // 没有注释组时不匹配
	}
	for _, comment := range group.List {
		if comment.Text == "//"+want {
			return true // 直接比较完整的行注释，避免把普通说明误判为指令
		}
	}
	return false
}

如果工具要保留整段原文，还要注意 Comment.Text 是解析器提供的单条文本：行注释不含行末换行，注释中的回车会被解析器去掉。也就是说，它比源文件更接近“词法节点内容”，但仍不是带原始字节偏移的文件切片。

五、回归检查：几个容易被忽略的边界

1. 不要漏掉 ParseComments。 没有该模式时，file.Comments 不会按预期提供注释组。
2. 空注释组不能直接假设非空。 正常解析得到的 CommentGroup.List 有成员，但手工构造 AST 时仍应尊重 API 约定，必要时先判断指针和列表。
3. Text 的尾部换行是有条件的。 结果非空时才会以换行结束；空结果不会凭空增加换行。
4. 连续空行会被折叠。 如果你的工具要呈现原始排版，必须用 Comment.Text 配合位置和源文件内容自行处理。
5. 行注释首个空格会被去掉。 // 说明 和 //说明 在文档文本中会按 Text() 的规则整理，不适合拿来做字节级比较。

可以把下面这张关系图当作迁移判断：先决定结果是“给人看的文档”还是“给工具继续处理的源码元数据”，再决定读取入口。

六、迁移清单：把“文档文本”和“源文本”分开

最后的判断标准很简单：ast.CommentGroup.Text() 不是“注释内容的另一个字段”，而是一套面向文档的规范化视图；Comment.Text 才是逐条注释节点上的原始文本视图。只要先确定下游要消费哪一种语义，注释指令消失就不再是意外。

常见问题

为什么 CommentGroup.Text() 结果最后多一个换行？

这是它的约定：清理后只要结果非空，就在文本末尾补换行，方便拼接多段文档。

使用 Comment.Text 能拿到源文件中的精确空格吗？

它保留单条注释节点的文本，但不是完整源文件切片；回车会被解析器处理，行注释也不包含行末换行。需要字节级保真时，应结合原始输入和位置范围。

普通的 // go:noinline 会被过滤吗？

不会按同一规则处理。Text() 识别的是特定的指令格式，前导空格和拼写都会影响是否匹配。

可以只解析注释而不关心完整 AST 吗？

仍应通过 parser.ParseFile 等解析入口得到 AST，并启用 ParseComments。如果工具还要判断注释与声明的关系，AST 节点和位置信息同样有用。