wangyang

14 KiB

Raw Blame History

API 参考文档

📚 核心 API 类库

🔧 解析器 (Parsers)

PerformanceParser

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

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>`

配置选项:

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 代码生成器，专为企业级项目设计。

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`

配置选项:

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

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

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

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

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);

错误级别:

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

内置验证规则:

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

🗄️ 缓存管理 (Cache)

SmartCache

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

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}');

缓存策略:

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

🔧 工具类 (Utils)

StringUtils

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

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

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

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

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

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);

🔄 完整使用流程

基本使用流程

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');
  }
}

高级使用流程 (企业级)

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');
  }
}

🔍 错误处理和调试

常见错误类型

// 解析错误
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}');
}

调试工具

// 启用调试模式
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

14 KiB Raw Blame History