824861c27c
- 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.
387 lines
12 KiB
Markdown
387 lines
12 KiB
Markdown
# 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. |