Android开发(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 实例。通常的做法是把它做成单例，方便全局复用。这里用 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)])

上面的写法里，每次创建 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（比如本地的 Mock 服务），还需要配置网络安全策略以允许明文流量。在 AndroidManifest.xml 的 标签里加上：

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

到这里，一个完整的 Retrofit 网络请求流程就搭好了。从依赖引入、单例创建、数据类映射、接口定义到实际调用，每一步都紧扣 Kotlin 的特性。用实化泛型优化后，代码的可读性和简洁性又提升了一个台阶。希望这个小教程能帮你快速上手 Retrofit，少踩几个坑。