133 lines
4.8 KiB
Markdown
133 lines
4.8 KiB
Markdown
# 目录结构审计报告（Dart/Flutter OpenAPI 代码生成器）
|
||
|
||
最后更新：2025-11-22
|
||
适用范围：lib/**、templates/**、docs/**、test/**、example/**（忽略 build/.dart_tool 等生成产物）
|
||
|
||
## 一、lib/ 目录结构（第二层深度）
|
||
|
||
```
|
||
lib/
|
||
commands/
|
||
base_command.dart
|
||
generate_command.dart
|
||
services/
|
||
config/
|
||
error_rules.yaml
|
||
core/
|
||
config.dart
|
||
config_repository.dart
|
||
error_reporter/ # models / reporter / renderers
|
||
error_reporter.dart # 聚合导出
|
||
error_rules.dart
|
||
exceptions/ # 细分异常定义
|
||
exceptions.dart # 聚合导出
|
||
models/ # Swagger 核心模型
|
||
models.dart # 聚合导出
|
||
performance_parser.dart
|
||
template/ # TemplateLoader (part of template_renderer)
|
||
template_renderer.dart
|
||
generators/
|
||
base_generator.dart
|
||
model/
|
||
model_code_generator.dart
|
||
retrofit_api/
|
||
retrofit_api_generator.dart
|
||
parsers/
|
||
swagger_data_parser.dart
|
||
swagger_fetcher.dart
|
||
templates/
|
||
api/
|
||
common/
|
||
models/
|
||
utils/
|
||
cache_manager.dart
|
||
file_utils.dart
|
||
logger.dart
|
||
path_resolver.dart
|
||
performance_monitor.dart
|
||
reference_resolver.dart
|
||
string_utils.dart # 统一导出
|
||
string_utils/ # naming_converter / template_service / text_cleaner
|
||
type_validator.dart
|
||
validators/
|
||
core/
|
||
rules/
|
||
enhanced_validator.dart
|
||
schema_validator.dart
|
||
swagger_cli_new.dart
|
||
swagger_generator_flutter.dart # 顶层聚合导出
|
||
```
|
||
|
||
关键聚合导出文件：
|
||
- lib/swagger_generator_flutter.dart（对外公共 API 入口）
|
||
- lib/core/error_reporter.dart（聚合导出 models/reporter/renderers）
|
||
- lib/core/models.dart（聚合导出核心模型）
|
||
- lib/utils/string_utils.dart（聚合导出 naming_converter/template_service/text_cleaner）
|
||
|
||
## 二、职责边界与潜在问题
|
||
|
||
- commands：参数解析 + 流程编排（解析→验证→生成→落盘），OK
|
||
- config：以 ConfigRepository 为主，SwaggerConfig 静态 getter 兼容，OK
|
||
- core：通用核心（模型/异常/错误报告/模板渲染/并行解析），OK
|
||
- parsers：SwaggerFetcher/SwaggerDataParser（获取与解析），OK
|
||
- validators：SchemaValidator 基础规则 + EnhancedValidator 装饰增强（依赖 ErrorReporter），OK
|
||
- generators：ModelCodeGenerator / RetrofitApiGenerator + Mustache 模板，OK
|
||
- utils：通用工具（I/O/路径/引用解析/字符串处理），OK
|
||
- templates：Mustache 模板，OK
|
||
|
||
发现与建议：
|
||
1) 依赖方向基本自上而下，无循环依赖。TemplateLoader 依赖 PathResolver，合理。
|
||
2) 工具分层已明确：string_utils（面向生成）与 file/path（基础设施）分离，良好。
|
||
3) validators 下“增强 vs 基础”是装饰关系，不应合并；已在文档中明确。
|
||
4) 顶层导出 swagger_generator_flutter.dart 已聚合核心能力，但 generators/validators/core/utils 的暴露范围建议仅保留聚合导出，避免深层路径泄漏。
|
||
|
||
## 三、跨层依赖与改进机会
|
||
|
||
- 配置注入点：
|
||
- TemplateRenderer/GenerationOutputService 等处已采用 ConfigRepository.loadSync()，建议命令层集中创建单例并向下传递（可选优化）。
|
||
- 模板上下文基线：
|
||
- TemplateRenderer._buildBaseContext 固化生成器名称/作者/版权，已统一。
|
||
- 输出服务边界：
|
||
- GenerationOutputService 已与生成器/文件写入解耦，清晰。
|
||
|
||
## 四、重复与冗余排查（enhanced/improved/v2）
|
||
|
||
- validators：EnhancedValidator（装饰器）与 SchemaValidator（基础）——场景互补，保留两者。
|
||
- config：已迁移至 ConfigRepository，ConfigLoader 已移除（docs/MIGRATION_CONFIG_LOADER.md 已提供映射）。
|
||
- 其他 v2/Enhanced 字样多为注释/示例，不构成并行实现。
|
||
|
||
结论：无须删除新增模块；已冗余项（ConfigLoader）已处置。
|
||
|
||
## 五、风险点
|
||
- 外部引用深层路径的风险：建议对外仅使用 swagger_generator_flutter.dart 和若干聚合导出；在 USAGE 指南提示。
|
||
- 模板根目录查找优先级：TemplateLoader 的向上搜集策略需在文档中明确（建议：自定义根 > 配置目录 > 工作目录链）。
|
||
|
||
## 六、关系示意（Mermaid）
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
CLI[CLI / Command] --> CFG[ConfigRepository]
|
||
CLI --> PF[SwaggerFetcher]
|
||
PF --> SDP[SwaggerDataParser]
|
||
SDP --> VAL[SchemaValidator]
|
||
VAL -->|decorate| EV[EnhancedValidator]
|
||
EV --> ER[ErrorReporter]
|
||
SDP --> MODELS[Core Models]
|
||
CLI --> GEN[Generators]
|
||
GEN --> MC[ModelCodeGenerator]
|
||
GEN --> RG[RetrofitApiGenerator]
|
||
RG --> TR[TemplateRenderer]
|
||
TR --> TS[TemplateService]
|
||
CLI --> OUT[GenerationOutputService]
|
||
subgraph Utils
|
||
FU[FileUtils]
|
||
PR[PathResolver]
|
||
RR[ReferenceResolver]
|
||
SU[StringUtils]
|
||
end
|
||
GEN -.-> Utils
|
||
SDP -.-> Utils
|
||
CLI -.-> Utils
|
||
```
|
||
|