android-retrofit

使用 Retrofit 进行 Android 网络通信

说明

使用 Retrofit 实现网络层时，请遵循这些现代 Android 最佳实践（2025 年）。

1. URL 操作

Retrofit 支持通过替换占位符和查询参数动态更新 URL。

• 动态路径：在相对 URL 中使用 {name}，并在参数中使用 @Path("name")。
• 查询参数：使用 @Query("key") 添加单个参数。
• 复杂查询：使用 @QueryMap Map<String, String> 添加动态参数集合。

interface SearchService {
    @GET("group/{id}/users")
    suspend fun groupList(
        @Path("id") groupId: Int,
        @Query("sort") sort: String?,
        @QueryMap options: Map<String, String> = emptyMap()
    ): List<User>
}

2. 请求正文与表单数据

你可以将对象作为 JSON 正文发送，也可以使用表单编码或多部分格式。

• @Body：使用已配置的转换器（JSON）序列化对象。
• @FormUrlEncoded：以 application/x-www-form-urlencoded 格式发送数据。使用 @Field。
• @Multipart：以 multipart/form-data 格式发送数据。使用 @Part。

interface UserService {
    @POST("users/new")
    suspend fun createUser(@Body user: User): User

    @FormUrlEncoded
    @POST("user/edit")
    suspend fun updateUser(
        @Field("first_name") first: String,
        @Field("last_name") last: String
    ): User

    @Multipart
    @PUT("user/photo")
    suspend fun uploadPhoto(
        @Part("description") description: RequestBody,
        @Part photo: MultipartBody.Part
    ): User
}

3. 请求头操作

可以为方法静态设置请求头，也可以通过参数动态设置。

• 静态请求头：使用 @Headers。
• 动态请求头：使用 @Header。
• 请求头映射：使用 @HeaderMap。
• 全局请求头：使用 OkHttp 拦截器。

interface WidgetService {
    @Headers("Cache-Control: max-age=640000")
    @GET("widget/list")
    suspend fun widgetList(): List<Widget>

    @GET("user")
    suspend fun getUser(@Header("Authorization") token: String): User
}

4. Kotlin 支持与响应处理

使用 suspend 函数时，返回类型有两种选择：

1. 直接正文（User）：返回反序列化后的正文。对于非 2xx 响应，会抛出 HttpException。
2. Response<User>：提供对状态码、请求头和错误正文的访问。对于非 2xx 响应，不会抛出异常。

@GET("users")
suspend fun getUsers(): List<User> // Throws on error

@GET("users")
suspend fun getUsersResponse(): Response<List<User>> // Manual check

5. Hilt 与序列化配置

在 Hilt 模块中将 Retrofit 实例作为单例提供。

@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {

    @Provides
    @Singleton
    fun provideJson(): Json = Json {
        ignoreUnknownKeys = true
        coerceInputValues = true
    }

    @Provides
    @Singleton
    fun provideOkHttpClient(): OkHttpClient = OkHttpClient.Builder()
        .addInterceptor(HttpLoggingInterceptor().apply { level = HttpLoggingInterceptor.Level.BODY })
        .connectTimeout(30, TimeUnit.SECONDS)
        .build()

    @Provides
    @Singleton
    fun provideRetrofit(okHttpClient: OkHttpClient, json: Json): Retrofit = Retrofit.Builder()
        .baseUrl("https://api.github.com/")
        .client(okHttpClient)
        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
        .build()
}

6. Repository 中的错误处理

始终在 Repository 层处理网络异常，以保持 UI 状态整洁。

class GitHubRepository @Inject constructor(private val service: GitHubService) {
    suspend fun getRepos(username: String): Result<List<Repo>> = runCatching {
        // Direct body call throws HttpException on 4xx/5xx
        service.listRepos(username)
    }.onFailure { exception ->
        // Handle specific exceptions like UnknownHostException or SocketTimeoutException
    }
}

7. 检查清单

• 所有网络调用都使用 suspend 函数。
• 如果需要处理特定状态码（例如 401 Unauthorized），优先使用 Response<T>。
• 使用 @Path 和 @Query，而不是手动拼接字符串来构造 URL。
• 为 OkHttpClient 配置日志记录（用于调试）和合理的超时时间。
• 将 API DTO 映射为 Domain 模型，以实现各层解耦。