468 lines
12 KiB
Markdown
468 lines
12 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)
|
||
|
||
#### RetrofitApiGenerator
|
||
|
||
基于 Retrofit 注解的 API 代码生成器，支持按 tag 拆分与多版本输出。
|
||
|
||
```dart
|
||
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` |
|
||
|
||
**配置选项:**
|
||
|
||
```dart
|
||
class RetrofitApiGenerator {
|
||
final String className; // 生成的类名
|
||
final bool useRetrofit; // 是否使用 Retrofit 注解
|
||
final bool useDio; // 是否使用 Dio
|
||
final bool splitByTags; // 是否按 tag 拆分
|
||
final bool versionedApi; // 是否按版本输出
|
||
}
|
||
```
|
||
|
||
#### 性能生成器（已移除）
|
||
|
||
该项目已简化，移除了 PerformanceGenerator。请使用 RetrofitApiGenerator 作为主要生成器。
|
||
|
||
```dart
|
||
final generator = RetrofitApiGenerator(
|
||
className: 'ApiService',
|
||
useRetrofit: true,
|
||
useDio: true,
|
||
splitByTags: true,
|
||
);
|
||
|
||
final code = generator.generateFromDocument(document);
|
||
```
|
||
|
||
---
|
||
|
||
### ✅ 验证器 (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，请在业务侧按需实现缓存策略（如内存缓存/磁盘缓存），或使用成熟的第三方库。
|
||
---
|
||
|
||
### 🔧 工具类 (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 = 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');
|
||
}
|
||
}
|
||
```
|
||
|
||
### 高级使用流程 (企业级)
|
||
|
||
```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 = 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');
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 错误处理和调试
|
||
|
||
### 常见错误类型
|
||
|
||
```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');
|
||
```
|
||
|
||
---
|
||
|
||
**文档版本**: v3.0
|
||
**最后更新**: 2025-11-21
|
||
**维护者**: Max |