diff --git a/STRUCTURE_AUDIT.md b/STRUCTURE_AUDIT.md new file mode 100644 index 0000000..c97318e --- /dev/null +++ b/STRUCTURE_AUDIT.md @@ -0,0 +1,132 @@ +# 目录结构审计报告（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 +``` + diff --git a/STRUCTURE_MIGRATION_CHECKLIST.md b/STRUCTURE_MIGRATION_CHECKLIST.md new file mode 100644 index 0000000..a6a034c --- /dev/null +++ b/STRUCTURE_MIGRATION_CHECKLIST.md @@ -0,0 +1,85 @@ +# 目录结构迁移步骤清单（方案 B：平衡，推荐） + +最后更新：2025-11-22 +目标：不改变行为与产物，在保持现有分层的基础上，补强聚合导出与依赖边界，减少深层路径依赖。 +质量门禁：每一步都需满足 +- dart analyze：0 errors / 0 warnings（info 可忽略） +- dart test：全部通过 +- CLI 行为与生成结果一致（如有差异必须回滚） +回滚策略：任一步失败，git revert 最近一次提交，恢复到上一步。 + +--- + +## 预备 +- 建立工作分支：feature/structure-governance +- 基线验证：`dart analyze`、`dart test` + +## 步骤 1：导入路径治理（聚合导出优先） +- 动作：检查对外导入，尽量使用聚合导出入口 + - 外部仅推荐导入： + - `package:swagger_generator_flutter/swagger_generator_flutter.dart` + - `package:swagger_generator_flutter/core/models.dart` + - `package:swagger_generator_flutter/core/error_reporter.dart` + - `package:swagger_generator_flutter/utils/string_utils.dart` +- 验证：`grep -R "lib/core/.*\.dart" example/` 无直接深层导入；构建与示例运行通过 +- 提交信息（示例）： + - chore(structure): 规范外部导入路径，统一使用聚合导出入口 + +## 步骤 2：为关键子系统补齐/校验聚合导出（如需） +- 动作：核对各子系统对外的唯一入口（index/聚合文件） + - validators：已有 schema/enhanced 两者并存，保持不变（装饰器与基础） + - core：error_reporter.dart / models.dart 已存在 + - utils：string_utils.dart 已存在 +- 验证：对外导入不依赖深层文件；现有单测与示例仍可编译运行 +- 提交： + - chore(structure): 校验与补齐聚合导出入口（无行为改动） + +## 步骤 3：模板上下文基线与模板搜索优先级固化（文档） +- 动作：在 PROJECT_OVERVIEW.md 增加： + - 仅在 TemplateRenderer 构建一次基础上下文（generatorName/author/copyright） + - 模板搜索优先级：自定义根 > 配置目录/templates > 配置目录/lib/templates > 工作目录向上搜集 +- 验证：无代码变更；生成行为一致 +- 提交： + - docs: 明确模板上下文构建点与模板搜索优先级 + +## 步骤 4（可选）：命令层集中注入 ConfigRepository 单例 +- 动作：在 GenerateCommand 执行期创建单个 config 实例，下传到 Renderer/Services（当前已通过懒加载避免多次 I/O，可暂缓） +- 验证：性能对比日志（可选），行为一致 +- 提交： + - perf(config): 命令层集中注入单例 ConfigRepository 减少 I/O + +## 步骤 5：文档与指南同步 +- 动作： + - 更新 USAGE_GUIDE.md：新增“导入路径规范（只用聚合导出）”“模板加载优先级” + - 在 README（或 QUICK_REFERENCE）加入 1 页速览 +- 验证：示例按照指南可跑通 +- 提交： + - docs: 增补导入路径规范与模板加载优先级 + +## 验收与合并 +- 运行：`dart analyze`、`dart test` +- grep 校验： + - `grep -R "package:swagger_generator_flutter/.*/.*\.dart" example/` 不应出现深层路径 +- 提交： + - chore(release): 目录结构治理（方案 B）— 聚合导出与导入规范 +- PR 检查项： + - 无行为变化；仅结构/文档治理 + - 附运行截图或日志 + +--- + +## 提交信息模板（中文） +- chore(structure): 规范外部导入路径，统一使用聚合导出入口 +- docs: 明确模板上下文构建点与模板搜索优先级 +- perf(config): 命令层集中注入单例 ConfigRepository 减少 I/O（可选） +- chore(release): 目录结构治理（方案 B）— 聚合导出与导入规范 + +## PR 拆分建议 +1) docs-only：新增/更新 STRUCTURE_* 文档与 PROJECT_OVERVIEW 补充 +2) structure-exports：聚合导出与导入路径治理（不改逻辑） +3) perf-config（可选）：命令层注入单例 ConfigRepository + +## 回滚策略 +- 任一 PR 合并后出现行为偏差：`git revert ` 回滚到上一步 +- 保留分支 feature/structure-governance 直到发布后稳定一周 + diff --git a/STRUCTURE_PROPOSAL.md b/STRUCTURE_PROPOSAL.md new file mode 100644 index 0000000..a580b56 --- /dev/null +++ b/STRUCTURE_PROPOSAL.md @@ -0,0 +1,151 @@ +# 目录组织候选方案与推荐方案（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` 全绿 +