# API 参考文档

## 📚 核心 API 类库

### 🔧 解析器 (Parsers)

#### PerformanceParser

高性能 OpenAPI 文档解析器，支持并行处理和性能监控。

```dart
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

// 创建解析器
final parser = PerformanceParser(
  config: ParseConfig(
    enablePerformanceStats: true,   // 启用性能统计
    enableParallelParsing: true,    // 启用并行解析
    enableCaching: true,            // 启用缓存
    maxConcurrency: 4,              // 最大并发数
    enableMemoryOptimization: true, // 内存优化
  ),
);

// 解析文档
final jsonString = await File('swagger.json').readAsString();
final document = await parser.parseDocument(jsonString);

// 获取性能统计
final stats = parser.lastStats;
print('解析时间: ${stats?.totalTime.inMilliseconds}ms');
print('路径数量: ${stats?.pathCount}');
print('吞吐量: ${stats?.bytesPerSecond.toStringAsFixed(2)} bytes/s');
```

**主要方法:**

| 方法 | 描述 | 返回类型 |
|------|------|----------|
| `parseDocument(String jsonString)` | 解析 OpenAPI 文档 | `Future<SwaggerDocument>` |
| `parseDocumentFromFile(String filePath)` | 从文件解析文档 | `Future<SwaggerDocument>` |
| `validateAndParse(String jsonString)` | 验证并解析文档 | `Future<SwaggerDocument>` |

**配置选项:**

```dart
class ParseConfig {
  final bool enablePerformanceStats;    // 启用性能统计
  final bool enableParallelParsing;     // 启用并行解析
  final bool enableStreamParsing;       // 启用流式解析
  final bool enableCaching;             // 启用缓存
  final int maxConcurrency;             // 最大并发数
  final bool enableMemoryOptimization;  // 内存优化
  final Duration cacheTimeout;          // 缓存超时时间
}
```

---

### 🏭 生成器 (Generators)

#### OptimizedRetrofitGenerator

优化的 Retrofit API 代码生成器，专为企业级项目设计。

```dart
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

// 创建生成器
final generator = OptimizedRetrofitGenerator(
  className: 'ApiService',           // API 服务类名
  generateModularApis: true,         // 生成模块化 API
  generateBaseResult: true,          // 生成基础响应类型
  generatePagination: true,          // 生成分页支持
  generateFileUpload: true,          // 生成文件上传支持
  baseResultType: 'BaseResult',      // 基础响应类型名
  pageResultType: 'BasePageResult',  // 分页响应类型名
);

// 生成代码
final generatedCode = generator.generateFromDocument(document);

// 保存到文件
await File('lib/api/api_service.dart').writeAsString(generatedCode);
```

**主要方法:**

| 方法 | 描述 | 返回类型 |
|------|------|----------|
| `generateFromDocument(SwaggerDocument doc)` | 从文档生成代码 | `String` |
| `generateModularApis(SwaggerDocument doc)` | 生成模块化 API | `Map<String, String>` |
| `generateModels(SwaggerDocument doc)` | 生成数据模型 | `Map<String, String>` |
| `generateUtils(SwaggerDocument doc)` | 生成工具类 | `String` |

**配置选项:**

```dart
class OptimizedRetrofitGenerator {
  final String className;              // 生成的类名
  final bool generateModularApis;       // 是否生成模块化 API
  final bool generateBaseResult;        // 是否生成基础响应类型
  final bool generatePagination;        // 是否生成分页支持
  final bool generateFileUpload;        // 是否生成文件上传支持
  final String baseResultType;          // 基础响应类型名
  final String pageResultType;          // 分页响应类型名
  final List<String> excludeTags;       // 排除的标签
  final Map<String, String> typeMapping; // 类型映射
}
```

#### PerformanceGenerator

高性能代码生成器，支持并发生成和增量更新。

```dart
final generator = PerformanceGenerator(
  maxConcurrency: 4,              // 最大并发数
  enableCaching: true,            // 启用缓存
  enableIncremental: true,        // 启用增量生成
  enableParallel: true,           // 启用并行生成
  cacheStrategy: CacheStrategy.smart, // 缓存策略
);

// 并行生成多个文件
final results = await generator.generateParallel(document, [
  GenerationTask.apis,
  GenerationTask.models,
  GenerationTask.utils,
]);
```

---

### ✅ 验证器 (Validators)

#### EnhancedValidator

增强型文档验证器，提供详细的错误报告和修复建议。

```dart
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

// 创建验证器
final validator = EnhancedValidator(
  strictMode: false,              // 严格模式
  includeWarnings: true,          // 包含警告
  enableAutoFix: true,            // 启用自动修复
  customRules: [                  // 自定义验证规则
    RequiredFieldRule(),
    NamingConventionRule(),
  ],
);

// 验证文档
final isValid = validator.validateDocument(document);

// 获取错误报告
final errors = validator.errorReporter.getErrorsBySeverity(ErrorSeverity.error);
final warnings = validator.errorReporter.getErrorsBySeverity(ErrorSeverity.warning);

// 生成详细报告
final report = validator.errorReporter.generateReport();
print(report);
```

