chore: 清理过期文档
删除已完成的提案、实现总结和审计报告: - 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)
This commit is contained in:
parent
52a242f392
commit
f08e478669
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
|
||||
|
|
@ -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<String, Map<dynamic, EnumKeyMapping>>? get enumKeyMappings {
|
||||
// 从配置文件解析枚举映射
|
||||
// 返回格式: { "EnumName": { value: EnumKeyMapping } }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. `lib/core/config.dart`
|
||||
|
||||
暴露枚举映射配置：
|
||||
|
||||
```dart
|
||||
class SwaggerConfig {
|
||||
/// 获取枚举键名映射配置（从配置文件读取）
|
||||
static Map<String, Map<dynamic, EnumKeyMapping>>? 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
|
||||
**状态**: ✅ 已完成
|
||||
|
||||
|
|
@ -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<String>? enumVarNames; // 新增
|
||||
final List<String>? enumDescriptions; // 新增
|
||||
|
||||
factory ApiModel.fromJson(...) {
|
||||
// 解析 x-enum-varnames
|
||||
final enumVarNames = json['x-enum-varnames'] as List<dynamic>?;
|
||||
final enumDescriptions = json['x-enum-descriptions'] as List<dynamic>?;
|
||||
|
||||
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<String, Map<dynamic, EnumKeyMapping>>? 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
|
||||
|
||||
|
|
@ -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 字符行长度限制，
|
||||
同时保持了代码的可读性和功能完整性。
|
||||
|
||||
|
|
@ -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<T>`
|
||||
- ✅ **多 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<T>`
|
||||
- 符合项目规范
|
||||
|
||||
**影响**: 所有分页 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<BaseResult<BasePageResult<SuperiorTaskListResult>>> // ✅ 正确类型
|
||||
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
|
||||
|
||||
|
|
@ -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 <html> text');
|
||||
```
|
||||
|
||||
## ✨ 总结
|
||||
|
||||
本次重构成功将 421 行的单一文件拆分为职责清晰的模块化结构，同时保持了完全的向后兼容性。所有测试通过，代码质量显著提升。
|
||||
|
||||
**check_list.md 状态**: ✅ 已完成并标记为 `[x]`
|
||||
|
||||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
@ -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 <commit>` 回滚到上一步
|
||||
- 保留分支 feature/structure-governance 直到发布后稳定一周
|
||||
|
||||
|
|
@ -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` 全绿
|
||||
|
||||
|
|
@ -105,6 +105,9 @@ generation:
|
|||
|
||||
# 方法命名
|
||||
method_naming: "camelCase"
|
||||
|
||||
# 启用 CancelToken 支持
|
||||
cancel_token_support: true
|
||||
|
||||
# 数据模型配置
|
||||
models:
|
||||
|
|
|
|||
|
|
@ -558,7 +558,7 @@ packages:
|
|||
path: ".."
|
||||
relative: true
|
||||
source: path
|
||||
version: "3.1.4"
|
||||
version: "3.2.1"
|
||||
term_glyph:
|
||||
dependency: transitive
|
||||
description:
|
||||
|
|
|
|||
Loading…
Reference in New Issue