本文是对Retrofit官网的翻译
1.介绍(Intorduction)
简单说来Retrofit实现的功能就是将HTTP API转化成了Java接口的形式。
官网是这样描述的：Retrofit truns your HTTP API into a Java interface
例子：
public interface GitHubService {
@GET("users/{user}/repos")
Call> listRepos(@Path("user") String user);
}
用Retrofit这个类可以生成对上述接口的实现类：
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com/")
.build();
GitHubService service = retrofit.create(GitHubService.class);
接口返回的每个call对象都可以实现和远程web服务器的同步或者一步的通信
Call> repos = service.listRepos("octocat");
用注解的形式来描述HTTP请求：
URL参数是可以替换的并且提供请求参数
对象可以转换成请求实体（例如JSON，protocol buffers）
多重请求和文件上传
2.API说明（API Declaration）
接口方法需要的注解和参数来声明了这个请求如何处理
2.1请求方法
每个方法必须有关于HTTP的注解来提供请求方式和相对的URL。这里有五种关于请求方式的注解：GET，POST，DELETE，和HEAD。请求资源的相对URL地址也需要在注解中指出。
@GET("users/list")
你也可以在URL中声明你的请求参数
@GET("users/list?sort=desc")
2.2URL操作
一个请求的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);
2.3请求实体
通过使用@Body注解可以实现将一个对象指定为HTTP的请求实体
@POST("users/new")
Call createUser(@Body User user);
这个参数对象会被Retrofit实例中的converter进行转化。如果没有给Retrofit实例添加任何converter的话则只有RequestBody可以作为参数使用。
2.4form encoded和multipart
方法也可以被声明来发送form-encoded和multipart
可以通过@FormUrlEncoded注解方法来发送form-encoded的数据。每个键值对需要用@Filed来注解键名，随后的对象需要提供值。
@FormUrlEncoded
@POST("user/edit")
Call updateUser(@Field("first_name") String first, @Field("last_name") String last);
也可以通过@Multipart注解方法来发送Mutipart请求。每个部分需要使用@Part来注解。
@Multipart
@PUT("user/photo")
Call updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
多部分请求的数据使用Retrofit的转换器或者自己实现的转换器来进行请求数据的序列化
2.5表头操作
你可以通过@Heather注解来给方法设置静态的表头
@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注解来实现头部的动态更新。相应的参数值必须提给表头。假如相应的值为null，则该头部会被忽略。否则的话， 值的 toString 方法将会被调用，并且使用调用结果。
@GET("user")
Call getUser(@Header("Authorization") String authorization)
你可以使用okHttp interceptor为每个请求添加需要的头部
2.6同步VS异步
Call实例既可以同步的执行也可以异步执行。一个实例只能被执行一次，但是，当调用clone（）将会产生一个新的实例供你使用。
在Android中，回调方法运行在主线程，在JVM，回调方法将和执行HTTP请求处于同一线程
3.Retrofit配置
Retrofit类会通过你定义的API接口转化为可调用的对象。默认情况下，Retrofit会返还给你合理的默认值，但也允许你进行指定。
3.1转化器（Converters）
默认情况下，Retrofit只能将HTTP体反序列化为OKHttp的 ResonseBody 类型，而且只能接收 RequestBody类型作为 @Body。
转化器的加入可以用于支持其他的类型。以下六个同级模块采用了常用的序列化库来为你提供方便。
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类生成 GitHubService的接口实现gson反序列化的例子。
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.addConverterFactory(GsonConverterFactory.create())
.build();
GitHubService service = retrofit.create(GitHubService.class);
3.2自定义转化器
如果你需要与没有使用Retrofit提供的内容格式的API进行交互的话或者是你希望使用一个不同的库来实现现有的格式，你也可以轻松创建使用自己的转化器。你需要创建一个继承自Converter.Factory的类并且在构建适配器的时候加入到实例里面。
网友评论