Retrofit2-Kotlin-Coroutines-Adapter 教程

1. 项目介绍

Retrofit2-Kotlin-Coroutines-Adapter 是一个用于 Retrofit2 的 CallAdapter 工厂，它使得在 Kotlin 中使用协程（Coroutines）处理网络请求变得简单。这个库允许你将 Retrofit 的 Call 对象转换成 Kotlin 的 Deferred 类型，从而可以在协程中以非阻塞的方式执行网络操作。

2. 项目快速启动

添加依赖

在你的 build.gradle 文件中添加以下依赖项：

dependencies {
    // 如果使用的是稳定版
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    implementation 'com.jakewharton.retrofit:retrofit2-kotlin-coroutines-adapter:0.9.2'

    // 或者，如果你使用的是实验性的协程
    implementation 'com.jakewharton.retrofit:retrofit2-kotlin-coroutines-experimental-adapter:1.0.0'
}

然后运行 ./gradlew sync 或 Gradle Sync 来更新依赖。

创建 Retrofit 实例

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .addCallAdapterFactory(CoroutineCallAdapterFactory()) // 添加 Coroutines 支持
    .build()

val apiService = retrofit.create(ApiService::class.java)

编写 API 接口

interface ApiService {
    @GET("users/{userId}")
    fun getUser(@Path("userId") userId: Int): Deferred<User>
}

使用协程执行网络请求

在需要的地方，使用 GlobalScope.launch 或者其他上下文来启动协程并调用 API。

fun main() {
    val user = GlobalScope.async(Dispatchers.IO) { 
        apiService.getUser(1).await() 
    }
    
    // 在 UI 线程中访问结果
    println("User: ${user.get()}") 
}

3. 应用案例和最佳实践

• 错误处理：由于 Deferred 的 await() 方法会抛出异常，建议在 try-catch 块中捕获可能的 HttpException 和其他运行时异常。

try {
    val user = GlobalScope.async(Dispatchers.IO) { 
        apiService.getUser(1).await() 
    }
    
    // 处理成功情况
} catch (e: HttpException) {
    // 处理 HTTP 错误
} catch (e: Exception) {
    // 处理其他运行时错误
}

• 避免全局作用域：尽量不在 GlobalScope 中启动协程，而是在适当的协程上下文中，如 Activity、Fragment 或者 ViewModel 的生命周期内。

• 取消协程：当不再需要网络请求时，使用 Job 可以取消正在执行的任务，以防止内存泄漏。

val job = GlobalScope.launch(Dispatchers.IO) {
    val user = apiService.getUser(1).await()
}

// 当不需要时，取消协程
job.cancel()

4. 典型生态项目

• Kotlin 协程：kotlinx.coroutines - 官方支持的 Kotlin 协程库。
• Retrofit2：square/retrofit - 网络请求库，用于构建类型安全的 RESTful API 客户端。
• Gson Converter：square/retrofit-converter-gson - 将 JSON 数据自动映射到 Kotlin/Java 对象。

本教程仅提供基本的使用示例，实际开发中应结合相关文档进行深入学习和实践。