Android 开发中的 API 调用全攻略

前言#

在现代 Android 开发中，网络 API 调用几乎是每个 App 都绕不开的核心需求——登录注册需要调接口、获取列表数据需要调接口、上传文件需要调接口。Android 生态中做网络请求的方案非常多，从最底层的 HttpURLConnection 到如今主流的 Retrofit + OkHttp 组合，各有优劣。

本文将系统性地介绍 Android 中 API 调用的各种方式，帮你建立完整的技术选型认知。

Note

本文所有示例均使用 Kotlin 编写，网络请求属于耗时操作，默认运行在协程中。关于协程的基础知识可参阅 Kotlin 协程官方文档。

1. 方案总览#

方案	层级	特点	适用场景
HttpURLConnection	底层	JDK 内置，无依赖，代码量多	极简需求、教学演示
OkHttp	中间层	高性能，拦截器链，连接池	大中型项目底层引擎
Retrofit	上层	注解式声明，自动序列化/反序列化	主流 RESTful API 项目
Ktor Client	上层	纯 Kotlin，跨平台，协程原生	KMP / Compose Multiplatform

实际项目中，Retrofit + OkHttp + Kotlin Coroutines 是绝大多数团队的标配。

2. HttpURLConnection：最底层的方式#

HttpURLConnection 是 JDK 内置的 HTTP 客户端，Android 也能用，但代码较为繁琐。

2.1 GET 请求#

1
import java.net.HttpURLConnection
2
import java.net.URL
3

4
fun httpGet(url: String): String {
5
    val connection = URL(url).openConnection() as HttpURLConnection
6

7
    connection.apply {
8
        requestMethod = "GET"
9
        connectTimeout = 10_000
10
        readTimeout = 10_000
11
        setRequestProperty("Accept", "application/json")
12
    }
13

14
    return try {
15
        val responseCode = connection.responseCode
16
        if (responseCode == HttpURLConnection.HTTP_OK) {
17
            connection.inputStream.bufferedReader().readText()
18
        } else {
19
            throw Exception("请求失败: $responseCode")
20
        }
21
    } finally {
22
        connection.disconnect()
23
    }
24
}

2.2 POST 请求#

1
import java.io.OutputStream
2
import org.json.JSONObject
3

4
fun httpPost(url: String, body: JSONObject): String {
5
    val connection = URL(url).openConnection() as HttpURLConnection
6

7
    connection.apply {
8
        requestMethod = "POST"
9
        connectTimeout = 10_000
10
        readTimeout = 10_000
11
        doOutput = true
12
        setRequestProperty("Content-Type", "application/json")
13
        setRequestProperty("Accept", "application/json")
14
    }
15

16
    // 写入请求体
17
    connection.outputStream.use { outputStream: OutputStream ->
18
        outputStream.write(body.toString().toByteArray(Charsets.UTF_8))
19
    }
20

21
    return try {
22
        val responseCode = connection.responseCode
23
        if (responseCode == HttpURLConnection.HTTP_OK) {
24
            connection.inputStream.bufferedReader().readText()
25
        } else {
26
            throw Exception("请求失败: $responseCode")
27
        }
28
    } finally {
29
        connection.disconnect()
30
    }
31
}

2.3 优缺点#

优点	缺点
无需任何第三方依赖	代码冗长，每次都要手写连接管理
JDK 内置，兼容性好	没有拦截器、连接池等高级特性
适合理解底层原理	不直接支持并发、取消操作

结论：几乎没有人会在生产项目中使用 HttpURLConnection，但它对于理解网络请求的底层机制很有帮助。

3. OkHttp：市场占有率最高的 HTTP 引擎#

OkHttp 是 Square 公司出品的 HTTP 客户端，也是 Retrofit 的默认底层引擎。它以拦截器链和连接池两大特性著称。

3.1 添加依赖#

1
dependencies {
2
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
3
    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
4
}

3.2 基本用法#

1
val client = OkHttpClient.Builder()
2
    .connectTimeout(30, TimeUnit.SECONDS)
3
    .readTimeout(30, TimeUnit.SECONDS)
4
    .addInterceptor(HttpLoggingInterceptor().apply {
5
        level = HttpLoggingInterceptor.Level.BODY
6
    })
7
    .build()
