在Go语言的静态分析与代码生成场景中，我们经常需要从源码中提取结构体定义以及它们上方的文档注释。Go官方标准库中的go/ast包把源代码解析成抽象语法树，让我们可以以编程方式访问类型声明和注释内容。理解AST中注释的存储位置以及遍历方式，是准确提取文档信息的关键。
Go AST中注释的存储方式
使用go/parser解析文件时，注释默认会被关联到对应的语法节点上，也可以通过parser.ParseComments模式保留全部注释。对于结构体类型声明，其文档注释通常保存在与之相邻的GenDecl或TypeSpec节点的Doc字段中，而结构体字段的注释则在Field.Doc里。
解析结构体文档注释的基本步骤
- 使用parser.ParseFile读取并解析Go源文件，开启ParseComments。
- 遍历文件中的声明，筛选出*ast.GenDecl且Tok为token.TYPE的节点。
- 在TypeSpec中判断Type是否为*ast.StructType，读取Spec.Doc获取结构体注释。
- 遍历StructType.Fields.List，通过Field.Doc提取字段注释。
完整代码示例
下面是一段可直接运行的示例程序，用于打印指定源文件中所有结构体及其文档注释：
package main
import (
"go/ast"
"go/parser"
"go/token"
"fmt"
"os"
)
func main() {
// 要解析的Go源文件路径
srcFile := "./demo.go"
fset := token.NewFileSet()
// 解析文件并保留注释
file, err := parser.ParseFile(fset, srcFile, nil, parser.ParseComments)
if err != nil {
fmt.Println("解析失败:", err)
os.Exit(1)
}
// 遍历文件顶层声明
for _, decl := range file.Decls {
genDecl, ok := decl.(*ast.GenDecl)
if !ok || genDecl.Tok != token.TYPE {
continue
}
for _, spec := range genDecl.Specs {
typeSpec := spec.(*ast.TypeSpec)
structType, ok := typeSpec.Type.(*ast.StructType)
if !ok {
continue
}
// 输出结构体名称与文档注释
fmt.Printf("结构体: %sn", typeSpec.Name.Name)
if typeSpec.Doc != nil {
fmt.Println("文档注释:", typeSpec.Doc.Text())
}
// 遍历字段注释
for _, field := range structType.Fields.List {
if field.Doc != nil {
fmt.Printf(" 字段 %s 注释: %s", field.Names[0].Name, field.Doc.Text())
}
}
}
}
}
注意事项
在实际工程中，如果注释与类型声明之间隔了空行，AST可能无法将其识别为Doc，而是归入文件级注释。因此书写文档时应遵循Go惯例，把注释紧挨着结构体或字段上方。此外，使用ast.Inspect可以更简洁地深度遍历节点，适合复杂项目使用。
掌握Go AST解析结构体注释的方法，是编写文档生成器、ORM绑定工具以及接口校验脚本的重要基础。
小结
通过go/parser与go/ast包，我们可以稳定地提取结构体及其字段的文档注释。核心在于理解TypeSpec.Doc与Field.Doc的对应关系，并在解析时保留注释信息。熟练运用这些API，能够显著提升Go项目自动化工具的开发效率。