**错误级别:**

```dart
enum ErrorSeverity {
  critical,  // 严重错误，阻止生成
  error,     // 错误，可能影响生成质量
  warning,   // 警告，建议修复
  info,      // 信息，仅供参考
}
```

**内置验证规则:**

| 规则 | 描述 | 级别 |
|------|------|------|
| `SchemaValidationRule` | Schema 定义验证 | Error |
| `ReferenceValidationRule` | 引用完整性验证 | Critical |
| `NamingConventionRule` | 命名规范验证 | Warning |
| `TypeConsistencyRule` | 类型一致性验证 | Error |
| `RequiredFieldRule` | 必填字段验证 | Warning |

---

### 🗄️ 缓存管理 (Cache)

#### SmartCache

智能缓存管理器，支持多级缓存和自动清理。

```dart
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

// 创建缓存
final cache = SmartCache<String>(
  maxSize: 1000,                    // 最大缓存大小
  strategy: CacheStrategy.smart,    // 缓存策略
  defaultTtl: Duration(hours: 1),   // 默认过期时间
  enablePersistence: true,          // 启用持久化
);

// 使用缓存
cache.put('key', 'value', ttl: Duration(minutes: 30));
final value = cache.get('key');

// 获取统计信息
final stats = cache.getStats();
print('缓存命中率: ${(stats.hitRate * 100).toStringAsFixed(1)}%');
print('内存使用: ${stats.memoryUsage}');
```

**缓存策略:**

```dart
enum CacheStrategy {
  lru,      // LRU (最近最少使用)
  lfu,      // LFU (最少使用频率)
  fifo,     // FIFO (先进先出)
  smart,    // 智能策略 (结合多种算法)
}
```

---

### 🔧 工具类 (Utils)

#### StringUtils

字符串处理工具类，提供命名转换和格式化功能。

```dart
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

// 命名转换
final camelCase = StringUtils.toCamelCase('user_name');        // userName
final pascalCase = StringUtils.toPascalCase('user_name');      // UserName
final snakeCase = StringUtils.toSnakeCase('userName');         // user_name

// 类型转换
final dartType = StringUtils.openApiTypeToDart('integer');     // int
final nullableType = StringUtils.makeNullable('String');       // String?

// 文档注释生成
final comment = StringUtils.generateDocComment(
  'User login endpoint',
  parameters: ['username', 'password'],
  returns: 'LoginResult',
);
```

#### FileUtils

文件操作工具类，提供安全的文件读写功能。

```dart
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

// 安全写入文件
await FileUtils.writeStringToFile(
  'lib/api/generated_api.dart',
  generatedCode,
  createDirs: true,        // 自动创建目录
  backup: true,           // 创建备份
);

// 批量写入文件
await FileUtils.writeMultipleFiles({
  'lib/api/user_api.dart': userApiCode,
  'lib/api/order_api.dart': orderApiCode,
  'lib/models/user.dart': userModelCode,
});

// 清理生成的文件
await FileUtils.cleanGeneratedFiles('lib/api/generated/');
```

---

### 📊 性能监控 (Performance)

#### PerformanceMonitor

性能监控器，提供详细的性能统计和分析。

```dart
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

// 创建监控器
final monitor = PerformanceMonitor();

// 开始监控
monitor.startOperation('parse_document');
// ... 执行操作
monitor.endOperation('parse_document');

// 获取统计信息
final stats = monitor.getOperationStats('parse_document');
print('操作次数: ${stats.count}');
print('平均耗时: ${stats.averageTime.inMilliseconds}ms');
print('最大耗时: ${stats.maxTime.inMilliseconds}ms');

// 生成性能报告
final report = monitor.generateReport();
print(report);
```

---

## 🔄 完整使用流程

### 基本使用流程

```dart
import 'dart:io';
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

Future<void> generateApiCode() async {
  // 1. 创建解析器
  final parser = PerformanceParser(
    config: ParseConfig(
      enablePerformanceStats: true,
      enableCaching: true,
    ),
  );

  // 2. 创建验证器
  final validator = EnhancedValidator(
    includeWarnings: true,
  );

  // 3. 创建生成器
  final generator = OptimizedRetrofitGenerator(
    className: 'ApiService',
    generateModularApis: true,
    generateBaseResult: true,
  );

  try {
    // 4. 解析文档
    final jsonString = await File('swagger.json').readAsString();
    final document = await parser.parseDocument(jsonString);

    // 5. 验证文档
    final isValid = validator.validateDocument(document);
    if (!isValid) {
      final report = validator.errorReporter.generateReport();
      print('验证失败:\n$report');
      return;
    }

    // 6. 生成代码
    final generatedCode = generator.generateFromDocument(document);

    // 7. 保存文件
    await File('lib/api/api_service.dart').writeAsString(generatedCode);

    print('✅ 代码生成完成!');
    
    // 8. 显示性能统计
    final stats = parser.lastStats;
    if (stats != null) {
      print('解析时间: ${stats.totalTime.inMilliseconds}ms');
      print('生成的路径数: ${stats.pathCount}');
    }
  } catch (e, stackTrace) {
    print('❌ 生成失败: $e');
    print('堆栈跟踪: $stackTrace');
  }
}
```

