Go CommentMap.Update 为什么没有替换 AST 中的旧节点

CommentMap.Update(old, replacement) 修改的是注释映射中的节点关联，不会替换 AST 父字段里的旧节点。要让语法树指向新节点，需要把 replacement 写回实际父字段或切片元素，再按需要整理注释列表。

官方文档：https://pkg.go.dev/go/ast

先看父节点引用是否真的改变

典型现象是：调用 Update 后，新节点已有注释关联，但遍历语法树时仍然看到旧节点。先观察父字段，例如 file.Decls[0]，是否还保存 old。局部变量改成 replacement、接住 Update 的返回值，都不会自动改变这个切片元素。

这里需要区分“节点对象的内容被修改”与“引用被替换”。如果直接改旧节点的某个字段，树上仍持有同一个对象，可以观察到内容变化；如果分配了一个新对象，父字段仍需显式更新。节点内容相同，也不代表两个指针作为映射键是同一个键。

分清注释映射负责的范围

CommentMap 的组成是节点键与注释组列表。NewCommentMap 根据传入语法树和注释列表建立关联，Update 将旧节点已经关联的注释组转到新节点，返回新节点供调用方使用。它没有接收父节点位置的参数，也不承担在语法树中搜索并替换节点的职责。

从标准库实现可以看出，有旧注释列表时，它删除旧键，再把列表追加到新键现有列表中。它不会重算注释与子节点的关系，不会递归迁移整个被替换子树的键，也不会修改 File.Comments、声明的 Doc 字段或注释位置。若旧键没有关联列表，不能指望 Update 凭空为新节点找到注释。

把新节点写回父字段的完整示例

下面的完整示例刻意保持声明文本不变，只创建一个新的声明对象，用指针比较观察“换对象”这件事。代码可供读者运行比较；图示仅说明结构，不代表实际运行记录。

package main

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

func main() {
    // 紧邻变量声明的注释，用于观察关联迁移。
    src := "package demo\n\n// Count 保存计数。\nvar Count = 1\n"
    fs := token.NewFileSet()
    file, err := parser.ParseFile(fs, "demo.go", src, parser.ParseComments)
    if err != nil {
        log.Fatal(err)
    }
    if len(file.Decls) != 1 {
        log.Fatal("示例需要一个顶层声明")
    }
    old, ok := file.Decls[0].(*ast.GenDecl)
    if !ok {
        log.Fatal("示例声明类型不匹配")
    }
    cmap := ast.NewCommentMap(fs, file, file.Comments)
    if len(cmap[old]) == 0 {
        log.Fatal("旧声明没有关联注释")
    }

    // 复制出不同的声明对象，保留原位置；这不是深复制。
    copied := *old
    replacement := &copied
    cmap.Update(old, replacement)
    fmt.Println("只迁移映射后仍引用旧声明：", file.Decls[0] == old)
    fmt.Println("新声明关联注释组数：", len(cmap[replacement]))

    // 真正替换父字段，不能只改局部变量。
    file.Decls[0] = replacement
    file.Comments = cmap.Filter(file).Comments()
    fmt.Println("父字段已经引用新声明：", file.Decls[0] == replacement)
}

只调用 Update 的位置，第一个比较表达式应为 true：父字段还引用 old。随后写入 file.Decls[0] = replacement，父字段才引用新声明。这个判断比肉眼查看格式化文本更直接，因为本例新旧声明的内容相同。

示例使用浅复制，Specs 等内部对象仍共享，仅用于隔离顶层声明身份。实际重写如果要独立修改内部节点，应按任务构造相应子节点，并分别处理原有注释归属。不能把此示例的复制方式当作通用深复制方案。

用三个观察点区分不同故障

定位时可以分别看父字段、新键和过滤后的注释列表。父字段还指向 old，说明树替换遗漏；新键没有注释，先判断旧键本来是否关联了注释；新键有关联但过滤后消失，则检查 replacement 是否真的位于传给 Filter 的那棵树内。

Filter(file) 根据实际树中的节点保留映射条目。如果只迁移映射、没有写回新节点，新键对应的节点不在树里，筛选时自然不能保留该条目。示例先完成父字段赋值，再以 Comments() 取得按源码顺序整理的注释组，赋给 File.Comments。该操作不保证任意源码搬移后的排版正确；跨位置搬移节点仍需单独处理位置与打印策略。

相关问题与修复清单

只修改原节点字段，还要调用 Update 吗？

如果映射键对应的节点对象没有更换，就没有为该节点迁移键的必要。内部节点被换掉时，则需要按内部节点各自的关联考虑。

Update 返回新节点，为什么没有自动更新树？

返回一个值与改写保存该值的父字段是两回事。调用方可以利用返回值赋值，但应写入真正的树结构，而不只是新的局部变量。

新节点原来就有关联注释，会被覆盖吗？

当前实现会把旧节点列表追加到新节点列表；这不等于注释语义已经重新判断，也不承诺消除重复项。需要合并时应先明确希望保留哪些注释组。