# 使用指南与最佳实践

## 🚀 快速开始

### 环境准备

1. **确保 Dart/Flutter 环境**
```bash
dart --version  # 确保 Dart >= 3.0
flutter --version  # 确保 Flutter >= 3.0
```

2. **安装项目依赖**
```bash
cd your_flutter_project
flutter pub get
```

3. **准备 OpenAPI 文档**
- 确保有有效的 `swagger.json` 或 `openapi.json` 文件
- 建议使用 OpenAPI 3.0 格式

### 基础使用

在项目根目录下（`generator_config.yaml` 所在目录）运行以下命令：

```bash
# 步骤 1: 生成 API 定义和 Freezed 模型
# 这会根据 swagger.json 生成 *.dart 文件，但它们还不完整
dart run swagger_generator_flutter generate --all

# 步骤 2: 运行 build_runner 完成代码生成
# 这会生成 *.freezed.dart 和 *.g.dart 文件，补全模型和序列化逻辑
dart run build_runner build --delete-conflicting-outputs
```

#### 编程方式 (推荐进阶用户)

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

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

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

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

  // 4. 生成并保存代码
  final code = generator.generateFromDocument(document);
  await File('lib/api/api_service.dart').writeAsString(code);
  
  print('✅ 代码生成完成!');
}
```

---

## 🏗️ 项目集成

### 1. 依赖配置

在你的 Flutter 项目的 `pubspec.yaml` 中添加必要依赖：

```yaml
dependencies:
  # 网络请求
  dio: ^5.4.0
  retrofit: ^4.0.0

  # Freezed 模型
  freezed_annotation: ^2.4.1
  json_annotation: ^4.8.1

dev_dependencies:
  # 代码生成
  build_runner: ^2.4.7
  retrofit_generator: ^8.0.0
  json_serializable: ^6.7.1
  freezed: ^2.4.7
```

### 2. 项目结构

推荐的项目结构：

```
your_flutter_project/
├── lib/
│   ├── api/
│   │   ├── generated/          # 生成的 API 文件
│   │   │   ├── api_service.dart
│   │   │   ├── user_api.dart
│   │   │   └── order_api.dart
│   │   ├── models/             # 生成的模型文件
│   │   │   ├── user.dart
│   │   │   ├── order.dart
│   │   │   └── index.dart
│   │   ├── config/             # API 配置
│   │   │   ├── api_config.dart
│   │   │   └── dio_config.dart
│   │   └── interceptors/       # 拦截器
│   │       ├── auth_interceptor.dart
│   │       └── error_interceptor.dart
│   ├── services/               # 业务服务层
│   └── ...
├── swagger.json                # OpenAPI 文档
└── generator_config.yaml       # 生成器配置
```

### 3. 配置文件

创建 `generator_config.yaml`：

```yaml
# 生成器配置
generator:
  className: "ApiService"
  outputDir: "lib/api/generated"
  generateModularApis: true
  generateBaseResult: true
  generatePagination: true
  generateFileUpload: true
  
# 类型映射
typeMapping:
  "integer": "int"
  "number": "double"
  "boolean": "bool"
  
# 排除的标签
excludeTags:
  - "Internal"
  - "Debug"
  
# 自定义模板
templates:
  baseResultType: "ApiResult"
  pageResultType: "PagedResult"
```

---

## 📝 最佳实践

### 1. OpenAPI 文档规范

#### ✅ 推荐的文档结构

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Your API",
    "version": "v1",
    "description": "API description"
  },
  "servers": [
    {
      "url": "https://api.yourdomain.com",
      "description": "Production server"
    }
  ],
  "components": {
    "schemas": {
      "BaseResult": {
        "type": "object",
        "properties": {
          "success": {"type": "boolean"},
          "message": {"type": "string"},
          "data": {"type": "object"}
        }
      },
      "User": {
        "type": "object",
        "required": ["id", "username"],
        "properties": {
          "id": {"type": "integer"},
          "username": {"type": "string"},
          "email": {"type": "string", "nullable": true}
        }
      }
    }
  }
}
```

