221 lines
9.0 KiB
Markdown
221 lines
9.0 KiB
Markdown
# XY Swagger Generator - 项目概览
|
||
|
||
## 📋 项目简介
|
||
|
||
XY Swagger Generator 是一个专为 Flutter 开发优化的 OpenAPI 3.0 代码生成器，旨在自动化 API 接口和数据模型的生成过程，提升开发效率并确保代码质量。
|
||
|
||
### 🎯 设计目标
|
||
|
||
- **标准化优先**: 严格遵循 OpenAPI 3.0 规范，确保与后端 API 文档完全一致
|
||
- **类型安全**: 生成强类型 Dart 代码，在编译时发现潜在问题
|
||
- **高性能**: 支持大型 API 文档的高效解析和代码生成
|
||
- **企业级**: 提供完整的验证、缓存、监控和错误处理机制
|
||
|
||
## 🏗️ 核心架构
|
||
|
||
### 架构层次
|
||
|
||
```
|
||
命令行输入
|
||
↓
|
||
SwaggerCLI / GenerateCommand（编排流程）
|
||
↓
|
||
Pipeline (按职责分层)
|
||
- Parse: SwaggerDataParser (获取与解析)
|
||
- Validate: EnhancedValidator (校验)
|
||
- Generate: ModelCodeGenerator, RetrofitApiGenerator (生成)
|
||
- Render: TemplateRenderer (渲染)
|
||
- Output: GenerationOutputService (落盘)
|
||
↓
|
||
Core (核心模型、配置、异常)
|
||
↓
|
||
Utils (通用工具)
|
||
```
|
||
|
||
|
||
### 模块关系图（简化）
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
CLI[CLI / main] --> GC[GenerateCommand]
|
||
GC --> Pipeline
|
||
|
||
subgraph Pipeline
|
||
direction LR
|
||
Parse[Parse] --> Validate[Validate]
|
||
Validate --> Generate[Generate]
|
||
Generate --> Render[Render]
|
||
Render --> Output[Output]
|
||
end
|
||
|
||
GC --> Core[Core Models, Config, Exceptions]
|
||
Pipeline --> Core
|
||
Pipeline --> Utils
|
||
```
|
||
|
||
## 模块职责与核心类
|
||
|
||
- Commands
|
||
- GenerateCommand: 解析参数、编排流程（解析→验证→生成→落盘）
|
||
- Pipeline
|
||
- Parse: `SwaggerDataParser` (获取与解析)
|
||
- Validate: `EnhancedValidator` (校验)
|
||
- Generate: `ModelCodeGenerator`, `RetrofitApiGenerator` (生成)
|
||
- Render: `TemplateRenderer` (渲染)
|
||
- Output: `GenerationOutputService` (落盘)
|
||
- Core
|
||
- `ConfigRepository`: 主配置入口
|
||
- `models`: 核心数据模型
|
||
- `exceptions`: 自定义异常
|
||
- `error_reporter`: 错误报告
|
||
- Utils
|
||
- `FileUtils`/`PathResolver`: 异步 IO、路径解析
|
||
- `ReferenceResolver`: $ref 解析与去循环
|
||
- `StringUtils`: 统一导出（NamingConverter/TextCleaner/TemplateService）
|
||
- Utils
|
||
- FileUtils/PathResolver: 异步 IO、路径解析
|
||
- ReferenceResolver: $ref 解析与去循环
|
||
- StringUtils: 统一导出（NamingConverter/TextCleaner/TemplateService）
|
||
|
||
## 代码生成流程（详细）
|
||
|
||
1) 读取配置
|
||
- 首选 ConfigRepository.loadSync()/load()，兼容 ConfigLoader
|
||
2) 获取与解析
|
||
- SwaggerFetcher 读取（网络/本地）→ CacheManager 命中 → SwaggerDataParser 解析
|
||
3) 校验
|
||
- SchemaValidator 执行基础校验 → EnhancedValidator 转换为结构化报告（ErrorReporter）
|
||
4) 数据准备
|
||
- 引用解析、模型依赖裁剪、版本/Tag 分组
|
||
5) 代码生成
|
||
- ModelCodeGenerator 产出 models
|
||
- RetrofitApiGenerator 产出 API（TemplateRenderer + 模板）
|
||
6) 文件输出
|
||
- GenerationOutputService/ FileUtils 落盘，按版本/分类组织
|
||
7) 总结输出
|
||
- 生成 SUMMARY.md、日志摘要、耗时统计
|
||
|
||
## 最近重构变更（摘自 check_list）
|
||
|
||
- 核心模型拆分为 models/ 子模块，路径支持 path+method 键，补齐 toJson
|
||
- GenerateCommand 拆出输出服务与调度，职责更清晰
|
||
- RetrofitApiGenerator 切换 Mustache 模板
|
||
- Validator 体系化（ValidationRule/Context），EnhancedValidator 装饰器化
|
||
- 引入 ConfigRepository，PathResolver 复用路径逻辑
|
||
- TypeValidator 规则化，复用 SchemaValidator 结果模型
|
||
- SwaggerFetcher 异步 IO + 内容哈希缓存
|
||
- FileUtils 全异步 API，统一 PathResolver
|
||
- performance_parser 使用 Isolate.run 实现并行
|
||
- error_rules 迁移至 YAML/JSON 配置
|
||
- exceptions 拆分为 exceptions/ 子目录
|
||
- error_reporter 拆分为 data/reporter/renderers，error_reporter.dart 仅作为汇总导出
|
||
- StringUtils 拆分为 naming_converter/text_cleaner/template_service，主文件为统一导出接口
|
||
|
||
### 核心组件
|
||
|
||
#### 1. 命令与配置
|
||
- **SwaggerCLI / GenerateCommand**: 注册命令、展示帮助、执行生成，支持多 Swagger 合并、版本化输出、Tag 过滤和忽略列表
|
||
- **ConfigLoader / SwaggerConfig**: 解析 `generator_config.yaml`，提供 swagger_urls 顺序合并、输出目录、版本提取正则、ApiClient 命名、BaseResult 导入等配置
|
||
|
||
#### 2. Pipeline (核心流程)
|
||
- **Parse**: `SwaggerDataParser` 支持 http(s) 与 file:// 源的 OpenAPI 解析，内置缓存与性能监测。
|
||
- **Validate**: `SchemaValidator` 与 `EnhancedValidator` 用于在生成前验证文档一致性。
|
||
- **Generate**: `ModelCodeGenerator` 和 `RetrofitApiGenerator` 负责生成数据模型和 API 代码。
|
||
- **Render**: `TemplateRenderer` (内部使用) 负责模板渲染。
|
||
- **Output**: `GenerationOutputService` 负责将生成的文件写入磁盘。
|
||
|
||
#### 5. 工具类 (Utils)
|
||
- **CacheManager / PerformanceMonitor**: 缓存解析结果并记录耗时
|
||
- **FileUtils / StringUtils**: 路径解析（基于配置文件目录）、命名转换、文件写入等
|
||
|
||
## 🔧 技术特性
|
||
|
||
### 生成行为
|
||
- 支持按顺序合并多个 `swagger_urls`，后者覆盖前者（适合 v1→v2 升级）
|
||
- 版本化输出：路径按版本分目录，v2+ 类名自动追加 `V2`/`V3` 后缀，统一 ApiClient 聚合各版本
|
||
- Tag 过滤与模型裁剪：`included_tags`/`excluded_tags` 与依赖分析确保只生成实际使用的模型
|
||
- 分页识别：检测 `total/items` 模式并替换为 `BasePageResult<T>`，包装在 `BaseResult`
|
||
- 查询参数实体：GET 查询参数超过 4 个时自动生成 parameters 类，集中导出
|
||
- 忽略列表与相对路径：`ignored_directories/files` 控制落盘，路径基于配置文件所在目录解析
|
||
- BaseResult/BasePageResult 导入可配置，模型导出自动补全统一的 index.dart
|
||
|
||
### 质量保障
|
||
- 模型使用 `@JsonSerializable(checked: true, includeIfNull: false)`，字符串/非空列表默认值自动补齐（响应模型）
|
||
- Request/Response/Enums/Parameters 分类生成，分页模型避免重复定义
|
||
- 生成器提供基本语法校验与类型推断，保持 Dart 命名规范（类名 PascalCase，字段 camelCase）
|
||
- 文档生成器输出接口统计、控制器分组与示例，辅助对齐后端文档
|
||
|
||
### 性能与观测
|
||
- CacheManager 缓存解析结果，避免重复请求 Swagger 源
|
||
- PerformanceMonitor 记录获取/解析耗时，生成流程有摘要 (SUMMARY.md)
|
||
- 文件写入前统一检查跳过策略，目录按需创建，减少无效 IO
|
||
|
||
## 📊 性能与可观测性
|
||
- 解析层通过 PerformanceMonitor 记录获取/解析耗时，并复用 CacheManager 结果避免重复网络请求
|
||
- 多文档合并时会输出模型/路径统计与覆盖提示，便于确认版本覆盖关系
|
||
- 生成结束会输出 SUMMARY.md 与控制台摘要，包含控制器、路径、模型数量
|
||
- 文件写入前的跳过策略减少无意义的 IO，提升重复生成时的稳定性
|
||
|
||
## 🎯 应用场景
|
||
|
||
### 适用项目类型
|
||
- **企业级 Flutter 应用**: 大量 API 接口，需要标准化管理
|
||
- **多人协作项目**: 需要统一的代码风格和开发规范
|
||
- **快速迭代项目**: API 变更频繁，需要快速同步
|
||
- **微服务架构**: 多个服务的 API 需要统一管理
|
||
|
||
### 团队规模
|
||
- **小型团队** (2-5人): 提升开发效率，减少重复工作
|
||
- **中型团队** (5-20人): 统一开发标准，提升协作效率
|
||
- **大型团队** (20+人): 企业级管理，确保代码质量和一致性
|
||
|
||
## 🚀 核心优势
|
||
|
||
### 1. 开发效率提升
|
||
- **自动化程度**: 95% 的 API 代码自动生成
|
||
- **开发时间节省**: 减少 70%+ 的 API 相关开发时间
|
||
- **错误率降低**: 类型相关错误减少 90%+
|
||
|
||
### 2. 代码质量保证
|
||
- **类型安全**: 编译时类型检查，避免运行时错误
|
||
- **标准一致**: 统一的代码风格和命名规范
|
||
- **文档同步**: API 文档与代码自动保持同步
|
||
|
||
### 3. 维护成本降低
|
||
- **变更响应**: API 变更响应时间从小时级降到分钟级
|
||
- **技术债务**: 标准化代码结构，易于维护和扩展
|
||
- **团队协作**: 统一的开发流程和代码规范
|
||
|
||
## 📈 发展路线
|
||
|
||
### 当前版本 (v2.1.x)
|
||
- ✅ dev dependency 场景的 CLI 入口与可执行别名
|
||
- ✅ 多 Swagger 顺序合并与版本化 API 输出
|
||
- ✅ Tag 过滤、忽略策略、BaseResult/BasePageResult 导入配置
|
||
- ✅ 示例项目与基础测试脚本（tests/）
|
||
|
||
### 后续计划
|
||
- 🔄 提升自动化测试覆盖与生成结果校验
|
||
- 🔄 完善配置校验与错误提示体验
|
||
- 🔄 持续同步 README/示例与最新生成逻辑
|
||
|
||
## 🤝 社区与支持
|
||
|
||
### 文档资源
|
||
- [项目主文档](../README.md)
|
||
- [使用指南](./USAGE_GUIDE.md)
|
||
- [API 参考文档](./API_REFERENCE.md)
|
||
- [快速参考](../QUICK_REFERENCE.md)
|
||
- [配置模板](../generator_config.template.yaml)
|
||
|
||
### 贡献方式
|
||
- 提交功能前运行 `dart run swagger_generator_flutter generate --all` 以及必要的 `build_runner`
|
||
- 在 Issue/PR 中附上配置片段与最小示例（可参考 example/）
|
||
- 变更生成规则时同步更新 README 与 docs/
|
||
|
||
---
|
||
|
||
**项目维护者**: Max
|
||
**最后更新**: 2025-11-09
|
||
**文档版本**: v2.1
|