atomctl/specs/001-pkg-ast-provider contracts/parser-api.md

Parser API Contract

概述

定义 pkg/ast/provider 包的解析器 API 契约，确保向后兼容性和一致的接口设计。

核心接口

Parser Interface

// Parser 定义 provider 解析器接口
type Parser interface {
    // ParseFile 解析单个 Go 文件
    ParseFile(filename string) ([]*Provider, error)

    // ParseDir 解析目录中的所有 Go 文件
    ParseDir(dirname string) ([]*Provider, error)

    // ParseString 解析字符串内容
    ParseString(content string, filename string) ([]*Provider, error)

    // SetConfig 设置解析器配置
    SetConfig(config ParserConfig) error

    // GetConfig 获取当前配置
    GetConfig() ParserConfig
}

Validator Interface

// Validator 定义 provider 验证器接口
type Validator interface {
    // Validate 验证 provider 配置
    Validate(p *Provider) []error

    // ValidateComment 验证 provider 注释
    ValidateComment(comment *ProviderComment) []error
}

Renderer Interface

// Renderer 定义 provider 渲染器接口
type Renderer interface {
    // Render 渲染 provider 代码
    Render(filename string, providers []*Provider) error

    // RenderTemplate 使用自定义模板渲染
    RenderTemplate(filename string, providers []*Provider, template string) error
}

数据结构

Provider

// Provider 表示一个依赖注入提供者
type Provider struct {
    StructName       string            `json:"struct_name"`
    ReturnType       string            `json:"return_type"`
    Mode             ProviderMode      `json:"mode"`
    ProviderGroup    string            `json:"provider_group"`
    GrpcRegisterFunc string            `json:"grpc_register_func"`
    NeedPrepareFunc  bool              `json:"need_prepare_func"`
    InjectParams     map[string]InjectParam `json:"inject_params"`
    Imports          map[string]string  `json:"imports"`
    PkgName          string            `json:"pkg_name"`
    ProviderFile     string            `json:"provider_file"`
    SourceLocation   SourceLocation    `json:"source_location"`
}

ProviderComment

// ProviderComment 表示解析的 provider 注释
type ProviderComment struct {
    RawText     string       `json:"raw_text"`
    Mode        ProviderMode `json:"mode"`
    Injection   InjectionMode `json:"injection"`
    ReturnType  string       `json:"return_type"`
    Group       string       `json:"group"`
    IsValid     bool         `json:"is_valid"`
    Errors      []string     `json:"errors"`
    Location    SourceLocation `json:"location"`
}

InjectParam

// InjectParam 表示注入参数
type InjectParam struct {
    Star         string `json:"star"`
    Type         string `json:"type"`
    Package      string `json:"package"`
    PackageAlias string `json:"package_alias"`
    FieldName    string `json:"field_name"`
    InjectTag    string `json:"inject_tag"`
}

枚举类型

ProviderMode

// ProviderMode 定义 provider 模式
type ProviderMode string

const (
    ModeDefault ProviderMode = ""
    ModeGRPC   ProviderMode = "grpc"
    ModeEvent  ProviderMode = "event"
    ModeJob    ProviderMode = "job"
    ModeCronJob ProviderMode = "cronjob"
    ModeModel  ProviderMode = "model"
)

InjectionMode

// InjectionMode 定义注入模式
type InjectionMode string

const (
    InjectionDefault InjectionMode = ""
    InjectionOnly    InjectionMode = "only"
    InjectionExcept  InjectionMode = "except"
)

配置结构

ParserConfig

// ParserConfig 定义解析器配置
type ParserConfig struct {
    StrictMode     bool   `json:"strict_mode"`     // 严格模式
    AllowTestFile  bool   `json:"allow_test_file"` // 是否允许解析测试文件
    IgnorePattern  string `json:"ignore_pattern"`  // 忽略文件模式
    MaxFileSize    int64  `json:"max_file_size"`   // 最大文件大小
    EnableCache    bool   `json:"enable_cache"`    // 启用缓存
    CacheTTL       int    `json:"cache_ttl"`       // 缓存 TTL（秒）
}

DefaultConfig

// DefaultConfig 返回默认配置
func DefaultConfig() ParserConfig {
    return ParserConfig{
        StrictMode:     false,
        AllowTestFile:  false,
        IgnorePattern:  "*.gen.go",
        MaxFileSize:    1024 * 1024, // 1MB
        EnableCache:    false,
        CacheTTL:       300, // 5 分钟
    }
}

工厂函数

NewParser

// NewParser 创建新的解析器实例
func NewParser(config ParserConfig) (Parser, error)

// NewParserWithContext 创建带上下文的解析器
func NewParserWithContext(ctx context.Context, config ParserConfig) (Parser, error)

// NewDefaultParser 创建默认配置的解析器
func NewDefaultParser() (Parser, error)

NewValidator

