# Augment 代码生成快速参考

## 🚀 **快速开始**

### **生成 API 代码**
```bash
# 生成所有代码
dart run bin/main.dart generate --api --models --split-by-tags

# 只生成 API 接口
dart run bin/main.dart generate --api --split-by-tags

# 只生成数据模型
dart run bin/main.dart generate --models
```

### **项目集成**
```yaml
# pubspec.yaml
dependencies:
  dio: ^5.0.0
  retrofit: ^4.0.0
  json_annotation: ^4.8.0

dev_dependencies:
  build_runner: ^2.3.0
  retrofit_generator: ^8.0.0
  json_serializable: ^6.6.0
```

```bash
# 运行代码生成
dart pub get
dart pub run build_runner build
```

---

## 📋 **常见问题解决**

### **Q: 生成的类型不存在怎么办？**
```dart
// ❌ 错误：生成了不存在的类型
Future<BaseResult<TaskInfoResult>> someMethod();

// ✅ 解决：检查 swagger.json 中是否定义了 TaskInfoResult
// 如果没有定义，联系后端添加 schema 定义
// 或者使用通用类型：
Future<BaseResult<Map<String, dynamic>>> someMethod();
```

### **Q: 接口缺少参数怎么办？**
```dart
// ❌ 错误：swagger 中没有定义参数，但生成器添加了
@POST('/api/v1/SomeAction')
Future<BaseResult<void>> someAction(
  @Body() Map<String, dynamic> request  // 不应该存在
);

// ✅ 解决：检查 swagger.json 中的参数定义
// 如果确实需要参数，联系后端在 swagger 中添加定义
```

### **Q: 可空性不正确怎么办？**
```dart
// ❌ 错误：字段应该可空但生成为非空
final String name;  // 但实际可能为 null

// ✅ 解决：检查 swagger.json 中的 nullable 字段
{
  "name": {
    "type": "string",
    "nullable": true  // 添加这个字段
  }
}
```

### **Q: 分页接口没有使用 BasePageResult？**
```dart
// ❌ 错误：分页接口使用了错误的返回类型
Future<BaseResult<List<UserResult>>> getUserList();

// ✅ 解决：检查接口是否真的是分页接口
// 确保 swagger 中定义了分页相关的查询参数和响应结构
Future<BasePageResult<UserResult>> getUserList();
```

---

## 🔧 **调试技巧**

### **1. 检查 swagger.json**
```bash
# 验证 swagger.json 格式
curl -X POST "https://validator.swagger.io/validator/debug" \
  -H "Content-Type: application/json" \
  -d @swagger.json
```

### **2. 查看生成日志**
```bash
# 启用详细日志
dart run bin/main.dart generate --api --models --verbose
```

### **3. 手动验证类型**
```dart
// 在生成的代码中添加断言验证
assert(response.data is UserResult);
assert(response.data?.name != null);
```

---

## 📝 **代码模板**

### **标准 API 接口模板**
```dart
/// {接口描述}
@{HTTP_METHOD}('{路径}')
Future<{返回类型}> {方法名}(
  // 路径参数（如果有）
  @Path('{参数名}') {类型} 参数名,
  
  // 查询参数（如果有）
  @Query('{参数名}') {类型}? 参数名,
  
  // 请求体（仅当 swagger 中明确定义时）
  @Body() {类型} request
);
```

### **标准数据模型模板**
```dart
@JsonSerializable(checked: true, includeIfNull: false)
class {类名} {
  /// {字段描述}
  final {类型} {字段名};
  
  const {类名}({
    required this.{非空字段},
    this.{可空字段},
  });

  factory {类名}.fromJson(Map<String, dynamic> json) =>
      _${类名}FromJson(json);

  Map<String, dynamic> toJson() => _${类名}ToJson(this);
}
```

---

## ⚡ **性能优化**

### **1. 按需导入**
```dart
// ✅ 只导入需要的类型
import 'package:learning_officer_oa/common/models/common/base_result.dart';

// ❌ 避免导入不需要的类型
// import 'package:learning_officer_oa/common/models/common/base_page_result.dart';
```

### **2. 使用 const 构造函数**
```dart
// ✅ 使用 const 构造函数
const UserResult({
  required this.id,
  required this.name,
});

// ❌ 避免非 const 构造函数
UserResult({
  required this.id,
  required this.name,
});
```

### **3. 合理的类型选择**
```dart
// ✅ 使用具体类型
Future<BaseResult<UserResult>> getUser();

// ❌ 避免过度使用 dynamic
Future<BaseResult<dynamic>> getUser();
```

---

## 🛡️ **安全检查**

### **生成前检查**
- [ ] swagger.json 格式正确
- [ ] 所有 $ref 引用存在
- [ ] 版本信息匹配

### **生成后检查**
- [ ] 代码通过 dart analyze
- [ ] 所有导入都存在
- [ ] 类型定义完整
- [ ] 可空性正确

### **部署前检查**
- [ ] 运行所有测试
- [ ] 代码格式化
- [ ] 文档更新
- [ ] 版本标记

---

## 📞 **获取帮助**

### **常见错误代码**
- **E001**: swagger.json 格式错误
- **E002**: 缺少必要的 schema 定义
- **E003**: $ref 引用不存在
- **E004**: 类型映射失败

### **联系方式**
- **技术支持**: 联系后端团队完善 swagger 文档
- **Bug 报告**: 提交到项目 Issues
- **功能请求**: 通过 PR 贡献代码

---

**快速参考版本**: v2.0  
**最后更新**: 2025-01-24