8

9
// GET 请求
10
fun get(url: String): String {
11
    val request = Request.Builder()
12
        .url(url)
13
        .header("Accept", "application/json")
14
        .get()
15
        .build()
16

17
    client.newCall(request).execute().use { response ->
18
        if (!response.isSuccessful) {
19
            throw IOException("Unexpected code $response")
20
        }
21
        return response.body?.string() ?: ""
22
    }
23
}
24

25
// POST 请求（JSON）
26
fun post(url: String, json: String): String {
27
    val requestBody = json.toRequestBody("application/json".toMediaTypeOrNull())
28
    val request = Request.Builder()
29
        .url(url)
30
        .post(requestBody)
31
        .build()
32

33
    client.newCall(request).execute().use { response ->
34
        return response.body?.string() ?: ""
35
    }
36
}

3.3 拦截器（Interceptor）—— OkHttp 的灵魂#

拦截器是 OkHttp 最强大的特性，可以在请求发送前和响应返回后做统一处理。

1
// 日志拦截器：打印请求和响应
2
class LoggingInterceptor : Interceptor {
3
    override fun intercept(chain: Interceptor.Chain): Response {
4
        val request = chain.request()
5
        Log.d("OkHttp", "--> ${request.method} ${request.url}")
6
        val startTime = System.nanoTime()
7
        val response = chain.proceed(request)
8
        val duration = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startTime)
9
        Log.d("OkHttp", "<-- ${response.code} ${request.url} (${duration}ms)")
10
        return response
11
    }
12
}
13

14
// Token 拦截器：自动添加认证头
15
class AuthInterceptor(private val tokenProvider: () -> String?) : Interceptor {
16
    override fun intercept(chain: Interceptor.Chain): Response {
17
        val original = chain.request()
18
        val token = tokenProvider()
19
        val request = if (token != null) {
20
            original.newBuilder()
21
                .header("Authorization", "Bearer $token")
22
                .build()
23
        } else {
24
            original
25
        }
26
        return chain.proceed(request)
27
    }
28
}
29

30
// 重试拦截器：网络异常时自动重试
31
class RetryInterceptor(private val maxRetries: Int = 3) : Interceptor {
32
    override fun intercept(chain: Interceptor.Chain): Response {
33
        var retryCount = 0
34
        var lastException: IOException? = null
35
        while (retryCount < maxRetries) {
36
            try {
37
                return chain.proceed(chain.request())
38
            } catch (e: IOException) {
39
                lastException = e
40
                retryCount++
41
                if (retryCount >= maxRetries) throw e
42
            }
43
        }
44
        throw lastException ?: IOException("Max retries exceeded")
45
    }
46
}

3.4 文件上传（Multipart）#

1
fun uploadFile(url: String, file: File, fieldName: String): String {
2
    val requestBody = MultipartBody.Builder()
3
        .setType(MultipartBody.FORM)
4
        .addFormDataPart(fieldName, file.name, file.asRequestBody("image/*".toMediaTypeOrNull()))
5
        .addFormDataPart("description", "这是文件描述")
6
        .build()
7

8
    val request = Request.Builder()
9
        .url(url)
10
        .post(requestBody)
11
        .build()
12

13
    client.newCall(request).execute().use { response ->
14
        return response.body?.string() ?: ""
15
    }
16
}

3.5 与协程结合#

OkHttp 从 4.x 开始原生支持 Kotlin 协程的 suspend 函数，但需要引入扩展库或者直接桥接。更常见的做法是用 Retrofit 来包装。

4. Retrofit：注解式 HTTP 客户端#

Retrofit 同样是 Square 出品，它将 HTTP API 声明为 Kotlin 接口，通过注解描述请求细节，是 Android 社区的事实标准。

4.1 添加依赖#

1
dependencies {
2
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
3
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
4
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
5
}

4.2 定义 API 接口#

