152 lines
4.3 KiB
Markdown
152 lines
4.3 KiB
Markdown
# 目录组织候选方案与推荐方案（Dart/Flutter OpenAPI 代码生成器）
|
||
|
||
最后更新：2025-11-22
|
||
适用范围：lib/**、templates/**、docs/**、test/**、example/**
|
||
不改变现有行为与生成结果；仅优化结构与依赖方向。
|
||
|
||
## 现状简述（基于 STRUCTURE_AUDIT）
|
||
- 分层清晰：commands/config/core/parsers/validators/generators/utils/templates
|
||
- 聚合导出：swagger_generator_flutter.dart、core/error_reporter.dart、core/models.dart、utils/string_utils.dart
|
||
- EnhancedValidator 为装饰器，依赖 SchemaValidator；ConfigRepository 为配置主入口
|
||
- 主要改进空间：
|
||
1) 统一对外“index.dart”聚合导出，避免深层路径泄漏
|
||
2) 命令层集中注入单个 ConfigRepository 实例以减少 I/O（可选）
|
||
3) 明确模板搜索优先级与上下文基线的构建点
|
||
|
||
---
|
||
|
||
## 方案 A（保守）：最小改动，快速落地
|
||
目标：基本不动现有目录，仅补充聚合导出与文档约束。
|
||
|
||
建议目录（节选）
|
||
```
|
||
lib/
|
||
core/
|
||
models/
|
||
models.dart # 已有：聚合导出
|
||
error_reporter/
|
||
error_reporter.dart# 已有：聚合导出
|
||
utils/
|
||
string_utils/
|
||
string_utils.dart # 已有：聚合导出
|
||
swagger_generator_flutter.dart # 对外主入口
|
||
```
|
||
措施
|
||
- 在 docs/USAGE_GUIDE.md 强化“仅从聚合入口导入”的约束
|
||
- 在 analysis_options.yaml 添加禁止深层导入的 lint（可选）
|
||
|
||
优点
|
||
- 变更最小，零风险，立刻可用
|
||
缺点
|
||
- 不能进一步降低跨层依赖；规范依赖于文档与自觉
|
||
影响面
|
||
- 对外零影响；测试与 CLI 行为不变
|
||
|
||
---
|
||
|
||
## 方案 B（平衡，推荐）：完善聚合导出与依赖边界
|
||
目标：降低跨层耦合，巩固入口文件，保留现有分层和命名
|
||
|
||
建议目录（节选）
|
||
```
|
||
lib/
|
||
commands/
|
||
base_command.dart
|
||
generate_command.dart
|
||
services/
|
||
document_merge_service.dart
|
||
document_filter_service.dart
|
||
generation_output_service.dart
|
||
core/
|
||
config.dart
|
||
config_repository.dart
|
||
template_renderer.dart
|
||
template/
|
||
template_loader.dart (part)
|
||
models/
|
||
models.dart
|
||
error_reporter/
|
||
error_reporter.dart
|
||
exceptions/
|
||
exceptions.dart
|
||
parsers/
|
||
swagger_fetcher.dart
|
||
swagger_data_parser.dart
|
||
validators/
|
||
core/
|
||
rules/
|
||
schema_validator.dart
|
||
enhanced_validator.dart
|
||
generators/
|
||
base_generator.dart
|
||
model/
|
||
model_code_generator.dart
|
||
retrofit_api/
|
||
retrofit_api_generator.dart
|
||
utils/
|
||
file_utils.dart
|
||
path_resolver.dart
|
||
reference_resolver.dart
|
||
string_utils/
|
||
string_utils.dart
|
||
templates/
|
||
api/
|
||
models/
|
||
common/
|
||
swagger_generator_flutter.dart
|
||
```
|
||
执行要点
|
||
- 为 commands/core/parsers/validators/generators/utils 分别补齐/校验聚合导出（需要时新增 index.dart）
|
||
- 内部互相依赖仅经聚合文件或上层入口（避免跨层直连深文件）
|
||
- TemplateRenderer 中的上下文构建固化（已完成）：仅从 ConfigRepository 构建一次
|
||
- 命令层（GenerateCommand）可选集中创建单例 config 并下传
|
||
|
||
优点
|
||
- 依赖边界更清晰；可渐进治理深层导入
|
||
- 变更成本适中，兼容性强
|
||
缺点
|
||
- 需少量导入路径梳理（指向聚合文件）
|
||
影响面
|
||
- 对外零影响；测试与 CLI 行为不变
|
||
|
||
---
|
||
|
||
## 方案 C（激进）：按业务流分区
|
||
目标：以 Parse → Validate → Generate → Render → Output 的流水线重组目录
|
||
|
||
建议目录草案（节选）
|
||
```
|
||
lib/
|
||
pipeline/
|
||
parse/ (swagger_fetcher, swagger_data_parser)
|
||
validate/ (schema_validator, enhanced_validator, error_reporter)
|
||
generate/
|
||
models/
|
||
apis/
|
||
templates/ (renderer, loader, services)
|
||
output/ (generation_output_service, file_utils)
|
||
core/ (models, exceptions, config_repository)
|
||
commands/
|
||
utils/
|
||
```
|
||
优点
|
||
- 强业务流程导向；定位问题成本更低
|
||
缺点
|
||
- 变动大，PR 体积大；回滚复杂
|
||
影响面
|
||
- 需要系统性迁移与长时间稳定验证
|
||
|
||
---
|
||
|
||
## 推荐方案
|
||
- 采纳方案 B（平衡）：
|
||
- 当前分层已合理，主要补强聚合导出与导入规范
|
||
- 最小代价减少未来跨层依赖与“深层路径”侵蚀
|
||
|
||
---
|
||
|
||
## 对测试与命令行为的影响
|
||
- 三个方案均“不改变行为”；仅目录/导入治理
|
||
- 质量门禁：每步迁移后确保 `dart analyze` 0 error / 0 warning、`dart test` 全绿
|
||
|