在 Kotlin 项目中集成和使用 Retrofit

在 Android 开发中，网络请求几乎是每个应用都绕不开的环节。

Retrofit 凭借其简洁的接口定义和强大的扩展性，已经成为很多项目的首选网络库。

下面就从零开始，一步步看怎么在 Kotlin 项目里集成和使用 Retrofit。

添加依赖

首先，加依赖。

直接把下面内容写进 build.gradle 的 dependencies 中即可：

dependencies {
  	........
    implementation("com.squareup.retrofit2:retrofit:3.0.0")
    implementation("com.squareup.retrofit2:converter-gson:3.0.0")
}

创建 Retrofit 实例

接下来，需要先准备一个 Retrofit 实例。

常见做法是把它写成单例，方便全局复用。

这里使用 Kotlin 的 object 声明一个 ServiceCreator 类。

在内部定义 Base URL 和 Gson 转换器，并提供一个通用的 create 方法：

object ServiceCreator {
    private const val BASE_URL = "https://7a6396f8-09a1-4ade-b42a-f6db7776fb31.mock.pstmn.io"
    private val retrofit = Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create())
        .build()
    fun  create(serviceClass: Class): T = retrofit.create(serviceClass)
}

定义返回数据结构

有了 Retrofit 实例之后，还需要数据类来解析返回的 JSON。

假设后台返回的数据格式如下：

{
    "data": [
        {
            "random": "3",
            "def": "中止，停顿；归属待定，暂搁",
            "word": "abeyance"
        }
    ]
}

对应的 Kotlin 数据类可以写成：

data class  WordListBean(val data: List)
data class WordBean(val random: String, val def: String, val word: String)

定义接口

Retrofit 的核心思路，就是把 HTTP API 映射成 Kotlin 接口方法。

通过注解声明路径和请求方式。

例如：

interface AppService {
    @GET("/flutter")
    fun getData(): Call
}

发起网络请求

前面的内容准备好之后，就可以在 Activity 或 Fragment 中发起网络调用了。

下面这段代码绑定了按钮点击事件。

它通过 ServiceCreator 获取 AppService 实例，然后异步请求数据：

        binding.clickButC.setOnClickListener {
            val appService = ServiceCreator.create(AppService::class.ja va)
            appService.getData().enqueue(object : Callback{
                override fun onResponse(call: Call, response: Response) {
                    Log.d("ClickActivity",response.body().toString())
                }
                override fun onFailure(call: Call, t: Throwable) {
                    Log.d("ClickActivity",t.toString())
                }
            })
        }

如果一切正常，Logcat 中会看到类似下面的输出：

2025-11-15 01:07:28.592 23340-23340 ClickActivity
com.bz.yh.xd.testkotlin
D WordListBean(data=[WordBean(random=0, def=抛弃，遗弃；中止；陷入，沉湎于, word=abandon), WordBean(random=1, def=抛弃；放纵, word=abandonment), WordBean(random=2, def=缩略词，缩写形式；缩略, word=abbreviation), WordBean(random=3, def=中止，停顿；归属待定，暂搁, word=abeyance)])

使用 reified 简化调用

上面的写法中，每次创建 AppService 都需要传一个 Class 参数。

其实可以使用 Kotlin 的实化类型参数（reified）来简化这一步。

把 ServiceCreator 改成下面这样：

object ServiceCreator {
    private const val BASE_URL = "https://7a6396f8-09a1-4ade-b42a-f6db7776fb31.mock.pstmn.io"
    private val retrofit = Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create())
        .build()
    inline fun  create(): T = create(T::class.ja va)
}

调用时就可以直接这样写：

        binding.clickButC.setOnClickListener {
            val appService = ServiceCreator.create()
            appService.getData().enqueue(object : Callback{
                override fun onResponse(call: Call, response: Response) {
                    Log.d("ClickActivity",response.body().toString())
                }
                override fun onFailure(call: Call, t: Throwable) {
                    Log.d("ClickActivity",t.toString())
                }
            })
        }

这样代码会清爽很多，不再需要手动传 Class。

补充两个基础配置

最后，别忘了两个基础配置：

• 在 AndroidManifest.xml 中声明网络权限

• 如果接口使用的是 HTTP 而不是 HTTPS，还需要配置网络安全策略以允许明文流量

在 AndroidManifest.xml 的 标签中加入：

然后在 res/xml/network_security_config.xml 文件中写入：

总结

到这里，一个完整的 Retrofit 网络请求流程就搭好了。

• 依赖引入
• 单例创建
• 数据类映射
• 接口定义
• 实际调用

每一步都紧扣 Kotlin 的特性。

用实化泛型优化后，代码的可读性和简洁性又提升了一个台阶。

希望这个小教程能帮你快速上手 Retrofit，少踩几个坑。