1
interface ApiService {
2

3
    @GET("users/{id}")
4
    suspend fun getUser(@Path("id") userId: Long): Response<User>
5

6
    @GET("users")
7
    suspend fun getUsers(
8
        @Query("page") page: Int = 1,
9
        @Query("per_page") perPage: Int = 20
10
    ): Response<List<User>>
11

12
    @POST("users")
13
    suspend fun createUser(@Body user: User): Response<User>
14

15
    @PUT("users/{id}")
16
    suspend fun updateUser(
17
        @Path("id") userId: Long,
18
        @Body user: User
19
    ): Response<User>
20

21
    @DELETE("users/{id}")
22
    suspend fun deleteUser(@Path("id") userId: Long): Response<Unit>
23

24
    @Multipart
25
    @POST("upload")
26
    suspend fun uploadFile(
27
        @Part file: MultipartBody.Part,
28
        @Part("description") description: RequestBody
29
    ): Response<UploadResult>
30

31
    @FormUrlEncoded
32
    @POST("auth/login")
33
    suspend fun login(
34
        @Field("username") username: String,
35
        @Field("password") password: String
36
    ): Response<LoginResult>
37

38
    @Headers("Cache-Control: max-age=3600")
39
    @GET("config")
40
    suspend fun getConfig(): Response<Config>
41
}

4.3 数据模型#

1
data class User(
2
    val id: Long,
3
    val name: String,
4
    val email: String,
5
    val avatar: String?
6
)
7

8
data class ApiResponse<T>(
9
    val code: Int,
10
    val message: String,
11
    val data: T?
12
)
13

14
data class LoginResult(
15
    val token: String,
16
    val userId: Long
17
)
18

19
data class Config(
20
    val apiVersion: String,
21
    val features: List<String>
22
)
23

24
data class UploadResult(
25
    val url: String,
26
    val fileId: String
27
)

4.4 构建 Retrofit 实例#

1
object ApiClient {
2

3
    private const val BASE_URL = "https://api.example.com/"
4

5
    private val okHttpClient: OkHttpClient by lazy {
6
        OkHttpClient.Builder()
7
            .connectTimeout(30, TimeUnit.SECONDS)
8
            .readTimeout(30, TimeUnit.SECONDS)
9
            .writeTimeout(30, TimeUnit.SECONDS)
10
            .addInterceptor(AuthInterceptor { TokenManager.token })
11
            .addInterceptor(HttpLoggingInterceptor().apply {
12
                level = HttpLoggingInterceptor.Level.BODY
13
            })
14
            .build()
15
    }
16

17
    private val retrofit: Retrofit by lazy {
18
        Retrofit.Builder()
19
            .baseUrl(BASE_URL)
20
            .client(okHttpClient)
21
            .addConverterFactory(GsonConverterFactory.create())
22
            .build()
23
    }
24

25
    val apiService: ApiService by lazy {
26
        retrofit.create(ApiService::class.java)
27
    }
28
}

4.5 在 ViewModel 中调用#

1
class UserViewModel : ViewModel() {
2

3
    private val _users = MutableStateFlow<List<User>>(emptyList())
4
    val users: StateFlow<List<User>> = _users.asStateFlow()
5

6
    private val _error = MutableStateFlow<String?>(null)
7
    val error: StateFlow<String?> = _error.asStateFlow()
8

9
    private val _loading = MutableStateFlow(false)
10
    val loading: StateFlow<Boolean> = _loading.asStateFlow()
11

12
    fun fetchUsers(page: Int = 1) {
13
        viewModelScope.launch {
14
            _loading.value = true
15
            try {
16
                val response = ApiClient.apiService.getUsers(page = page)
17
                if (response.isSuccessful) {
18
                    _users.value = response.body() ?: emptyList()
19
                } else {
20
                    _error.value = "请求失败: ${response.code()}"
21
                }
22
            } catch (e: IOException) {
23
                _error.value = "网络异常: ${e.message}"
24
            } catch (e: Exception) {
25
                _error.value = "未知错误: ${e.message}"
26
            } finally {
27
                _loading.value = false
28
            }
29
        }
30
    }
31
}

4.6 封装统一响应处理#

很多人会封装一个工具类来处理统一的 API 响应格式：

1
sealed class NetworkResult<out T> {
2
    data class Success<T>(val data: T) : NetworkResult<T>()
3
    data class Error(val code: Int, val message: String) : NetworkResult<Nothing>()
4
    data class Exception(val e: Throwable) : NetworkResult<Nothing>()
5
}
6

