Retrofit for Kotlin：完整指南与示例

什么是 Retrofit，为什么需要它？

Retrofit 是由 Square 公司开发的适用于 Java 和 Kotlin 的类型安全 HTTP 客户端。它是 Android 生态系统中用于处理 REST API 最流行的库之一。Retrofit 允许开发者轻松优雅地执行对远程服务器的 HTTP 请求，自动将 JSON 响应转换为 Kotlin 对象，反之亦然。

为什么需要 Retrofit？

• 简化 API 操作： 无需编写使用 HttpURLConnection 或 OkHttp 的冗长代码，您只需定义一个带有注解的接口，Retrofit 会自动生成实现。
• 自动序列化/反序列化： 通过与转换器（Gson、Moshi、Kotlinx Serialization）集成，Retrofit 自动将 JSON 转换为 Kotlin 对象。
• 支持多种 HTTP 方法： GET、POST、PUT、DELETE、PATCH、HEAD 和 OPTIONS。
• 管理标头和参数： 轻松添加动态或静态标头、查询参数和路径参数。
• 异步支持： 支持 Kotlin 协程（suspend 函数）和 Callback 接口。
• 与 OkHttp 集成： Retrofit 使用 OkHttp 作为 HTTP 引擎，从而可以访问强大的请求拦截功能。

Retrofit 非常适合与 RESTful Web 服务交互的 Android 应用：从简单的天气应用到复杂的社交网络。

在 Kotlin 项目中安装 Retrofit

与 Python（使用 pip）不同，在 Kotlin/Android 项目中，依赖项通过 Gradle 管理。将以下行添加到您的模块（通常是 app）的 build.gradle.kts（或 build.gradle）文件中：

// build.gradle.kts (Module :app)dependencies {    // Retrofit 主库    implementation("com.squareup.retrofit2:retrofit:2.9.0")        // 用于处理 JSON 的转换器 (Gson)    implementation("com.squareup.retrofit2:converter-gson:2.9.0")        // 替代转换器 (Moshi)    // implementation("com.squareup.retrofit2:converter-moshi:2.9.0")        // 用于支持协程 (suspend 函数)    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")        // OkHttp (通常已包含，但可以显式添加)    implementation("com.squareup.okhttp3:okhttp:4.12.0")    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")}

重要提示： 添加依赖项后，在 Android Studio 中点击 "Sync Now" 以加载库。

快速入门：代码示例

让我们创建一个简单的应用，从 JSONPlaceholder（免费测试 API）获取帖子列表。

步骤 1：创建响应的 data 类

data class Post(    val userId: Int,    val id: Int,    val title: String,    val body: String)

步骤 2：定义 API 接口

interface ApiService {    @GET("posts")    suspend fun getPosts(): List<Post>        @GET("posts/{id}")    suspend fun getPostById(@Path("id") postId: Int): Post}

步骤 3：创建 Retrofit 客户端

object RetrofitClient {    private const val BASE_URL = "https://jsonplaceholder.typicode.com/"        val instance: ApiService by lazy {        Retrofit.Builder()            .baseUrl(BASE_URL)            .addConverterFactory(GsonConverterFactory.create())            .build()            .create(ApiService::class.java)    }}

步骤 4：在 Activity 或 ViewModel 中使用

class MainActivity : AppCompatActivity() {    override fun onCreate(savedInstanceState: Bundle?) {