Go ast.CommentMap 怎样在删除声明后保留关联注释

我在做 Go AST 重写时，最容易漏掉的不是节点本身，而是节点旁边的注释。直接从 file.Decls 删除声明，再调用 format.Node，通常会留下旧的 file.Comments，结果就是已删除声明的说明还出现在输出里。稳定的做法是：解析时保留注释，先创建 ast.CommentMap，修改 AST 后再用 Filter(file).Comments() 重建注释列表；如果是新指针替换旧节点，则先调用 Update(old, new)。

先把注释关联关系保存下来

CommentMap 的键是 AST 节点，值是与节点关联的注释组。关联并不是简单的“注释紧挨着哪一行”：官方规则会考虑注释是否和节点结束在同一行、是否位于节点后一行并隔着空行，以及节点前的注释。它还会尽量选择更大的节点来承接行尾注释，这正是重写工具不应自己重新猜测的部分。

删除声明后，用 Filter 重建 file.Comments

下面的例子删除第一个变量声明。关键顺序是先改 file.Decls，再把过滤后的注释组赋回 file.Comments。这样，变量声明的文档注释和行尾注释会一起被移除，包注释、常量注释和函数注释仍然保留。

package main

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

func main() {
    // 输入保留声明前后的注释，便于 CommentMap 建立关联。
    src := `// 包注释
package demo

// 保留的常量说明
const name = "go"

// 这个变量和它的行尾注释会被删除
var legacy = 1 // 旧字段

// 保留函数说明
func Run() { fmt.Println(name) }
`
    fset := token.NewFileSet()
    // ParseComments 是关键选项；SkipObjectResolution 避免无关对象解析。
    file, err := parser.ParseFile(fset, "demo.go", src, parser.ParseComments|parser.SkipObjectResolution)
    if err != nil {
        panic(err)
    }
    cmap := ast.NewCommentMap(fset, file, file.Comments)

    // 删除第一个 VAR 声明，但保留其他声明的节点指针。
    for i, decl := range file.Decls {
        gen, ok := decl.(*ast.GenDecl)
        if ok && gen.Tok == token.VAR {
            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 strings.Builder
    // format.Node 根据更新后的 AST 和注释列表生成 Go 源码。
    if err := format.Node(&out, fset, file); err != nil {
        panic(err)
    }
    fmt.Print(out.String())
}

这里不需要逐条删除注释。Filter 返回新的映射，只保留目标 AST 中仍存在的节点；Comments 再按源码顺序给出注释组。对声明列表做切片删除时，注意不要把已经删除的节点重新放回其他字段，否则它仍可能被遍历到。

替换节点时，先用 Update 迁移注释

删除和替换是两种不同动作。若把旧的 *ast.GenDecl 换成新建的节点，虽然新节点看起来位置相同，但它不是 CommentMap 的原键。我的经验是把节点替换拆成两步：先 cmap.Update(old, replacement)，再写回 AST 字段；最后统一执行 Filter(file)，这样能同时处理迁移和清理。

几个容易误判的边界

第一，CommentMap 不是文本位置索引，不能在改完节点位置后自行按行号重排全部注释。第二，Filter 只关心节点是否仍存在，不会替你判断新节点的语义是否正确。第三，解析时漏掉 ParseComments，后面再调用 NewCommentMap 已经没有完整注释可关联。最后，生成结果前仍要用 format.Node，不要把 AST 结构变化误当作源码字符串替换。

相关问题

只修改 GenDecl 的 Tok，需要调用 Update 吗？

如果仍使用同一个节点指针，通常不需要；修改完成后统一 Filter 即可。

为什么删除了声明，注释还在？

因为 file.Comments 是独立字段。仅修改 file.Decls 不会自动同步它，必须重新赋值过滤结果。

CommentMap 能保证注释语义永远正确吗？

不能。它按 AST 位置和节点关系建立关联；跨大范围移动代码时仍要检查新节点边界和输出格式。

对 AST 重写来说，最稳的收尾动作可以记成一句话：删除节点用 Filter，换节点用 Update，两者完成后再按根节点过滤一次。