#### ❌ 避免的常见问题

```json
// 不要：缺少 schema 定义
{
  "responses": {
    "200": {
      "description": "Success"
      // 缺少 content 和 schema
    }
  }
}

// 不要：模糊的类型定义
{
  "properties": {
    "data": {"type": "object"}  // 应该明确定义结构
  }
}

// 不要：不一致的命名
{
  "paths": {
    "/getUsers": {},      // 应该用 RESTful 风格
    "/user/create": {}    // 应该是 POST /users
  }
}
```

### 2. 代码生成最佳实践

#### 配置合适的解析器

```dart
// 开发环境 - 详细统计
final parser = PerformanceParser(
  config: ParseConfig(
    enablePerformanceStats: true,
    enableDebugMode: true,
    logLevel: LogLevel.debug,
  ),
);

// 生产环境 - 高性能
final parser = PerformanceParser(
  config: ParseConfig(
    enableParallelParsing: true,
    enableCaching: true,
    maxConcurrency: 4,
    enableMemoryOptimization: true,
  ),
);
```

### 3. 错误处理策略

#### 分层错误处理

```dart
class ApiService {
  final Dio _dio;
  
  ApiService(this._dio) {
    _setupInterceptors();
  }
  
  void _setupInterceptors() {
    // 请求拦截器
    _dio.interceptors.add(InterceptorsWrapper(
      onRequest: (options, handler) {
        // 添加认证头
        options.headers['Authorization'] = 'Bearer $token';
        handler.next(options);
      },
      onError: (error, handler) {
        // 统一错误处理
        final apiError = _handleError(error);
        handler.reject(DioException(
          requestOptions: error.requestOptions,
          error: apiError,
        ));
      },
    ));
  }
  
  ApiError _handleError(DioException error) {
    switch (error.response?.statusCode) {
      case 401:
        return ApiError.unauthorized();
      case 403:
        return ApiError.forbidden();
      case 404:
        return ApiError.notFound();
      case 500:
        return ApiError.serverError();
      default:
        return ApiError.unknown(error.message);
    }
  }
}
```

#### 业务层错误处理

```dart
class UserService {
  final UserApi _userApi;
  
  UserService(this._userApi);
  
  Future<Result<User>> getUser(int userId) async {
    try {
      final response = await _userApi.getUser(userId);
      if (response.success) {
        return Result.success(response.data!);
      } else {
        return Result.failure(response.message ?? 'Unknown error');
      }
    } on ApiError catch (e) {
      return Result.failure(e.message);
    } catch (e) {
      return Result.failure('Network error: $e');
    }
  }
}
```

### 4. 性能优化

#### 缓存策略

```dart
// 配置智能缓存
final cache = SmartCache<String>(
  maxSize: 1000,
  strategy: CacheStrategy.smart,
  defaultTtl: Duration(minutes: 30),
);

// 使用缓存包装 API 调用
class CachedApiService {
  final ApiService _apiService;
  final SmartCache<String> _cache;
  
  Future<BaseResult<User>> getUser(int userId) async {
    final cacheKey = 'user_$userId';
    
    // 尝试从缓存获取
    final cached = _cache.get(cacheKey);
    if (cached != null) {
      return BaseResult.fromJson(jsonDecode(cached));
    }
    
    // 从 API 获取
    final result = await _apiService.getUser(userId);
    
    // 缓存结果
    if (result.success) {
      _cache.put(cacheKey, jsonEncode(result.toJson()));
    }
    
    return result;
  }
}
```

#### 并发控制

