feat: 重构 pkg/ast/provider 模块，优化代码组织逻辑和功能实现

## 主要改进 ### 架构重构 - 将单体 provider.go 拆分为多个专门的模块文件 - 实现了清晰的职责分离和模块化设计 - 遵循 SOLID 原则，提高代码可维护性 ### 新增功能 - **验证规则系统**: 实现了完整的 provider 验证框架 - **报告生成器**: 支持多种格式的验证报告 (JSON/HTML/Markdown/Text) - **解析器优化**: 重新设计了解析流程，提高性能和可扩展性 - **错误处理**: 增强了错误处理和诊断能力 ### 修复关键 Bug - 修复 @provider(job) 注解缺失 __job 注入参数的问题 - 统一了 job 和 cronjob 模式的处理逻辑 - 确保了 provider 生成的正确性和一致性 ### 代码质量提升 - 添加了完整的测试套件 - 引入了 golangci-lint 代码质量检查 - 优化了代码格式和结构 - 增加了详细的文档和规范 ### 文件结构优化 ``` pkg/ast/provider/ ├── types.go # 类型定义 ├── parser.go # 解析器实现 ├── validator.go # 验证规则 ├── report_generator.go # 报告生成 ├── renderer.go # 渲染器 ├── comment_parser.go # 注解解析 ├── modes.go # 模式定义 ├── errors.go # 错误处理 └── validator_test.go # 测试文件 ``` ### 兼容性 - 保持向后兼容性 - 支持现有的所有 provider 模式 - 优化了 API 设计和用户体验 This completes the implementation of T025-T029 tasks following TDD principles, including validation rules implementation and critical bug fixes.
2025-09-19 18:58:30 +08:00
parent 8c65c6a854
commit e1f83ae469
45 changed files with 8643 additions and 313 deletions
--- a/specs/001-pkg-ast-provider/data-model.md
+++ b/specs/001-pkg-ast-provider/data-model.md
@@ -0,0 +1,209 @@
+# Data Model Design
+
+## Core Entities
+
+### 1. Provider
+代表一个依赖注入提供者的核心实体
+
+```go
+type Provider struct {
+    StructName       string                 // 结构体名称
+    ReturnType       string                 // 返回类型
+    Mode             ProviderMode           // 提供者模式
+    ProviderGroup    string                 // 提供者分组
+    GrpcRegisterFunc string                // gRPC 注册函数
+    NeedPrepareFunc  bool                   // 是否需要 Prepare 函数
+    InjectParams     map[string]InjectParam // 注入参数
+    Imports          map[string]string       // 导入包
+    PkgName          string                 // 包名
+    ProviderFile     string                 // 生成文件路径
+    SourceLocation   SourceLocation         // 源码位置
+}
+```
+
+### 2. ProviderMode
+提供者模式枚举
+
+```go
+type ProviderMode string
+
+const (
+    ModeDefault ProviderMode = ""
+    ModeGRPC   ProviderMode = "grpc"
+    ModeEvent  ProviderMode = "event"
+    ModeJob    ProviderMode = "job"
+    ModeCronJob ProviderMode = "cronjob"
+    ModeModel  ProviderMode = "model"
+)
+```
+
+### 3. InjectParam
+注入参数描述
+
+```go
+type InjectParam struct {
+    Star         string // 指针标记 (*)
+    Type         string // 类型名称
+    Package      string // 包路径
+    PackageAlias string // 包别名
+    FieldName    string // 字段名称
+    InjectTag    string // inject 标签值
+}
+```
+
+### 4. ProviderComment
+Provider 注释描述
+
+```go
+type ProviderComment struct {
+    RawText     string       // 原始注释文本
+    Mode        ProviderMode // 模式
+    Injection   InjectionMode // 注入模式
+    ReturnType  string       // 返回类型
+    Group       string       // 分组
+    IsValid     bool         // 是否有效
+    Errors      []string     // 解析错误
+}
+```
+
+### 5. InjectionMode
+注入模式枚举
+
+```go
+type InjectionMode string
+
+const (
+    InjectionDefault InjectionMode = ""
+    InjectionOnly    InjectionMode = "only"
+    InjectionExcept  InjectionMode = "except"
+)
+```
+
+### 6. SourceLocation
+源码位置信息
+
+```go
+type SourceLocation struct {
+    File      string // 文件路径
+    Line      int    // 行号
+    Column    int    // 列号
+    StartPos  int    // 开始位置
+    EndPos    int    // 结束位置
+}
+```
+
+### 7. ParserContext
+解析器上下文
+
+```go
+type ParserContext struct {
+    FileSet      *token.FileSet           // 文件集合
+    Imports      map[string]string       // 导入映射
+    PkgName      string                  // 包名
+    ScalarTypes  []string                // 标量类型列表
+    ErrorHandler func(error)             // 错误处理器
+    Config       ParserConfig            // 解析配置
+}
+```
+
+### 8. ParserConfig
+解析器配置
+
+```go
+type ParserConfig struct {
+    StrictMode    bool   // 严格模式
+    AllowTestFile bool   // 是否允许解析测试文件
+    IgnorePattern string // 忽略文件模式
+}
+```
+
+## Relationships
+
+### Entity Relationships
+```
+Provider (1) -> (0..*) InjectParam
+Provider (1) -> (1) ProviderComment
+Provider (1) -> (1) SourceLocation
+ProviderComment (1) -> (1) ProviderMode
+ProviderComment (1) -> (1) InjectionMode
+```
+
+### Data Flow
+```
+SourceFile -> ParserContext -> ProviderComment -> Provider -> GeneratedCode
+```
+
+## Validation Rules
+
+### Provider Validation
+- 结构体名称必须有效（符合 Go 标识符规则）
+- 返回类型不能为空
+- 模式必须为预定义值之一
+- 注入参数不能包含标量类型
+- 包名必须能正确解析
+
+### Comment Validation
+- 注释必须以 @provider 开头
+- 模式格式必须正确
+- 注入模式只能是 only 或 except
+- 返回类型和分组格式必须正确
+
+### Import Validation
+- 包路径必须有效
+- 包别名不能重复
+- 匿名导入必须正确处理
+
+## State Transitions
+
+### Parser States
+```
+Idle -> Parsing -> Validating -> Generating -> Complete
+                     ↓
+                   Error
+```
+
+### Provider States
+```
+Discovered -> Parsing -> Validated -> Ready -> Generated
+                    ↓
+                  Invalid
+```
+
+## Performance Considerations
+
+### Memory Usage
+- 每个文件创建一个 ParserContext
+- Provider 对象在解析完成后可以释放
+- 导入映射应该在文件级别共享
+
+### Processing Speed
+- 并行解析独立文件
+- 缓存常用的标量类型列表
+- 延迟验证直到所有信息收集完成
+
+## Error Handling
+
+### Error Types
+- ParseError: 解析错误
+- ValidationError: 验证错误
+- GenerationError: 生成错误
+- ConfigurationError: 配置错误
+
+### Error Recovery
+- 单个 Provider 错误不影响其他 Provider
+- 文件级别错误应该跳过该文件
+- 提供详细的错误位置和建议
+
+## Extension Points
+
+### Custom Provider Modes
+- 通过 ProviderMode 接口支持自定义模式
+- 使用注册机制添加新模式处理器
+
+### Custom Validation Rules
+- 通过 Validator 接口支持自定义验证
+- 支持链式验证器组合
+
+### Custom Renderers
+- 通过 Renderer 接口支持自定义渲染器
+- 支持多种输出格式