Android Academy · 课时

Retrofit 与 REST API

使用 Retrofit 发起 HTTP 请求。定义 API 接口，使用 Gson/Moshi 解析 JSON，处理响应和错误，并与协程集成。

第 1 / 6 课11 个步骤

Retrofit 与 REST API 是 CoddyKit 上的免费 Android Academy 课时。这是第 1 节课，共 6 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Android Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Android Academy 课程共包含 6 节课。

什么是 Retrofit？

Retrofit 是由 Square 开发的 Android 上最流行的 HTTP 客户端。它可以让您将 REST API 定义为 Kotlin 接口，无需编写繁琐的 HTTP 代码。

使用 @GET、@POST 等注解标记方法
自动将 JSON 响应转换为 Kotlin 数据类
原生支持协程（suspend fun）

添加依赖项

将 Retrofit 和 Gson 转换器添加到 app/build.gradle：

// app/build.gradle
dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.11.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.11.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
}

// AndroidManifest.xml — add internet permission:
// <uses-permission android:name="android.permission.INTERNET" />

定义 API 接口

创建描述 API 端点的 Kotlin 接口：

import retrofit2.http.*

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

interface ApiService {

    @GET("posts")
    suspend fun getPosts(): List<Post>

    @GET("posts/{id}")
    suspend fun getPost(@Path("id") id: Int): Post

    @POST("posts")
    suspend fun createPost(@Body post: Post): Post

    @GET("posts")
    suspend fun getPostsByUser(@Query("userId") userId: Int): List<Post>
}

构建 Retrofit 实例

创建一个 Retrofit 单例实例，通常放在 object 中，或通过 Hilt 创建：

import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory

object RetrofitClient {
    private const val BASE_URL = "https://jsonplaceholder.typicode.com/"

    val api: ApiService by lazy {
        Retrofit.Builder()
            .baseUrl(BASE_URL)
            .addConverterFactory(GsonConverterFactory.create())
            .build()
            .create(ApiService::class.java)
    }
}

发起 GET 请求

使用 Kotlin 协程从 Repository 调用 API：

class PostRepository {
    private val api = RetrofitClient.api

    suspend fun getPosts(): List<Post> {
        return api.getPosts()  // Retrofit handles threading for you
    }

    suspend fun getPost(id: Int): Post {
        return api.getPost(id)
    }
}

// In ViewModel:
fun loadPosts() {
    viewModelScope.launch {
        try {
            val posts = withContext(Dispatchers.IO) {
                repository.getPosts()
            }
            _posts.value = posts
        } catch (e: Exception) {
            _error.value = "Network error: ${e.message}"
        }
    }
}

Gson JSON 映射

Gson 会自动将 JSON 转换为 Kotlin 数据类。字段名称必须与 JSON 键匹配，否则请使用 @SerializedName：

import com.google.gson.annotations.SerializedName

data class User(
    val id: Int,
    val name: String,
    val email: String,
    @SerializedName("phone_number")  // JSON key is 'phone_number'
    val phoneNumber: String,
    @SerializedName("created_at")
    val createdAt: String
)

使用请求体发送 POST 请求

使用 @POST 和 @Body 向服务器发送数据：

// API interface:
@POST("users")
suspend fun createUser(@Body user: User): User

// In Repository:
suspend fun createUser(name: String, email: String): User {
    val newUser = User(id = 0, name = name, email = email, phoneNumber = "", createdAt = "")
    return api.createUser(newUser)
}

// In ViewModel:
fun registerUser(name: String, email: String) {
    viewModelScope.launch {
        val user = withContext(Dispatchers.IO) {
            repo.createUser(name, email)
        }
        _registeredUser.value = user
    }
}

请求头与身份验证

使用 OkHttp 拦截器为每个请求添加请求头：

import okhttp3.OkHttpClient
import okhttp3.Interceptor

val authClient = OkHttpClient.Builder()
    .addInterceptor { chain ->
        val request = chain.request().newBuilder()
            .addHeader("Authorization", "Bearer $token")
            .addHeader("Accept", "application/json")
            .build()
        chain.proceed(request)
    }
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl(BASE_URL)
    .client(authClient)  // use our authenticated client
    .addConverterFactory(GsonConverterFactory.create())
    .build()

处理 HTTP 错误

成功的 HTTP 响应（200-299）会返回一个值。错误响应（4xx、5xx）会抛出 HttpException。请始终处理这两种情况：

HttpException — 服务器返回了错误状态码
IOException — 没有网络连接

快速检查

哪个 Retrofit 注解可以将方法参数映射到 URL 路径片段，例如 /posts/{id}？

在交互式课程中回答

回顾：Retrofit 与 API

现在您可以从任意 REST API 获取数据：

使用 Kotlin 接口和注解（@GET、@POST、@Path、@Query）定义 API
使用基础 URL 和 Gson 转换器构建 Retrofit 实例
在 ViewModel 的协程中调用挂起函数
自动将 JSON 映射为 Kotlin 数据类
处理 HttpException 和 IOException

下一节：使用 Coil 显示网络图片。

免费开始

用 AI 导师学习 Kotlin — 免费

在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。

课程: 36
课程: 152

免费开始学习查看完整课程

常见问题解答

「Retrofit 与 REST API」课时是免费的吗？

是的 — 「Retrofit 与 REST API」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Android Academy 课程的其余内容，请升级到 CoddyKit PRO。 Android Academy 课程共包含 6 节课。

「Retrofit 与 REST API」这节课中我会学到什么？

使用 Retrofit 发起 HTTP 请求。定义 API 接口，使用 Gson/Moshi 解析 JSON，处理响应和错误，并与协程集成。你通过在浏览器中直接运行的动手代码来练习 Android Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Android Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Android Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 6 节。

「Retrofit 与 REST API」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Android Academy 课中编写并运行代码吗？

能。每节 Android Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Android Academy