介绍
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参数替换和查询参数支持；
＊请求主体的对象转换；
＊多个请求主体和文件上传。
API声明
接口中方法的注解和它的参数指定请求怎么被处理。
请求方法
每个方法必须有提供请求方法和相对URL的HTTP注解。有五种注解：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 createUser(@Body User user);
表格编码和多参数
当在方法前添加@FormUrlEncoded注解的时候表示以表格编码的方式发送数据。每个键值对使用@Field包含的名字和提供值的对象来表示。
@FormUrlEncoded
@POST("user/edit")
Call updateUser(@Field("first_name") String first, @Field("last_name") String last);
多参数请求使用@Multipart。Parts使用@Part注解声明。
@Multipart
@PUT("user/photo")
Call updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
Header操作
方法可以通过@Header注解使用静态的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);
注意headers不会被彼此覆盖。所有相同名字的的headers会被包含在请求中。
一个请求Header可以使用@Header注解动态的更新。相应的参数必须使用@Header提供。如果值为null，header会被忽略。否则，值的toString的结果会被使用。
@GET("user")
Call getUser(@Header("Authorization") String authorization)
同步VS异步
Call实例可以同步执行也可以异步执行。每个实例智能执行一次，但是调用clone（）会创建一个新的实例来使用。
在Android，回调会在主线程中被执行。在JVM，回调会在执行HTTP请求的线程中执行。
Retrofit 配置
转换器
Retrofit是通过你的API接口转换为回调对象的类。默认情况下，Retrofit会有默认理智的配置，但是也允许自定义。
默认情况下，Retrofit只能反序列化HTTP body为OkHttp的ResponseBody类型而且只能接受RequestBody类型的@Body。
转换器可以添加来支持其他类型。为了方便提供了六个模块来适应流行的序列化库。
＊Gson: com.squareup.retrofit2:converter-goon
＊Jackson: com.squareup.retrofit2:converter-jackson
＊Moshi: com.squareup.retrofit2:converter-mosh
＊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);
自定义转换器
如果api使用的是Retrofit不支持的内容格式（比如YAML，txt，自定义格式）或者希望使用不同的库来实现已经存在的格式，可以创建需要的转换器。创建一个继承自Converter.Factory的类，然后在创建适配器的时候传入到实例中。