Retrofit 官方文档

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了Retrofit 官方文档相关的知识,希望对你有一定的参考价值。

参考技术A 官网
https://square.github.io/retrofit/
Java 文档
https://square.github.io/retrofit/2.x/retrofit/

Retrofit 可以将 HTTP API 转换为 Java 接口:

通过 Retrofit 类生成一个 GitHubService 接口的实现类实例:

每个 GitHubService 中的方法都可以向远程 web 服务器发出同步或异步的 HTTP 请求:

可以通过使用注解来描述具体的 HTTP 请求:

接口方法和其参数上的注解指明了请求需要如何处理。

每个方法都必须有一个 HTTP 注解,用于提供请求类型和对应的 URL 。
有五个内置的注释可以使用:GET、POST、PUT、DELETE 和 HEAD。
对应的 URL 也需要同时在注解中指定:

还可以在 URL 中指定查询参数。

可以使用方法上的替换块和参数动态更新请求的 URL。
替换块是一个由 和 包围的字符串。
对应的参数必须使用相同的字符串用 @Path 进行注解:

还可以添加查询参数:

对于复杂的查询参数组合,可以使用 Map 以 key-value 形式指定多个参数,需要使用 @QueryMap 注解:

可以使用 @Body 注释将对象指定为 HTTP 请求体:

参数对象还可以通过在 Retrofit 实例上指定的转换器进行转换。
如果没有添加转换器,则只能使用 RequestBody。

还可以声明方法来发送格式编码和复合类型的数据。
当方法上出现 @FormUrlEncoded 时,发送格式编码的数据。
每个键值对都用 @Field 注释,在其后面是具体的名称和提供值的对象:

当方法上出现 @Multipart 时,将使用复合类型的请求。每个部分使用 @Part 注释声明:

复合类型的部件可以使用一个 Retrofit 的转换器,或者实现 RequestBody 来处理自己的序列化。

可以使用 @Headers 注解为方法设置静态的请求头:

注意,请求头不会相互覆盖。所有具有相同名称的请求头都将包含在请求中。

另外,可以使用 @Header 注解来动态更新请求标头。但必须向 @Header 提供相应的参数。
如果值为 null,这个请求头将被省略。不为空的话,将对值和使用的结果调用 toString 。

与查询参数类似,对于复杂的请求标头组合,可以使用 Map:

需要添加到每个请求中的请求头可以使用 OkHttp intercepter 指定。

Call 的实例可以同步执行,也可以异步执行。
每个实例只能使用一次,但是调用 clone() 将创建一个可以使用的新实例。
android 上,回调将在主线程上执行。在 JVM 上,回调将发生在执行 HTTP 请求的同一线程上。

Retrofit 是将 API 接口转换为可调用对象的类。默认情况下,Retrofit 将为您的平台提供健全的默认设置,但它允许定制。

默认情况下,Retrofit 只能将 HTTP body 反序列化为 OkHttp 的 ResponseBody 类型,并且只能接受 @Body 的请求体类型。
可以添加转换器来支持其他类型。有六个流行的序列化库可以提供方便:

下面是一个使用 GsonConverterFactory 类生成 GitHubService 接口实现的示例,该接口使用 Gson 进行反序列化:

如果您需要与使用特殊格式内容的 API 进行通信,而这种内容格式是 Retrofit 不支持的(例如YAML、txt、定制格式),或者您希望使用不同的库来实现现有的格式,那么您可以轻松地创建自己的转换器。
创建一个类继承 Converter.Factory class 并在构建适配器时传入实例就可以了。

Retrofit2源码解析

  最近项目将网络框架换成Retrofit2.0.2,文中说的Retrofit都是指的Retrofit2这里要说明一下,毕竟和Retrofit1差别还是蛮大的,结合Okhttp,RxJava还是比较好用的,网上有很多前辈介绍过使用方法,本文是想研究一下Retrofit的源码。关于Retrofit的介绍可以查阅Retrofit的官方网站
  直接进入主题:(注本文是结合RxJava介绍的,最好可以了解一下RxJava不了解也没有关系,大部分的思想是一样的)
  Retrofit的基本使用
  Retrofit使用是非常简单的,在上边的官网上介绍的也非常详细。但是为了后边的分析,还是把使用的代码贴在这儿:
  一般在项目中会将需要请求网络方法写在一个接口中,如下:

 public interface GitHubService {
    @GET("users/{user}/repos")
    Observable<List<Repo>> listRepos(@Path("user") String user);
 }

  如果要使用Retrofit还需要构建Retrofit的对象:

Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("https://api.github.com/")
            .addConverterFactory(GsonConverterFactory.create())
            .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
            .build();

  主要就是配置baseUrl,ConverterFactory,CallAdapterFactory。这里用的是Gson,和RxJava所以相应的就是GsonConverterFactoryRxJavaCallAdaperFactory这个在后边的源码分析中会用到。
  最后直接调用就可以了:
  

GitHubService service = retrofit.create(GitHubService.class);

service.listRepos("octocat")
              .observeOn(AndroidSchedulers.mainThread())
              .subscribeOn(Schedulers.io())
              .subscribe(list->{
              if(list!=null){
              //TODO 取得数据后逻辑处理
              }
             });

  可以说,代码还是非常简洁的。用起来也很容易上手。
  Retrofit工作流程
  如上面的使用中我们可以看到:
1.通过Retrofit.Builder().build()构建Retrofit实例。
2.调用Retrofit的create()方法将生成接口GitHubService的实例。
3.调用GitHubService的listRepos()方法返回Observable<List<Repo>>,这里的GitHubService实例实际上是个代理对象,这个下文再说。
  下图是我整理的Retrofit运行时主要节点的时序图,当然不是所有的过程都反映出来了。
  这里写图片描述
  看不懂没关系,一步一步来,先看看Retrofit源码的构成: