2025年05月最新！Supabase开源项目在Android手机的实践指南

引言

Supabase作为Firebase的开源替代方案，在2025年已经成为移动开发者的热门选择。本文将带你从零开始，在Android手机上实现Supabase的完整集成，包括认证、数据库操作等核心功能。

准备工作

环境要求

Android Studio Flamingo 2025.1.1 或更高版本
Android手机（API级别31+）
Java 17或Kotlin 2.0
Gradle 9.0

前置条件

注册Supabase账号
创建一个新项目
获取项目URL和anon(public) key

步骤一：创建Android项目并添加依赖

新建Android项目（选择Empty Activity模板）
修改build.gradle(Module:app)：

代码片段

dependencies {
    // Supabase核心库 (2025最新版本)
    implementation 'io.github.supabase:postgrest-kt:2.5.0'
    implementation 'io.github.supabase:gotrue-kt:2.5.0'

    // Kotlin协程支持
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0'

    // JSON序列化
    implementation 'com.squareup.moshi:moshi-kotlin:1.16.0'
}

同步Gradle后，添加网络权限到AndroidManifest.xml：

代码片段

<uses-permission android:name="android.permission.INTERNET" />

步骤二：初始化Supabase客户端

创建SupabaseClient.kt单例类：

代码片段

import io.github.jan.supabase.SupabaseClient
import io.github.jan.supabase.createSupabaseClient
import io.github.jan.supabase.postgrest.Postgrest
import io.github.jan.supabase.gotrue.GoTrue

object SupabaseClient {
    private const val SUPABASE_URL = "你的项目URL"
    private const val SUPABASE_KEY = "你的anon key"

    val client: SupabaseClient by lazy {
        createSupabaseClient(
            supabaseUrl = SUPABASE_URL,
            supabaseKey = SUPABASE_KEY
        ) {
            install(Postgrest)
            install(GoTrue) {
                scheme = "https" // 2025年强制要求HTTPS
            }
        }
    }
}

注意事项：
– URL和Key不要硬编码，实际项目中应使用local.properties
– GoTrue是Supabase的认证模块，必须安装

步骤三：实现用户认证功能

3.1 Email/Password注册

代码片段

suspend fun signUpWithEmail(email: String, password: String) {
    try {
        SupabaseClient.client.auth.signUpWith(
            GoTrue.Email(email, password)
        )
        // 注册成功处理
    } catch (e: Exception) {
        // 错误处理（如邮箱已存在）
        Log.e("Supabase", "注册失败", e)
    }
}

3.2 Email/Password登录

代码片段

suspend fun signInWithEmail(email: String, password: String): Boolean {
    return try {
        SupabaseClient.client.auth.signInWith(
            GoTrue.Email(email, password)
        )
        true // 登录成功
    } catch (e: Exception) {
        Log.e("Supabase", "登录失败", e)
        false
    }
}

实践经验：
– 使用协程suspend函数处理异步操作
– UI层应使用viewModelScope.launch调用这些函数

步骤四：数据库CRUD操作示例

假设我们有一个todos表：
– id (uuid)
– task (text)
– iscomplete (boolean)
– userid (uuid)

4.1 创建数据模型

代码片段

@Serializable
data class Todo(
    val id: String,
    val task: String,
    val is_complete: Boolean,
    val user_id: String,

    @Transient // 不序列化到数据库的字段示例 
    val isSelected: Boolean = false 
)

4.2 INSERT操作

代码片段

suspend fun createTodo(task: String): Result<Todo> {
    return try {
        val currentUser = SupabaseClient.client.auth.currentUserOrNull()
            ?: return Result.failure(Exception("用户未登录"))

        val newTodo = Todo(
            id = UUID.randomUUID().toString(),
            task = task,
            is_complete = false,
            user_id = currentUser.id.toString()
        )

        SupabaseClient.client.postgrest["todos"]
            .insert(newTodo)

        Result.success(newTodo)
    } catch (e: Exception) {
        Result.failure(e)
    }
}

4.3 SELECT操作（带过滤）

代码片段

suspend fun fetchUserTodos(): List<Todo> {
    val currentUser = SupabaseClient.client.auth.currentUserOrNull()
        ?: return emptyList()

    return SupabaseClient.client.postgrest["todos"]
        .select {
            filter { eq("user_id", currentUser.id.toString()) }
            order("created_at", ascending = false) // 假设表中有created_at字段 
        }
        .decodeList<Todo>()
}

原理说明：
– postgrest["todos"]访问todos表
– filter构建PostgreSQL查询条件
– decodeList<Todo>将结果反序列化为模型列表

步骤五：实时订阅功能（2025新增API）

Supabse的实时订阅功能现在更加高效：

代码片段

fun subscribeToTodos(callback: (List<Todo>) -> Unit): Closeable {
    val currentUserId = SupabaseClient.client.auth.currentUserOrNull()?.id.toString()

    return SupabaseClient.client.realtime.channel("todos_$currentUserId")
        .on("todos") { event ->
            when(event) {  
                is RealtimeEvent.Insert -> callback(event.decodeRecords<Todo>())
                is RealtimeEvent.Update -> callback(event.decodeRecords<Todo>())
                else -> Unit 
            }
         }.subscribe()
}

// UI层使用示例：
val subscription = subscribeToTodos { todos ->
     runOnUiThread { adapter.submitList(todos) } 
}

// Don't forget to close when done!
override fun onDestroy() {  
     subscription.close()  
}

Android特定优化建议

网络状态处理：

代码片段

// NetworkUtils.isOnline()需要自己实现或使用ConnectivityManager 
if(!NetworkUtils.isOnline(context)) {  
    showOfflineMessage()  
    return  
}

数据缓存策略：
- Room + Supabase组合使用实现离线优先架构

后台同步：

代码片段

WorkManager.enqueue(
    OneTimeWorkRequestBuilder<SyncWorker>().build()
)

FAQ与常见问题解决

Q：遇到”SSL handshake failed”错误怎么办？
A：更新设备根证书或配置网络安全配置：

代码片段

<network-security-config>
     <base-config cleartextTrafficPermitted="false">
         <trust-anchors>
             <certificates src="system"/>
             <certificates src="@raw/my_custom_ca"/> <!-- if needed -->
         </trust-anchors>
     </base-config>
</network-security-config>

Q：如何优化大列表的性能？
A：使用Paging库 + Supabse的分页查询：

代码片段

fun getTodosPagingSource(): PagingSource<Int, Todo> {  
     return PostgrestPagingSource(  
         client.postgrest["todos"],  
         pageSize = PAGE_SIZE  
     )   
}

总结

本文涵盖了2025年最新的Supabse在Android上的集成方法，关键点包括：

Kotlin优先的API设计更加简洁
GoTrue认证模块的安全增强
PostgREST的强类型查询构建器
Realtime订阅的性能优化

完整示例代码可访问：[GitHub仓库链接]

下一步可以探索Storage模块或Edge Functions集成！