Retrofit — 是什么、HTTP库及在应用程序中的使用

什么是Retrofit？

Retrofit是一个用于在Android应用中执行HTTP请求的库，由Square公司开发。它提供了一种声明式的API定义方法，通过带有注解的Java接口进行定义，使得网络通信代码清晰且可预测。

Retrofit的核心思想是开发者将API描述为带有方法和注解的接口，然后库自动生成实现。这种方法确保了所有端点都是类型化的，URL或参数中的错误会在编译阶段发现，而不是在运行时。

Retrofit支持所有流行的HTTP方法和数据格式。该库由Square和社区积极维护：新版本定期发布，当前版本2.11支持Java 17和Kotlin 2.0。Retrofit仍然是Android最流行的HTTP客户端。

Retrofit基于OkHttp运行——同样由Square开发的高效HTTP客户端。这种组合提供了缓存、请求拦截和传输协议级别的连接管理。该库支持同步和异步调用。

自2013年首次发布以来，Retrofit经历了多次重大更新。当前版本Retrofit 2基于第一版的经验完全重写，为异步提供了更灵活的转换器和适配器系统。

Retrofit的架构遵循分离责任原则：接口只定义API契约，转换器负责序列化，适配器管理异步。这允许在不修改其余代码的情况下替换任何组件。例如，可以在不更改端点定义的情况下从Gson切换到Moshi。

Retrofit的主要功能

Retrofit提供了涵盖移动应用中几乎所有网络通信场景的功能集。关键优势是声明式的API定义风格。

端点的声明式注解

注解 @GET、@POST、@PUT、@PATCH、@DELETE和@HTTP允许直接在接口中定义HTTP方法和URL模板。路径参数通过@Path设置，查询参数通过@Query设置，请求体通过@Body设置。这种方法使应用的API层完全类型化。

用于序列化的转换器

转换器将HTTP响应转换为Java对象，反之亦然。Retrofit支持Gson、Moshi、Jackson、Protobuf和Wire。开发者通过Converter.Factory连接所需的转换器，库会自动将其应用于所有请求和响应。

用于异步的适配器

适配器 CallAdapter允许更改API方法的返回类型。可以使用RxJava的Observable、Kotlin协程的Deferred或LiveData代替标准Call。这使网络请求与所选的应用程序架构集成在一起。

动态URL和标头

动态 URL通过@Url注解设置，允许在运行时传递端点。标头可以通过@Headers静态指定或通过@Header参数动态指定。对于所有请求的全局标头，使用OkHttp拦截器为每个传出请求添加标头。

Retrofit如何工作？

Retrofit分三个阶段工作：定义API接口、创建Retrofit实例和执行请求。库根据注解和转换器在运行时生成接口的实现。

请求的生命周期

当调用API方法时，Retrofit根据注解和参数创建一个Request对象。请求被传递给OkHttp执行。收到响应后，库将其传递给Converter.Factory转换为所需类型。CallAdapter将结果包装在异步包装器中。每个阶段都可以自定义。

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

val api = retrofit.create(ApiService::class.java)

Retrofit的安装和配置

安装 Retrofit通过Gradle进行——Android的标准构建系统。该库通过Maven Central分发，需要向项目的build.gradle中添加几个依赖项。

添加依赖项

在build.gradle文件中（模块级别）添加Retrofit、Gson转换器和OkHttp的依赖项。建议将库版本提取到根build.gradle中的变量进行集中管理。Retrofit 2至少需要Android API 21。

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

创建Retrofit实例

Retrofit实例通过Builder创建。必需参数：baseUrl和ConverterFactory。建议为Retrofit和OkHttpClient使用单例，以避免创建冗余连接。添加logging-interceptor可以简化开发过程中网络请求的调试。

对于Kotlin项目，建议在API接口中使用suspend函数而不是Call类型。这简化了代码，并允许使用协程的结构化并发。从Call迁移到suspend时，只需更改接口中的返回类型——其余代码会自动适应。

Retrofit使用示例

示例下面展示了在Android应用中使用Retrofit的典型场景：从简单的GET请求到向服务器上传文件。

带查询参数的GET请求

带查询字符串参数的简单GET请求——基本操作。@Query注解自动将参数添加到URL，suspend函数允许从协程调用请求而不阻塞主线程。

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

带JSON体的POST请求

带JSON体的POST请求使用@Body注解传递对象。GsonConverterFactory自动将User对象序列化为JSON。Kotlin协程确保在后台线程中执行请求，无需Callback接口。

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "安娜·伊万诺娃", email = "anna@example.com")
val created = api.createUser(user)

通过Multipart上传文件

@Multipart注解与@Part允许将文件上传到服务器。Retrofit会自动创建带有必要标头的multipart请求。OkHttp通过RequestBody管理上传进度，允许向用户显示进度指示器。

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Retrofit中的错误处理和拦截器

错误处理在Retrofit中基于OkHttp机制和Kotlin协程的组合。OkHttp拦截器允许记录请求、添加认证标头以及在错误到达应用程序代码之前处理它们。

对于集中式错误处理，通常在API调用周围创建一个sealed class Result形式的包装器。这样的类包含两个子类：带数据的Success和带异常的Error。ViewModel接收统一的结果，并可以显示相应用户界面状态，而无需在每个函数中重复错误处理代码。

拦截器有两种类型：应用程序拦截器在发送到服务器之前修改请求，网络拦截器在收到响应后工作。例如，拦截器可以在收到401时自动刷新访问令牌，并用新令牌重试请求，无需开发者干预。

通过Interceptor记录请求

日志拦截器 HttpLoggingInterceptor——调试网络请求时必不可少的工具。它在Logcat中显示请求方法、URL、标头、主体和响应代码。日志级别可以配置：BASIC用于最少信息，HEADERS用于标头，BODY用于完整内容。在生产环境中，建议使用BASIC或完全禁用日志记录。

OkHttp中的拦截器分为两种类型：用于修改请求的应用程序拦截器和用于处理原始网络数据的网络拦截器。日志拦截器会自动在Logcat中显示请求和响应的详细信息。

协程级别的错误处理通过suspend函数调用周围的try-catch进行。Retrofit返回4xx和5xx代码的HttpException、无网络时的UnknownHostException和超时的SocketTimeoutException。建议使用sealed class Result进行统一处理。