From f08e4786694c04f7926f54ab708d8e500b1ee357 Mon Sep 17 00:00:00 2001 From: Max Date: Sat, 31 Jan 2026 00:27:40 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=B8=85=E7=90=86=E8=BF=87=E6=9C=9F?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 删除已完成的提案、实现总结和审计报告: - ENUM_KEY_NAMES_PROPOSAL.md - ENUM_CONFIG_MAPPING_SUMMARY.md - LINE_LENGTH_FIX_SUMMARY.md - STRING_UTILS_REFACTOR_SUMMARY.md - STRUCTURE_PROPOSAL.md - STRUCTURE_AUDIT.md - STRUCTURE_MIGRATION_CHECKLIST.md - PROJECT_QUALITY_REVIEW.md - DEPENDENCY_UPDATE.md - CHANGELOG_CANCELTOKEN.md (已合并到主 CHANGELOG) --- CHANGELOG_CANCELTOKEN.md | 41 --- DEPENDENCY_UPDATE.md | 159 ---------- ENUM_CONFIG_MAPPING_SUMMARY.md | 408 ------------------------ ENUM_KEY_NAMES_PROPOSAL.md | 384 ----------------------- LINE_LENGTH_FIX_SUMMARY.md | 101 ------ PROJECT_QUALITY_REVIEW.md | 512 ------------------------------- STRING_UTILS_REFACTOR_SUMMARY.md | 159 ---------- STRUCTURE_AUDIT.md | 132 -------- STRUCTURE_MIGRATION_CHECKLIST.md | 85 ----- STRUCTURE_PROPOSAL.md | 151 --------- example/generator_config.yaml | 3 + example/pubspec.lock | 2 +- 12 files changed, 4 insertions(+), 2133 deletions(-) delete mode 100644 CHANGELOG_CANCELTOKEN.md delete mode 100644 DEPENDENCY_UPDATE.md delete mode 100644 ENUM_CONFIG_MAPPING_SUMMARY.md delete mode 100644 ENUM_KEY_NAMES_PROPOSAL.md delete mode 100644 LINE_LENGTH_FIX_SUMMARY.md delete mode 100644 PROJECT_QUALITY_REVIEW.md delete mode 100644 STRING_UTILS_REFACTOR_SUMMARY.md delete mode 100644 STRUCTURE_AUDIT.md delete mode 100644 STRUCTURE_MIGRATION_CHECKLIST.md delete mode 100644 STRUCTURE_PROPOSAL.md diff --git a/CHANGELOG_CANCELTOKEN.md b/CHANGELOG_CANCELTOKEN.md deleted file mode 100644 index c247b7e..0000000 --- a/CHANGELOG_CANCELTOKEN.md +++ /dev/null @@ -1,41 +0,0 @@ -# CancelToken 功能变更日志 / CancelToken Feature Changelog - -## [3.3.0] - 2026-01-31 - -### 🎉 新特性 / New Features - -#### CancelToken 支持 -- ✅ **配置开关**：在 `generator_config.yaml` 中配置 `generation.api.cancel_token_support: true` 启用 -- ✅ **自动添加参数**：启用后，所有 API 方法自动添加 `@CancelRequest() CancelToken? cancelToken` 参数 -- ✅ **向后兼容**：默认关闭，不影响现有项目 - -### 📝 文档 / Documentation -- ✅ 新增 `CANCELTOKEN_USAGE_GUIDE.md` - 使用指南和最佳实践 -- ✅ 更新 `generator_config.template.yaml` - 添加配置示例 - -### 🔧 技术细节 / Technical Details - -**修改的文件：** -- `lib/core/config_repository.dart` - 添加 `cancelTokenSupport` 配置解析 -- `lib/pipeline/generate/impl/retrofit_api/api_parameters.dart` - 在 `_generateParameters()` 中添加 CancelToken 参数生成逻辑 -- `generator_config.template.yaml` - 添加配置项说明 - -**生成的参数格式：** -```dart -@CancelRequest() CancelToken? cancelToken -``` - -### 💡 使用场景 / Use Cases - -1. **页面离开取消请求** - 避免内存泄漏和不必要的状态更新 -2. **用户主动取消** - 如搜索框输入时取消之前的搜索请求 -3. **超时控制** - 配合 Timer 实现自定义超时逻辑 -4. **批量取消** - 一个 CancelToken 可用于多个请求 - ---- - -## 相关资源 / Related Resources - -- [Dio CancelToken 文档](https://pub.dev/packages/dio#cancellation) -- [Retrofit CancelRequest 注解](https://pub.dev/packages/retrofit) -- [使用指南](./CANCELTOKEN_USAGE_GUIDE.md) diff --git a/DEPENDENCY_UPDATE.md b/DEPENDENCY_UPDATE.md deleted file mode 100644 index fad6bc3..0000000 --- a/DEPENDENCY_UPDATE.md +++ /dev/null @@ -1,159 +0,0 @@ -# 依赖包版本更新说明 - -## 更新日期 -2025-11-21 - -## 更新内容 - -### 主项目 (pubspec.yaml) - -#### 更新前 -```yaml -dependencies: - json_annotation: ^4.8.1 - freezed_annotation: ^2.4.1 - -dev_dependencies: - build_runner: ^2.4.7 - json_serializable: ^6.7.1 - retrofit_generator: ^8.0.0 - freezed: ^2.4.7 -``` - -#### 更新后 -```yaml -dependencies: - json_annotation: ^4.9.0 - freezed_annotation: ^3.1.0 - -dev_dependencies: - build_runner: ^2.10.4 - json_serializable: ^6.11.2 - retrofit_generator: ^10.2.0 - freezed: ^3.2.3 -``` - -### Example 项目 (example/pubspec.yaml) - -#### 更新前 -```yaml -dependencies: - json_annotation: ^4.9.0 - freezed_annotation: ^2.4.1 - -dev_dependencies: - build_runner: ^2.4.7 - retrofit_generator: ^9.0.0 - json_serializable: ^6.7.1 - freezed: ^2.4.7 -``` - -#### 更新后 -```yaml -dependencies: - json_annotation: ^4.9.0 - freezed_annotation: ^3.1.0 - -dev_dependencies: - build_runner: ^2.10.4 - retrofit_generator: ^10.2.0 - json_serializable: ^6.11.2 - freezed: ^3.2.3 -``` - -## 版本说明 - -### build_runner -- **旧版本**: 2.4.7 -- **新版本**: 2.10.4 -- **发布时间**: 2天前 (2025-11-19) -- **说明**: 最新稳定版本，修复了多个已知问题 - -### json_serializable -- **旧版本**: 6.7.1 -- **新版本**: 6.11.2 -- **说明**: 使用 6.11.2 而非 6.11.3，因为 6.11.3 与 freezed 3.2.3 存在 analyzer 版本冲突 - -### retrofit_generator -- **旧版本**: 8.0.0 / 9.0.0 -- **新版本**: 10.2.0 -- **发布时间**: 33小时前 (2025-11-20) -- **说明**: 最新版本，支持更多特性 - -### freezed -- **旧版本**: 2.4.7 -- **新版本**: 3.2.3 -- **发布时间**: 2个月前 (2025-09-10) -- **重要变更**: - - 需要 freezed_annotation 3.1.0+ - - 支持 Dart 3 的原生模式匹配 - - 建议使用 `switch` 表达式替代 `when`/`map` 方法 - -### freezed_annotation -- **旧版本**: 2.4.1 / 2.4.4 -- **新版本**: 3.1.0 -- **说明**: 必须升级到 3.x 以配合 freezed 3.x - -### json_annotation -- **旧版本**: 4.8.1 -- **新版本**: 4.9.0 -- **说明**: 保持 4.x 版本以确保兼容性 - -## 版本兼容性矩阵 - -| 包名 | 版本 | analyzer 依赖 | 兼容性 | -|------|------|--------------|--------| -| freezed 3.2.3 | ✅ | 7.5.9 - 9.0.0 | ✅ | -| json_serializable 6.11.2 | ✅ | 8.x | ✅ | -| json_serializable 6.11.3 | ❌ | 9.0.0+ | ❌ 与 freezed 冲突 | -| build_runner 2.10.4 | ✅ | - | ✅ | -| retrofit_generator 10.2.0 | ✅ | - | ✅ | - -## 解决的问题 - -1. **build_runner 缓存损坏**: 通过升级到最新版本解决 -2. **版本冲突**: - - freezed 3.x 需要 freezed_annotation 3.x - - freezed 3.2.3 与 json_serializable 6.11.3 存在 analyzer 版本冲突 - - 使用 json_serializable 6.11.2 解决冲突 - -## 清理步骤 - -如果遇到问题，执行以下清理步骤： - -```bash -# 1. 清理缓存 -rm -rf .dart_tool -rm -rf pubspec.lock - -# 2. 重新获取依赖 -flutter pub get - -# 3. 清理构建文件 -flutter clean - -# 4. 重新运行 build_runner -flutter pub run build_runner build --delete-conflicting-outputs -``` - -## 注意事项 - -1. **Freezed 3.x 迁移**: - - 建议使用 Dart 3 的原生 `switch` 表达式 - - 旧的 `when`/`map` 方法仍然可用，但已标记为遗留功能 - -2. **analyzer 版本**: - - 当前配置使用 analyzer 8.x - - 避免使用需要 analyzer 9.x 的包版本 - -3. **pub.dev 镜像**: - - 如果使用国内镜像 (pub.flutter-io.cn)，可能需要等待同步 - - 建议使用官方源或清华镜像 - -## 参考链接 - -- [build_runner](https://pub.dev/packages/build_runner) -- [json_serializable](https://pub.dev/packages/json_serializable) -- [retrofit_generator](https://pub.dev/packages/retrofit_generator) -- [freezed](https://pub.dev/packages/freezed) - diff --git a/ENUM_CONFIG_MAPPING_SUMMARY.md b/ENUM_CONFIG_MAPPING_SUMMARY.md deleted file mode 100644 index c30b6ca..0000000 --- a/ENUM_CONFIG_MAPPING_SUMMARY.md +++ /dev/null @@ -1,408 +0,0 @@ -# 枚举配置文件映射功能实现总结 - -**实现日期**: 2025-11-24 -**功能状态**: ✅ 已完成并测试 - -## 概述 - -成功实现了**阶段 2：配置文件映射**功能，允许用户通过 `generator_config.yaml` 配置文件为枚举值定义有意义的键名和描述，即使后端不支持 OpenAPI 扩展字段。 - -## 核心特性 - -### 1. 三级优先级系统 - -``` -配置文件映射 > x-enum-varnames > 智能生成 -``` - -- **配置文件映射**（最高优先级）：用户在 `generator_config.yaml` 中显式配置 -- **x-enum-varnames**（中优先级）：后端在 Swagger 文档中提供的扩展字段 -- **智能生成**（最低优先级）：自动生成 `valueN` 格式 - -### 2. 灵活的配置方式 - -支持在 `generator_config.yaml` 中配置： - -```yaml -generation: - models: - enum_key_mappings: - SysTaskTypeEnums: - - value: 1 - name: SPOT_CHECK - description: 抽查 - - value: 2 - name: CULTURAL - description: 文创建设 -``` - -### 3. 完整的类型支持 - -- ✅ 整数枚举 (`integer`, `number`) -- ✅ 字符串枚举 (`string`) -- ✅ 枚举键名和描述 -- ✅ 部分映射（可以只配置部分枚举值） -- ✅ 自动添加 `UNKNOWN` 枚举值（整数类型用 `-9999`，字符串类型用 `'UNKNOWN'`） -- ✅ 容错处理（未知值返回 `UNKNOWN` 而不是抛异常） - -## 实现细节 - -### 修改的文件 - -#### 1. `lib/core/config_repository.dart` - -新增 `EnumKeyMapping` 数据类和解析逻辑： - -```dart -/// 枚举键名映射 -class EnumKeyMapping { - const EnumKeyMapping({ - required this.name, - this.description, - }); - - final String name; - final String? description; -} - -class ConfigRepository { - /// 获取枚举键名映射配置 - Map>? get enumKeyMappings { - // 从配置文件解析枚举映射 - // 返回格式: { "EnumName": { value: EnumKeyMapping } } - } -} -``` - -#### 2. `lib/core/config.dart` - -暴露枚举映射配置： - -```dart -class SwaggerConfig { - /// 获取枚举键名映射配置（从配置文件读取） - static Map>? get enumKeyMappings => - ConfigRepository.loadSync().enumKeyMappings; -} -``` - -#### 3. `lib/pipeline/generate/impl/model/model_content_builders.dart` - -修改枚举生成逻辑，支持三级优先级： - -```dart -String _generateEnumCodeWithoutImports(ApiModel model) { - // 获取配置文件中的枚举映射 - final enumMappings = SwaggerConfig.enumKeyMappings?[model.name]; - - for (var i = 0; i < model.enumValues.length; i++) { - final value = model.enumValues[i]; - - String enumName; - String? description; - - // 优先级 1: 配置文件映射 - if (enumMappings != null && enumMappings.containsKey(value)) { - final mapping = enumMappings[value]!; - enumName = mapping.name; - description = mapping.description; - } - // 优先级 2: x-enum-varnames - else if (model.enumVarNames != null && i < model.enumVarNames!.length) { - enumName = model.enumVarNames![i]; - if (model.enumDescriptions != null && i < model.enumDescriptions!.length) { - description = model.enumDescriptions![i]; - } - } - // 优先级 3: 智能生成 - else { - enumName = StringHelper.generateEnumValueName(value, i); - } - - // 生成枚举代码... - } -} -``` - -#### 4. `generator_config.template.yaml` - -添加详细的配置示例和说明： - -```yaml -generation: - models: - # 枚举键名映射配置（可选） - # 用于为枚举值定义有意义的键名和描述 - # 优先级：配置文件映射 > x-enum-varnames > 智能生成 - enum_key_mappings: - SysTaskTypeEnums: - - value: 1 - name: SPOT_CHECK - description: 抽查 - - value: 2 - name: CULTURAL - description: 文创建设 -``` - -### 测试文件 - -#### 测试 Swagger 文档 - -创建了 `example/swagger_config_mapping_test.json`： - -```json -{ - "components": { - "schemas": { - "SysTaskTypeEnums": { - "type": "integer", - "description": "任务类型枚举", - "enum": [1, 2, 3, 4, 5, 6, 7] - } - } - } -} -``` - -#### 测试配置文件 - -创建了 `example/test_config_mapping.yaml`，包含完整的枚举映射配置。 - -#### 测试结果 - -✅ 成功生成了包含有意义键名和描述的枚举代码： - -```dart -/// 任务类型枚举 -@JsonEnum() -enum SysTaskTypeEnums { - /// 抽查 - SPOT_CHECK(1), - /// 文创建设 - CULTURAL(2), - /// 班干部会议 - CLASS_CADRE_MEETING(3), - /// 文创项目 - CULTURAL_PROJECT(4), - /// 教工评优 - TEACHER_AWARD(5), - /// 班级评比 - CLASS_EVALUATION(6), - /// 组织生活 - ORGANIZATION_LIFE(7), - - /// 未知值 - UNKNOWN(-9999); - - const SysTaskTypeEnums(this.value); - final int value; - - static SysTaskTypeEnums fromValue(dynamic value) { - for (final enumValue in SysTaskTypeEnums.values) { - if (enumValue.value == value) { - return enumValue; - } - } - return SysTaskTypeEnums.UNKNOWN; // 返回 UNKNOWN 而不是抛异常 - } - // ... 其余代码 -} -``` - -## 文档更新 - -### 1. ENUM_KEY_NAMES_PROPOSAL.md - -- ✅ 标记阶段 2 已完成 -- ✅ 更新实施步骤 -- ✅ 添加配置文件格式说明 - -### 2. ENUM_KEY_NAMES_USAGE.md - -- ✅ 添加"方法 2: 通过配置文件映射"章节 -- ✅ 提供完整的配置示例 -- ✅ 说明优先级规则 -- ✅ 列出使用场景和注意事项 - -### 3. generator_config.template.yaml - -- ✅ 添加 `enum_key_mappings` 配置节 -- ✅ 提供详细的注释和示例 -- ✅ 说明优先级和使用场景 - -## 使用示例 - -### 场景 1: 后端不支持扩展字段 - -**Swagger 文档**: - -```json -{ - "SysTaskTypeEnums": { - "enum": [1, 2, 3], - "type": "integer" - } -} -``` - -**配置文件**: - -```yaml -generation: - models: - enum_key_mappings: - SysTaskTypeEnums: - - value: 1 - name: SPOT_CHECK - description: 抽查 - - value: 2 - name: CULTURAL - description: 文创建设 - - value: 3 - name: CLASS_CADRE_MEETING - description: 班干部会议 -``` - -**生成结果**: 使用配置文件中的键名和描述 ✅ - -### 场景 2: 覆盖 Swagger 文档定义 - -**Swagger 文档**: - -```json -{ - "SysTaskTypeEnums": { - "enum": [1, 2, 3], - "type": "integer", - "x-enum-varnames": ["TYPE_1", "TYPE_2", "TYPE_3"] - } -} -``` - -**配置文件**: - -```yaml -generation: - models: - enum_key_mappings: - SysTaskTypeEnums: - - value: 1 - name: SPOT_CHECK - description: 抽查 -``` - -**生成结果**: -- value 1: 使用配置文件的 `SPOT_CHECK` ✅ -- value 2: 使用 Swagger 的 `TYPE_2` ✅ -- value 3: 使用 Swagger 的 `TYPE_3` ✅ - -### 场景 3: 只使用 Swagger 扩展字段 - -**Swagger 文档**: - -```json -{ - "SysTaskTypeEnums": { - "enum": [1, 2, 3], - "type": "integer", - "x-enum-varnames": ["SPOT_CHECK", "CULTURAL", "CLASS_CADRE_MEETING"] - } -} -``` - -**配置文件**: 无配置 - -**生成结果**: 使用 Swagger 的枚举键名 ✅ - -## UNKNOWN 枚举值 - -### 设计理念 - -每个生成的枚举都会自动添加一个 `UNKNOWN` 枚举值，用于处理未知或无效的枚举值，提供更好的容错性。 - -### 值的选择 - -- **整数枚举**: 使用 `-9999` 作为 `UNKNOWN` 的值 -- **字符串枚举**: 使用 `'UNKNOWN'` 作为 `UNKNOWN` 的值 - -### 优势 - -1. **容错处理**: 当接收到未知的枚举值时，返回 `UNKNOWN` 而不是抛出异常 -2. **前向兼容**: 当后端添加新的枚举值时，前端不会崩溃 -3. **安全检查**: 可以在业务逻辑中检查是否为 `UNKNOWN` 值 - -### 使用示例 - -```dart -// 后端返回了一个新增的枚举值 99（前端代码还未更新） -final taskType = SysTaskTypeEnums.fromValue(99); -print(taskType); // SysTaskTypeEnums.UNKNOWN - -// 业务逻辑中检查 -if (taskType == SysTaskTypeEnums.UNKNOWN) { - print('遇到未知的任务类型，请更新应用版本'); -} -``` - -## 优势 - -### 1. 灵活性 - -- ✅ 无需后端支持即可使用 -- ✅ 可以快速修改枚举定义 -- ✅ 支持覆盖 Swagger 文档定义 - -### 2. 兼容性 - -- ✅ 完全向后兼容 -- ✅ 不影响现有功能 -- ✅ 与 x-enum-varnames 共存 -- ✅ 自动容错处理（UNKNOWN 枚举值） - -### 3. 可维护性 - -- ✅ 集中式配置管理 -- ✅ 易于团队协作 -- ✅ 支持部分映射 - -## 注意事项 - -### 1. 维护成本 - -⚠️ 配置文件需要手动维护，当后端枚举值变化时需要同步更新。 - -**建议**: 如果后端支持，优先使用 Swagger 扩展字段，保持单一数据源。 - -### 2. 值匹配 - -⚠️ 配置文件中的 `value` 必须与 Swagger 文档中的枚举值完全匹配（类型和值都要匹配）。 - -### 3. 命名规范 - -⚠️ 枚举键名必须是有效的 Dart 标识符（大写字母+下划线）。 - -## 后续计划 - -1. ✅ 基础功能实现 -2. ✅ 测试验证 -3. ✅ 文档更新 -4. 🔄 收集用户反馈 -5. 🔄 优化用户体验 - -## 总结 - -阶段 2 的配置文件映射功能已成功实现，为用户提供了更灵活的枚举键名配置方式。用户现在可以： - -1. ✅ 在后端不支持扩展字段时使用配置文件 -2. ✅ 覆盖 Swagger 文档中的枚举定义 -3. ✅ 快速修改枚举键名，无需等待后端 -4. ✅ 为不同项目使用不同的枚举命名规范 - -功能已完成测试，生成的代码符合预期，文档已更新完毕。 - ---- - -**实现者**: Assistant -**日期**: 2025-11-24 -**状态**: ✅ 已完成 - diff --git a/ENUM_KEY_NAMES_PROPOSAL.md b/ENUM_KEY_NAMES_PROPOSAL.md deleted file mode 100644 index 747c4e9..0000000 --- a/ENUM_KEY_NAMES_PROPOSAL.md +++ /dev/null @@ -1,384 +0,0 @@ -# 枚举键名生成优化方案 - -## 问题描述 - -当前生成的枚举使用通用的键名（`value1`, `value2`, `value3`...），不够语义化。 - -### 当前生成结果 - -```dart -enum SysTaskTypeEnums { - value1(1), // 实际应该是 SPOT_CHECK (抽查) - value2(2), // 实际应该是 CULTURAL (文创建设) - value3(3), // 实际应该是 CLASS_CADRE_MEETING (班干部会议) - ... -} -``` - -### 期望结果 - -```dart -enum SysTaskTypeEnums { - /// 抽查 - SPOT_CHECK(1), - - /// 文创建设 - CULTURAL(2), - - /// 班干部会议 - CLASS_CADRE_MEETING(3), - - /// 学生谈话 - STUDENT_TALK(4), - ... -} -``` - -## 根本原因 - -Swagger 文档中的枚举定义只包含值（numbers），没有提供键名映射： - -```json -{ - "SysTaskTypeEnums": { - "enum": [1, 2, 3, 4, 5, ...], - "type": "integer", - "description": "任务类型枚举" - } -} -``` - -## 解决方案 - -### 方案 1: 使用 OpenAPI 扩展字段 (推荐) - -在 Swagger 文档中添加 `x-enum-varnames` 和 `x-enum-descriptions` 扩展字段： - -```json -{ - "SysTaskTypeEnums": { - "enum": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13], - "type": "integer", - "description": "任务类型枚举", - "format": "int32", - "x-enum-varnames": [ - "SPOT_CHECK", - "CULTURAL", - "CLASS_CADRE_MEETING", - "STUDENT_TALK", - "FOLLOW_CLASS", - "TEACHER_BEHAVIOR_OBSERVATION", - "MEETING", - "COACH_SUBJECT", - "DATA_COLLECTION", - "CLASS_MEETING", - "TEACHER_TALK", - "OTHER_WORK", - "CLASS_ACTIVITY" - ], - "x-enum-descriptions": [ - "抽查", - "文创建设", - "班干部会议", - "学生谈话", - "双师跟课", - "教师行为观察", - "参加会议", - "学科辅助", - "数据采集", - "召开班会", - "教师谈话", - "其他工作", - "班级活动" - ] - } -} -``` - -**优点**: -- ✅ 标准的 OpenAPI 扩展方式 -- ✅ 枚举定义和键名在同一处 -- ✅ 易于维护 - -**缺点**: -- ⚠️ 需要修改后端 Swagger 文档 -- ⚠️ 需要后端配合 - -### 方案 2: 配置文件映射 - -在 `generator_config.yaml` 中添加枚举键名映射： - -```yaml -# generator_config.yaml - -generation: - models: - # 枚举键名映射配置 - enum_key_mappings: - SysTaskTypeEnums: - 1: - name: SPOT_CHECK - description: 抽查 - 2: - name: CULTURAL - description: 文创建设 - 3: - name: CLASS_CADRE_MEETING - description: 班干部会议 - 4: - name: STUDENT_TALK - description: 学生谈话 - 5: - name: FOLLOW_CLASS - description: 双师跟课 - # ... 其他映射 - - SysRoleEnum: - 1: - name: ADMIN - description: 管理员 - 2: - name: USER - description: 普通用户 - # ... 其他映射 -``` - -**优点**: -- ✅ 不需要修改后端 -- ✅ 灵活配置 -- ✅ 支持批量管理 - -**缺点**: -- ⚠️ 配置文件可能很大 -- ⚠️ 需要手动维护映射 - -### 方案 3: 智能命名策略（备选） - -如果 Swagger 文档中枚举的 description 字段包含中文说明，可以尝试智能转换： - -``` -"抽查" -> SPOT_CHECK (通过翻译API或预定义映射) -"文创建设" -> CULTURAL -"班干部会议" -> CLASS_CADRE_MEETING -``` - -**优点**: -- ✅ 自动化程度高 -- ✅ 不需要额外配置 - -**缺点**: -- ⚠️ 翻译质量不稳定 -- ⚠️ 需要外部服务或大量预定义映射 - -## 推荐实施方案 - -### 阶段 1: 支持 OpenAPI 扩展字段（立即实施） - -修改枚举解析逻辑，支持读取 `x-enum-varnames` 和 `x-enum-descriptions`： - -```dart -// lib/core/models/api_schema.dart - -class ApiModel { - final List? enumVarNames; // 新增 - final List? enumDescriptions; // 新增 - - factory ApiModel.fromJson(...) { - // 解析 x-enum-varnames - final enumVarNames = json['x-enum-varnames'] as List?; - final enumDescriptions = json['x-enum-descriptions'] as List?; - - return ApiModel( - enumVarNames: enumVarNames?.map((e) => e.toString()).toList(), - enumDescriptions: enumDescriptions?.map((e) => e.toString()).toList(), - ... - ); - } -} -``` - -修改枚举生成逻辑： - -```dart -// lib/pipeline/generate/impl/model/model_content_builders.dart - -String _generateEnumCodeWithoutImports(ApiModel model) { - ... - for (var i = 0; i < model.enumValues.length; i++) { - final value = model.enumValues[i]; - - // 优先使用 x-enum-varnames - final enumName = model.enumVarNames != null && i < model.enumVarNames!.length - ? model.enumVarNames![i] - : StringHelper.generateEnumValueName(value, i); - - // 添加描述注释 - if (model.enumDescriptions != null && i < model.enumDescriptions!.length) { - buffer.writeln(' /// ${model.enumDescriptions![i]}'); - } - - final enumLine = enumType == 'integer' || enumType == 'number' - ? ' $enumName($value),' - : " $enumName('$value'),"; - - buffer.writeln(enumLine); - } - ... -} -``` - -### 阶段 2: 支持配置文件映射 ✅ - -已实现配置支持： - -```dart -// lib/core/config_repository.dart - -class EnumKeyMapping { - final String name; - final String? description; - - const EnumKeyMapping({required this.name, this.description}); -} - -class ConfigRepository { - /// 获取枚举键名映射配置 - /// 返回格式: { "EnumName": { value: { "name": "KEY_NAME", "description": "描述" } } } - Map>? get enumKeyMappings { ... } -} -``` - -配置文件格式（`generator_config.yaml`）： - -```yaml -generation: - models: - enum_key_mappings: - SysTaskTypeEnums: - - value: 1 - name: SPOT_CHECK - description: 抽查 - - value: 2 - name: CULTURAL - description: 文创建设 -``` - -## 实施步骤 - -### Step 1: 修改数据模型 ✅ - -1. 在 `ApiModel` 中添加 `enumVarNames` 和 `enumDescriptions` 字段 -2. 在 `fromJson` 中解析扩展字段 - -### Step 2: 修改生成逻辑 ✅ - -1. 修改 `_generateEnumCodeWithoutImports` 方法 -2. 实现三级优先级：配置文件 > x-enum-varnames > 智能生成 -3. 支持配置文件覆盖 Swagger 文档定义 - -### Step 3: 配置文件支持 ✅ - -1. 在 `ConfigRepository` 中添加 `enumKeyMappings` 解析 -2. 在 `SwaggerConfig` 中暴露配置 -3. 在枚举生成逻辑中使用配置 -4. 更新配置模板文件 - -### Step 4: 文档和示例 ✅ - -1. 更新使用文档 -2. 提供 Swagger 文档示例 -3. 提供配置文件示例 -4. 创建测试配置和测试文档 - -### Step 5: 测试 ✅ - -1. 创建测试 Swagger 文档 -2. 创建测试配置文件 -3. 运行生成器验证功能 -4. 确认生成的枚举键名和描述正确 - -## 使用示例 - -### 后端 Swagger 文档（推荐） - -```json -{ - "components": { - "schemas": { - "SysTaskTypeEnums": { - "enum": [1, 2, 3], - "type": "integer", - "description": "任务类型枚举", - "x-enum-varnames": ["SPOT_CHECK", "CULTURAL", "CLASS_CADRE_MEETING"], - "x-enum-descriptions": ["抽查", "文创建设", "班干部会议"] - } - } - } -} -``` - -### 配置文件映射（备选） - -```yaml -# generator_config.yaml -generation: - models: - enum_key_mappings: - SysTaskTypeEnums: - 1: { name: "SPOT_CHECK", description: "抽查" } - 2: { name: "CULTURAL", description: "文创建设" } - 3: { name: "CLASS_CADRE_MEETING", description: "班干部会议" } -``` - -### 生成结果 - -```dart -/// 任务类型枚举 -@JsonEnum() -enum SysTaskTypeEnums { - /// 抽查 - SPOT_CHECK(1), - - /// 文创建设 - CULTURAL(2), - - /// 班干部会议 - CLASS_CADRE_MEETING(3); - - const SysTaskTypeEnums(this.value); - final int value; - - static SysTaskTypeEnums fromValue(dynamic value) { - for (final enumValue in SysTaskTypeEnums.values) { - if (enumValue.value == value) { - return enumValue; - } - } - throw ArgumentError('Unknown enum value: $value'); - } - - factory SysTaskTypeEnums.fromJson(dynamic json) { - return fromValue(json); - } - - dynamic toJson() => value; -} -``` - -## 兼容性 - -- ✅ 向后兼容：如果没有提供扩展字段或配置，仍使用 `value1`, `value2` 等 -- ✅ 灵活配置：支持全局配置或单个枚举配置 -- ✅ 标准支持：使用标准的 OpenAPI 扩展字段 - -## 相关资源 - -- [OpenAPI Extensions](https://swagger.io/docs/specification/openapi-extensions/) -- [x-enum-varnames Extension](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/templating.md#enum) - ---- - -**提案日期**: 2025-11-24 -**状态**: 待实施 -**优先级**: Medium - diff --git a/LINE_LENGTH_FIX_SUMMARY.md b/LINE_LENGTH_FIX_SUMMARY.md deleted file mode 100644 index 4852951..0000000 --- a/LINE_LENGTH_FIX_SUMMARY.md +++ /dev/null @@ -1,101 +0,0 @@ -# 代码行长度修复总结 - -## ✅ 已完成 - -成功修复了生成代码中超过 80 字符限制的问题。 - -## 📋 修复内容 - -### 1. 模板文件修改 - -#### `lib/templates/api/api_class.mustache` -- ✅ @RestApi 注解改为多行格式 -- ✅ Factory 构造函数改为多行格式 - -#### `lib/templates/api/main_api.mustache` -- ✅ Factory 构造函数改为多行格式 - -#### `lib/templates/api/api_method.mustache` -- ✅ 方法参数列表改为多行格式 - -### 2. 生成器代码修改 - -#### `lib/generators/retrofit_api/api_template_data.dart` -- ✅ 添加 `_wrapDocLine()` 方法实现智能文档换行 -- ✅ 更新 `_buildDocLines()` 方法使用自动换行 -- ✅ 支持参数文档的缩进和换行 - -### 3. 测试文件更新 - -#### `test/comprehensive_generator_test.dart` -- ✅ 更新测试断言以匹配新的代码格式 - -## 🎯 修复效果 - -### 修复前的问题 -```dart -// ❌ 84 字符 -@RestApi(baseUrl: 'https://api.example.com/api/v1', parser: Parser.JsonSerializable) - -// ❌ 123 字符 -factory VeryLongApiServiceNameForTestingPurposes(Dio dio, {String? baseUrl}) = _VeryLongApiServiceNameForTestingPurposes; - -// ❌ 101 字符 -/// Retrieve a list of all users with optional pagination parameters and advanced filtering options -``` - -### 修复后的效果 -```dart -// ✅ 每行都在 80 字符以内 -@RestApi( - baseUrl: 'https://api.example.com/api/v1', - parser: Parser.JsonSerializable, -) - -factory VeryLongApiServiceNameForTestingPurposes( - Dio dio, { - String? baseUrl, -}) = _VeryLongApiServiceNameForTestingPurposes; - -/// Retrieve a list of all users with optional pagination parameters and -/// advanced filtering options -``` - -## 🧪 测试结果 - -```bash -flutter test -``` - -- ✅ **230 个测试通过** -- ❌ 10 个测试失败（与行长度修复无关，是之前就存在的问题） -- ✅ **所有生成的代码行长度均符合 80 字符限制** - -## 🔍 智能换行特性 - -1. **自动检测**: 自动检测超过 76 字符的行（80 - '/// '.length） -2. **智能断点**: 优先在空格处断行，避免在单词中间断开 -3. **保持格式**: 支持缩进前缀，保持文档结构清晰 -4. **合理分配**: 断行位置不会太靠前（至少 60% 位置），确保每行有足够内容 - -## 📁 修改的文件 - -1. `lib/templates/api/api_class.mustache` -2. `lib/templates/api/main_api.mustache` -3. `lib/templates/api/api_method.mustache` -4. `lib/generators/retrofit_api/api_template_data.dart` -5. `test/comprehensive_generator_test.dart` -6. `docs/LINE_LENGTH_FIX.md` (新增文档) - -## 💡 技术亮点 - -- **零破坏性**: 所有修改仅影响代码格式，不改变功能 -- **智能算法**: 文档换行使用智能算法，确保可读性 -- **全面覆盖**: 处理了注解、构造函数、方法签名、文档注释等所有场景 -- **符合规范**: 完全符合 Dart 和 Flutter 的代码风格指南 - -## 🎉 总结 - -成功解决了生成代码中的行长度警告问题，所有生成的代码现在都符合 Dart 80 字符行长度限制， -同时保持了代码的可读性和功能完整性。 - diff --git a/PROJECT_QUALITY_REVIEW.md b/PROJECT_QUALITY_REVIEW.md deleted file mode 100644 index 48a1b39..0000000 --- a/PROJECT_QUALITY_REVIEW.md +++ /dev/null @@ -1,512 +0,0 @@ -# 项目质量审查报告 -## XY Swagger Generator Flutter - -**审查日期**: 2025-11-24 -**审查范围**: 项目结构、代码质量、测试覆盖、文档完整性 -**审查人员**: AI Assistant -**版本**: v1.0 - ---- - -## 📊 项目概览 - -### 基本信息 -- **项目名称**: swagger_generator_flutter (XY Swagger Generator) -- **项目类型**: Dart/Flutter OpenAPI 3.0 代码生成器 -- **代码行数**: ~13,504 行 (85个 Dart 文件) -- **测试文件**: 14 个测试文件 -- **测试通过率**: 220/222 (99.1%) - -### 技术栈 -- **核心**: Dart 3.x -- **模板引擎**: Mustache -- **CLI框架**: args -- **代码生成**: Retrofit + Freezed + JsonSerializable -- **代码质量**: very_good_analysis - ---- - -## ✅ 优势与亮点 - -### 1. 🏗️ **优秀的架构设计** - -#### Pipeline 架构模式 -``` -Parse → Validate → Generate → Render → Output -``` - -**优点**: -- ✅ 清晰的职责分离 -- ✅ 单向数据流 -- ✅ 易于测试和维护 -- ✅ 符合 SOLID 原则 - -#### 模块化设计 -``` -lib/ - ├── commands/ # CLI 命令层 - ├── pipeline/ # 处理流水线 - │ ├── parse/ # 解析 Swagger - │ ├── validate/ # 验证规则 - │ ├── generate/ # 代码生成 - │ ├── render/ # 模板渲染 - │ └── output/ # 文件输出 - ├── core/ # 核心模型 - ├── utils/ # 工具类 - └── templates/ # Mustache 模板 -``` - -**评分**: ⭐⭐⭐⭐⭐ (5/5) - -### 2. 📝 **完善的文档体系** - -#### 已有文档 -- ✅ `PROJECT_OVERVIEW.md` - 项目概览 -- ✅ `USAGE_GUIDE.md` - 使用指南 -- ✅ `STRUCTURE_AUDIT.md` - 结构审计 -- ✅ `STRUCTURE_PROPOSAL.md` - 结构优化方案 -- ✅ `API_IMPORTS_FIX_SUMMARY.md` - API 导入优化 -- ✅ `COMMENT_NEWLINE_FIX.md` - 注释修复 -- ✅ `LINE_LENGTH_FIX_SUMMARY.md` - 行长度修复 -- ✅ `STRING_UTILS_REFACTOR_SUMMARY.md` - 工具类重构 -- ✅ `generator/api_documentation.md` - API 文档 -- ✅ `example/QUICK_START.md` - 快速开始 -- ✅ `example/README.md` - 示例说明 - -**评分**: ⭐⭐⭐⭐⭐ (5/5) - -### 3. 🧪 **高测试覆盖率** - -#### 测试文件 -``` -test/ - ├── comprehensive_generator_test.dart # 生成器综合测试 - ├── comprehensive_parser_test.dart # 解析器综合测试 - ├── integration_test.dart # 集成测试 - ├── pagination_wrapping_test.dart # 分页包裹测试 - ├── encoding_test.dart # 编码测试 - ├── media_type_test.dart # 媒体类型测试 - ├── security_test.dart # 安全测试 - ├── reference_resolver_test.dart # 引用解析测试 - ├── template_renderer_test.dart # 模板渲染测试 - ├── text_cleaner_test.dart # 文本清理测试 - └── ... -``` - -**测试结果**: -- ✅ 220 个测试通过 -- ⚠️ 2 个测试失败（由于最近的重构导致） -- ✅ 测试通过率 99.1% - -**评分**: ⭐⭐⭐⭐ (4/5) - -### 4. 🔧 **实用的功能特性** - -#### 核心功能 -- ✅ **多版本支持**: 自动识别 v1、v2 等 API 版本 -- ✅ **分页响应智能识别**: 自动使用 `BasePageResult` -- ✅ **多 Swagger 源合并**: 支持合并多个 Swagger 文档 -- ✅ **Tag 分组生成**: 按 tag 生成独立 API 文件 -- ✅ **类型安全**: 生成强类型 Dart 代码 -- ✅ **Freezed 集成**: 支持不可变数据类 -- ✅ **Retrofit 支持**: 生成 Retrofit API 接口 -- ✅ **JsonSerializable**: 自动 JSON 序列化 -- ✅ **错误处理**: 完善的异常体系 -- ✅ **性能监控**: 内置性能监控 -- ✅ **缓存管理**: 智能缓存机制 - -**评分**: ⭐⭐⭐⭐⭐ (5/5) - -### 5. 📦 **优秀的示例项目** - -``` -example/ - ├── lib/ - │ ├── common/ # 基础类 - │ │ ├── base_result.dart - │ │ └── base_page_result.dart - │ └── src/ - │ ├── api/ # 生成的 API - │ │ ├── v1/ - │ │ └── v2/ - │ └── api_models/ # 生成的模型 - │ ├── enums/ - │ ├── parameters/ - │ ├── request/ - │ └── result/ - ├── generator_config.yaml # 配置文件 - ├── generate_api.sh # 生成脚本 - └── swagger.json # Swagger 文档 -``` - -**评分**: ⭐⭐⭐⭐⭐ (5/5) - ---- - -## ⚠️ 需要改进的地方 - -### 1. 代码质量问题 - -#### Linter 警告 (40 issues) - -**高优先级 (3 warnings)**: -```dart -// lib/pipeline/generate/impl/retrofit_api/api_return_types.dart -- _hasPaginationParameters 未使用 -- _hasPaginationTypeName 未使用 -- _hasPaginationPathPattern 未使用 -``` - -**建议**: -- ✅ **已完成**: 这些方法在最近的重构中被移除使用，但忘记删除 -- 📝 **行动项**: 删除未使用的方法 - -**中优先级 (10+ infos)**: -- 行长度超过 80 字符 -- 缺少 const 构造函数 -- 文件末尾缺少换行符 -- 不必要的原始字符串 - -**建议**: 运行 `dart fix --apply` 自动修复 - -**评分**: ⭐⭐⭐ (3/5) - -### 2. 测试失败 - -**失败的测试**: -``` -1. RetrofitApiGenerator generates split APIs by tags - - 期望: import 'users_api.dart' - - 实际: import 'users.dart' - -2. RetrofitApiGenerator generates security annotations - - 需要更新测试以匹配新的导入逻辑 -``` - -**原因**: 最近的 API 导入优化修改了导入路径格式 - -**建议**: -- 📝 **行动项**: 更新测试用例以匹配新的导入逻辑 -- 📝 **行动项**: 确保所有测试通过后再发布 - -**评分**: ⭐⭐⭐ (3/5) - -### 3. 代码复杂度 - -**高复杂度文件**: -``` -lib/pipeline/generate/impl/retrofit_api_generator.dart -lib/pipeline/generate/impl/model_code_generator.dart -lib/pipeline/parse/impl/swagger_data_parser.dart -``` - -**建议**: -- 考虑进一步拆分大文件 -- 使用更多的 mixin 来分离职责 -- 添加更多内联文档 - -**评分**: ⭐⭐⭐⭐ (4/5) - -### 4. 配置复杂性 - -**当前配置项**: 30+ 配置选项 - -**问题**: -- 配置项较多，学习曲线陡峭 -- 某些配置项相互依赖 - -**建议**: -- ✅ 已有 `generator_config.template.yaml` 模板 -- 📝 添加配置验证和提示 -- 📝 提供更多配置预设（minimal、standard、full） - -**评分**: ⭐⭐⭐ (3/5) - ---- - -## 📈 代码质量指标 - -### 静态分析结果 - -| 指标 | 数值 | 评价 | -|------|------|------| -| 代码行数 | ~13,504 | ✅ 适中 | -| 文件数量 | 85 | ✅ 良好 | -| 平均文件大小 | ~159 行 | ✅ 优秀 | -| Linter 错误 | 0 | ✅ 优秀 | -| Linter 警告 | 3 | ⚠️ 需修复 | -| Linter Info | 37 | ℹ️ 可选修复 | -| 测试通过率 | 99.1% | ✅ 优秀 | - -### 架构质量 - -| 维度 | 评分 | 说明 | -|------|------|------| -| 模块化 | ⭐⭐⭐⭐⭐ | Pipeline 架构清晰 | -| 可维护性 | ⭐⭐⭐⭐⭐ | 职责分离明确 | -| 可扩展性 | ⭐⭐⭐⭐⭐ | 易于添加新功能 | -| 可测试性 | ⭐⭐⭐⭐ | 测试覆盖率高 | -| 性能 | ⭐⭐⭐⭐⭐ | 缓存与优化到位 | -| 文档完整性 | ⭐⭐⭐⭐⭐ | 文档齐全详细 | - ---- - -## 🎯 最近的优化 - -### 1. BasePageResult 包裹逻辑修复 ✅ - -**问题**: -- 包含 `total` 和 `items` 的分页模型被错误处理 -- 生成了不必要的 `*PageResponse` 类 - -**解决**: -- 添加 `_extractPaginationItemType` 方法 -- 自动识别分页模型并使用 `BasePageResult` -- 符合项目规范 - -**影响**: 所有分页 API 的返回类型更加规范 - -### 2. API 导入逻辑优化 ✅ - -**问题**: -- API 文件缺少 models 导入 -- 需要手动添加类型导入 - -**解决**: -- 自动添加 `package:xxx/src/api_models/index.dart` 导入 -- models index.dart 导出所有必需类型 -- 代码更整洁 - -**影响**: 所有 API 文件自动包含正确导入 - -### 3. 智能分页判断逻辑移除 ✅ - -**原因**: -- 之前的启发式判断逻辑复杂且不可靠 -- 基于 schema 的判断更准确 - -**结果**: -- 移除了 `_isPageableType` 等启发式方法 -- 只使用 `_hasPaginationSchema` 进行判断 -- 代码更简洁可靠 - ---- - -## 🔍 生成代码质量 - -### 生成的 API 文件 - -**示例**: `superior_api.dart` - -```dart -import 'package:dio/dio.dart'; -import 'package:example_app/src/api_models/index.dart'; // ✅ 自动导入 -import 'package:retrofit/retrofit.dart'; - -part 'superior_api.g.dart'; - -@RestApi( - baseUrl: '', - parser: Parser.JsonSerializable, -) -abstract class SuperiorApiV2 { - factory SuperiorApiV2(Dio dio, {String? baseUrl}) = _SuperiorApiV2; - - /// 获取作为布置者的布置任务列表 - @GET('/api/v2/Superior/GetSuperiorTaskListResult') - Future>> // ✅ 正确类型 - getGetSuperiorTaskListResult( - @Queries() GetGetSuperiorTaskListResultParameters? parameters, - ); -} -``` - -**质量评价**: -- ✅ 类型安全 -- ✅ 文档完整 -- ✅ 导入正确 -- ✅ 命名规范 -- ✅ 支持泛型 - -**评分**: ⭐⭐⭐⭐⭐ (5/5) - -### 生成的模型文件 - -**示例**: models index.dart - -```dart -// API 模型导出文件 -export 'package:example_app/common/base_page_result.dart'; // ✅ 导出基础类 -export 'package:example_app/common/base_result.dart'; - -export 'enums/index.dart'; // ✅ 统一导出 -export 'parameters/index.dart'; -export 'request/index.dart'; -export 'result/index.dart'; -``` - -**质量评价**: -- ✅ 使用 barrel exports 模式 -- ✅ 分类清晰 -- ✅ 易于维护 - -**评分**: ⭐⭐⭐⭐⭐ (5/5) - ---- - -## 📋 改进建议 - -### 立即修复 (High Priority) - -1. **删除未使用的方法** ⚡ - ```dart - // lib/pipeline/generate/impl/retrofit_api/api_return_types.dart - - 删除 _hasPaginationParameters - - 删除 _hasPaginationTypeName - - 删除 _hasPaginationPathPattern - ``` - -2. **修复失败的测试** ⚡ - ``` - - 更新 'generates split APIs by tags' 测试 - - 更新 'generates security annotations' 测试 - ``` - -3. **运行代码格式化** ⚡ - ```bash - dart fix --apply - dart format lib test - ``` - -### 短期改进 (Medium Priority) - -1. **完善配置验证** 📝 - - 添加配置项相互依赖检查 - - 提供更友好的错误提示 - -2. **添加更多示例** 📝 - - 最小配置示例 - - 完整配置示例 - - 常见场景示例 - -3. **优化错误消息** 📝 - - 更详细的错误上下文 - - 提供修复建议 - -### 长期规划 (Low Priority) - -1. **性能优化** 🚀 - - 并行处理多个 API 文件 - - 优化大型 Swagger 文档解析 - -2. **功能增强** 🎯 - - 支持 OpenAPI 3.1 - - 支持更多代码生成模式 - - 支持自定义模板 - -3. **开发体验** 💡 - - VS Code 插件 - - 可视化配置界面 - - 实时预览 - ---- - -## 🏆 总体评分 - -### 综合评价 - -| 维度 | 评分 | 权重 | 加权分 | -|------|------|------|--------| -| 架构设计 | ⭐⭐⭐⭐⭐ (5.0) | 25% | 1.25 | -| 代码质量 | ⭐⭐⭐⭐ (4.0) | 20% | 0.80 | -| 测试覆盖 | ⭐⭐⭐⭐ (4.0) | 20% | 0.80 | -| 文档完整 | ⭐⭐⭐⭐⭐ (5.0) | 15% | 0.75 | -| 功能实用 | ⭐⭐⭐⭐⭐ (5.0) | 20% | 1.00 | - -**总分**: 4.6/5.0 ⭐⭐⭐⭐⭐ - -### 结论 - -XY Swagger Generator Flutter 是一个**高质量**的企业级代码生成器项目： - -**✅ 优势**: -1. 优秀的架构设计（Pipeline 模式） -2. 完善的文档体系 -3. 高测试覆盖率 -4. 实用的功能特性 -5. 持续的质量改进 - -**⚠️ 待改进**: -1. 3 个 linter 警告需要修复 -2. 2 个测试用例需要更新 -3. 配置复杂度可以优化 - -**📊 推荐指数**: 9.2/10 - -该项目已经具备了生产环境使用的条件，只需要修复少量警告和测试即可。 - ---- - -## 📝 行动计划 - -### Phase 1: 立即修复 (1-2 小时) - -- [ ] 删除未使用的方法 -- [ ] 修复失败的测试 -- [ ] 运行 `dart fix --apply` -- [ ] 确保所有测试通过 - -### Phase 2: 短期改进 (1-2 天) - -- [ ] 完善配置验证 -- [ ] 添加更多示例 -- [ ] 优化错误消息 - -### Phase 3: 长期规划 (持续) - -- [ ] 性能优化 -- [ ] 功能增强 -- [ ] 开发体验提升 - ---- - -**审查完成日期**: 2025-11-24 -**下次审查计划**: 2025-12-24 -**审查状态**: ✅ 通过（建议修复 minor issues） - ---- - -## 附录 - -### 相关文档 - -- [PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md) - 项目概览 -- [USAGE_GUIDE.md](docs/USAGE_GUIDE.md) - 使用指南 -- [STRUCTURE_AUDIT.md](STRUCTURE_AUDIT.md) - 结构审计 -- [API_IMPORTS_FIX_SUMMARY.md](API_IMPORTS_FIX_SUMMARY.md) - API 导入优化 - -### 测试命令 - -```bash -# 静态分析 -dart analyze - -# 运行所有测试 -dart test - -# 代码格式化 -dart format lib test - -# 自动修复 -dart fix --apply - -# 生成示例代码 -cd example && ./generate_api.sh -``` - -### 联系方式 - -- **项目**: swagger_generator_flutter -- **作者**: max -- **组织**: YuanXuan - diff --git a/STRING_UTILS_REFACTOR_SUMMARY.md b/STRING_UTILS_REFACTOR_SUMMARY.md deleted file mode 100644 index 18f4467..0000000 --- a/STRING_UTILS_REFACTOR_SUMMARY.md +++ /dev/null @@ -1,159 +0,0 @@ -# StringUtils 重构总结 - -**重构日期**: 2025-11-22 -**状态**: ✅ 完成 - -## 📋 重构目标 - -根据 `check_list.md` 的要求，对 `lib/utils/string_utils.dart`（421 行）进行重构： - -- **主要痛点**: 单文件包含命名转换、注释模板、复数化等杂项，并频繁同步读取配置 -- **首要行动**: 根据职责拆分（命名转换/注释模板/文本清理），缓存配置项并提供可注入模板服务 - -## 🎯 重构成果 - -### 1. 模块化拆分 - -将原有的 421 行单文件拆分为职责清晰的子模块： - -``` -lib/utils/string_utils/ -├── naming_converter.dart # 命名转换（187 行） -├── text_cleaner.dart # 文本清理（86 行） -└── template_service.dart # 模板服务（86 行） -``` - -### 2. 主文件重构 - -`lib/utils/string_utils.dart` 重构为统一导出接口（184 行）： -- 作为 Facade 模式，聚合各子模块功能 -- 保持向后兼容性，所有现有 API 保持不变 -- 清晰的功能分组注释 - -### 3. 各模块职责 - -#### NamingConverter（命名转换） -- `toCamelCase()` - 转换为 camelCase -- `toPascalCase()` - 转换为 PascalCase -- `toSnakeCase()` - 转换为 snake_case -- `toConstantCase()` - 转换为 UPPER_SNAKE_CASE -- `toDartPropertyName()` - 转换为 Dart 属性名 -- `generateClassName()` - 生成类名 -- `generateFileName()` - 生成文件名 -- `generateEnumValueName()` - 生成枚举值名称 -- `isValidDartIdentifier()` - 验证 Dart 标识符 -- `pluralize()` - 单词复数化 - -#### TextCleaner（文本清理） -- `cleanDescription()` - 清理描述文本 -- `cleanForCode()` - 清理代码标识符 -- `escapeString()` - 转义字符串 -- `unescapeString()` - 反转义字符串 -- `truncate()` - 截断文本 -- `normalize()` - 标准化文本（统一换行符和空白） - -#### TemplateService（模板服务） -- `generateComment()` - 生成注释块 -- `generateFileHeader()` - 生成文件头（使用 ConfigRepository） -- 支持自定义模板变量替换 -- 集成配置缓存，避免频繁读取 - -## 🔧 技术改进 - -### 1. 配置缓存优化 - -**之前**: 每次调用都读取配置 -```dart -final generatorName = ConfigLoader.getGeneratorName(); -final author = ConfigLoader.getAuthor(); -final copyright = ConfigLoader.getCopyright(); -``` - -**现在**: 使用 ConfigRepository 实例，支持配置缓存 -```dart -final config = ConfigRepository.loadSync(); -final generatorName = config.generatorName; -``` - -### 2. 依赖注入支持 - -TemplateService 设计为可实例化，支持依赖注入： -```dart -final service = TemplateService(); -service.generateFileHeader(description, source); -``` - -### 3. 单一职责原则 - -每个子模块专注于单一职责： -- **NamingConverter**: 仅处理命名转换 -- **TextCleaner**: 仅处理文本清理 -- **TemplateService**: 仅处理模板生成 - -## ✅ 质量保证 - -### 1. 代码分析 -```bash -dart analyze -``` -**结果**: -- ✅ 0 errors -- ✅ 0 warnings -- ℹ️ 62 info（仅为代码风格建议） - -### 2. 测试通过 -```bash -dart test -``` -**结果**: -- ✅ 所有 203 个测试全部通过 -- ✅ 集成测试通过 -- ✅ 性能测试通过 - -### 3. 向后兼容性 -- ✅ 所有现有 API 保持不变 -- ✅ 现有代码无需修改 -- ✅ 导入路径保持一致 - -## 📦 文件结构 - -``` -lib/utils/ -├── string_utils.dart # 统一导出接口（184 行） -└── string_utils/ - ├── naming_converter.dart # 命名转换（187 行） - ├── text_cleaner.dart # 文本清理（86 行） - └── template_service.dart # 模板服务（86 行） -``` - -## 🎉 重构收益 - -1. **可维护性提升**: 代码按职责清晰分离，易于理解和修改 -2. **可测试性提升**: 每个模块可独立测试 -3. **可扩展性提升**: 新增功能只需扩展对应模块 -4. **性能优化**: 配置缓存减少重复读取 -5. **代码复用**: 子模块可独立导入使用 - -## 📝 使用示例 - -```dart -// 方式 1: 使用统一接口（推荐，向后兼容） -import 'package:swagger_generator_flutter/utils/string_utils.dart'; - -final camelCase = StringUtils.toCamelCase('user_name'); -final comment = StringUtils.generateComment('API description'); - -// 方式 2: 直接使用子模块（高级用法） -import 'package:swagger_generator_flutter/utils/string_utils/naming_converter.dart'; -import 'package:swagger_generator_flutter/utils/string_utils/text_cleaner.dart'; - -final className = NamingConverter.generateClassName('user_api'); -final cleaned = TextCleaner.cleanDescription('Some text'); -``` - -## ✨ 总结 - -本次重构成功将 421 行的单一文件拆分为职责清晰的模块化结构，同时保持了完全的向后兼容性。所有测试通过，代码质量显著提升。 - -**check_list.md 状态**: ✅ 已完成并标记为 `[x]` - diff --git a/STRUCTURE_AUDIT.md b/STRUCTURE_AUDIT.md deleted file mode 100644 index c97318e..0000000 --- a/STRUCTURE_AUDIT.md +++ /dev/null @@ -1,132 +0,0 @@ -# 目录结构审计报告（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 deleted file mode 100644 index a6a034c..0000000 --- a/STRUCTURE_MIGRATION_CHECKLIST.md +++ /dev/null @@ -1,85 +0,0 @@ -# 目录结构迁移步骤清单（方案 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 deleted file mode 100644 index a580b56..0000000 --- a/STRUCTURE_PROPOSAL.md +++ /dev/null @@ -1,151 +0,0 @@ -# 目录组织候选方案与推荐方案（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` 全绿 - diff --git a/example/generator_config.yaml b/example/generator_config.yaml index 0c9c861..53b493a 100644 --- a/example/generator_config.yaml +++ b/example/generator_config.yaml @@ -105,6 +105,9 @@ generation: # 方法命名 method_naming: "camelCase" + + # 启用 CancelToken 支持 + cancel_token_support: true # 数据模型配置 models: diff --git a/example/pubspec.lock b/example/pubspec.lock index 247db8e..ebe1687 100644 --- a/example/pubspec.lock +++ b/example/pubspec.lock @@ -558,7 +558,7 @@ packages: path: ".." relative: true source: path - version: "3.1.4" + version: "3.2.1" term_glyph: dependency: transitive description: