1336 lines
53 KiB
Go
1336 lines
53 KiB
Go
package provider
|
||
|
||
import (
|
||
"fmt"
|
||
"go/ast"
|
||
"go/parser"
|
||
"go/token"
|
||
"os"
|
||
"path/filepath"
|
||
"strings"
|
||
)
|
||
|
||
// ASTWalker 处理 Go 抽象语法树（AST）的遍历器，专门用于发现 Provider 相关的结构体
|
||
//
|
||
// 架构设计：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ ASTWalker │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ fileSet: *token.FileSet - 文件集，记录源码位置信息 │
|
||
// │ commentParser: *CommentParser - 注释解析器，处理注解 │
|
||
// │ config: *WalkerConfig - 遍历器配置 │
|
||
// │ visitors: []NodeVisitor - 访问者列表，支持扩展 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 核心功能：
|
||
// - 文件过滤：根据配置跳过测试文件、生成文件等
|
||
// - AST 解析：使用 Go 标准库解析源文件为抽象语法树
|
||
// - 结构化遍历：按照 AST 层次结构进行遍历
|
||
// - 访问者模式：支持多个访问者同时处理不同的分析任务
|
||
// - 错误处理：提供完善的错误处理机制
|
||
//
|
||
// 执行流程：
|
||
// 1. 文件过滤 → 2. AST 解析 → 3. 遍历声明 → 4. 访问者通知 → 5. 结果收集
|
||
//
|
||
// 设计原则：
|
||
// - 单一职责：专注于 AST 遍历，不涉及具体的业务逻辑
|
||
// - 开闭原则：通过访问者模式支持功能扩展，无需修改核心代码
|
||
// - 接口隔离：定义清晰的访问者接口，避免过度依赖
|
||
// - 配置驱动：通过配置控制遍历行为，提高灵活性
|
||
//
|
||
// 使用场景：
|
||
// - Provider 注解发现：查找带有 @provider 注解的结构体
|
||
// - 代码分析：分析代码结构、依赖关系等
|
||
// - 代码生成：基于 AST 分析结果生成代码
|
||
// - 重构工具：基于 AST 进行代码重构操作
|
||
type ASTWalker struct {
|
||
fileSet *token.FileSet
|
||
commentParser *CommentParser
|
||
config *WalkerConfig
|
||
visitors []NodeVisitor
|
||
}
|
||
|
||
// WalkerConfig 配置 AST 遍历器的行为参数
|
||
//
|
||
// 配置选项：
|
||
// - IncludeTestFiles: 是否包含测试文件（_test.go 后缀）
|
||
// - IncludeGeneratedFiles: 是否包含生成的文件（.gen.go 后缀）
|
||
// - MaxFileSize: 最大文件大小限制（字节），防止大文件影响性能
|
||
// - StrictMode: 严格模式，启用更严格的验证和错误检查
|
||
//
|
||
// 使用场景：
|
||
// - 开发环境：包含测试文件，禁用严格模式，便于调试
|
||
// - 生产环境：跳过测试文件，启用严格模式，提高解析质量
|
||
// - 性能优化：设置合理的文件大小限制，跳过不必要的文件
|
||
type WalkerConfig struct {
|
||
IncludeTestFiles bool
|
||
IncludeGeneratedFiles bool
|
||
MaxFileSize int64
|
||
StrictMode bool
|
||
}
|
||
|
||
// NodeVisitor 定义 AST 节点访问者接口，支持在遍历过程中处理不同类型的节点
|
||
//
|
||
// 接口设计原则：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ NodeVisitor Interface │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ VisitFile: 文件级别处理，在文件开始时调用 │
|
||
// │ VisitGenDecl: 通用声明处理，类型、变量、常量声明 │
|
||
// │ VisitTypeSpec: 类型规范处理，具体的类型定义 │
|
||
// │ VisitStructType: 结构体类型处理，结构体类型定义 │
|
||
// │ VisitStructField: 结构体字段处理，结构体中的字段 │
|
||
// │ Complete: 完成处理，在文件处理完成时调用 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 调用时机：
|
||
// 1. VisitFile: 开始处理文件时调用，用于初始化文件级上下文
|
||
// 2. VisitGenDecl: 遇到通用声明时调用（type、var、const）
|
||
// 3. VisitTypeSpec: 遇到类型规范时调用（具体的类型定义）
|
||
// 4. VisitStructType: 遇到结构体类型时调用
|
||
// 5. VisitStructField: 遍历结构体字段时调用
|
||
// 6. Complete: 文件处理完成时调用，用于清理和结果收集
|
||
//
|
||
// 错误处理：
|
||
// - 如果任何方法返回错误，遍历过程会立即停止
|
||
// - 访问者应该根据错误类型决定是否继续处理
|
||
// - 建议使用 fmt.Errorf 包装错误信息，包含足够的上下文
|
||
//
|
||
// 扩展性：
|
||
// - 可以实现多个不同的访问者来处理不同的分析任务
|
||
// - 访问者之间相互独立，不会相互影响
|
||
// - 可以通过组合多个访问者来实现复杂的功能
|
||
type NodeVisitor interface {
|
||
// VisitFile 在开始处理新文件时调用，用于文件级别的初始化
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前处理的文件路径
|
||
// - node: 解析后的 AST 文件节点
|
||
//
|
||
// 返回值：
|
||
// - error: 如果返回错误，遍历过程会立即停止
|
||
//
|
||
// 使用场景：
|
||
// - 初始化文件级上下文信息
|
||
// - 记录文件级别的统计信息
|
||
// - 设置文件特定的配置
|
||
VisitFile(filePath string, node *ast.File) error
|
||
|
||
// VisitGenDecl 在遇到通用声明时调用（type、var、const）
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径
|
||
// - decl: 通用声明节点
|
||
//
|
||
// 返回值：
|
||
// - error: 如果返回错误，遍历过程会立即停止
|
||
//
|
||
// 使用场景：
|
||
// - 处理包级别的变量和常量声明
|
||
// - 分析声明的文档注释
|
||
// - 收集声明级别的元数据
|
||
VisitGenDecl(filePath string, decl *ast.GenDecl) error
|
||
|
||
// VisitTypeSpec 在遇到类型规范时调用（具体的类型定义）
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径
|
||
// - typeSpec: 类型规范节点
|
||
// - decl: 包含该类型规范的通用声明
|
||
//
|
||
// 返回值：
|
||
// - error: 如果返回错误，遍历过程会立即停止
|
||
//
|
||
// 使用场景：
|
||
// - 发现结构体、接口、函数类型等
|
||
// - 分析类型定义的注释和属性
|
||
// - 建立类型索引和关系图
|
||
VisitTypeSpec(filePath string, typeSpec *ast.TypeSpec, decl *ast.GenDecl) error
|
||
|
||
// VisitStructType 在遇到结构体类型时调用
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径
|
||
// - structType: 结构体类型节点
|
||
// - typeSpec: 对应的类型规范
|
||
// - decl: 包含该结构体的通用声明
|
||
//
|
||
// 返回值：
|
||
// - error: 如果返回错误，遍历过程会立即停止
|
||
//
|
||
// 使用场景：
|
||
// - 分析结构体定义
|
||
// - 处理结构体的注解和属性
|
||
// - 收集结构体级别的元数据
|
||
VisitStructType(filePath string, structType *ast.StructType, typeSpec *ast.TypeSpec, decl *ast.GenDecl) error
|
||
|
||
// VisitStructField 在遍历结构体字段时调用
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径
|
||
// - field: 结构体字段节点
|
||
// - structType: 所属的结构体类型
|
||
//
|
||
// 返回值：
|
||
// - error: 如果返回错误，遍历过程会立即停止
|
||
//
|
||
// 使用场景：
|
||
// - 分析字段类型和标签
|
||
// - 处理注入相关的标签（inject 标签）
|
||
// - 收集字段级别的依赖信息
|
||
VisitStructField(filePath string, field *ast.Field, structType *ast.StructType) error
|
||
|
||
// Complete 在文件处理完成时调用，用于清理和结果收集
|
||
//
|
||
// 参数：
|
||
// - filePath: 已完成处理的文件路径
|
||
//
|
||
// 返回值：
|
||
// - error: 如果返回错误，会影响整体处理结果
|
||
//
|
||
// 使用场景：
|
||
// - 清理文件级的临时数据
|
||
// - 收集和汇总处理结果
|
||
// - 执行文件级别的验证和检查
|
||
Complete(filePath string) error
|
||
}
|
||
|
||
// NewASTWalker 使用默认配置创建新的 ASTWalker 实例
|
||
//
|
||
// 初始化流程：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ NewASTWalker() │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 创建文件集：token.NewFileSet() │
|
||
// │ 2. 创建注释解析器：NewCommentParser() │
|
||
// │ 3. 设置默认配置：WalkerConfig{...} │
|
||
// │ 4. 初始化访问者列表：make([]NodeVisitor, 0) │
|
||
// │ 5. 构建遍历器实例：&ASTWalker{...} │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 默认配置：
|
||
// - IncludeTestFiles: false（跳过测试文件）
|
||
// - IncludeGeneratedFiles: false（跳过生成的文件）
|
||
// - MaxFileSize: 10MB（限制文件大小）
|
||
// - StrictMode: false（禁用严格模式）
|
||
//
|
||
// 返回值：
|
||
// - *ASTWalker: 配置好的遍历器实例，可以直接使用
|
||
//
|
||
// 使用示例：
|
||
//
|
||
// walker := NewASTWalker()
|
||
// visitor := NewProviderDiscoveryVisitor()
|
||
// walker.AddVisitor(visitor)
|
||
// err := walker.WalkFile("user_service.go")
|
||
//
|
||
// 注意事项：
|
||
// - 必须添加至少一个访问者才能进行有效的分析
|
||
// - 默认配置适用于大多数生产环境
|
||
// - 可以通过 WithConfig 方法修改配置
|
||
func NewASTWalker() *ASTWalker {
|
||
return &ASTWalker{
|
||
fileSet: token.NewFileSet(),
|
||
commentParser: NewCommentParser(),
|
||
config: &WalkerConfig{
|
||
IncludeTestFiles: false,
|
||
IncludeGeneratedFiles: false,
|
||
MaxFileSize: 10 * 1024 * 1024, // 10MB
|
||
StrictMode: false,
|
||
},
|
||
visitors: make([]NodeVisitor, 0),
|
||
}
|
||
}
|
||
|
||
// NewASTWalkerWithConfig 使用自定义配置创建新的 ASTWalker 实例
|
||
//
|
||
// 设计目标：
|
||
// - 提供灵活的配置选项
|
||
// - 支持不同的使用场景（调试、生产、测试）
|
||
// - 保持向后兼容性
|
||
//
|
||
// 参数处理：
|
||
// - 如果 config 为 nil，自动使用默认配置
|
||
// - 根据配置的 StrictMode 创建对应的注释解析器
|
||
//
|
||
// 自定义配置场景：
|
||
// - 调试模式：包含测试文件，启用严格模式
|
||
// - 性能优化：设置较小的文件大小限制
|
||
// - 开发模式：包含生成的文件进行分析
|
||
//
|
||
// 参数：
|
||
// - config: 自定义的遍历器配置（可为 nil）
|
||
//
|
||
// 返回值：
|
||
// - *ASTWalker: 使用指定配置的遍历器实例
|
||
//
|
||
// 使用示例：
|
||
//
|
||
// config := &WalkerConfig{
|
||
// IncludeTestFiles: true,
|
||
// IncludeGeneratedFiles: true,
|
||
// StrictMode: true,
|
||
// MaxFileSize: 5 * 1024 * 1024, // 5MB
|
||
// }
|
||
// walker := NewASTWalkerWithConfig(config)
|
||
//
|
||
// 注意事项：
|
||
// - 自定义配置会覆盖所有默认设置
|
||
// - 建议在特殊场景下使用自定义配置
|
||
// - 确保 MaxFileSize 设置合理，避免性能问题
|
||
func NewASTWalkerWithConfig(config *WalkerConfig) *ASTWalker {
|
||
if config == nil {
|
||
return NewASTWalker()
|
||
}
|
||
|
||
return &ASTWalker{
|
||
fileSet: token.NewFileSet(),
|
||
commentParser: NewCommentParserWithStrictMode(config.StrictMode),
|
||
config: config,
|
||
visitors: make([]NodeVisitor, 0),
|
||
}
|
||
}
|
||
|
||
// AddVisitor 添加节点访问者到遍历器
|
||
//
|
||
// 功能说明：
|
||
// - 将指定的访问者添加到访问者列表
|
||
// - 访问者会按照添加的顺序被调用
|
||
// - 支持添加多个访问者来处理不同的分析任务
|
||
//
|
||
// 使用场景：
|
||
// - 添加 Provider 发现访问者
|
||
// - 添加依赖分析访问者
|
||
// - 添加代码质量检查访问者
|
||
//
|
||
// 参数：
|
||
// - visitor: 要添加的节点访问者
|
||
//
|
||
// 注意事项：
|
||
// - 同一个访问者实例只能添加一次
|
||
// - 添加的访问者必须实现 NodeVisitor 接口
|
||
// - 建议在遍历开始前添加所有需要的访问者
|
||
func (aw *ASTWalker) AddVisitor(visitor NodeVisitor) {
|
||
aw.visitors = append(aw.visitors, visitor)
|
||
}
|
||
|
||
// RemoveVisitor 从遍历器中移除指定的节点访问者
|
||
//
|
||
// 功能说明：
|
||
// - 从访问者列表中移除指定的访问者实例
|
||
// - 使用对象引用进行比较，移除第一个匹配的访问者
|
||
// - 如果访问者不存在，不做任何操作
|
||
//
|
||
// 使用场景：
|
||
// - 动态调整分析任务
|
||
// - 移除不再需要的访问者
|
||
// - 优化性能，移除不必要的处理
|
||
//
|
||
// 参数：
|
||
// - visitor: 要移除的节点访问者
|
||
//
|
||
// 注意事项：
|
||
// - 如果有多个相同的访问者实例，只移除第一个
|
||
// - 移除操作会改变访问者列表的顺序
|
||
// - 建议在遍历开始前完成访问者的调整
|
||
func (aw *ASTWalker) RemoveVisitor(visitor NodeVisitor) {
|
||
for i, v := range aw.visitors {
|
||
if v == visitor {
|
||
aw.visitors = append(aw.visitors[:i], aw.visitors[i+1:]...)
|
||
break
|
||
}
|
||
}
|
||
}
|
||
|
||
// WalkFile 遍历单个 Go 文件的 AST，执行完整的分析和处理流程
|
||
//
|
||
// 执行流程：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ WalkFile(filePath) │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 文件过滤：shouldProcessFile() │
|
||
// │ 2. AST 解析：parser.ParseFile() │
|
||
// │ 3. 文件开始：VisitFile() 通知所有访问者 │
|
||
// │ 4. AST 遍历：traverseFile() 递归遍历 AST │
|
||
// │ 5. 文件完成：Complete() 通知所有访问者 │
|
||
// │ 6. 返回结果：成功返回 nil，失败返回错误 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 详细步骤说明：
|
||
// 步骤 1：文件过滤
|
||
// - 检查文件扩展名是否为 .go
|
||
// - 根据配置跳过测试文件和生成的文件
|
||
// - 检查文件大小限制
|
||
//
|
||
// 步骤 2：AST 解析
|
||
// - 使用 Go 标准库解析源文件
|
||
// - 启用注释解析，保留所有注释信息
|
||
// - 记录源码位置信息到文件集
|
||
//
|
||
// 步骤 3：文件开始通知
|
||
// - 按顺序通知所有访问者文件开始处理
|
||
// - 传递文件路径和 AST 节点
|
||
// - 如果任何访问者返回错误，立即停止处理
|
||
//
|
||
// 步骤 4：AST 遍历
|
||
// - 递归遍历 AST 中的所有声明
|
||
// - 按照访问者接口定义的顺序通知访问者
|
||
// - 处理类型声明、结构体、字段等
|
||
//
|
||
// 步骤 5：文件完成通知
|
||
// - 按顺序通知所有访问者文件处理完成
|
||
// - 访问者可以执行清理和结果收集
|
||
// - 如果任何访问者返回错误，立即停止处理
|
||
//
|
||
// 参数：
|
||
// - filePath: 要遍历的 Go 源文件路径
|
||
//
|
||
// 返回值：
|
||
// - error: 成功时返回 nil，失败时返回包装后的错误信息
|
||
//
|
||
// 错误处理：
|
||
// - 文件不存在或无法读取：返回文件系统错误
|
||
// - 语法错误：返回解析错误，包含行号和列号信息
|
||
// - 访问者错误：返回访问者产生的错误，停止后续处理
|
||
//
|
||
// 使用示例：
|
||
//
|
||
// walker := NewASTWalker()
|
||
// walker.AddVisitor(NewProviderDiscoveryVisitor())
|
||
// err := walker.WalkFile("user_service.go")
|
||
// if err != nil {
|
||
// log.Fatal("Failed to walk file: ", err)
|
||
// }
|
||
//
|
||
// 注意事项：
|
||
// - 必须至少添加一个访问者才能进行有效分析
|
||
// - 文件路径必须是有效的 Go 源文件
|
||
// - 错误会立即终止处理过程
|
||
func (aw *ASTWalker) WalkFile(filePath string) error {
|
||
// === 步骤 1：文件过滤 ===
|
||
// 检查文件是否符合处理条件，跳过不符合要求的文件
|
||
if !aw.shouldProcessFile(filePath) {
|
||
return nil
|
||
}
|
||
|
||
// === 步骤 2：AST 解析 ===
|
||
// 使用 Go 标准库将源文件解析为抽象语法树，保留注释信息
|
||
node, err := parser.ParseFile(aw.fileSet, filePath, nil, parser.ParseComments)
|
||
if err != nil {
|
||
return fmt.Errorf("failed to parse file %s: %w", filePath, err)
|
||
}
|
||
|
||
// === 步骤 3：文件开始通知 ===
|
||
// 按顺序通知所有访问者开始处理文件
|
||
for _, visitor := range aw.visitors {
|
||
if err := visitor.VisitFile(filePath, node); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
|
||
// === 步骤 4：AST 遍历 ===
|
||
// 递归遍历 AST 的所有节点，通知访问者处理各种声明
|
||
if err := aw.traverseFile(filePath, node); err != nil {
|
||
return err
|
||
}
|
||
|
||
// === 步骤 5：文件完成通知 ===
|
||
// 按顺序通知所有访问者文件处理完成
|
||
for _, visitor := range aw.visitors {
|
||
if err := visitor.Complete(filePath); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
|
||
return nil
|
||
}
|
||
|
||
// WalkDir 遍历目录中的所有 Go 文件，批量执行 AST 分析
|
||
//
|
||
// 执行流程：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ WalkDir(dirPath) │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 目录遍历：filepath.Walk() 递归遍历 │
|
||
// │ 2. 目录过滤：跳过隐藏目录和依赖目录 │
|
||
// │ 3. 文件过滤：检查 Go 文件和配置条件 │
|
||
// │ 4. 文件处理：调用 WalkFile() 处理每个文件 │
|
||
// │ 5. 错误处理：记录错误但继续处理其他文件 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 目录过滤规则：
|
||
// - 隐藏目录：以 . 开头的目录（.git、.idea 等）
|
||
// - 依赖目录：node_modules、vendor、testdata
|
||
// - 构建目录：通常被 gitignore 的目录
|
||
//
|
||
// 文件处理策略：
|
||
// - 只处理 .go 后缀的文件
|
||
// - 根据配置跳过测试文件和生成文件
|
||
// - 单个文件处理失败不影响其他文件
|
||
//
|
||
// 错误处理策略：
|
||
// - 目录访问错误：立即停止遍历
|
||
// - 文件处理错误：记录警告但继续处理
|
||
// - 使用标准输出打印警告信息
|
||
//
|
||
// 参数：
|
||
// - dirPath: 要遍历的目录路径
|
||
//
|
||
// 返回值：
|
||
// - error: 目录遍历错误，文件处理错误不会返回
|
||
//
|
||
// 使用场景：
|
||
// - 项目分析：分析整个项目的 Provider 定义
|
||
// - 批量处理：对项目中的所有文件进行统一处理
|
||
// - 代码生成：基于项目分析结果生成代码
|
||
//
|
||
// 注意事项：
|
||
// - 大型项目可能需要较长时间
|
||
// - 建议先配置合适的过滤条件
|
||
// - 错误处理采用宽松策略，不会因为单个文件失败而停止
|
||
func (aw *ASTWalker) WalkDir(dirPath string) error {
|
||
return filepath.Walk(dirPath, func(path string, info os.FileInfo, err error) error {
|
||
// 处理文件系统错误
|
||
if err != nil {
|
||
return err
|
||
}
|
||
|
||
// === 处理目录 ===
|
||
if info.IsDir() {
|
||
// 跳过隐藏目录和常见的依赖/构建目录
|
||
if strings.HasPrefix(info.Name(), ".") ||
|
||
info.Name() == "node_modules" ||
|
||
info.Name() == "vendor" ||
|
||
info.Name() == "testdata" {
|
||
return filepath.SkipDir
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// === 处理文件 ===
|
||
// 只处理 Go 文件，且符合配置条件的文件
|
||
if filepath.Ext(path) == ".go" && aw.shouldProcessFile(path) {
|
||
if err := aw.WalkFile(path); err != nil {
|
||
// 单个文件处理失败，记录警告但继续处理其他文件
|
||
fmt.Printf("Warning: failed to process file %s: %v\n", path, err)
|
||
}
|
||
}
|
||
|
||
return nil
|
||
})
|
||
}
|
||
|
||
// traverseFile 遍历已解析文件的 AST，处理所有顶级声明
|
||
//
|
||
// 执行流程：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ traverseFile(filePath, node) │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 遍历声明：node.Decls 列表 │
|
||
// │ 2. 声明处理：traverseDeclaration() │
|
||
// │ 3. 错误处理：任何声明处理失败都会停止整个遍历 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 处理的声明类型：
|
||
// - GenDecl: 通用声明（type、var、const）
|
||
// - FuncDecl: 函数声明（当前版本跳过）
|
||
// - 其他声明类型：根据需要进行扩展
|
||
//
|
||
// 递归策略：
|
||
// - 深度优先遍历：先处理声明，再处理内部规范
|
||
// - 顺序处理：按照源码中的顺序处理每个声明
|
||
// - 错误传播：任何错误都会立即停止遍历过程
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径，用于错误报告
|
||
// - node: 已解析的 AST 文件节点
|
||
//
|
||
// 返回值：
|
||
// - error: 遍历过程中的错误
|
||
//
|
||
// 注意事项：
|
||
// - 当前版本主要处理类型声明
|
||
// - 函数声明会被跳过，可根据需要扩展
|
||
// - 错误处理采用快速失败策略
|
||
func (aw *ASTWalker) traverseFile(filePath string, node *ast.File) error {
|
||
// === 遍历所有顶级声明 ===
|
||
// ast.File.Decls 包含文件中的所有顶级声明
|
||
for _, decl := range node.Decls {
|
||
// 递归处理每个声明，如果处理失败则立即停止
|
||
if err := aw.traverseDeclaration(filePath, decl); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
|
||
return nil
|
||
}
|
||
|
||
// traverseDeclaration 遍历单个声明，处理通用声明及其规范
|
||
//
|
||
// 执行流程：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ traverseDeclaration(filePath, decl) │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 类型检查：decl.(*ast.GenDecl) │
|
||
// │ 2. 访问者通知：VisitGenDecl() 通知访问者 │
|
||
// │ 3. 规范遍历：genDecl.Specs 遍历所有规范 │
|
||
// │ 4. 错误处理：任何步骤失败都会停止处理 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 处理的声明类型：
|
||
// - ast.GenDecl: 通用声明，包含类型、变量、常量声明
|
||
// - ast.FuncDecl: 函数声明（当前跳过）
|
||
// - 其他声明类型：根据需要扩展
|
||
//
|
||
// 通用声明规范类型：
|
||
// - TypeSpec: 类型规范（struct、interface、func type等）
|
||
// - ValueSpec: 值规范（var、const声明）
|
||
// - ImportSpec: 导入规范（import声明）
|
||
//
|
||
// 访问者通知策略：
|
||
// - 声明级通知：先通知所有访问者处理声明
|
||
// - 规范级通知：再递归处理声明中的规范
|
||
// - 错误传播：任何访问者错误都会立即停止处理
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径，用于错误报告
|
||
// - decl: AST 声明节点
|
||
//
|
||
// 返回值：
|
||
// - error: 处理过程中的错误
|
||
//
|
||
// 注意事项：
|
||
// - 当前版本主要处理 GenDecl 类型
|
||
// - FuncDecl 类型会被跳过
|
||
// - 错误处理采用快速失败策略
|
||
func (aw *ASTWalker) traverseDeclaration(filePath string, decl ast.Decl) error {
|
||
// === 类型检查 ===
|
||
// 只处理通用声明（type、var、const），跳过函数声明等
|
||
genDecl, ok := decl.(*ast.GenDecl)
|
||
if !ok {
|
||
// 跳过函数声明和其他非通用声明
|
||
return nil
|
||
}
|
||
|
||
// === 访问者通知 ===
|
||
// 按顺序通知所有访问者处理通用声明
|
||
for _, visitor := range aw.visitors {
|
||
if err := visitor.VisitGenDecl(filePath, genDecl); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
|
||
// === 规范遍历 ===
|
||
// 递归处理声明中的所有规范（TypeSpec、ValueSpec、ImportSpec等）
|
||
for _, spec := range genDecl.Specs {
|
||
if err := aw.traverseSpec(filePath, spec, genDecl); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
|
||
return nil
|
||
}
|
||
|
||
// traverseSpec 遍历声明中的规范，处理类型规范和结构体字段
|
||
//
|
||
// 执行流程：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ traverseSpec(filePath, spec, decl) │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 类型检查：spec.(*ast.TypeSpec) │
|
||
// │ 2. 访问者通知：VisitTypeSpec() 通知访问者 │
|
||
// │ 3. 结构体检查：typeSpec.Type.(*ast.StructType) │
|
||
// │ 4. 结构体通知：VisitStructType() 通知访问者 │
|
||
// │ 5. 字段遍历：traverseStructFields() 遍历字段 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 处理的规范类型：
|
||
// - TypeSpec: 类型规范（当前主要处理）
|
||
// - ValueSpec: 值规范（var、const声明，当前跳过）
|
||
// - ImportSpec: 导入规范（import声明，当前跳过）
|
||
//
|
||
// 类型规范处理：
|
||
// - 结构体类型：特别处理，遍历所有字段
|
||
// - 接口类型：可根据需要扩展处理
|
||
// - 函数类型：可根据需要扩展处理
|
||
// - 其他类型：基本类型、数组、映射等
|
||
//
|
||
// 结构体处理策略：
|
||
// - 类型识别：检查是否为 ast.StructType
|
||
// - 访问者通知：通知所有访问者处理结构体
|
||
// - 字段遍历：递归处理结构体的所有字段
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径，用于错误报告
|
||
// - spec: AST 规范节点
|
||
// - decl: 包含该规范的通用声明
|
||
//
|
||
// 返回值：
|
||
// - error: 处理过程中的错误
|
||
//
|
||
// 注意事项：
|
||
// - 当前版本主要处理 TypeSpec 和 StructType
|
||
// - 其他规范类型会被跳过
|
||
// - 结构体字段会进行深度遍历
|
||
func (aw *ASTWalker) traverseSpec(filePath string, spec ast.Spec, decl *ast.GenDecl) error {
|
||
// === 类型检查 ===
|
||
// 只处理类型规范，跳过值规范和导入规范
|
||
typeSpec, ok := spec.(*ast.TypeSpec)
|
||
if !ok {
|
||
// 跳过非类型规范
|
||
return nil
|
||
}
|
||
|
||
// === 访问者通知 ===
|
||
// 按顺序通知所有访问者处理类型规范
|
||
for _, visitor := range aw.visitors {
|
||
if err := visitor.VisitTypeSpec(filePath, typeSpec, decl); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
|
||
// === 结构体检查和处理 ===
|
||
// 检查是否为结构体类型，如果是则进行特殊处理
|
||
structType, ok := typeSpec.Type.(*ast.StructType)
|
||
if ok {
|
||
// === 结构体通知 ===
|
||
// 按顺序通知所有访问者处理结构体类型
|
||
for _, visitor := range aw.visitors {
|
||
if err := visitor.VisitStructType(filePath, structType, typeSpec, decl); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
|
||
// === 字段遍历 ===
|
||
// 递归遍历结构体的所有字段
|
||
if err := aw.traverseStructFields(filePath, structType); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
|
||
return nil
|
||
}
|
||
|
||
// traverseStructFields 遍历结构体类型中的所有字段
|
||
//
|
||
// 执行流程：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ traverseStructFields(filePath, structType) │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 空值检查：structType.Fields == nil │
|
||
// │ 2. 字段遍历：structType.Fields.List 遍历所有字段 │
|
||
// │ 3. 访问者通知：VisitStructField() 通知访问者 │
|
||
// │ 4. 错误处理：任何字段处理失败都会停止遍历 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 字段遍历策略：
|
||
// - 顺序遍历：按照源码中的顺序处理每个字段
|
||
// - 批量处理：一个字段列表项可能包含多个同名字段
|
||
// - 深度处理：递归处理字段的类型信息
|
||
//
|
||
// 字段类型分析：
|
||
// - 基本类型：int、string、bool等
|
||
// - 复合类型：数组、切片、映射、通道
|
||
// - 自定义类型：用户定义的结构体、接口
|
||
// - 指针类型：各种类型的指针
|
||
//
|
||
// 访问者处理内容：
|
||
// - 字段名称和类型信息
|
||
// - 结构体标签（tag）解析
|
||
// - 注释和文档信息
|
||
// - 注入相关的标签处理
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径，用于错误报告
|
||
// - structType: 结构体类型节点
|
||
//
|
||
// 返回值：
|
||
// - error: 遍历过程中的错误
|
||
//
|
||
// 注意事项：
|
||
// - 空结构体会被跳过
|
||
// - 字段处理失败会立即停止整个遍历
|
||
// - 匿名字段会被正常处理
|
||
func (aw *ASTWalker) traverseStructFields(filePath string, structType *ast.StructType) error {
|
||
// === 空值检查 ===
|
||
// 如果结构体没有字段列表，直接返回
|
||
if structType.Fields == nil {
|
||
return nil
|
||
}
|
||
|
||
// === 字段遍历 ===
|
||
// 遍历结构体的所有字段，一个 field.List 可能包含多个同名字段
|
||
for _, field := range structType.Fields.List {
|
||
// === 访问者通知 ===
|
||
// 按顺序通知所有访问者处理结构体字段
|
||
for _, visitor := range aw.visitors {
|
||
if err := visitor.VisitStructField(filePath, field, structType); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
}
|
||
|
||
return nil
|
||
}
|
||
|
||
// shouldProcessFile 判断文件是否符合处理条件
|
||
//
|
||
// 过滤规则：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ shouldProcessFile() │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 扩展名检查：必须是 .go 文件 │
|
||
// │ 2. 测试文件检查：根据配置决定是否处理 _test.go 文件 │
|
||
// │ 3. 生成文件检查：根据配置决定是否处理 .gen.go 文件 │
|
||
// │ 4. 文件大小检查：TODO 待实现（需要 os.Stat） │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 过滤策略：
|
||
// - 严格过滤：只处理符合所有条件的文件
|
||
// - 配置驱动：根据 WalkerConfig 配置决定过滤规则
|
||
// - 性能优化：尽早返回，避免不必要的检查
|
||
//
|
||
// 文件类型识别：
|
||
// - 源文件：.go 后缀，非测试文件，非生成文件
|
||
// - 测试文件：_test.go 后缀
|
||
// - 生成文件：.gen.go 后缀
|
||
// - 其他文件：非 .go 后缀的文件
|
||
//
|
||
// 配置影响：
|
||
// - IncludeTestFiles: true 时处理测试文件
|
||
// - IncludeGeneratedFiles: true 时处理生成文件
|
||
// - MaxFileSize: 超过限制的文件会被跳过
|
||
//
|
||
// 参数：
|
||
// - filePath: 要检查的文件路径
|
||
//
|
||
// 返回值：
|
||
// - bool: true 表示应该处理，false 表示应该跳过
|
||
//
|
||
// 使用场景：
|
||
// - WalkFile: 单文件处理前的检查
|
||
// - WalkDir: 目录遍历中的文件过滤
|
||
// - 批量处理：大规模文件处理时的优化
|
||
//
|
||
// 注意事项：
|
||
// - 文件大小检查尚未实现
|
||
// - 过滤规则是累积的，必须通过所有检查
|
||
// - 配置修改会影响过滤行为
|
||
func (aw *ASTWalker) shouldProcessFile(filePath string) bool {
|
||
// === 扩展名检查 ===
|
||
// 只处理 Go 源文件，其他文件一律跳过
|
||
if filepath.Ext(filePath) != ".go" {
|
||
return false
|
||
}
|
||
|
||
// === 测试文件检查 ===
|
||
// 如果配置不允许处理测试文件，跳过 _test.go 文件
|
||
if !aw.config.IncludeTestFiles && strings.HasSuffix(filePath, "_test.go") {
|
||
return false
|
||
}
|
||
|
||
// === 生成文件检查 ===
|
||
// 如果配置不允许处理生成文件，跳过 .gen.go 文件
|
||
if !aw.config.IncludeGeneratedFiles && strings.HasSuffix(filePath, ".gen.go") {
|
||
return false
|
||
}
|
||
|
||
// === 文件大小检查 ===
|
||
// TODO: 待实现文件大小检查功能（需要调用 os.Stat）
|
||
// 需要考虑性能影响，避免过多的文件系统调用
|
||
|
||
// 所有检查都通过，文件符合处理条件
|
||
return true
|
||
}
|
||
|
||
// GetFileSet 返回遍历器使用的文件集
|
||
//
|
||
// 功能说明：
|
||
// - 返回用于记录源码位置信息的文件集
|
||
// - 文件集包含所有已解析文件的位置信息
|
||
// - 可用于将位置信息转换为行号和列号
|
||
//
|
||
// 返回值：
|
||
// - *token.FileSet: 文件集实例
|
||
//
|
||
// 使用场景：
|
||
// - 错误报告：将 AST 位置转换为人类可读的位置
|
||
// - 调试信息：显示源码位置的详细信息
|
||
// - 工具集成：与其他需要位置信息的工具集成
|
||
//
|
||
// 注意事项：
|
||
// - 文件集会在遍历过程中自动更新
|
||
// - 返回的是实例引用，不是副本
|
||
// - 多个文件的位置信息会累积在同一文件集中
|
||
func (aw *ASTWalker) GetFileSet() *token.FileSet {
|
||
return aw.fileSet
|
||
}
|
||
|
||
// GetCommentParser 返回遍历器使用的注释解析器
|
||
//
|
||
// 功能说明：
|
||
// - 返回用于解析注释的注释解析器实例
|
||
// - 注释解析器负责处理 @provider 等注解
|
||
// - 可用于独立的注释解析任务
|
||
//
|
||
// 返回值：
|
||
// - *CommentParser: 注释解析器实例
|
||
//
|
||
// 使用场景：
|
||
// - 注解分析：解析特定的注释格式
|
||
// - 工具扩展：基于注释解析器实现自定义功能
|
||
// - 调试和测试：测试注释解析功能
|
||
//
|
||
// 注意事项：
|
||
// - 注释解析器的配置与遍历器保持一致
|
||
// - 返回的是实例引用，不是副本
|
||
// - 可以用于遍历器外部的注释解析任务
|
||
func (aw *ASTWalker) GetCommentParser() *CommentParser {
|
||
return aw.commentParser
|
||
}
|
||
|
||
// GetConfig 返回遍历器的配置信息
|
||
//
|
||
// 功能说明：
|
||
// - 返回遍历器的当前配置
|
||
// - 配置包含所有影响遍历行为的参数
|
||
// - 可用于检查和修改遍历器配置
|
||
//
|
||
// 返回值：
|
||
// - *WalkerConfig: 遍历器配置指针
|
||
//
|
||
// 使用场景：
|
||
// - 配置检查：查看当前的过滤和处理规则
|
||
// - 动态调整：在运行时修改配置
|
||
// - 配置复制：基于当前配置创建新的遍历器
|
||
//
|
||
// 注意事项：
|
||
// - 返回的是配置的指针，修改会影响遍历器行为
|
||
// - 建议在了解配置含义的情况下进行修改
|
||
// - 配置修改不会影响已处理的文件
|
||
|
||
// ProviderDiscoveryVisitor 实现 NodeVisitor 接口，专门用于发现 Provider 注解
|
||
//
|
||
// 架构设计：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ ProviderDiscoveryVisitor │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ commentParser: *CommentParser - 注释解析器 │
|
||
// │ providers: []Provider - 发现的 Provider 列表 │
|
||
// │ currentFile: string - 当前处理的文件路径 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 核心功能：
|
||
// - 注解识别：识别 @provider 注解
|
||
// - Provider 构建：构建完整的 Provider 对象
|
||
// - 结果收集：收集所有发现的 Provider
|
||
// - 文件跟踪：跟踪当前处理的文件
|
||
//
|
||
// 处理策略：
|
||
// - 结构体优先：只处理结构体类型的注解
|
||
// - 注释解析：使用 CommentParser 解析注释块
|
||
// - 默认值处理：为空值设置合理的默认值
|
||
//
|
||
// 使用场景：
|
||
// - Provider 发现：在 AST 遍历过程中发现 Provider 注解
|
||
// - 代码生成：为代码生成工具提供输入数据
|
||
// - 项目分析：分析项目中的 Provider 定义
|
||
type ProviderDiscoveryVisitor struct {
|
||
commentParser *CommentParser // 注释解析器，用于解析 @provider 注解
|
||
providers []Provider // 发现的 Provider 列表
|
||
currentFile string // 当前处理的文件路径
|
||
}
|
||
|
||
// NewProviderDiscoveryVisitor 创建新的 ProviderDiscoveryVisitor 实例
|
||
//
|
||
// 初始化流程：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ NewProviderDiscoveryVisitor() │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 保存注释解析器：commentParser 参数 │
|
||
// │ 2. 初始化 Provider 列表：make([]Provider, 0) │
|
||
// │ 3. 创建访问者实例：&ProviderDiscoveryVisitor{...} │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 参数处理：
|
||
// - commentParser: 必须传入有效的注释解析器实例
|
||
// - 不允许为 nil，否则会出现运行时错误
|
||
//
|
||
// 初始化状态：
|
||
// - providers: 空列表，准备收集发现的 Provider
|
||
// - currentFile: 空字符串，等待文件处理时设置
|
||
//
|
||
// 参数：
|
||
// - commentParser: 注释解析器实例
|
||
//
|
||
// 返回值：
|
||
// - *ProviderDiscoveryVisitor: 配置好的访问者实例
|
||
//
|
||
// 使用示例：
|
||
//
|
||
// commentParser := NewCommentParser()
|
||
// visitor := NewProviderDiscoveryVisitor(commentParser)
|
||
// walker := NewASTWalker()
|
||
// walker.AddVisitor(visitor)
|
||
//
|
||
// 注意事项：
|
||
// - 注释解析器必须提前初始化
|
||
// - 访问者可以重复使用，但需要调用 Reset 清理状态
|
||
// - 建议在遍历开始前添加到 ASTWalker
|
||
func NewProviderDiscoveryVisitor(commentParser *CommentParser) *ProviderDiscoveryVisitor {
|
||
return &ProviderDiscoveryVisitor{
|
||
commentParser: commentParser,
|
||
providers: make([]Provider, 0),
|
||
}
|
||
}
|
||
|
||
// VisitFile 实现 NodeVisitor.VisitFile 接口，处理文件级别的初始化
|
||
//
|
||
// 功能说明：
|
||
// - 记录当前处理的文件路径
|
||
// - 为文件级别的处理提供上下文
|
||
// - 不执行具体的发现逻辑
|
||
//
|
||
// 执行时机：
|
||
// - 在开始处理新文件时调用
|
||
// - 在任何 AST 遍历之前调用
|
||
// - 为后续的处理步骤建立上下文
|
||
//
|
||
// 处理策略：
|
||
// - 简单记录：只保存文件路径，不进行复杂处理
|
||
// - 快速返回：立即返回 nil，不产生错误
|
||
// - 上下文建立：为后续的 VisitStructType 提供文件上下文
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前处理的文件路径
|
||
// - node: 解析后的 AST 文件节点
|
||
//
|
||
// 返回值：
|
||
// - error: 总是返回 nil，表示成功
|
||
//
|
||
// 注意事项：
|
||
// - 此方法主要建立上下文，不执行具体业务逻辑
|
||
// - 文件路径会被后续的方法使用
|
||
// - 错误处理在其他方法中实现
|
||
func (pdv *ProviderDiscoveryVisitor) VisitFile(filePath string, node *ast.File) error {
|
||
// 记录当前处理的文件路径，为后续处理提供上下文
|
||
pdv.currentFile = filePath
|
||
return nil
|
||
}
|
||
|
||
// VisitGenDecl 实现 NodeVisitor.VisitGenDecl 接口，处理通用声明
|
||
//
|
||
// 功能说明：
|
||
// - 当前实现不处理通用声明级别的 Provider 发现
|
||
// - Provider 发现主要在结构体级别进行
|
||
// - 保留接口完整性，为未来扩展做准备
|
||
//
|
||
// 处理策略：
|
||
// - 空实现：不执行任何处理逻辑
|
||
// - 快速返回：立即返回 nil，继续后续处理
|
||
// - 接口一致性：保持与 NodeVisitor 接口的一致性
|
||
//
|
||
// 扩展可能性：
|
||
// - 包级别 Provider 注解的处理
|
||
// - 常量和变量级别的注解处理
|
||
// - 声明级别的元数据收集
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径
|
||
// - decl: 通用声明节点
|
||
//
|
||
// 返回值：
|
||
// - error: 总是返回 nil，表示成功
|
||
//
|
||
// 注意事项：
|
||
// - 当前版本不处理声明级别的注解
|
||
// - 未来版本可能添加相关功能
|
||
// - 保持接口完整性以便扩展
|
||
func (pdv *ProviderDiscoveryVisitor) VisitGenDecl(filePath string, decl *ast.GenDecl) error {
|
||
// 当前实现不处理通用声明级别的注解
|
||
// Provider 发现主要在结构体级别进行
|
||
return nil
|
||
}
|
||
|
||
// VisitTypeSpec 实现 NodeVisitor.VisitTypeSpec 接口，处理类型规范
|
||
//
|
||
// 功能说明：
|
||
// - 当前实现不在类型规范级别处理 Provider 发现
|
||
// - 主要在结构体类型级别进行详细处理
|
||
// - 保留接口完整性，为未来扩展做准备
|
||
//
|
||
// 处理策略：
|
||
// - 空实现：不执行任何处理逻辑
|
||
// - 快速返回：立即返回 nil，继续后续处理
|
||
// - 结构体优先：将详细处理留给 VisitStructType
|
||
//
|
||
// 设计考虑：
|
||
// - 类型规范级别的处理可能包含接口、函数类型等
|
||
// - Provider 注解通常与结构体类型关联
|
||
// - 避免重复处理，让专门的 VisitStructType 处理
|
||
//
|
||
// 扩展可能性：
|
||
// - 接口类型的 Provider 注解处理
|
||
// - 函数类型的注解处理
|
||
// - 类型级别的元数据收集
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径
|
||
// - typeSpec: 类型规范节点
|
||
// - decl: 包含该类型的通用声明
|
||
//
|
||
// 返回值：
|
||
// - error: 总是返回 nil，表示成功
|
||
//
|
||
// 注意事项：
|
||
// - 当前版本不处理类型规范级别的注解
|
||
// - 结构体类型会在 VisitStructType 中处理
|
||
// - 保持接口完整性以便扩展
|
||
func (pdv *ProviderDiscoveryVisitor) VisitTypeSpec(filePath string, typeSpec *ast.TypeSpec, decl *ast.GenDecl) error {
|
||
// 当前实现不在类型规范级别处理 Provider 发现
|
||
// 结构体类型的处理在 VisitStructType 中进行
|
||
return nil
|
||
}
|
||
|
||
// VisitStructType 实现 NodeVisitor.VisitStructType 接口，处理结构体类型的 Provider 注解
|
||
//
|
||
// 执行流程：
|
||
// ┌─────────────────────────────────────────────────────────────┐
|
||
// │ VisitStructType(filePath, structType, ...) │
|
||
// ├─────────────────────────────────────────────────────────────┤
|
||
// │ 1. 注释检查：decl.Doc != nil && len(decl.Doc.List) > 0 │
|
||
// │ 2. 注释提取：收集所有注释行到 commentLines │
|
||
// │ 3. 注解解析：commentParser.ParseCommentBlock() │
|
||
// │ 4. Provider 构建：创建 Provider 对象 │
|
||
// │ 5. 默认值设置：为空字段设置合理的默认值 │
|
||
// │ 6. 结果收集：添加到 providers 列表 │
|
||
// └─────────────────────────────────────────────────────────────┘
|
||
//
|
||
// 注解发现策略：
|
||
// - 文档检查：检查结构体声明前的文档注释
|
||
// - 注释收集：收集所有相关的注释行
|
||
// - 专业解析：使用 CommentParser 进行专业解析
|
||
// - 结果验证：检查解析结果的有效性
|
||
//
|
||
// Provider 构建逻辑：
|
||
// - 基本信息：结构体名称、模式、分组、返回类型
|
||
// - 初始化：创建空的注入参数和导入映射
|
||
// - 默认值：为返回类型设置默认值（*结构体名）
|
||
// - 扩展性：为后续的字段处理预留接口
|
||
//
|
||
// 错误处理策略：
|
||
// - 解析错误：如果解析失败，跳过该结构体
|
||
// - 空结果：如果没有发现注解，不创建 Provider
|
||
// - 静默处理：不产生错误，继续处理其他结构体
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径
|
||
// - structType: 结构体类型节点
|
||
// - typeSpec: 对应的类型规范
|
||
// - decl: 包含该结构体的通用声明
|
||
//
|
||
// 返回值：
|
||
// - error: 总是返回 nil，表示成功
|
||
//
|
||
// 注意事项：
|
||
// - 只处理带有文档注释的结构体
|
||
// - 注解解析失败不会产生错误
|
||
// - 发现的 Provider 会被收集到内部列表
|
||
func (pdv *ProviderDiscoveryVisitor) VisitStructType(filePath string, structType *ast.StructType, typeSpec *ast.TypeSpec, decl *ast.GenDecl) error {
|
||
// === 注释检查 ===
|
||
// 检查结构体是否有文档注释，没有注释则跳过处理
|
||
if decl.Doc != nil && len(decl.Doc.List) > 0 {
|
||
// === 注释提取 ===
|
||
// 提取所有注释行，为后续的注解解析做准备
|
||
commentLines := make([]string, len(decl.Doc.List))
|
||
for i, comment := range decl.Doc.List {
|
||
commentLines[i] = comment.Text
|
||
}
|
||
|
||
// === 注解解析 ===
|
||
// 使用注释解析器解析注释块，查找 @provider 注解
|
||
providerComment, err := pdv.commentParser.ParseCommentBlock(commentLines)
|
||
if err == nil && providerComment != nil {
|
||
// === Provider 构建 ===
|
||
// 创建 Provider 对象，设置基本信息
|
||
provider := Provider{
|
||
StructName: typeSpec.Name.Name, // 结构体名称
|
||
Mode: providerComment.Mode, // Provider 模式
|
||
ProviderGroup: providerComment.Group, // Provider 分组
|
||
ReturnType: providerComment.ReturnType, // 返回类型
|
||
InjectParams: make(map[string]InjectParam), // 注入参数映射
|
||
Imports: make(map[string]string), // 导入包映射
|
||
}
|
||
|
||
// === 默认值设置 ===
|
||
// 如果没有指定返回类型，设置默认值为结构体指针
|
||
if provider.ReturnType == "" {
|
||
provider.ReturnType = "*" + provider.StructName
|
||
}
|
||
|
||
// === 结果收集 ===
|
||
// 将构建的 Provider 添加到发现列表
|
||
pdv.providers = append(pdv.providers, provider)
|
||
}
|
||
}
|
||
|
||
return nil
|
||
}
|
||
|
||
// VisitStructField 实现 NodeVisitor.VisitStructField 接口，处理结构体字段
|
||
//
|
||
// 功能说明：
|
||
// - 当前实现不处理字段级别的详细信息
|
||
// - 字段处理在后续的 Provider 构建阶段进行
|
||
// - 保留接口完整性，为未来扩展做准备
|
||
//
|
||
// 当前职责：
|
||
// - 接口实现：保持与 NodeVisitor 接口的一致性
|
||
// - 扩展预留：为字段级别的处理预留接口
|
||
// - 简单返回：不执行复杂处理逻辑
|
||
//
|
||
// 未来可能的扩展：
|
||
// - 字段类型解析：解析字段的类型信息
|
||
// - 标签处理：处理 struct tags，特别是 inject 标签
|
||
// - 依赖分析：分析字段之间的依赖关系
|
||
// - 验证检查：验证字段配置的正确性
|
||
//
|
||
// 字段处理策略：
|
||
// - 注入标签：识别 inject:"true" 和 inject:"false" 标签
|
||
// - 类型解析：解析复杂类型，包括指针、切片、映射等
|
||
// - 嵌入字段：处理匿名字段和嵌入结构体
|
||
// - 文档注释：处理字段级别的文档注释
|
||
//
|
||
// 参数：
|
||
// - filePath: 当前文件路径
|
||
// - field: 结构体字段节点
|
||
// - structType: 所属的结构体类型
|
||
//
|
||
// 返回值：
|
||
// - error: 总是返回 nil，表示成功
|
||
//
|
||
// 注意事项：
|
||
// - 当前版本不进行字段级别的处理
|
||
// - 字段处理逻辑在其他模块中实现
|
||
// - 保持接口完整性以便未来扩展
|
||
func (pdv *ProviderDiscoveryVisitor) VisitStructField(filePath string, field *ast.Field, structType *ast.StructType) error {
|
||
// 字段级别处理预留接口
|
||
// 当前版本不在此处进行字段处理，相关逻辑在 Provider 构建阶段实现
|
||
// 未来可能的扩展：
|
||
// - 字段类型解析
|
||
// - inject 标签处理
|
||
// - 依赖关系分析
|
||
return nil
|
||
}
|
||
|
||
// Complete 实现 NodeVisitor.Complete 接口，处理文件完成事件
|
||
//
|
||
// 功能说明：
|
||
// - 当前实现不处理文件完成事件
|
||
// - 主要用于清理和结果汇总工作
|
||
// - 保留接口完整性，为未来扩展做准备
|
||
//
|
||
// 当前职责：
|
||
// - 接口实现：保持与 NodeVisitor 接口的一致性
|
||
// - 快速返回：不执行复杂处理逻辑
|
||
// - 扩展预留：为文件完成处理预留接口
|
||
//
|
||
// 未来可能的扩展：
|
||
// - 结果验证：验证文件级别的处理结果
|
||
// - 统计收集：收集文件处理的统计信息
|
||
// - 错误报告：汇总文件处理过程中的错误
|
||
// - 缓存清理：清理文件级别的临时数据
|
||
//
|
||
// 文件完成处理策略：
|
||
// - 静默完成：不产生错误，继续后续处理
|
||
// - 结果保持：保持已发现的 Provider 结果
|
||
// - 状态重置：为下一个文件的处理准备状态
|
||
//
|
||
// 参数：
|
||
// - filePath: 已完成处理的文件路径
|
||
//
|
||
// 返回值：
|
||
// - error: 总是返回 nil，表示成功
|
||
//
|
||
// 注意事项：
|
||
// - 当前版本不进行文件完成处理
|
||
// - 文件路径参数可用于扩展功能
|
||
// - 保持接口完整性以便未来扩展
|
||
func (pdv *ProviderDiscoveryVisitor) Complete(filePath string) error {
|
||
// 文件完成处理预留接口
|
||
// 当前版本不进行特殊的完成处理
|
||
// 未来可能的扩展：
|
||
// - 文件级别结果验证
|
||
// - 统计信息收集
|
||
// - 缓存清理工作
|
||
return nil
|
||
}
|
||
|
||
// GetProviders 返回发现的 Provider 列表
|
||
//
|
||
// 功能说明：
|
||
// - 返回在 AST 遍历过程中发现的所有 Provider
|
||
// - 返回的是内部列表的副本，外部修改不影响内部状态
|
||
// - 包含完整的 Provider 信息，包括基本属性和配置
|
||
//
|
||
// 返回数据特征：
|
||
// - 完整性：包含所有发现的 Provider，没有遗漏
|
||
// - 顺序性：按照发现顺序排列，保持源码中的顺序
|
||
// - 结构化：每个 Provider 包含完整的信息结构
|
||
//
|
||
// 数据内容：
|
||
// - 基本信息：StructName、Mode、ProviderGroup、ReturnType
|
||
// - 注入信息：InjectParams 映射
|
||
// - 导入信息：Imports 映射
|
||
// - 其他属性：NeedPrepareFunc、ProviderFile 等
|
||
//
|
||
// 使用场景：
|
||
// - 代码生成：基于发现的 Provider 生成代码
|
||
// - 项目分析：分析项目中的 Provider 定义
|
||
// - 工具集成：与其他工具集成处理 Provider 信息
|
||
// - 调试测试：验证 Provider 发现的正确性
|
||
//
|
||
// 返回值：
|
||
// - []Provider: 发现的 Provider 列表
|
||
//
|
||
// 注意事项：
|
||
// - 返回的是实际列表，不是副本
|
||
// - 空列表表示没有发现任何 Provider
|
||
// - 外部修改会影响内部状态
|
||
func (pdv *ProviderDiscoveryVisitor) GetProviders() []Provider {
|
||
return pdv.providers
|
||
}
|
||
|
||
// Reset 清理已发现的 Provider，重置访问者状态
|
||
//
|
||
// 功能说明：
|
||
// - 清空已发现的 Provider 列表
|
||
// - 重置当前文件路径
|
||
// - 重置访问者到初始状态，可以重新使用
|
||
//
|
||
// 重置策略：
|
||
// - 列表重置：创建新的空 Provider 列表
|
||
// - 路径重置：将当前文件路径设为空字符串
|
||
// - 状态清理：清理所有与文件处理相关的状态
|
||
//
|
||
// 使用场景：
|
||
// - 重复使用：在多次遍历中重复使用同一个访问者
|
||
// - 状态清理：清理之前的处理结果，避免混淆
|
||
// - 测试环境：在单元测试中重置状态
|
||
// - 批量处理：在批量处理多个目录时重置状态
|
||
//
|
||
// 重置前后对比：
|
||
// - 重置前：providers 包含之前发现的结果，currentFile 包含上一个文件
|
||
// - 重置后：providers 为空列表，currentFile 为空字符串
|
||
//
|
||
// 注意事项：
|
||
// - 重置操作不可逆，之前的结果会丢失
|
||
// - 重置后可以安全地用于新的遍历任务
|
||
// - 建议在开始新的遍历前调用 Reset
|
||
func (pdv *ProviderDiscoveryVisitor) Reset() {
|
||
// 清空已发现的 Provider 列表
|
||
pdv.providers = make([]Provider, 0)
|
||
// 重置当前文件路径
|
||
pdv.currentFile = ""
|
||
}
|