Go AST 删除节点后怎么用 CommentMap 保留注释归属

用 Go 修改 AST 时，直接从 ast.File.Decls 或 BlockStmt.List 中删除节点，只改变了语法树结构，并不会自动从 ast.File.Comments 中移除原来的注释。要让注释继续跟着正确的节点走，做法是先用 ast.NewCommentMap 建立映射：删除节点后调用 Filter，替换节点时调用 Update。

删除节点：先改 AST，再用 cmap.Filter(file).Comments() 取回仍有对应节点的注释；替换节点：用 cmap.Update(old, new) 把旧节点上的注释转移给新节点，最后同样用 Filter 生成文件的注释列表。

• 解析阶段：必须带上 parser.ParseComments，否则没有可供映射的注释组。
• 删除阶段：切片操作只负责移除 AST 节点，注释清理交给 Filter。
• 替换阶段：节点语义改变但注释仍适用时，先 Update，再把新节点放回树。
• 输出阶段：把过滤后的结果重新赋给 file.Comments，不要只保留内存中的 CommentMap。

CommentMap 解决的是节点与注释的关联

ast.CommentMap 本质上是“AST 节点到注释组列表”的映射。NewCommentMap 会根据源码位置建立关联：同一行尾部的注释通常属于前面的节点，紧跟节点且与下一个节点之间有空行的注释也会归到前一个较大的节点；无法归给前一个节点时，才会考虑后面的节点。

因此，CommentMap 不是按变量名保存注释，也不是给注释附加一个永远不变的 ID。源码重写后，旧节点可能已经不存在，新节点也可能需要接手旧注释，这正是 Filter 和 Update 的分工。

只删除 AST 节点，为什么会留下旧注释

下面的代码从声明列表中删除一个变量声明。它能改变语法树，但如果没有同步处理 file.Comments，被删除声明上方或行尾的注释仍可能被格式化输出。

package main

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

func removeVar(file *ast.File) {
	for i, decl := range file.Decls {
		gen, ok := decl.(*ast.GenDecl)
		if !ok || gen.Tok != token.VAR {
			continue
		}
		// 只改声明切片；此时注释列表还没有被同步清理。
		copy(file.Decls[i:], file.Decls[i+1:])
		file.Decls = file.Decls[:len(file.Decls)-1]
		break
	}
}

func parseSource(src []byte) (*token.FileSet, *ast.File, error) {
	fset := token.NewFileSet()
	// ParseComments 保留注释组，后续 CommentMap 才有输入。
	file, err := parser.ParseFile(fset, "input.go", src, parser.ParseComments)
	return fset, file, err
}

这个问题的关键不在 copy 是否正确，而在于 CommentMap 仍然持有被删除节点作为 key。输出前必须依据修改后的 AST 过滤一次，否则文件的注释集合与语法树不一致。

删除节点后用 Filter 清理注释

删除完成后，调用 cmap.Filter(file) 会返回只包含当前 AST 中仍存在节点的映射；再调用 Comments() 按源码顺序取出注释组，并赋回 file.Comments。

func removeVarAndComments(src []byte) ([]byte, error) {
	fset := token.NewFileSet()
	// 解析时保留注释，避免后续只能处理没有注释的 AST。
	file, err := parser.ParseFile(fset, "input.go", src, parser.ParseComments)
	if err != nil {
		return nil, err
	}

	cmap := ast.NewCommentMap(fset, file, file.Comments)
	for i, decl := range file.Decls {
		gen, ok := decl.(*ast.GenDecl)
		if !ok || gen.Tok != token.VAR {
			continue
		}
		// 移除目标节点，但不在这里手工猜测它关联了哪些注释。
		copy(file.Decls[i:], file.Decls[i+1:])
		file.Decls = file.Decls[:len(file.Decls)-1]
		break
	}

	// Filter 丢弃已经不在 file 中的节点映射，并按源码顺序重建注释列表。
	file.Comments = cmap.Filter(file).Comments()
	var out bytes.Buffer
	if err := format.Node(&out, fset, file); err != nil {
		return nil, err
	}
	return out.Bytes(), nil
}

这里的 Filter 只负责“当前树里还存在什么”。它不会把一个删除节点的注释自动猜给相邻声明，因此删除工具应先明确节点的生命周期：确认该声明连同其注释都应消失，再过滤整个文件。

替换节点时用 Update 保留原注释

如果只是把旧节点换成语义等价的新节点，例如把一条变量声明重写成常量声明，注释通常仍然有价值。这时不要依赖新旧节点的源码位置重新匹配，而是显式调用 Update。

func replaceVarWithConst(file *ast.File, cmap ast.CommentMap) {
	for i, decl := range file.Decls {
		old, ok := decl.(*ast.GenDecl)
		if !ok || old.Tok != token.VAR {
			continue
		}

		newDecl := &ast.GenDecl{
			// 复用起始位置，让格式化器仍能按原声明定位。
			TokPos: old.TokPos,
			Tok:    token.CONST,
			Specs:  old.Specs,
		}
		// 把旧声明关联的注释转移给新声明。
		cmap.Update(old, newDecl)
		file.Decls[i] = newDecl
		break
	}

	// 清掉可能在多次变换中遗留的无效映射。
	file.Comments = cmap.Filter(file).Comments()
}

Update 会删除旧 key，并把旧节点上的注释追加到新节点。如果新节点本身已经有映射，原有注释会与转移过来的注释合并；因此批量重写时要避免对同一替换重复调用。

多次改写时要守住这几个边界

先解析注释。没有 parser.ParseComments 时，file.Comments 为空，之后再创建 CommentMap 也无法恢复源文件里的注释。

不要把位置当作稳定身份。节点的 Pos 和 End 适合描述源码范围，不适合替代新旧节点的对应关系。替换节点时，显式 Update 比重新扫描位置更清楚。

每轮变换后都要整理 File.Comments。如果工具连续执行删除、替换和插入，建议每个阶段都在 AST 结构稳定后调用一次 Filter，避免下一阶段继续携带已经失效的 key。

CommentMap 不负责格式化。它只管理注释组与节点的关联；最终输出仍由 go/format 或其他打印器完成。本文关注的是注释归属，不展开完整的源码格式化策略。

删除和替换的速查表

常见问题

CommentMap.Filter 会修改原来的 map 吗？

官方 API 返回一个只包含当前 AST 对应节点的新映射。工程上应直接使用返回值的 Comments() 更新 file.Comments，不要假设原 map 已经被原地清空。

删除函数声明也能用同样的做法吗？

可以。只要节点实现 ast.Node 并且已经从当前 AST 中移除，过滤逻辑不依赖它是变量、函数还是其他声明。

替换节点后注释仍然位置不对怎么办？

先确认注释原本是否属于旧节点，再确认新节点已经通过 Update 接手映射，并在最终 AST 稳定后重新执行 Filter。若注释本来属于被删除的节点，就不应强行转移给邻居。

掌握这条边界即可：AST 的增删改负责结构，CommentMap 的 Filter 与 Update 负责把注释关联同步到新的结构上。