544 lines
14 KiB
Markdown
544 lines
14 KiB
Markdown
# 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 |