rogee/atomctl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Refactor AST generation routes workflow

Browse Source 
- Introduced a comprehensive data model for route definitions, parameters, and validation rules.
- Established component interfaces for route parsing, comment parsing, import resolution, route building, validation, and rendering.
- Developed a detailed implementation plan outlining execution flow, user requirements, and compliance with design principles.
- Created a quickstart guide to assist users in utilizing the refactored system effectively.
- Conducted thorough research on existing architecture, identifying key improvements and establishing a refactoring strategy.
- Specified functional requirements and user scenarios to ensure clarity and testability.
- Generated a task list for implementation, emphasizing test-driven development and parallel execution where applicable.
This commit is contained in:
Rogee
2025-09-22 11:33:13 +08:00
parent 0cfc573960
commit 824861c27c
17 changed files with 3324 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

387
specs/002-refactor-ast-gen/data-model.md Normal file
View File

@@ -0,0 +1,387 @@
# Phase 1: Data Model Design
## Overview
This document defines the core data models and contracts for the refactored AST route generation system, following the component-based architecture pattern established in the provider module.
## Core Entities
### 1. RouteDefinition
Represents a complete route definition extracted from source code annotations.
```go
type RouteDefinition struct {
// Basic Information
StructName string // Name of the handler struct
FilePath string // Source file path
PackageName string // Go package name
// Route Configuration
Path string // HTTP path pattern
Methods []string // HTTP methods (GET, POST, etc.)
Name string // Route name for identification
// Dependencies & Imports
Imports map[string]string // Package path -> alias mapping
Parameters []ParamDefinition // Route parameters
Middleware []string // Middleware chain
// Code Generation
HandlerFunc string // Handler function name
ReturnType string // Return type specification
ProviderGroup string // Dependency injection group
// Metadata
Location SourceLocation // Source location for error reporting
Annotations map[string]string // Additional annotations
}
```
### 2. ParamDefinition
Represents a parameter binding from different sources.
```go
type ParamDefinition struct {
// Parameter Identification
Name string // Parameter name
Position ParamPosition // Parameter location (path, query, etc.)
Type string // Parameter type
Source string // Source annotation text
// Type Information
BaseType string // Base type without pointer
IsPointer bool // Is pointer type
IsSlice bool // Is slice type
IsMap bool // Is map type
// Model Information (for structured parameters)
ModelName string // Model name for model() binding
ModelField string // Target field in model
ModelType string // Model field type
// Validation & Constraints
Required bool // Is required parameter
DefaultValue string // Default value
Validation []ValidationRule // Validation rules
// Code Generation
ParamToken string // Template token for generation
ImportPath string // Import path for type
}
```
### 3. ParamPosition
Parameter position enumeration.
```go
type ParamPosition string
const (
ParamPositionPath ParamPosition = "path" // URL path parameters
ParamPositionQuery ParamPosition = "query" // Query string parameters
ParamPositionBody ParamPosition = "body" // Request body
ParamPositionHeader ParamPosition = "header" // HTTP headers
ParamPositionCookie ParamPosition = "cookie" // Cookies
ParamPositionLocal ParamPosition = "local" // Local context values
ParamPositionFile ParamPosition = "file" // File uploads
)
```
### 4. ValidationRule
Parameter validation rule definition.
```go
type ValidationRule struct {
Type ValidationType // Validation type (required, min, max, etc.)
Value string // Validation value
Message string // Error message
Constraint string // Constraint expression
}
```
### 5. SourceLocation
Source code location information.
```go
type SourceLocation struct {
File string // Source file path
Line int // Line number
Column int // Column position
}
```
## Component Interfaces
### 1. RouteParser Interface
Main coordinator interface for route parsing.
```go
type RouteParser interface {
ParseFile(filePath string) ([]RouteDefinition, error)
ParseDir(dirPath string) ([]RouteDefinition, error)
ParseString(code string) ([]RouteDefinition, error)
// Configuration
SetConfig(config *RouteParserConfig) error
GetConfig() *RouteParserConfig
// Context & Diagnostics
GetContext() *ParserContext
GetDiagnostics() []Diagnostic
}
```
### 2. CommentParser Interface
Handles annotation parsing from source comments.
```go
type CommentParser interface {
ParseRouteComment(comment string) (*RouteAnnotation, error)
ParseBindComment(comment string) (*BindAnnotation, error)
IsRouteComment(comment string) bool
IsBindComment(comment string) bool
}
```
### 3. ImportResolver Interface
Manages import resolution and dependencies.
```go
type ImportResolver interface {
ResolveFileImports(node *ast.File, filePath string) (*ImportContext, error)
ResolveImportPath(alias string) (string, error)
AddImport(imports map[string]string, path, alias string) error
}
```
### 4. RouteBuilder Interface
Constructs route definitions from parsed components.
```go
type RouteBuilder interface {
BuildFromTypeSpec(typeSpec *ast.TypeSpec, decl *ast.GenDecl, context *BuilderContext) (RouteDefinition, error)
BuildFromComment(comment string, context *BuilderContext) (RouteDefinition, error)
ValidateDefinition(def *RouteDefinition) error
}
```
### 5. RouteValidator Interface
Validates route definitions and configurations.
```go
type RouteValidator interface {
ValidateRoute(def *RouteDefinition) error
ValidateParameters(params []ParamDefinition) error
ValidateImports(imports map[string]string) error
GetValidationRules() []ValidationRule
}
```
### 6. RouteRenderer Interface
Handles template rendering and code generation.
```go
type RouteRenderer interface {
Render(routes []RouteDefinition, outputPath string) error
RenderToFile(route RouteDefinition, outputPath string) error
SetTemplate(template *template.Template) error
GetTemplate() *template.Template
}
```
## Supporting Data Structures
### 1. RouteAnnotation
Parsed route annotation information.
```go
type RouteAnnotation struct {
Path string // Route path
Methods []string // HTTP methods
Name string // Route name
Options map[string]string // Additional options
}
```
### 2. BindAnnotation
Parsed bind annotation information.
```go
type BindAnnotation struct {
Name string // Parameter name
Position ParamPosition // Parameter position
Key string // Source key
Model *ModelInfo // Model binding info (optional)
Options map[string]string // Additional options
}
```
### 3. ModelInfo
Model binding information.
```go
type ModelInfo struct {
Name string // Model name
Field string // Target field
Type string // Field type
Required bool // Is required
}
```
### 4. ImportContext
Import resolution context.
```go
type ImportContext struct {
FileImports map[string]*ImportResolution // Alias -> Resolution
ImportPaths map[string]string // Path -> Alias
ModuleInfo map[string]string // Module path -> module name
WorkingDir string // Current working directory
ModuleName string // Current module name
ProcessedFiles map[string]bool // Track processed files
}
```
### 5. ImportResolution
Individual import resolution information.
```go
type ImportResolution struct {
Path string // Import path
Alias string // Import alias
Type ImportType // Import type
Used bool // Whether import is used
}
```
### 6. BuilderContext
Context for route building process.
```go
type BuilderContext struct {
FilePath string // Current file path
PackageName string // Package name
ImportContext *ImportContext // Import information
ASTFile *ast.File // AST node
ProcessedTypes map[string]bool // Processed types cache
Errors []error // Error collection
Warnings []string // Warning collection
Config *BuilderConfig // Builder configuration
}
```
## Configuration Structures
### 1. RouteParserConfig
Configuration for route parser behavior.
```go
type RouteParserConfig struct {
// Parsing Options
ParseComments bool // Parse comments (default: true)
StrictMode bool // Strict validation mode
SourceLocations bool // Include source locations
// File Processing
SkipTestFiles bool // Skip test files (default: true)
SkipGenerated bool // Skip generated files (default: true)
AllowedPatterns []string // Allowed file patterns
// Validation Options
EnableValidation bool // Enable validation (default: true)
ValidationLevel ValidationLevel // Validation strictness
// Performance Options
CacheEnabled bool // Enable parsing cache
ParallelProcessing bool // Enable parallel processing
}
```
### 2. BuilderConfig
Configuration for route builder.
```go
type BuilderConfig struct {
EnableValidation bool // Enable validation
StrictMode bool // Strict validation mode
DefaultParamPosition ParamPosition // Default parameter position
AutoGenerateReturnTypes bool // Auto-generate return types
ResolveImportDependencies bool // Resolve import dependencies
}
```
### 3. ValidationLevel
Validation strictness levels.
```go
type ValidationLevel int
const (
ValidationLevelNone ValidationLevel = iota // No validation
ValidationLevelBasic // Basic validation
ValidationLevelStrict // Strict validation
ValidationLevelPedantic // Pedantic validation
)
```
## Error Handling
### 1. RouteError
Route-specific error type.
```go
type RouteError struct {
Code ErrorCode // Error code
Message string // Error message
File string // File path
Line int // Line number
Column int // Column number
Context string // Error context
Severity ErrorSeverity // Error severity
Inner error // Inner error
}
```
### 2. ErrorCode
Error code enumeration.
```go
type ErrorCode string
const (
ErrCodeInvalidSyntax ErrorCode = "INVALID_SYNTAX"
ErrCodeMissingAnnotation ErrorCode = "MISSING_ANNOTATION"
ErrCodeInvalidParameter ErrorCode = "INVALID_PARAMETER"
ErrCodeDuplicateRoute ErrorCode = "DUPLICATE_ROUTE"
ErrCodeImportResolution ErrorCode = "IMPORT_RESOLUTION"
ErrCodeValidation ErrorCode = "VALIDATION_ERROR"
ErrCodeTemplateError ErrorCode = "TEMPLATE_ERROR"
)
```
### 3. Diagnostic
Rich diagnostic information.
```go
type Diagnostic struct {
Level DiagnosticLevel // Diagnostic level
Code ErrorCode // Error code
Message string // Diagnostic message
File string // File path
Location SourceLocation // Source location
Context string // Additional context
Suggestions []string // Suggested fixes
}
```
## Summary
This data model design provides a comprehensive foundation for the refactored route generation system. Key features include:
1. **Clear separation of concerns**: Each component has well-defined interfaces and responsibilities
2. **Comprehensive error handling**: Structured error types with rich diagnostic information
3. **Extensible validation**: Configurable validation system with multiple levels
4. **Type safety**: Strong typing throughout the system
5. **Configuration management**: Flexible configuration system for different use cases
6. **Backward compatibility**: Designed to support existing annotation formats
The design follows SOLID principles and provides a solid foundation for implementing the refactored route generation system.