229 lines
4.8 KiB
Markdown
229 lines
4.8 KiB
Markdown
# 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
|