feat(structure): 完成方案C重构，引入pipeline架构

- 物理迁移：所有核心模块（parse, validate, generate, render, output）已按 pipeline 结构重组。 - 统一入口：创建 lib/index.dart 作为唯一的公共 API 入口。 - 导入路径切换：commands 模块已更新为新的导入风格。 - 文档更新：PROJECT_OVERVIEW.md 已同步更新架构图和模块说明。质量门禁： - dart analyze: 0 error / 0 warning (info only) - dart test: all pass
2025-11-22 22:22:51 +08:00 · 2025-11-22 22:22:51 +08:00 · 481db5bf8f
parent 7627236650
commit 481db5bf8f
3 changed files with 77 additions and 55 deletions
--- a/docs/PROJECT_OVERVIEW.md
+++ b/docs/PROJECT_OVERVIEW.md
@ -18,19 +18,18 @@ XY Swagger Generator 是一个专为 Flutter 开发优化的 OpenAPI 3.0 代码
 ```
 命令行输入
   ↓
-SwaggerCLI / GenerateCommand（合并多 Swagger、处理版本与 Tag 过滤）
+SwaggerCLI / GenerateCommand（编排流程）
   ↓
-配置层（ConfigRepository 为主，SwaggerConfig 静态访问保持兼容）
+Pipeline (按职责分层)
+  - Parse: SwaggerDataParser (获取与解析)
+  - Validate: EnhancedValidator (校验)
+  - Generate: ModelCodeGenerator, RetrofitApiGenerator (生成)
+  - Render: TemplateRenderer (渲染)
+  - Output: GenerationOutputService (落盘)
   ↓
-获取与解析（SwaggerFetcher / SwaggerDataParser，带缓存与性能监控）
+Core (核心模型、配置、异常)
   ↓
-验证层（SchemaValidator 基础规则 → EnhancedValidator 装饰增强 + ErrorReporter 渲染）
-   ↓
-生成器层（ModelCodeGenerator / RetrofitApiGenerator + TemplateRenderer/TemplateService）
-   ↓
-工具层（FileUtils / PathResolver / ReferenceResolver / StringUtils 模块化）
-   ↓
-落盘输出（按版本与模型类别组织）
+Utils (通用工具)
 ```


@ -39,48 +38,40 @@ SwaggerCLI / GenerateCommand（合并多 Swagger、处理版本与 Tag 过滤）
 ```mermaid
 flowchart TD
  CLI[CLI / main] --> GC[GenerateCommand]
-  GC --> CFG[ConfigRepository]
-  GC --> PF[SwaggerFetcher]
-  PF --> SDP[SwaggerDataParser]
-  SDP --> VAL[SchemaValidator]
-  VAL -->|decorated by| EV[EnhancedValidator]
-  SDP --> MODELS[Core Models]
-  EV --> ER[ErrorReporter]
-  GC --> GEN[Generators]
-  GEN --> MC[ModelCodeGenerator]
-  GEN --> RG[RetrofitApiGenerator]
-  RG --> TR[TemplateRenderer]
-  TR --> TS[TemplateService]
-  GC --> OUT[File Output / Writer]
-  subgraph Utils
-    FU[FileUtils]
-    PR[PathResolver]
-    RR[ReferenceResolver]
-    SU[StringUtils]
+  GC --> Pipeline
+
+  subgraph Pipeline
+    direction LR
+    Parse[Parse] --> Validate[Validate]
+    Validate --> Generate[Generate]
+    Generate --> Render[Render]
+    Render --> Output[Output]
  end
-  GEN -.-> Utils
-  SDP -.-> Utils
-  GC -.-> Utils
+
+  GC --> Core[Core Models, Config, Exceptions]
+  Pipeline --> Core
+  Pipeline --> Utils
 ```

 ## 模块职责与核心类

 - Commands
  - GenerateCommand: 解析参数、编排流程（解析→验证→生成→落盘）