```dart
class ApiService {
  final Semaphore _semaphore = Semaphore(3); // 限制并发数
  
  Future<T> _executeWithLimit<T>(Future<T> Function() operation) async {
    await _semaphore.acquire();
    try {
      return await operation();
    } finally {
      _semaphore.release();
    }
  }
  
  Future<List<User>> getUsers(List<int> userIds) async {
    final futures = userIds.map((id) => 
      _executeWithLimit(() => getUser(id))
    );
    
    return Future.wait(futures);
  }
}
```

---

## 🔧 高级配置

### 1. 自定义生成器

```dart
class CustomRetrofitGenerator extends BaseGenerator {
  @override
  String generate() {
    final buffer = StringBuffer();
    
    // 自定义文件头
    buffer.writeln('// Custom Generated API');
    buffer.writeln('// Generated at: ${DateTime.now()}');
    
    // 自定义导入
    buffer.writeln("import 'package:dio/dio.dart';");
    buffer.writeln("import 'package:retrofit/retrofit.dart';");
    
    // 生成自定义代码
    _generateCustomMethods(buffer);
    
    return buffer.toString();
  }
  
  void _generateCustomMethods(StringBuffer buffer) {
    // 实现自定义生成逻辑
  }
}
```

### 2. 自定义验证规则

```dart
class CustomValidationRule extends ValidationRule {
  @override
  String get name => 'CustomRule';
  
  @override
  List<ValidationError> validate(SwaggerDocument document) {
    final errors = <ValidationError>[];
    
    // 检查所有 API 是否有描述
    for (final path in document.paths.values) {
      for (final operation in path.operations.values) {
        if (operation.summary?.isEmpty ?? true) {
          errors.add(ValidationError(
            severity: ErrorSeverity.warning,
            title: 'Missing API description',
            description: 'API ${operation.operationId} lacks description',
            location: operation.operationId,
          ));
        }
      }
    }
    
    return errors;
  }
}
```

### 3. 自定义模板

创建自定义模板文件 `templates/custom_api.mustache`：

```mustache
/// {{title}} API
/// Generated by Custom Generator
class {{className}} {
  final Dio _dio;
  
  {{className}}(this._dio);
  
  {{#operations}}
  /// {{summary}}
  @{{httpMethod}}('{{path}}')
  Future<{{returnType}}> {{methodName}}(
    {{#parameters}}
    @{{paramType}}('{{name}}') {{type}} {{name}},
    {{/parameters}}
  );
  {{/operations}}
}
```

使用自定义模板：

```dart
// 使用自定义生成器时，请继承 BaseGenerator 并实现 generate()
// 或基于 RetrofitApiGenerator 的输出进行二次处理。
```

---

## 🐛 故障排除

### 常见问题及解决方案

#### 1. 解析失败

**问题**: `SwaggerParseException: Invalid JSON format`

**解决方案**:
```bash
# 验证 JSON 格式
jsonlint swagger.json

# 或使用在线工具验证
# https://jsonlint.com/
```

**问题**: `Reference not found: #/components/schemas/User`

**解决方案**:
```dart
// 检查引用是否存在
final validator = EnhancedValidator();
final isValid = validator.validateDocument(document);
final errors = validator.errorReporter.getErrorsBySeverity(ErrorSeverity.error);

for (final error in errors) {
  if (error.title.contains('Reference')) {
    print('缺少引用: ${error.description}');
  }
}
```

#### 2. 生成错误

**问题**: 生成的代码包含语法错误

**解决方案**:
```dart
// 启用严格验证
final validator = EnhancedValidator(
  strictMode: true,
  customRules: [
    TypeConsistencyRule(),
    NamingConventionRule(),
  ],
);

// 检查生成前的文档质量
if (!validator.validateDocument(document)) {
  final report = validator.errorReporter.generateReport();
  print('文档质量问题:\n$report');
  return;
}
```

**问题**: 生成的类型不存在

**解决方案**:
```dart
// 检查 Schema 定义
final schemas = document.components?.schemas ?? {};
if (!schemas.containsKey('YourType')) {
  print('错误: Schema YourType 不存在');
  print('可用 Schemas: ${schemas.keys.join(', ')}');
}
```

