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.
This commit is contained in:
Rogee
657
specs/001-pkg-ast-provider/contracts/validation-rules.md
Normal file
657
specs/001-pkg-ast-provider/contracts/validation-rules.md
Normal file
@@ -0,0 +1,657 @@
|
||||
# Validation Rules Contract
|
||||
|
||||
## 概述
|
||||
|
||||
定义 pkg/ast/provider 包的验证规则契约，确保 provider 配置的正确性和一致性。
|
||||
|
||||
## 验证规则分类
|
||||
|
||||
### 1. 结构验证规则
|
||||
|
||||
#### 命名规则
|
||||
```go
|
||||
// StructNameRule 验证结构体名称
|
||||
type StructNameRule struct{}
|
||||
|
||||
func (r *StructNameRule) Name() string {
|
||||
return "struct_name"
|
||||
}
|
||||
|
||||
func (r *StructNameRule) Validate(p *Provider) error {
|
||||
if p.StructName == "" {
|
||||
return &ValidationError{
|
||||
Field: "StructName",
|
||||
Value: "",
|
||||
Message: "struct name cannot be empty",
|
||||
}
|
||||
}
|
||||
|
||||
if !isValidGoIdentifier(p.StructName) {
|
||||
return &ValidationError{
|
||||
Field: "StructName",
|
||||
Value: p.StructName,
|
||||
Message: "struct name must be a valid Go identifier",
|
||||
}
|
||||
}
|
||||
|
||||
if !isExported(p.StructName) {
|
||||
return &ValidationError{
|
||||
Field: "StructName",
|
||||
Value: p.StructName,
|
||||
Message: "struct name must be exported (start with uppercase letter)",
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
#### 包名规则
|
||||
```go
|
||||
// PackageNameRule 验证包名
|
||||
type PackageNameRule struct{}
|
||||
|
||||
func (r *PackageNameRule) Name() string {
|
||||
return "package_name"
|
||||
}
|
||||
|
||||
func (r *PackageNameRule) Validate(p *Provider) error {
|
||||
if p.PkgName == "" {
|
||||
return &ValidationError{
|
||||
Field: "PkgName",
|
||||
Value: "",
|
||||
Message: "package name cannot be empty",
|
||||
}
|
||||
}
|
||||
|
||||
if !isValidGoIdentifier(p.PkgName) {
|
||||
return &ValidationError{
|
||||
Field: "PkgName",
|
||||
Value: p.PkgName,
|
||||
Message: "package name must be a valid Go identifier",
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 类型验证规则
|
||||
|
||||
#### 返回类型规则
|
||||
```go
|
||||
// ReturnTypeRule 验证返回类型
|
||||
type ReturnTypeRule struct{}
|
||||
|
||||
func (r *ReturnTypeRule) Name() string {
|
||||
return "return_type"
|
||||
}
|
||||
|
||||
func (r *ReturnTypeRule) Validate(p *Provider) error {
|
||||
if p.ReturnType == "" {
|
||||
return &ValidationError{
|
||||
Field: "ReturnType",
|
||||
Value: "",
|
||||
Message: "return type cannot be empty",
|
||||
}
|
||||
}
|
||||
|
||||
if !isValidGoType(p.ReturnType) {
|
||||
return &ValidationError{
|
||||
Field: "ReturnType",
|
||||
Value: p.ReturnType,
|
||||
Message: "return type must be a valid Go type",
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
#### 模式验证规则
|
||||
```go
|
||||
// ProviderModeRule 验证 provider 模式
|
||||
type ProviderModeRule struct {
|
||||
validModes map[ProviderMode]bool
|
||||
}
|
||||
|
||||
func NewProviderModeRule() *ProviderModeRule {
|
||||
return &ProviderModeRule{
|
||||
validModes: map[ProviderMode]bool{
|
||||
ModeDefault: true,
|
||||
ModeGRPC: true,
|
||||
ModeEvent: true,
|
||||
ModeJob: true,
|
||||
ModeCronJob: true,
|
||||
ModeModel: true,
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func (r *ProviderModeRule) Name() string {
|
||||
return "provider_mode"
|
||||
}
|
||||
|
||||
func (r *ProviderModeRule) Validate(p *Provider) error {
|
||||
if !r.validModes[p.Mode] {
|
||||
return &ValidationError{
|
||||
Field: "Mode",
|
||||
Value: string(p.Mode),
|
||||
Message: fmt.Sprintf("invalid provider mode: %s", p.Mode),
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 依赖注入验证规则
|
||||
|
||||
#### 注入参数规则
|
||||
```go
|
||||
// InjectParamsRule 验证注入参数
|
||||
type InjectParamsRule struct{}
|
||||
|
||||
func (r *InjectParamsRule) Name() string {
|
||||
return "inject_params"
|
||||
}
|
||||
|
||||
func (r *InjectParamsRule) Validate(p *Provider) error {
|
||||
// 验证注入参数不为标量类型
|
||||
for name, param := range p.InjectParams {
|
||||
if isScalarType(param.Type) {
|
||||
return &ValidationError{
|
||||
Field: fmt.Sprintf("InjectParams.%s", name),
|
||||
Value: param.Type,
|
||||
Message: fmt.Sprintf("scalar type '%s' cannot be injected", param.Type),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 验证 only 模式下的 inject:true 标签
|
||||
if p.InjectionMode == InjectionOnly {
|
||||
for name, param := range p.InjectParams {
|
||||
if param.InjectTag != "true" {
|
||||
return &ValidationError{
|
||||
Field: fmt.Sprintf("InjectParams.%s", name),
|
||||
Value: param.InjectTag,
|
||||
Message: "all fields must have inject:\"true\" tag in 'only' mode",
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 验证 except 模式下的 inject:false 标签
|
||||
if p.InjectionMode == InjectionExcept {
|
||||
for name, param := range p.InjectParams {
|
||||
if param.InjectTag == "false" {
|
||||
return &ValidationError{
|
||||
Field: fmt.Sprintf("InjectParams.%s", name),
|
||||
Value: param.InjectTag,
|
||||
Message: "fields with inject:\"false\" tag should not be included in 'except' mode",
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
#### 包别名规则
|
||||
```go
|
||||
// PackageAliasRule 验证包别名
|
||||
type PackageAliasRule struct{}
|
||||
|
||||
func (r *PackageAliasRule) Name() string {
|
||||
return "package_alias"
|
||||
}
|
||||
|
||||
func (r *PackageAliasRule) Validate(p *Provider) error {
|
||||
// 收集所有包别名
|
||||
aliases := make(map[string]string)
|
||||
for alias, pkg := range p.Imports {
|
||||
if existing, exists := aliases[alias]; exists && existing != pkg {
|
||||
return &ValidationError{
|
||||
Field: "Imports",
|
||||
Value: alias,
|
||||
Message: fmt.Sprintf("duplicate package alias '%s' for different packages", alias),
|
||||
}
|
||||
}
|
||||
aliases[alias] = pkg
|
||||
}
|
||||
|
||||
// 验证注入参数的包别名
|
||||
for name, param := range p.InjectParams {
|
||||
if param.PackageAlias != "" {
|
||||
if _, exists := aliases[param.PackageAlias]; !exists {
|
||||
return &ValidationError{
|
||||
Field: fmt.Sprintf("InjectParams.%s", name),
|
||||
Value: param.PackageAlias,
|
||||
Message: fmt.Sprintf("undefined package alias '%s'", param.PackageAlias),
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 模式特定验证规则
|
||||
|
||||
#### gRPC 模式规则
|
||||
```go
|
||||
// GRPCModeRule 验证 gRPC 模式特定规则
|
||||
type GRPCModeRule struct{}
|
||||
|
||||
func (r *GRPCModeRule) Name() string {
|
||||
return "grpc_mode"
|
||||
}
|
||||
|
||||
func (r *GRPCModeRule) Validate(p *Provider) error {
|
||||
if p.Mode != ModeGRPC {
|
||||
return nil
|
||||
}
|
||||
|
||||
// 验证 gRPC 注册函数
|
||||
if p.GrpcRegisterFunc == "" {
|
||||
return &ValidationError{
|
||||
Field: "GrpcRegisterFunc",
|
||||
Value: "",
|
||||
Message: "gRPC register function cannot be empty in gRPC mode",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证返回类型
|
||||
if p.ReturnType != "contracts.Initial" {
|
||||
return &ValidationError{
|
||||
Field: "ReturnType",
|
||||
Value: p.ReturnType,
|
||||
Message: "return type must be 'contracts.Initial' in gRPC mode",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证 provider 组
|
||||
if p.ProviderGroup != "atom.GroupInitial" {
|
||||
return &ValidationError{
|
||||
Field: "ProviderGroup",
|
||||
Value: p.ProviderGroup,
|
||||
Message: "provider group must be 'atom.GroupInitial' in gRPC mode",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证必须包含 __grpc 注入参数
|
||||
if _, exists := p.InjectParams["__grpc"]; !exists {
|
||||
return &ValidationError{
|
||||
Field: "InjectParams",
|
||||
Value: "",
|
||||
Message: "gRPC provider must include '__grpc' injection parameter",
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
#### Event 模式规则
|
||||
```go
|
||||
// EventModeRule 验证 Event 模式特定规则
|
||||
type EventModeRule struct{}
|
||||
|
||||
func (r *EventModeRule) Name() string {
|
||||
return "event_mode"
|
||||
}
|
||||
|
||||
func (r *EventModeRule) Validate(p *Provider) error {
|
||||
if p.Mode != ModeEvent {
|
||||
return nil
|
||||
}
|
||||
|
||||
// 验证返回类型
|
||||
if p.ReturnType != "contracts.Initial" {
|
||||
return &ValidationError{
|
||||
Field: "ReturnType",
|
||||
Value: p.ReturnType,
|
||||
Message: "return type must be 'contracts.Initial' in event mode",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证 provider 组
|
||||
if p.ProviderGroup != "atom.GroupInitial" {
|
||||
return &ValidationError{
|
||||
Field: "ProviderGroup",
|
||||
Value: p.ProviderGroup,
|
||||
Message: "provider group must be 'atom.GroupInitial' in event mode",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证必须包含 __event 注入参数
|
||||
if _, exists := p.InjectParams["__event"]; !exists {
|
||||
return &ValidationError{
|
||||
Field: "InjectParams",
|
||||
Value: "",
|
||||
Message: "event provider must include '__event' injection parameter",
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
#### Job 模式规则
|
||||
```go
|
||||
// JobModeRule 验证 Job 模式特定规则
|
||||
type JobModeRule struct{}
|
||||
|
||||
func (r *JobModeRule) Name() string {
|
||||
return "job_mode"
|
||||
}
|
||||
|
||||
func (r *JobModeRule) Validate(p *Provider) error {
|
||||
if p.Mode != ModeJob && p.Mode != ModeCronJob {
|
||||
return nil
|
||||
}
|
||||
|
||||
// 验证返回类型
|
||||
if p.ReturnType != "contracts.Initial" {
|
||||
return &ValidationError{
|
||||
Field: "ReturnType",
|
||||
Value: p.ReturnType,
|
||||
Message: "return type must be 'contracts.Initial' in job mode",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证 provider 组
|
||||
if p.ProviderGroup != "atom.GroupInitial" {
|
||||
return &ValidationError{
|
||||
Field: "ProviderGroup",
|
||||
Value: p.ProviderGroup,
|
||||
Message: "provider group must be 'atom.GroupInitial' in job mode",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证必须包含 __job 注入参数
|
||||
if _, exists := p.InjectParams["__job"]; !exists {
|
||||
return &ValidationError{
|
||||
Field: "InjectParams",
|
||||
Value: "",
|
||||
Message: "job provider must include '__job' injection parameter",
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
#### Model 模式规则
|
||||
```go
|
||||
// ModelModeRule 验证 Model 模式特定规则
|
||||
type ModelModeRule struct{}
|
||||
|
||||
func (r *ModelModeRule) Name() string {
|
||||
return "model_mode"
|
||||
}
|
||||
|
||||
func (r *ModelModeRule) Validate(p *Provider) error {
|
||||
if p.Mode != ModeModel {
|
||||
return nil
|
||||
}
|
||||
|
||||
// 验证返回类型
|
||||
if p.ReturnType != "contracts.Initial" {
|
||||
return &ValidationError{
|
||||
Field: "ReturnType",
|
||||
Value: p.ReturnType,
|
||||
Message: "return type must be 'contracts.Initial' in model mode",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证 provider 组
|
||||
if p.ProviderGroup != "atom.GroupInitial" {
|
||||
return &ValidationError{
|
||||
Field: "ProviderGroup",
|
||||
Value: p.ProviderGroup,
|
||||
Message: "provider group must be 'atom.GroupInitial' in model mode",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证必须设置 NeedPrepareFunc
|
||||
if !p.NeedPrepareFunc {
|
||||
return &ValidationError{
|
||||
Field: "NeedPrepareFunc",
|
||||
Value: "false",
|
||||
Message: "model provider must set NeedPrepareFunc to true",
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 注释验证规则
|
||||
|
||||
#### 注释格式规则
|
||||
```go
|
||||
// CommentFormatRule 验证注释格式
|
||||
type CommentFormatRule struct{}
|
||||
|
||||
func (r *CommentFormatRule) Name() string {
|
||||
return "comment_format"
|
||||
}
|
||||
|
||||
func (r *CommentFormatRule) Validate(p *Provider) error {
|
||||
if p.Comment == nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
comment := p.Comment
|
||||
|
||||
// 验证注释必须以 @provider 开头
|
||||
if !strings.HasPrefix(comment.RawText, "@provider") {
|
||||
return &ValidationError{
|
||||
Field: "Comment.RawText",
|
||||
Value: comment.RawText,
|
||||
Message: "provider comment must start with '@provider'",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证模式格式
|
||||
if comment.Mode != "" && !isValidProviderMode(comment.Mode) {
|
||||
return &ValidationError{
|
||||
Field: "Comment.Mode",
|
||||
Value: string(comment.Mode),
|
||||
Message: fmt.Sprintf("invalid provider mode: %s", comment.Mode),
|
||||
}
|
||||
}
|
||||
|
||||
// 验证注入模式
|
||||
if comment.Injection != "" && !isValidInjectionMode(comment.Injection) {
|
||||
return &ValidationError{
|
||||
Field: "Comment.Injection",
|
||||
Value: string(comment.Injection),
|
||||
Message: fmt.Sprintf("invalid injection mode: %s", comment.Injection),
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 文件路径验证规则
|
||||
|
||||
#### 文件路径规则
|
||||
```go
|
||||
// FilePathRule 验证文件路径
|
||||
type FilePathRule struct{}
|
||||
|
||||
func (r *FilePathRule) Name() string {
|
||||
return "file_path"
|
||||
}
|
||||
|
||||
func (r *FilePathRule) Validate(p *Provider) error {
|
||||
if p.ProviderFile == "" {
|
||||
return &ValidationError{
|
||||
Field: "ProviderFile",
|
||||
Value: "",
|
||||
Message: "provider file path cannot be empty",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证文件扩展名
|
||||
if !strings.HasSuffix(p.ProviderFile, ".go") {
|
||||
return &ValidationError{
|
||||
Field: "ProviderFile",
|
||||
Value: p.ProviderFile,
|
||||
Message: "provider file must have .go extension",
|
||||
}
|
||||
}
|
||||
|
||||
// 验证文件路径安全性
|
||||
if !isSafeFilePath(p.ProviderFile) {
|
||||
return &ValidationError{
|
||||
Field: "ProviderFile",
|
||||
Value: p.ProviderFile,
|
||||
Message: "provider file path is not safe",
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
## 验证器注册
|
||||
|
||||
### 默认验证器
|
||||
```go
|
||||
// DefaultValidator 返回默认验证器
|
||||
func DefaultValidator() Validator {
|
||||
validator := NewCompositeValidator()
|
||||
|
||||
// 注册所有验证规则
|
||||
validator.AddRule(&StructNameRule{})
|
||||
validator.AddRule(&PackageNameRule{})
|
||||
validator.AddRule(&ReturnTypeRule{})
|
||||
validator.AddRule(NewProviderModeRule())
|
||||
validator.AddRule(&InjectParamsRule{})
|
||||
validator.AddRule(&PackageAliasRule{})
|
||||
validator.AddRule(&GRPCModeRule{})
|
||||
validator.AddRule(&EventModeRule{})
|
||||
validator.AddRule(&JobModeRule{})
|
||||
validator.AddRule(&ModelModeRule{})
|
||||
validator.AddRule(&CommentFormatRule{})
|
||||
validator.AddRule(&FilePathRule{})
|
||||
|
||||
return validator
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义验证器
|
||||
```go
|
||||
// CompositeValidator 组合验证器
|
||||
type CompositeValidator struct {
|
||||
rules []ValidationRule
|
||||
}
|
||||
|
||||
func NewCompositeValidator() *CompositeValidator {
|
||||
return &CompositeValidator{
|
||||
rules: make([]ValidationRule, 0),
|
||||
}
|
||||
}
|
||||
|
||||
func (v *CompositeValidator) AddRule(rule ValidationRule) {
|
||||
v.rules = append(v.rules, rule)
|
||||
}
|
||||
|
||||
func (v *CompositeValidator) Validate(p *Provider) []error {
|
||||
var errors []error
|
||||
|
||||
for _, rule := range v.rules {
|
||||
if err := rule.Validate(p); err != nil {
|
||||
errors = append(errors, err)
|
||||
}
|
||||
}
|
||||
|
||||
return errors
|
||||
}
|
||||
```
|
||||
|
||||
## 验证结果
|
||||
|
||||
### 验证报告
|
||||
```go
|
||||
// ValidationReport 验证报告
|
||||
type ValidationReport struct {
|
||||
Provider *Provider `json:"provider"`
|
||||
Errors []error `json:"errors"`
|
||||
Warnings []error `json:"warnings"`
|
||||
IsValid bool `json:"is_valid"`
|
||||
Timestamp time.Time `json:"timestamp"`
|
||||
}
|
||||
|
||||
// ValidateProvider 验证 provider 并生成报告
|
||||
func ValidateProvider(p *Provider) *ValidationReport {
|
||||
report := &ValidationReport{
|
||||
Provider: p,
|
||||
Timestamp: time.Now(),
|
||||
}
|
||||
|
||||
validator := DefaultValidator()
|
||||
errors := validator.Validate(p)
|
||||
|
||||
if len(errors) == 0 {
|
||||
report.IsValid = true
|
||||
} else {
|
||||
report.Errors = errors
|
||||
report.IsValid = false
|
||||
}
|
||||
|
||||
return report
|
||||
}
|
||||
```
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 验证性能优化
|
||||
- 快速失败：遇到第一个错误立即返回
|
||||
- 缓存验证结果
|
||||
- 并行验证独立规则
|
||||
- 懒加载验证器
|
||||
|
||||
### 内存优化
|
||||
- 重用验证器实例
|
||||
- 避免重复分配错误对象
|
||||
- 使用对象池管理验证器
|
||||
|
||||
## 扩展性
|
||||
|
||||
### 自定义规则注册
|
||||
```go
|
||||
// RegisterValidationRule 注册全局验证规则
|
||||
func RegisterValidationRule(name string, rule ValidationRule) error {
|
||||
// 实现规则注册逻辑
|
||||
}
|
||||
|
||||
// GetValidationRule 获取验证规则
|
||||
func GetValidationRule(name string) (ValidationRule, bool) {
|
||||
// 实现规则获取逻辑
|
||||
}
|
||||
```
|
||||
|
||||
### 规则优先级
|
||||
```go
|
||||
// PrioritizedRule 优先级规则
|
||||
type PrioritizedRule struct {
|
||||
Rule ValidationRule
|
||||
Priority int
|
||||
}
|
||||
|
||||
// PriorityValidator 优先级验证器
|
||||
type PriorityValidator struct {
|
||||
rules []PrioritizedRule
|
||||
}
|
||||
|
||||
func (v *PriorityValidator) Validate(p *Provider) []error {
|
||||
// 按优先级执行验证
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user