// NewValidator 创建新的验证器实例
func NewValidator() (Validator, error)

// NewCustomValidator 创建自定义验证器
func NewCustomValidator(rules []ValidationRule) (Validator, error)

NewRenderer

// NewRenderer 创建新的渲染器实例
func NewRenderer() (Renderer, error)

// NewRendererWithTemplate 创建带自定义模板的渲染器
func NewRendererWithTemplate(template string) (Renderer, error)

错误处理

Error Types

// ParseError 解析错误
type ParseError struct {
    File    string `json:"file"`
    Line    int    `json:"line"`
    Column  int    `json:"column"`
    Message string `json:"message"`
}

// ValidationError 验证错误
type ValidationError struct {
    Field   string `json:"field"`
    Value   string `json:"value"`
    Message string `json:"message"`
}

// GenerationError 生成错误
type GenerationError struct {
    File    string `json:"file"`
    Message string `json:"message"`
}

// ConfigurationError 配置错误
type ConfigurationError struct {
    Field   string `json:"field"`
    Message string `json:"message"`
}

Error Interface

// ProviderError 定义 provider 相关错误接口
type ProviderError interface {
    error
    Code() string
    Details() map[string]interface{}
    IsRetryable() bool
}

兼容性保证

向后兼容

• 所有公共 API 保持向后兼容
• 结构体字段只能添加，不能删除或重命名
• 接口方法只能添加，不能删除或修改签名

废弃策略

• 废弃的 API 会标记为 deprecated
• 废弃的 API 会在至少 2 个主版本后移除
• 提供迁移指南和工具

版本控制

版本格式

• 遵循语义化版本控制 (SemVer)
• 主版本：不兼容的 API 变更
• 次版本：向下兼容的功能性新增
• 修订号：向下兼容的问题修正

版本检查

// Version 返回当前版本
func Version() string

// Compatible 检查版本兼容性
func Compatible(version string) bool

性能要求

解析性能

• 单个文件解析时间 < 100ms
• 目录解析时间 < 1s（100 个文件以内）
• 内存使用 < 50MB（正常情况）

生成性能

• 代码生成时间 < 200ms
• 模板渲染时间 < 50ms
• 生成的代码大小合理（< 10KB per provider）

安全考虑

输入验证

• 所有输入参数必须验证
• 文件路径必须安全检查
• 防止路径遍历攻击

资源限制

• 最大文件大小限制
• 最大递归深度限制
• 最大并发处理数限制

扩展点

自定义模式

// RegisterProviderMode 注册自定义 provider 模式
func RegisterProviderMode(mode string, handler ProviderModeHandler) error

// ProviderModeHandler provider 模式处理器接口
type ProviderModeHandler interface {
    Parse(comment string) (*ProviderComment, error)
    Validate(comment *ProviderComment) error
    Generate(comment *ProviderComment) (*Provider, error)
}

自定义验证器

// ValidationRule 验证规则接口
type ValidationRule interface {
    Name() string
    Validate(p *Provider) error
}

// RegisterValidationRule 注册验证规则
func RegisterValidationRule(rule ValidationRule) error

自定义渲染器

// TemplateFunction 模板函数类型
type TemplateFunction func(args ...interface{}) (interface{}, error)

// RegisterTemplateFunction 注册模板函数
func RegisterTemplateFunction(name string, fn TemplateFunction) error

测试契约

单元测试

// TestParserContract 测试解析器契约
func TestParserContract(t *testing.T) {
    parser := NewDefaultParser()

    // 测试基本功能
    providers, err := parser.ParseFile("testdata/simple.go")
    assert.NoError(t, err)
    assert.NotEmpty(t, providers)

    // 测试错误处理
    _, err = parser.ParseFile("testdata/invalid.go")
    assert.Error(t, err)
}

集成测试

// TestFullWorkflow 测试完整工作流
func TestFullWorkflow(t *testing.T) {
    // 解析 -> 验证 -> 生成 -> 验证结果
}

基准测试

// BenchmarkParser 基准测试
func BenchmarkParser(b *testing.B) {
    parser := NewDefaultParser()

    for i := 0; i < b.N; i++ {
        _, err := parser.ParseFile("testdata/large.go")
        if err != nil {
            b.Fatal(err)
        }
    }
}

监控和日志

日志接口

// Logger 定义日志接口
type Logger interface {
    Debug(msg string, fields ...interface{})
    Info(msg string, fields ...interface{})
    Warn(msg string, fields ...interface{})
    Error(msg string, fields ...interface{})
}

// SetLogger 设置日志器
func SetLogger(logger Logger)

指标接口

// Metrics 定义指标接口
type Metrics interface {
    Counter(name string, value int64, tags ...string)
    Timer(name string, value time.Duration, tags ...string)
    Gauge(name string, value float64, tags ...string)
}

// SetMetrics 设置指标收集器
func SetMetrics(metrics Metrics)