wangyang
/
swagger_generator_flutter
1
0
Fork 0
Code Pull Requests Actions Releases Activity
swagger_generator_flutter/CODE_REVIEW_CHECKLIST.md

5.4 KiB
Raw Blame History

Augment 代码生成审查清单

📋 生成前检查

Swagger 文档验证

  • swagger.json 文件格式正确
  • OpenAPI 版本为 3.0.x
  • 所有 $ref 引用都存在对应的定义
  • components/schemas 部分完整
  • 所有接口都有明确的 responses 定义
  • 参数定义完整（name, in, schema）
  • requestBody 定义明确（如果需要）

环境准备

  • Dart SDK 版本 >= 3.0.0
  • 依赖包版本正确
  • 网络连接正常（如果从 URL 获取 swagger）
  • 输出目录权限正确

🔧 生成过程检查

命令执行

  • 使用正确的生成命令
  • 参数配置正确
  • 没有错误或警告信息
  • 生成统计信息合理

文件生成

  • API 文件按 tag 正确分组
  • 模型文件命名规范
  • 目录结构正确
  • index.dart 文件更新

✅ 生成后验证

API 接口检查

文件结构

  • 文件头注释完整
  • 导入语句正确且按需导入
  • 类名符合 PascalCase 规范
  • 方法名符合 camelCase 规范

方法定义

  • HTTP 方法注解正确（@GET, @POST, @PUT, @DELETE）
  • 路径定义与 swagger 一致
  • 返回类型正确提取
  • 参数定义完整且正确
// ✅ 正确的方法定义示例
/// 用户登录
@POST('/api/v1/Login/userLogin')
Future<BaseResult<UserLoginResult>> userLogin(
  @Body() LoginRequest request
);

// ❌ 错误示例
@POST('/api/v1/Login/userLogin')
Future<BaseResult<TaskInfoResult>> userLogin(  // 错误：不存在的类型
  @Body() Map<String, dynamic> request         // 错误：swagger 中没有定义
);

参数检查

  • 路径参数使用 @Path 注解
  • 查询参数使用 @Query 注解
  • 请求体参数使用 @Body 注解
  • 参数类型与 swagger 定义一致
  • 可空性正确（? 标记）
  • 没有多余的参数

返回类型检查

  • 使用 BaseResult 包装
  • 分页接口使用 BasePageResult
  • 健康检查接口返回 void
  • 泛型类型存在于 swagger 中
  • 没有硬编码推断的类型

导入检查

  • 基础类型导入正确
  • 分页类型按需导入
  • 模型类型导入完整
  • 没有未使用的导入
  • 导入路径正确

数据模型检查

类定义

  • 类名符合 PascalCase 规范
  • @JsonSerializable 注解正确
  • 注解参数配置正确（checked: true, includeIfNull: false）

属性定义

  • 属性名符合 camelCase 规范
  • 类型映射正确（string -> String, integer -> int）
  • 可空性严格按照 nullable 字段
  • 注释信息完整
  • final 修饰符正确使用
// ✅ 正确的属性定义
/// 用户ID
final int id;

/// 用户名
final String username;

/// 昵称（可空）
final String? nickname;  // swagger 中 "nullable": true

// ❌ 错误示例
final String? username;  // 错误：swagger 中没有 "nullable": true
final String nickname;   // 错误：swagger 中有 "nullable": true

构造函数检查

  • 使用 const 构造函数
  • 非空字段标记为 required
  • 可空字段不使用 required
  • 参数顺序合理

序列化方法

  • fromJson 工厂方法存在
  • toJson 方法存在
  • part 文件引用正确
  • 生成的方法名正确

代码质量检查

静态分析

  • dart analyze 无错误
  • dart analyze 无警告
  • 代码格式化正确
  • 命名规范一致

类型安全

  • 避免使用 dynamic
  • 泛型类型明确
  • 可空性处理正确
  • 类型转换安全

性能考虑

  • 使用 const 构造函数
  • 避免不必要的对象创建
  • 导入优化
  • 内存使用合理

🚫 常见问题检查

类型相关

  • 没有生成不存在的类型（如 TaskInfoResult）
  • 没有硬编码的类型映射
  • 没有基于路径关键词的推断
  • 没有基于 tag 的类型推断

参数相关

  • 没有添加 swagger 中未定义的参数
  • 没有遗漏 swagger 中定义的参数
  • 参数位置正确（path, query, body）
  • 参数类型正确

导入相关

  • 没有循环导入
  • 没有未使用的导入
  • 没有缺失的导入
  • 导入路径正确

命名相关

  • 文件名符合 snake_case
  • 类名符合 PascalCase
  • 方法名符合 camelCase
  • 变量名符合 camelCase

🔄 集成测试

构建测试

  • dart pub get 成功
  • dart pub run build_runner build 成功
  • 生成的 .g.dart 文件正确
  • 没有构建错误或警告

运行时测试

  • API 调用正常
  • 序列化/反序列化正常
  • 类型转换正确
  • 错误处理正确

兼容性测试

  • Dart 版本兼容
  • Flutter 版本兼容
  • 依赖包版本兼容
  • 平台兼容性

📝 文档检查

代码注释

  • 类注释完整
  • 方法注释完整
  • 属性注释完整
  • 特殊逻辑有说明

生成信息

  • 文件头信息正确
  • 版本信息正确
  • 生成时间标记
  • 来源信息明确

✍️ 审查签名

审查者: _______________
审查日期: _______________
审查结果: [ ] 通过 [ ] 需要修改 [ ] 拒绝
备注: _______________

检查清单版本: v2.0
最后更新: 2025-01-24