#### 3. 性能问题

**问题**: 解析大文档时内存不足

**解决方案**:
```dart
// 启用内存优化
final parser = PerformanceParser(
  config: ParseConfig(
    enableMemoryOptimization: true,
    enableStreamParsing: true,
    maxConcurrency: 2, // 降低并发数
  ),
);
```

**问题**: 生成速度慢

**解决方案**:
```dart
// 在 CI 中按模块并行执行多个 RetrofitApiGenerator 任务
final generator = RetrofitApiGenerator(
  className: 'ApiService',
  splitByTags: true,
);
```

### 调试技巧

#### 1. 启用详细日志

```dart
// 配置日志级别
import 'package:logging/logging.dart';

void setupLogging() {
  Logger.root.level = Level.ALL;
  Logger.root.onRecord.listen((record) {
    print('${record.level.name}: ${record.time}: ${record.message}');
  });
}

// 在解析器中使用
final parser = PerformanceParser(
  config: ParseConfig(
    enableVerboseLogging: true,
    logLevel: LogLevel.debug,
  ),
);
```

#### 2. 性能分析

```dart
// 使用性能监控器
final monitor = PerformanceMonitor();

monitor.startOperation('full_generation');

// 解析阶段
monitor.startOperation('parse');
final document = await parser.parseDocument(jsonString);
monitor.endOperation('parse');

// 验证阶段
monitor.startOperation('validate');
final isValid = validator.validateDocument(document);
monitor.endOperation('validate');

// 生成阶段
monitor.startOperation('generate');
final code = generator.generateFromDocument(document);
monitor.endOperation('generate');

monitor.endOperation('full_generation');

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

#### 3. 内存分析

```dart
// 监控内存使用
import 'dart:developer';

void trackMemoryUsage(String operation) {
  final info = ProcessInfo.currentRss;
  print('$operation - Memory: ${info / 1024 / 1024:.2f}MB');
}

trackMemoryUsage('Before parsing');
final document = await parser.parseDocument(jsonString);
trackMemoryUsage('After parsing');

final code = generator.generateFromDocument(document);
trackMemoryUsage('After generation');
```

---

## 📚 示例项目

### 完整示例项目结构

```
example_project/
├── lib/
│   ├── main.dart
│   ├── api/
│   │   ├── generated/
│   │   │   ├── api_service.dart
│   │   │   ├── user_api.dart
│   │   │   └── order_api.dart
│   │   ├── models/
│   │   │   ├── user.dart
│   │   │   ├── order.dart
│   │   │   └── index.dart
│   │   ├── config/
│   │   │   └── api_config.dart
│   │   └── services/
│   │       ├── user_service.dart
│   │       └── order_service.dart
│   ├── ui/
│   │   ├── pages/
│   │   └── widgets/
│   └── utils/
├── swagger.json
├── generator_config.yaml
└── generate_api.dart
```

### 生成脚本示例

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

Future<void> main() async {
  print('🚀 开始生成 API 代码...');
  
  try {
    // 1. 配置和初始化
    final config = await _loadConfig();
    final parser = _createParser(config);
    final validator = _createValidator(config);
    final generator = _createGenerator(config);
    
    // 2. 解析文档
    print('📖 解析 OpenAPI 文档...');
    final document = await _parseDocument(parser, config.swaggerPath);
    
    // 3. 验证文档
    print('✅ 验证文档...');
    await _validateDocument(validator, document);
    
    // 4. 生成代码
    print('🔧 生成代码...');
    await _generateCode(generator, document, config);
    
    // 5. 后处理
    print('🎯 后处理...');
    await _postProcess(config);
    
    print('✅ API 代码生成完成！');
    
  } catch (e, stackTrace) {
    print('❌ 生成失败: $e');
    print('堆栈跟踪: $stackTrace');
    exit(1);
  }
}

// 实现各个辅助方法...
```

---

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