本技能用于在 supabase_flutter v3 中编写或审查 Dart 代码。资料提醒:已发布的 Supabase Dart 示例大多是 v2 代码,v3 改动了许多 API,不要凭记忆直接照搬;升级现有 v2 项目应使用 supabase-flutter-migrate-v3 技能。
主要规则:查询表用 table() 结合生成的 schema,不使用 from() 和 Map<String, dynamic>,除非表中缺失该表;用 Supabase CLI(3.0.0 或更新版本)生成 schema,不要手工编辑,数据库 schema 每次变更(无论是迁移还是控制台改动)以及升级 supabase_typegen 或 CLI 后都要重新生成;引入 publishableKey,v3 中不存在 anonKey;实时监听使用 stream,v3 没有回调参数;捕获 SupabaseException 层级,不要捕获 ClientException、TimeoutException 或 String;类型化 update() 或 delete() 在调用 .where(…) 或 .all() 前不会生效,分析器会以 unused_result 警告提示;整个应用使用一个客户端 Supabase.instance.client。
客户端初始化:调用 Supabase.initialize 传入 url 与 publishableKey,它会用 SharedPreferencesAsync 持久化会话并在返回前恢复;如需其他存储(如安全存储)可传 FlutterAuthClientOptions(asyncStorage: …)。
读取行:生成文件为每张表提供行类型、插入与更新类型以及带表定义和列常量的类;其他 schema 的表带 schema 前缀。过滤器是列常量上的方法,可用 &、| 和 not() 组合;值须与列类型匹配,isNull() 仅存在于可空列;order() 默认升序。可用 selectOnly 只读部分列或嵌入关联行,并通过同一组常量读取值。
写入行:insert 接受生成的插入类型;需要返回写入行时加 .select();null 参数会省略该列,写入 SQL NULL 用生成的 set…ToNull() 方法;批量用 insertAll() 和 upsertAll();upsert() 的 onConflict 接受列列表。
调用数据库函数:PostgREST 暴露的函数在 rpc 上有类型化方法;生成器未提供方法的函数可用未类型化回退 supabase.rpc('fn', params: {...})。
认证:一定产生会话的登录方法返回 Session;signUp() 和 verifyOTP() 仍返回 AuthResponse。AuthState 是密封类型,每个新监听器先收到携带当前会话或 null 的 AuthInitialSession;令牌刷新失败是流的错误,因此每个监听器都应传 onError。
实时:用 stream() 保持行列表更新;用 onTableChanges 响应单条变更,需先创建流再 subscribe(),完成后移除通道;broadcast 和连接状态也是流;表必须加入 supabase_realtime publication,否则收不到变更;流应在 State 中创建一次,不要放在 build() 内。
错误:SDK 抛出的失败请求异常都继承 SupabaseException;SupabaseApiException 表示服务器返回错误,SupabaseTransportException 表示未收到响应(含超时);各服务还有自己的基类(如 PostgrestException、AuthException、StorageException),AuthApiException 和 PostgrestApiException 携带服务器的 errorCode。
日志:SDK 不打印,通过 package:logging 在 supabase logger 下记录,监听 Logger.root 过滤 supabase. 前缀即可查看。
测试:使用 supabase_test 作为开发依赖,而不是手工模拟 HTTP 客户端;MockSupabaseHttpClient、testSupabaseClient 和 signInTestUser 可应答请求并让客户端处于已登录状态;相关细节见 supabase-test-testing 技能。