Go ast.CommentMap.Update 怎样迁移替换节点的注释归属

用 Go 重写源码时，最容易被忽略的不是 AST 节点本身，而是节点旁边的注释。ast.CommentMap 记录的是“某个节点指针对应哪些注释组”；如果把旧节点替换成新节点，注释不会因为内容看起来相同就自动跟过去。

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

处理这种迁移，直接调用 cmap.Update(old, new)。它会删除旧节点键，把旧节点关联的注释追加到新节点键，并返回 new。如果新节点原本已有注释，结果是两组列表合并，而不是覆盖。

记住一句话：AST 替换解决“树里放哪个节点”，CommentMap.Update 解决“旧节点的注释跟谁走”。

为什么替换 AST 节点后注释会“丢”

CommentMap 的本质是 map[ast.Node][]*ast.CommentGroup。映射键是接口背后的节点身份，不是节点内容的字符串快照。下面这张图只表达静态对象关系，帮助区分原 AST、新节点和注释映射的边界。

例如，先把一个 *ast.AssignStmt 放入映射，再新建另一个赋值节点。即使两个节点打印出来的代码相同，新节点仍然是新的键。此时只改 AST 树而不改映射，遍历新树时就找不到旧注释。

Update 的迁移规则与边界

官方实现的核心动作很短：取出 old 的注释列表，删除旧键，再用 append 追加到 new 的列表中，最后返回 new。它不重新计算注释应该属于哪一个语法节点，也不改变注释组对象本身。

package main

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

func main() {
	// 解析带注释的最小文件，保留 FileSet 以便后续打印位置。
	const src = "package demo\n\n// 保留给新节点的说明\nvar value = 1\n"
	fset := token.NewFileSet()
	file, err := parser.ParseFile(fset, "demo.go", src, parser.ParseComments)
	if err != nil {
		// 解析失败时立即退出，避免拿不完整的 AST 继续改写。
		panic(err)
	}

	// 从原 AST 建立注释映射；声明节点是迁移的旧节点。
	cmap := ast.NewCommentMap(fset, file, file.Comments)
	oldDecl := file.Decls[0]
	newDecl := &ast.GenDecl{Tok: oldDecl.(*ast.GenDecl).Tok}
	newDecl.Specs = oldDecl.(*ast.GenDecl).Specs

	// Update 会删除 old 键，并把旧注释组追加到 new 键。
	returned := cmap.Update(oldDecl, newDecl)
	file.Decls[0] = returned.(*ast.GenDecl)

	// 这里用 Comments 汇总迁移后的注释组，便于接入后续格式化流程。
	fmt.Println(len(cmap.Comments()))
}

示例中的关键不是复制 GenDecl 的所有字段，而是把新节点放回 AST 后，立刻用同一对 old/new 更新映射。生产代码通常会先完成节点改写，再在替换点集中调用 Update，这样不容易漏掉旧节点。

旧节点有注释、新节点也有注释时怎么办

这种情况常见于重写器先给新节点生成一组工具注释，再迁移原始注释。Update 使用追加语义：新节点已有列表在前，旧节点列表追加在后。它不会去重，也不会按源码位置重新排序映射键。

func moveComments(cmap ast.CommentMap, old, new ast.Node) ast.Node {
	// old 与 new 必须是当前映射和当前 AST 中对应的节点对象。
	if old == nil || new == nil {
		// nil 不是有效的迁移目标，调用方应保留原节点并记录原因。
		return old
	}

	// 如果 new 已经有注释，Update 会把 old 的列表追加到它后面。
	return cmap.Update(old, new)
}

迁移后的回归检查清单

迁移完成后，不要只看新节点能否打印。至少检查三件事：旧节点是否已经不在映射中，新节点是否拿到了原注释，以及最终 AST 过滤后是否只保留当前树上的节点。

func checkCommentOwner(cmap ast.CommentMap, file *ast.File, old, new ast.Node) bool {
	// Filter 只保留 file 当前 AST 中存在的节点，适合检查替换后的归属。
	filtered := cmap.Filter(file)
	_, oldStillExists := filtered[old]
	newComments := filtered[new]

	// old 不应继续作为当前树的注释键，new 至少应有一组迁移后的注释。
	return !oldStillExists && len(newComments) > 0
}

如果 old 仍然出现在未过滤的映射里，不必立刻认定迁移失败：CommentMap 可能还保留着已经从 AST 树移除的其他节点键。把 Filter(file) 作为最终输出前的清理动作，再检查新树上的注释归属更稳妥。

常见问题还有两个：Update 不会帮你替换 file.Decls 或父节点字段，树结构仍要由调用方完成；它也不会重新按行号推断注释归属，只有明确的旧节点到新节点关系才适合使用。

相关问题

CommentMap.Update 会复制 CommentGroup 吗？不会。它移动的是注释组指针列表，注释组对象本身不被复制。

什么时候应该重新调用 NewCommentMap？如果改写范围很大、节点关系已经无法逐一对应，重新根据最终 AST 和完整注释列表建立映射更合适；局部替换则用 Update 更直接。

为什么 Update 后打印顺序还要关注？Update 只维护节点到列表的关联。需要按源码位置输出全部注释时，使用 cmap.Comments() 获取排序后的注释组，而不是依赖 map 遍历顺序。

迁移清单可以压缩成四句话：先保存旧节点，创建并挂入新节点，再调用 cmap.Update(old, new)，最后用 Filter 和 Comments 检查当前树。这样注释归属就不会随着一次 AST 替换悄悄断开。