# 目录组织候选方案与推荐方案（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` 全绿