- Config
-  - ConfigRepository: 主配置入口，提供只读配置访问和缓存
-  - ConfigLoader: 向后兼容的静态加载器（保留，推荐迁移到 ConfigRepository）
- Parsers
-  - SwaggerFetcher: 统一 http/file 源获取、缓存与错误处理
-  - SwaggerDataParser: OpenAPI 3.0 解析为内部模型
- Validators
-  - SchemaValidator: 基础规则验证器（必留）
-  - EnhancedValidator: 装饰器，复用 SchemaValidator 结果并通过 ErrorReporter 渲染
-  - ErrorReporter: 可插拔渲染（文本/JSON/CI）
- Generators
-  - ModelCodeGenerator: 生成模型（Freezed/json_serializable）
-  - RetrofitApiGenerator: 生成 API（Mustache 模板、按 tag 拆分、版本化）
-  - TemplateRenderer/TemplateService: 模板加载与注释/文件头生成
+- 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 解析与去循环
--- a/lib/commands/generate_command.dart
+++ b/lib/commands/generate_command.dart
@ -1,10 +1,7 @@
 import 'package:swagger_generator_flutter/commands/base_command.dart';
 import 'package:swagger_generator_flutter/commands/services/document_filter_service.dart';
 import 'package:swagger_generator_flutter/commands/services/document_merge_service.dart';
-import 'package:swagger_generator_flutter/commands/services/generation_output_service.dart';
-import 'package:swagger_generator_flutter/core/config.dart';
-import 'package:swagger_generator_flutter/core/config_repository.dart';
-import 'package:swagger_generator_flutter/utils/logger.dart';
+import 'package:swagger_generator_flutter/index.dart';

 /// Generate命令
 /// 用于生成各种代码文件
@ -81,9 +78,10 @@ class GenerateCommand extends BaseCommand {
      validateArguments(parsedArgs);

      await prepare(parsedArgs);
+      final config = ConfigRepository.loadSync();

-      progress('正在解析 ${SwaggerConfig.swaggerJsonUrls.length} 个 Swagger 文档...');
-      final urls = SwaggerConfig.swaggerJsonUrls;
+      progress('正在解析 ${config.swaggerUrls.length} 个 Swagger 文档...');
+      final urls = config.swaggerUrls;
      progress('URL 处理顺序: ${urls.join(" -> ")}');

      final mergedDocument = await _documentMergeService.fetchAndMerge(
@ -96,7 +94,7 @@ class GenerateCommand extends BaseCommand {
        return 1;
      }

-      success('成功合并 ${SwaggerConfig.swaggerJsonUrls.length} 个 Swagger 文档');
+      success('成功合并 ${config.swaggerUrls.length} 个 Swagger 文档');

      final options = _parseGenerateOptions(parsedArgs);

@ -108,9 +106,9 @@ class GenerateCommand extends BaseCommand {
      );

      // 使用配置的输出目录
-      final baseDir = SwaggerConfig.generatorDir;
-      final apiDir = SwaggerConfig.apiDir;
-      final modelsDir = SwaggerConfig.modelsDir;
+      final baseDir = config.baseDir;
+      final apiDir = config.apiDir;
+      final modelsDir = config.modelsDir;

      progress('输出目录: $baseDir');
      progress('API 目录: $apiDir');
--- a/lib/index.dart
+++ b/lib/index.dart
@ -0,0 +1,33 @@
+/// # Swagger Generator Flutter
+///
+/// A powerful Flutter OpenAPI 3.0 code generator, optimized for the Dio + Retrofit stack.
+///
+/// ## Core Components
+///
+/// - **Config**: `ConfigRepository` for loading and accessing configuration.
+/// - **Parse**: `SwaggerDataParser` to fetch and parse OpenAPI documents.
+/// - **Validate**: `EnhancedValidator` to validate documents against OpenAPI specs and best practices.
+/// - **Generate**: `ModelCodeGenerator` and `RetrofitApiGenerator` for creating Dart code.
+/// - **Render**: `TemplateRenderer` for Mustache-based template rendering.
+/// - **Output**: `GenerationOutputService` to write generated files to disk.
+
+library swagger_generator_flutter;
+
+// --- Core Public API ---
+export 'core/config_repository.dart';
+export 'core/error_reporter.dart';
+export 'core/models.dart';
+
+// --- Pipeline API (New Structure) ---
+export 'pipeline/parse/swagger_data_parser.dart';
+export 'pipeline/validate/enhanced_validator.dart';
+export 'pipeline/generate/model_code_generator.dart';
+export 'pipeline/generate/retrofit_api_generator.dart';
+export 'pipeline/render/template_renderer.dart';
+export 'pipeline/output/generation_output_service.dart';
+
+// --- Utilities ---
+export 'utils/logger.dart';
+export 'utils/path_resolver.dart';
+export 'utils/string_utils.dart';
+