SuperAPI AI 工具集

supabase-flutter-migrate-v3

编程与开发

查看项目

更新于 11-18 08:31

技能介绍

用途:这是一个迁移技能,指导把 Dart 或 Flutter 项目从 supabase_flutter v2 升级到 v3,包括处理重命名后的包(gotrue、realtime_client、storage_client、functions_client)以及一系列 API 变化。完整迁移指南位于 references/migration-v2-v3.md,其中每个“Before/After”片段被视为权威依据,该技能给出实施顺序与完成检查。

主要能力与步骤:

  1. 预检:读取 pubspec.yaml 记录相关依赖及版本;检查 git status 要求干净工作树;运行 flutter analyze 保存基线;检查是否存在 supabase/ 目录(config.toml 与 migrations/),以决定类型生成来源。
  2. 要求 Supabase CLI 3.0.0 或更新版本,提供各平台升级命令(Homebrew、npm、Scoop、未安装时参考官方文档),不达标不得继续或回退手写类型。
  3. 在 v2 阶段固定 order() 默认值变化:无 ascending 的调用补 ascending: false;可空列降序查询补 nullsFirst: false。
  4. 更新依赖到最新 3.x:将 supabase_flutter 升至 3.x;重命名直接依赖及其导入(gotrue→supabase_auth、realtime_client→supabase_realtime、storage_client→supabase_storage、functions_client→supabase_functions);添加 dev:supabase_typegen;用 supabase gen types --lang dart 生成 schema 到 lib/supabase_schema.g.dart,并确保生成文件分析干净。
  5. 机械重命名:如 GoTrueClient→AuthClient、queryParams→queryParameters、opts→options、User.confirmedAt→User.emailConfirmedAt、AuthUser→User、Supabase.initialize 的 anonKey→publishableKey 等。
  6. 编译器驱动修复:按错误中符号检索参考文档并应用 After 形式,涵盖登录方法返回 Session、AuthState 密封类、Realtime 回调改流、服务异常基类、重试选项、时间戳 DateTime、rpc 为 getter、insert/upsert 不再带过滤器等。
  7. 编译器无法捕获的变更:逐项用给定 grep 模式检索处理,包括 order() 默认值、connectionState 类型化、HttpMethod 枚举、userUpdated 事件、initialSession 广播、pkce 存储、重试退避、无 select 的写操作返回 void、userMetadata 非空、errors 为 List<String>、默认 HTTP 客户端、HTTPS 要求、传输异常与 AccessTokenException、请求超时语义、Realtime 异常类型、登出移除频道、初始化唯一性、Web 回调时序、SharedPreferencesAsync 会话持久化等。
  8. 将所有查询迁移到类型化 table() API:按表逐一转换并重跑分析;给出 from() 与 table() 的对应写法,包括 selectOnly、where 条件、or 组合、order、embedded、insert/insertAll、update/delete(必须带 where 或 all)、upsert、stream、rpc 方法;保留 from() 与无类型 rpc 仅限生成文件缺失的表/视图/函数、运行时表名、生成器未提供方法的函数等情况。
  9. 验证与报告:flutter analyze 不得超出基线;对修改文件运行 dart format(不格式化生成文件);运行 flutter test 并修复迁移导致的问题;汇总依赖与生成命令、需人工决策的站点、剩余 from()/rpc 及原因,并提醒每次数据库 schema 变更或升级生成器/CLI 后需用同一命令重新生成。

规则要点:按顺序执行、不跳过 CLI 检查;不手写表定义;查询最终落在类型化 table() 除非匹配例外并报告;保持应用行为,v3 改变的默认值除非用户要求否则显式固定为 v2 行为;不通过抑制分析器错误求干净;涉及未覆盖的运行时行为选择需询问用户。

适用场景:计划将使用 supabase_flutter v2 的 Dart/Flutter 应用升级到 v3 的开发者,尤其是需要处理包重命名、API 破坏性变更和类型化查询迁移的项目。

限制:资料仅提供迁移流程与命令,未提供该技能自身的收费、价格、平台要求或效果数据;部分要求依赖 docker、Supabase 项目链接或项目 ref;生成类型需 Supabase CLI 3.0.0+。