目录组织候选方案与推荐方案（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 体积大；回滚复杂影响面
需要系统性迁移与长时间稳定验证

对测试与命令行为的影响

三个方案均“不改变行为”；仅目录/导入治理
质量门禁：每步迁移后确保 dart analyze 0 error / 0 warning、dart test 全绿

4.3 KiB Raw Blame History Unescape Escape