7
suspend fun <T> safeApiCall(call: suspend () -> Response<T>): NetworkResult<T> {
8
    return try {
9
        val response = call()
10
        if (response.isSuccessful) {
11
            val body = response.body()
12
            if (body != null) {
13
                NetworkResult.Success(body)
14
            } else {
15
                NetworkResult.Error(response.code(), "响应体为空")
16
            }
17
        } else {
18
            val errorBody = response.errorBody()?.string() ?: "未知错误"
19
            NetworkResult.Error(response.code(), errorBody)
20
        }
21
    } catch (e: IOException) {
22
        NetworkResult.Exception(e)
23
    } catch (e: Exception) {
24
        NetworkResult.Exception(e)
25
    }
26
}
27

28
// 使用
29
class UserViewModel : ViewModel() {
30
    fun fetchUsers() {
31
        viewModelScope.launch {
32
            when (val result = safeApiCall { ApiClient.apiService.getUsers() }) {
33
                is NetworkResult.Success -> _users.value = result.data
34
                is NetworkResult.Error -> _error.value = result.message
35
                is NetworkResult.Exception -> _error.value = result.e.message
36
            }
37
        }
38
    }
39
}

5. Ktor Client：跨平台新势力#

Ktor Client 是 JetBrains 出品，原生 Kotlin 编写，特别适合 Kotlin Multiplatform（KMP） 项目。

5.1 添加依赖#

1
// libs.versions.toml 或 build.gradle.kts
2
dependencies {
3
    implementation("io.ktor:ktor-client-core:2.3.7")
4
    implementation("io.ktor:ktor-client-android:2.3.7")
5
    implementation("io.ktor:ktor-client-content-negotiation:2.3.7")
6
    implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.7")
7
    implementation("io.ktor:ktor-client-logging:2.3.7")
8
    implementation("io.ktor:ktor-client-auth:2.3.7")
9
}

5.2 基本配置#

1
import io.ktor.client.*
2
import io.ktor.client.plugins.*
3
import io.ktor.client.plugins.contentnegotiation.*
4
import io.ktor.client.plugins.logging.*
5
import io.ktor.client.request.*
6
import io.ktor.client.statement.*
7
import io.ktor.serialization.kotlinx.json.*
8

9
val ktorClient = HttpClient {
10
    // 超时配置
11
    install(HttpTimeout) {
12
        connectTimeoutMillis = 30_000
13
        requestTimeoutMillis = 30_000
14
    }
15

16
    // JSON 序列化
17
    install(ContentNegotiation) {
18
        json(kotlinx.serialization.json.Json {
19
            ignoreUnknownKeys = true
20
            isLenient = true
21
        })
22
    }
23

24
    // 日志
25
    install(Logging) {
26
        level = LogLevel.BODY
27
    }
28

29
    // 默认请求配置
30
    defaultRequest {
31
        url("https://api.example.com/")
32
        contentType(ContentType.Application.Json)
33
    }
34
}

5.3 发起请求#

1
@Serializable
2
data class KtorUser(val id: Long, val name: String, val email: String)
3

4
class KtorApiService(private val client: HttpClient) {
5

6
    suspend fun getUsers(): List<KtorUser> {
7
        return client.get("users").body()
8
    }
9

10
    suspend fun getUser(id: Long): KtorUser {
11
        return client.get("users/$id").body()
12
    }
13

14
    suspend fun createUser(user: KtorUser): KtorUser {
15
        return client.post("users") {
16
            setBody(user)
17
        }.body()
18
    }
19

20
    suspend fun deleteUser(id: Long): Boolean {
21
        val response = client.delete("users/$id")
22
        return response.status.value == 204
23
    }
24
}

6. 进阶实践#

6.1 动态 Base URL（多环境切换）#

1
object DynamicRetrofitClient {
2

3
    var currentBaseUrl: String = "https://api.example.com/"
4

5
    private val okHttpClient = OkHttpClient.Builder()
6
        .addInterceptor(HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.BODY))
7
        .build()
8

9
    val apiService: ApiService
10
        get() = Retrofit.Builder()
11
            .baseUrl(currentBaseUrl)
12
            .client(okHttpClient)
13
            .addConverterFactory(GsonConverterFactory.create())
14
            .build()
15
            .create(ApiService::class.java)
16
}

6.2 SSL 证书固定（Certificate Pinning）#

