3.9 KiB
3.9 KiB
目录结构迁移步骤清单（方案 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.dartpackage:swagger_generator_flutter/core/models.dartpackage:swagger_generator_flutter/core/error_reporter.dartpackage: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 拆分建议
- docs-only：新增/更新 STRUCTURE_* 文档与 PROJECT_OVERVIEW 补充
- structure-exports：聚合导出与导入路径治理（不改逻辑）
- perf-config（可选）：命令层注入单例 ConfigRepository
回滚策略
- 任一 PR 合并后出现行为偏差：
git revert <commit>回滚到上一步 - 保留分支 feature/structure-governance 直到发布后稳定一周