### 高级使用流程 (企业级)

```dart
Future<void> generateEnterpriseApiCode() async {
  // 1. 配置高性能解析器
  final parser = PerformanceParser(
    config: ParseConfig(
      enablePerformanceStats: true,
      enableParallelParsing: true,
      enableCaching: true,
      maxConcurrency: 8,
      enableMemoryOptimization: true,
    ),
  );

  // 2. 配置增强验证器
  final validator = EnhancedValidator(
    strictMode: true,
    includeWarnings: true,
    enableAutoFix: true,
    customRules: [
      RequiredFieldRule(),
      NamingConventionRule(),
      TypeConsistencyRule(),
    ],
  );

  // 3. 配置性能生成器
  final generator = PerformanceGenerator(
    maxConcurrency: 4,
    enableCaching: true,
    enableIncremental: true,
    enableParallel: true,
  );

  // 4. 配置智能缓存
  final cache = SmartCache<SwaggerDocument>(
    maxSize: 100,
    strategy: CacheStrategy.smart,
    defaultTtl: Duration(hours: 2),
  );

  try {
    // 5. 解析和缓存文档
    final cacheKey = 'swagger_document_v1';
    var document = cache.get(cacheKey);
    
    if (document == null) {
      final jsonString = await File('swagger.json').readAsString();
      document = await parser.parseDocument(jsonString);
      cache.put(cacheKey, document);
    }

    // 6. 验证文档
    final isValid = validator.validateDocument(document);
    if (!isValid) {
      final errors = validator.errorReporter
          .getErrorsBySeverity(ErrorSeverity.critical);
      if (errors.isNotEmpty) {
        throw Exception('文档包含严重错误，无法继续生成');
      }
    }

    // 7. 并行生成多个文件
    final results = await generator.generateParallel(document, [
      GenerationTask.apis,
      GenerationTask.models,
      GenerationTask.utils,
      GenerationTask.documentation,
    ]);

    // 8. 保存生成的文件
    for (final entry in results.entries) {
      final filePath = 'lib/api/generated/${entry.key}.dart';
      await FileUtils.writeStringToFile(
        filePath,
        entry.value,
        createDirs: true,
        backup: true,
      );
    }

    print('✅ 企业级代码生成完成!');
    
    // 9. 生成性能报告
    final performanceReport = parser.generatePerformanceReport();
    await File('reports/performance_report.md')
        .writeAsString(performanceReport);
    
    // 10. 生成验证报告
    final validationReport = validator.errorReporter.generateReport();
    await File('reports/validation_report.md')
        .writeAsString(validationReport);

  } catch (e, stackTrace) {
    print('❌ 企业级生成失败: $e');
    print('堆栈跟踪: $stackTrace');
  }
}
```

---

## 🔍 错误处理和调试

### 常见错误类型

```dart
// 解析错误
try {
  final document = await parser.parseDocument(jsonString);
} on SwaggerParseException catch (e) {
  print('解析错误: ${e.message}');
  print('错误位置: ${e.location}');
  print('修复建议: ${e.suggestion}');
}

// 验证错误
try {
  final isValid = validator.validateDocument(document);
} on ValidationException catch (e) {
  print('验证错误: ${e.message}');
  print('错误字段: ${e.fieldPath}');
  print('期望值: ${e.expectedValue}');
  print('实际值: ${e.actualValue}');
}

// 生成错误
try {
  final code = generator.generateFromDocument(document);
} on CodeGenerationException catch (e) {
  print('生成错误: ${e.message}');
  print('错误类型: ${e.errorType}');
  print('相关对象: ${e.relatedObject}');
}
```

### 调试工具

```dart
// 启用调试模式
final parser = PerformanceParser(
  config: ParseConfig(
    enableDebugMode: true,        // 启用调试模式
    enableVerboseLogging: true,   // 详细日志
    logLevel: LogLevel.debug,     // 日志级别
  ),
);

// 性能分析
final profiler = PerformanceProfiler();
profiler.startProfiling();
// ... 执行操作
final profile = profiler.endProfiling();
print('性能分析: ${profile.summary}');

// 内存分析
final memoryAnalyzer = MemoryAnalyzer();
final usage = memoryAnalyzer.getCurrentUsage();
print('内存使用: ${usage.totalMemory}MB');
print('缓存占用: ${usage.cacheMemory}MB');
```

---

**文档版本**: v2.0  
**最后更新**: 2025-01-24  
**维护者**: Max