wangyang

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

RetrofitApiGenerator

基于 Retrofit 注解的 API 代码生成器，支持按 tag 拆分与多版本输出。

import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

// 创建生成器
final generator = RetrofitApiGenerator(
  className: 'ApiService',           // API 服务类名
  useRetrofit: true,                  // 使用 Retrofit 注解
  useDio: true,                       // 使用 Dio
  splitByTags: true,                  // 按 tag 拆分
  versionedApi: true,                 // 多版本输出
);

// 生成代码
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 RetrofitApiGenerator {
  final String className;    // 生成的类名
  final bool useRetrofit;    // 是否使用 Retrofit 注解
  final bool useDio;         // 是否使用 Dio
  final bool splitByTags;    // 是否按 tag 拆分
  final bool versionedApi;   // 是否按版本输出
}

性能生成器（已移除）

该项目已简化，移除了 PerformanceGenerator。请使用 RetrofitApiGenerator 作为主要生成器。

final generator = RetrofitApiGenerator(
  className: 'ApiService',
  useRetrofit: true,
  useDio: true,
  splitByTags: true,
);

final code = generator.generateFromDocument(document);

✅ 验证器 (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，请在业务侧按需实现缓存策略（如内存缓存/磁盘缓存），或使用成熟的第三方库。

🔧 工具类 (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 = RetrofitApiGenerator(
    className: 'ApiService',
    splitByTags: 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 = RetrofitApiGenerator(
    className: 'ApiService',
    splitByTags: 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 errors = validator.errorReporter
          .getErrorsBySeverity(ErrorSeverity.critical);
      if (errors.isNotEmpty) {
        throw Exception('文档包含严重错误，无法继续生成');
      }
    }

    // 6. 生成代码（单文件或模块化）
    final code = generator.generateFromDocument(document);

    // 7. 保存生成的文件
    await File('lib/api/api_service.dart').writeAsString(code);

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

文档版本: v3.0 最后更新: 2025-11-21 维护者: Max

12 KiB Raw Blame History Unescape Escape