Go go/parser.ParseFile 怎样保留注释并建立可用的 AST

如果只想分析一份 Go 源码文件，不需要先搭建完整类型检查器。用 token.FileSet 管理位置，用 parser.ParseFile 得到 ast.File，并在模式中加入 parser.ParseComments，就能同时读取包名、声明和注释。关键点是：注释不会默认进入 AST，FileSet 也不能省略。

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

下面的示例只处理单文件解析，适合做轻量源码索引、注释提取或格式化前的结构读取。

ParseFile 的最小输入和输出

ParseFile 接收一个非空的 *token.FileSet、文件名、源码和模式。源码可以是字符串、[]byte 或 io.Reader；这里直接传字符串，文件名只用于记录位置信息。

package main

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

func main() {
    src := "package demo\n\n// User 是一个示例类型。\ntype User struct {\n    Name string\n}"

    // FileSet 保存 token.Pos 到文件名、行号的映射。
    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "demo.go", src, 0)
    if err != nil {
        // 解析失败时不要继续读取 file 的结构。
        fmt.Println("parse error:", err)
        return
    }
    fmt.Println(file.Name.Name, len(file.Decls))
}

这段代码得到的 file 是 *ast.File。file.Name.Name 是包名，file.Decls 保存顶层声明。模式传 0 时能解析语法结构，但不会把普通注释收集到 file.Comments。

用 ParseComments 把注释留在 AST 中

需要读取文档注释时，把模式改成 parser.ParseComments。解析器会把注释组挂到 ast.File.Comments，声明本身的文档注释则通常可从 ast.GenDecl.Doc 或 ast.TypeSpec.Doc 读取。

package main

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

func main() {
    src := "package demo\n\n// User 表示一个用户。\ntype User struct{}"

    // ParseComments 让注释组进入 ast.File.Comments。
    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "demo.go", src, parser.ParseComments)
    if err != nil {
        fmt.Println("parse error:", err)
        return
    }

    fmt.Println("comments:", len(file.Comments))
    for _, decl := range file.Decls {
        // 只关注声明节点，其他 AST 节点不在本文范围内。
        if gen, ok := decl.(*ast.GenDecl); ok && gen.Doc != nil {
            fmt.Println(gen.Doc.Text())
        }
    }
}

这里的两个入口用途不同：file.Comments 是文件级注释集合，GenDecl.Doc 更适合跟随某个声明读取文档。不要把“有注释”误认为“每个注释都自动绑定到声明”，两者之间还受注释位置影响。

空源码、语法错误和部分 AST 怎么处理

空字符串不是“没有问题的空 AST”。它缺少包声明，解析器会返回错误；源码有语法错误时，返回值可能包含部分 AST，同时错误描述具体位置。生产代码应先判断 err，再决定是否使用部分结果。

fset := token.NewFileSet()
file, err := parser.ParseFile(fset, "broken.go", "package demo; type User struct {", parser.AllErrors)
if err != nil {
    // Position 能把错误映射回文件名和行列，便于展示给用户。
    if file == nil {
        fmt.Println("没有可用 AST:", err)
        return
    }
    fmt.Println("部分 AST，仍需修复:", err)
}

parser.AllErrors 只改变错误报告范围，不会把不完整源码变成合法程序。需要稳定分析多个完整包、解析导入关系或做类型信息关联时，应考虑 golang.org/x/tools/go/packages；单文件结构读取继续使用 go/parser 更直接。

一张速查表和两个常见误区

第一个误区是把 ParseComments 当成默认行为；第二个误区是拿到非空 file 就忽略 err。最小程序可以容忍部分结果，代码扫描或索引服务则应明确记录错误并决定是否丢弃本次 AST。

相关问题

ParseFile 的 filename 必须是真实文件吗？不需要。源码非空时可以直接传字符串，filename 主要用于位置信息和错误文本。

为什么需要 token.FileSet？AST 中的位置是 token 位置，FileSet 负责把它映射到文件、行和列。

ParseFile 能直接分析整个项目吗？它面向单文件；完整包加载、导入和类型信息应交给更高层的包分析工具。