Retrofit中文文档

• 最近公司的新项目终于赶上潮流，使用了Retrofit+Rxjava的方式来进行联网请求。之前也看过一些关于Retrofit的文章，不过大多数都不是很友好（也可能是没找对），今天准备认真研究一下其中原理，发现它官网给出的文档倒是看起来很舒服，抱着加深印象的态度，就一边看一边翻译，也能给英语能力不好的朋友提供一些参考，如有不妥的地方，欢迎大家拍砖。
• 先给出官方文档的地址，有兴趣的小伙伴，可以自己去查看。Retrofit

Retrofit

一个在Android和Java上类型安全的HTTP客户端

介绍

• Retrofit使你的HTTP API变成一个java接口

• public interface GitHubService {
    @GET("users/{user}/repos")
    Call> listRepos(@Path("user") String user);
  }
  

• Retrofit类生成一个GitHubService的是实例

• Retrofit retrofit = new Retrofit.Builder()
      .baseUrl("https://api.github.com/")
      .build();
  
  GitHubService service = retrofit.create(GitHubService.class);
  

• 通过GitHubService产生的每一个call都能产生一个同步或者异步的HTTP请求到远程的服务器
  Call> repos = service.listRepos("octocat");

• 使用注解去描述HTTP请求：

  • 替代url参数和查询参数的支持情况
  • 请求体的类型转换（e.g.,json,协议缓冲区）
  • 多方请求体和文件上传

API声明

• 写在接口方法上的注解显示一个请求如何被处理。

请求方法

• 每一个请求方法必须要有一个提供请求方法和关联URL的HTTP注解。Retrofit有五种内置的注解：GET、POST、PUT、DELETE和HEAD。在注解中资源的相对URL是详细指明的。

  @GET("users/list")
  

• 你也可以在URL中查询详细的参数

  @GET("users/list?sort=desc")
  

URL操作

• 在方法中使用可替代的块和参数来使一个请求URL动态的更新。一个可替代的块是一个被“{}”包裹的文数串。对应的参数必须用 @Path 和相同的字符串来声明。
  @GET("group/{id}/users")
  Call> groupList(@Path("id") int groupId);
• 查询参数也可以被添加。
  @GET("group/{id}/users")
  Call> groupList(@Path("id") int groupId ,@Query("sort" String sort));
• 对于复杂的查询参数，可以使用一个Map。
  @GET("group/{id}/users")
  Call> groupList(@Path("id"） int groupId,@QueryMap Map options)

请求体

• 一个对象可以是指定的通过使用带有@Body注解的HTTP 请求体
  @POST("users/new")
  Call creatUser(@Body User user);
• 也可以通过在Retrofit的实例上转换类型来修改这个对象。如果没有添加转换器，那么只有请求体可以被使用。

编码形式和更多部件

• 方法也可以被声明来发送编码形式和多部分数据
• 当@FormUrlEncoded 出现在方法上时编码数据就被发送了。每一个键值对通过包含名字和提供值的对象@Filed来注解。
  @FormUrlEncoded
  @POST("user/edit")
  Call updateUser(@Field ("first_name") String first,@Field("last_name") String last)
• 当@Multipart注解出现在方法上，说明使用了多组件的请求。使用@Part注解声明组件。
  @Multipart
  @PUT("user/photo")
  Call updateUser(@Part（"photo"） RequsetBody photo,@Part("description") RequestBody description);
• 多组件的组件使用了一种Retrofit的转换器或者可以实现RequestBody来处理它们自己的序列。

头部操作

• 你可以使用@Header注解来为一个方法设置静态的头部
  @Headers("Cache-Control：max-age=640000")
  @GET("widget/list")
  Call> widgetList();

  @Headers({
      "Accept: application/vnd.github.v3.full+json",
      "User-Agent: Retrofit-Sample-App"
  })
  @GET("users/{username}")
  Call getUser(@Path("username") String username);
  

• 要注意头部是不会互相重写的，所有的头部使用相同的名字都会被包含进请求中。

• 一个请求头可以被动态更新通过使用@Header注解。必须提供一个对应的参数给@Header。如果这个值是null，头部将会被忽略。
  @GET("user")
  Call getUser(@Header("Authorization") String authorization)

• 可以使用的OkHttp的拦截器（interceptor）来指定需要添加到请求上的头部。

同步与异步

• Call 对象可以同步地或异步地执行。每一个对象只能使用一次，但是调用clone()会创建一个可以被调用的新对象。
• 在Android中,回调（callbacks）会在主线程中执行。在JVM中，回调（callbacks）会在与执行HTTP请求的相同线程。

Retrofit配置

• Retrofit类会根据你的API接口转变为可调用的对象。默认情况下，Retrofit会给你返回一个和你的值但他同样允许你自定义。

转换器（converters）

• 默认情况下，Retrofit只能把HTTP bodies反序列化成OkHttp的ResponseBody的类型并且只能接受它的RequsetBody的类型是@Body。

• 转换器可以被添加来支持其他的类型。为了方便，添加了6个同级的模块来适配流行的序列化库。

  • Gson: com.squareup.retrofit2:converter-gson

  • Jackson: com.squareup.retrofit2:converter-jackson

  • Moshi: com.squareup.retrofit2:converter-moshi

  • Protobuf: com.squareup.retrofit2:converter-protobuf

  • Wire: com.squareup.retrofit2:converter-wire

  • Simple XML: com.squareup.retrofit2:converter-simplexml
    Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars

• 下面是一个使用GsonConverterFactory类来生成一个使用Gson来反序列化的GithubService interface的实现的例子
  Retrofit retrofit = new Retrofit.Builder()
  .baseUrl("https://api.github.com")
  .addConverterFactory(GsonConverterFactory.create())
  .build();
  GitHubService service = retrofit.create(GitHubService.class);

自定义转换器

• 如果你要和一个使用Retroft不支持的内容格式的API交互，或者你希望使用一个不同的库来实现已经存在的格式，你可以很容易的创建你自己的转换器。创建一个继成自Convert.Factory 的类然后再创建适配器的时候写到一个实例中就可以了。