介绍
Retrofit 将你的HTTP API转化为一个Java接口
public interface GitHubService {
@GET("users/{user}/repos")
Call<List<Repo>> 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<List<Repo>> repos = service.listRepos("octocat");
可以使用注解去描述一个HTTP请求：
- URL参数替换与查询参数支持
- 将对象转换为请求报文体（例如，JSON，protocol buffers）
- 多媒体支持和文件上传
API声明
接口上的注解与其参数表明如何处理请求
请求方法
每一个方法必须有一个HTTP注解，这个注解需要提供请求方法和URL的相对路径。
有五种内置的注解，分别为：GET, POST, PUT, DELETE与HEAD。请求的相对URL也是在注解中指定的。
@GET("users/list")
你可以在URL中指定查询参数
@GET("users/list?sort=desc")
URL的操作
我们可以在方法中使用替换块或参数来动态更新请求URL。替换块是一个被{与}包围着的字母或数字组成的字符串。相应的参数必须使用 @Path 与相同的字符串注释起来。
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);
GET中的查询参数也应该这样添加
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);
更复杂的GET查询参数可以使用Map进行添加
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);
请求体
可以使用 加了 @Body 注解的对象作为一个HTTP请求的请求体
@POST("users/new")
Call<User> createUser(@Body User user);
如果你在创建Retrofit对象时指定了转换器，则会使用该转换器转换对象为相应的请求体。如果没有指定转换器，则只能使用 RequestBody。
表单与多媒体数据
可以申明方法为发送表单数据或多媒体数据
可以在方法上使用 @FormUrlEncoded 注解来发送表单数据。表单中要提交的键值对数据可以通过该方法参数中的 @Field 注解指定。
@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);
可以在方法上使用 @Multipart 注解来发送多媒体数据。要提交的数据可以通过方法参数中的 @Part 注解指定。
@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
多媒体数据使用的转换器也是Retrofit转换器中的一个，当然，我们也可以自己实现RequestBody来处理数据的序列化。
请求头的操作
你可以通过使用 @Headers 注解来指定静态的请求头
@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();
@Headers({
"Accept: application/vnd.github.v3.full+json",
"User-Agent: Retrofit-Sample-App"
})
@GET("users/{username}")
Call<User> getUser(@Path("username") String username);
注意：headers中的项不能被重写覆盖，所有拥有相同名字的headers都会被包含在请求中。
一个请求的header可以使用 @Header 注解进行动态的更新，当然，相关的参数也应该在 @Header 中提供。如果值为空的话，那个这个header就会被忽略。因此，值的 toString() 方法将会被调用，并且作为其header的值。
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
与查询参数类似，Map也可以被用在header中，用来指定复杂的header组合。
@GET("user")
Call<User> getUser(@HeaderMap Map<String, String> headers)
可以使用OkHttp拦截器指定需要添加到每个请求的请求头。
同步请求 VS 异步请求
Call 实例可以通过同步或异步的方式执行。每个实例本来应当只能被调用一次，但调用 clone() 方法则会创建一个新的可用的实例。
在Android中，回调函数将会通过主线程执行。但在JVM中，回调函数将会在调用HTTP请求的同一个线程中执行。
Retrofit配置
Retrofit是将API接口转换为可调用对象的类。默认情况下，Retrofit将为您的平台提供合理的默认值，但它允许自定义。
转换器
默认情况下，Retrofit只能将HTTP主体反序列化为OkHttp的ResponseBody类型，并且只能接受其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);
定制转换器
如果您需要与使用 Retrofit 不支持开箱即用的内容格式的API（例如YAML，txt，自定义格式）进行通信，或者您希望使用其他库来实现现有格式，则可以轻松创建你自己的转换器。创建一个扩展 Converter.Factory 的类，并在构建适配器时传入实例。
下载
MAVEN
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>(insert latest version)</version>
</dependency>
GRADLE
implementation 'com.squareup.retrofit2:retrofit:(insert latest version)'
