Retrofit

定义

Retrofit是一个类型安全的HTTP客户端库，适用于Android平台与Java虚拟机，由Square公司开发并开源。它的核心作用是充当HTTP接口与编程语言接口之间的转换层：开发者用接口声明网络请求，Retrofit负责在运行时生成该接口的实现对象^[3]。

与直接使用底层网络类相比，Retrofit把请求方法、地址、参数和响应类型统一写在接口注解中，减少了手工拼接地址、设置请求头与解析响应体的重复代码。它本身不完成实际的字节传输，而是依赖OkHttp执行网络通信^[1]。

原理

Retrofit的工作方式基于动态代理。声明为接口的服务类型在运行时被动态生成实现类，方法上的注解在运行时被解析成请求描述，进而构造出HTTP请求。为降低反射开销，解析结果会被缓存复用。

请求的描述由注解完成。请求方法注解如@GET、@POST、@PUT、@DELETE、@PATCH、@HEAD、@OPTIONS用于指定HTTP方法与相对路径；参数注解如@Path替换路径占位符，@Query与@QueryMap添加查询参数，@Body发送请求体，@Field与@FieldMap提交表单字段，@Header与@Headers添加请求头。此外还有@FormUrlEncoded、@Multipart、@Streaming等请求类型注解，分别对应表单提交、文件上传和流式响应。

响应数据与接口返回类型之间的转换由转换器(Converter)完成，常见的实现支持JSON、XML、Protocol Buffers等格式，Gson、Moshi、Jackson、kotlinx.serialization等序列化库均有对应组件^[4]。请求的执行机制则可以由调用适配器(CallAdapter)替换，使接口能够返回RxJava的Observable、Java 8的CompletableFuture，或直接返回Kotlin挂起函数的结果^[4]。

底层通信交给OkHttp处理，包括连接建立、TLS握手、连接复用、超时控制与缓存^[2]。开发者可以向Retrofit传入一个配置好的OkHttp实例，以设置拦截器、套接字工厂或超时数值。

发展历程

Retrofit由Square公司开源，首次发布时间为2013年5月13日^[1]。早期版本的适配器类型名为RestAdapter，配置项使用endpoint；在后续版本中该类型更名为Retrofit，配置项改称baseUrl。

2.0版本是变化较大的一次迭代。该版本改为强制依赖OkHttp，不再在HTTP客户端层保留抽象；同时取消了内置的默认转换器，使用前必须显式声明所用转换器，核心代码也不再依赖序列化相关的第三方库。执行机制也随之改为可插拔形式，RxJava支持由内置转为通过扩展组件提供。经过这一系列调整，库的体积缩减了约60%。

版本3.0.0把对OkHttp的依赖从3.14升级到4.12，因而引入了Kotlin的传递依赖；3.x版本与2.x版本保持向后的二进制兼容，针对2.x编译的库仍可在3.x下使用^[5]。当前稳定版本要求Java 8及以上或Android API 21及以上。

应用

Retrofit主要用于Android应用与服务器之间的数据通信，列表加载、用户登录、图片上传等场景的HTTP请求均可用它实现^[2]。它遵循注解式接口的写法，接口方法的返回类型决定使用同步调用、异步回调还是协程，调用方通过execute()获得同步结果，通过enqueue()提交异步回调^[3]。

在实际工程中，Retrofit常与仓库模式配合使用，由仓库类封装网络操作并向上层暴露结果，使调用方无需了解数据的存放方式。它也可以与ViewModel等生命周期组件结合，使数据在配置变更时得以保留。此外，Retrofit提供了Mock组件，可在不连接网络的情况下为接口提供模拟实现，便于本地测试^[4]。

局限

Retrofit的网络操作不能在Android的主线程上执行，否则系统会抛出NetworkOnMainThreadException，因此调用方必须自行通过协程或enqueue()处理方法所在的线程。

该库不包含日志功能，请求与响应的日志需要通过自定义OkHttp拦截器实现。它也不提供WebSocket能力，这类需求需由底层的OkHttp提供支持。

从2.0版本起，Retrofit不再附带默认的数据转换器，若未显式声明可用的转换器，运行时就会报错，因为此时无法验证响应的类型。在安全方面，2.0.0至2.5.0之前的版本曾存在路径遍历漏洞，该问题在2.5.0版本中修复^[1]。

参见

• OkHttp —— Retrofit底层依赖的网络库，负责实际的HTTP传输。

• 动态代理 —— Retrofit生成接口实现所依赖的运行时机制。

• Kotlin协程 —— Retrofit支持的一种请求执行与线程处理方式。

• REST —— Retrofit接口注解所遵循的接口设计风格。

• 序列化 —— 转换器组件所完成的对象与数据格式互转过程。

• Android —— Retrofit最主要的应用平台。