1
// 只信任指定的证书哈希
2
val certificatePinner = CertificatePinner.Builder()
3
    .add("api.example.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
4
    .build()
5

6
val client = OkHttpClient.Builder()
7
    .certificatePinner(certificatePinner)
8
    .build()

6.3 缓存策略#

1
val cacheDir = context.cacheDir
2
val cacheSize = 10 * 1024 * 1024L // 10MB
3

4
val cache = Cache(cacheDir, cacheSize)
5

6
val client = OkHttpClient.Builder()
7
    .cache(cache)
8
    .addInterceptor { chain ->
9
        val request = chain.request()
10
        // 有网络时，缓存有效期 60 秒
11
        val response = chain.proceed(request)
12
        response.newBuilder()
13
            .header("Cache-Control", "public, max-age=60")
14
            .build()
15
    }
16
    .addNetworkInterceptor { chain ->
17
        // 离线时使用缓存（有效期 24 小时）
18
        val request = chain.request().newBuilder()
19
            .header("Cache-Control", "public, only-if-cached, max-stale=${60 * 60 * 24}")
20
            .build()
21
        chain.proceed(request)
22
    }
23
    .build()

6.4 请求限流与重试（简易版）#

1
class RateLimitInterceptor(
2
    private val maxRequestsPerSecond: Int = 5
3
) : Interceptor {
4
    private val requestTimestamps = ArrayDeque<Long>()
5

6
    override fun intercept(chain: Interceptor.Chain): Response {
7
        val now = System.currentTimeMillis()
8
        // 移除 1 秒前的时间戳
9
        while (requestTimestamps.isNotEmpty() && requestTimestamps.first() < now - 1000) {
10
            requestTimestamps.removeFirst()
11
        }
12
        // 等待直到有空位
13
        if (requestTimestamps.size >= maxRequestsPerSecond) {
14
            Thread.sleep(requestTimestamps.first() + 1000 - now)
15
        }
16
        requestTimestamps.add(System.currentTimeMillis())
17
        return chain.proceed(chain.request())
18
    }
19
}

7. 方案对比总结#

特性	HttpURLConnection	OkHttp	Retrofit	Ktor Client
依赖量	0	1个库	2个库（含 OkHttp）	多模块
代码简洁度	⭐	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
拦截器	❌	✅	✅（通过 OkHttp）	✅（插件体系）
连接池	❌	✅	✅	✅
协程支持	需手动适配	需手动适配	原生支持	原生支持
多平台	❌	❌	❌	✅
社区成熟度	—	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
学习曲线	低	中	低	中

8. 选型建议#

1
需要 KMP 跨平台？
2
├── 是 → 用 Ktor Client
3
└── 否
4
    └── RESTful API 为主？
5
        ├── 是 → Retrofit + OkHttp + Coroutines（首选）
6
        └── 否 → OkHttp 原生（WebSocket、文件下载等特殊场景）

一句话总结：如果你做纯 Android 开发，直接用 Retrofit + OkHttp 就好，这是社区验证过的黄金组合。如果你的项目涉及 Kotlin Multiplatform，Ktor Client 是无脑首选。

音乐

音乐

前言#

1. 方案总览#

2. HttpURLConnection：最底层的方式#

2.1 GET 请求#

2.2 POST 请求#

2.3 优缺点#

3. OkHttp：市场占有率最高的 HTTP 引擎#

3.1 添加依赖#

3.2 基本用法#

3.3 拦截器（Interceptor）—— OkHttp 的灵魂#

3.4 文件上传（Multipart）#

3.5 与协程结合#

4. Retrofit：注解式 HTTP 客户端#

4.1 添加依赖#

4.2 定义 API 接口#

4.3 数据模型#

4.4 构建 Retrofit 实例#

4.5 在 ViewModel 中调用#

4.6 封装统一响应处理#

5. Ktor Client：跨平台新势力#

5.1 添加依赖#

5.2 基本配置#

5.3 发起请求#

6. 进阶实践#

6.1 动态 Base URL（多环境切换）#

6.2 SSL 证书固定（Certificate Pinning）#

6.3 缓存策略#

6.4 请求限流与重试（简易版）#

7. 方案对比总结#

8. 选型建议#

参考资料#

文章分享

评论区