官网
https://square.github.io/retrofit/
Java 文档
https://square.github.io/retrofit/2.x/retrofit/
介绍
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 中的方法都可以向远程 web 服务器发出同步或异步的 HTTP 请求：
Call<List<Repo>> repos = service.listRepos("octocat");
可以通过使用注解来描述具体的 HTTP 请求：
- 支持 URL 参数替换和指定查询参数
- 支持对象转换成请求体(例如 JSON、协议缓冲区等)
- 支持 Multipart 的请求体和文件上传
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("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);
对于复杂的查询参数组合，可以使用 Map 以 key-value 形式指定多个参数，需要使用 @QueryMap 注解：
@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。
格式编码和复合类型 （FORM ENCODED & MULTIPART）
还可以声明方法来发送格式编码和复合类型的数据。
当方法上出现 @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 来处理自己的序列化。
头操作 （HEADER MANIPULATION）
可以使用 @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);
注意，请求头不会相互覆盖。所有具有相同名称的请求头都将包含在请求中。
另外，可以使用 @Header 注解来动态更新请求标头。但必须向 @Header 提供相应的参数。
如果值为 null，这个请求头将被省略。不为空的话，将对值和使用的结果调用 toString 。
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
与查询参数类似，对于复杂的请求标头组合，可以使用 Map：
@GET("user")
Call<User> getUser(@HeaderMap Map<String, String> headers)
需要添加到每个请求中的请求头可以使用 OkHttp intercepter 指定。
同步与异步
Call 的实例可以同步执行，也可以异步执行。
每个实例只能使用一次，但是调用 clone() 将创建一个可以使用的新实例。
在 Android 上，回调将在主线程上执行。在 JVM 上，回调将发生在执行 HTTP 请求的同一线程上。
Retrofit 配置
Retrofit 是将 API 接口转换为可调用对象的类。默认情况下，Retrofit 将为您的平台提供健全的默认设置，但它允许定制。
转换器 CONVERTERS
默认情况下，Retrofit 只能将 HTTP body 反序列化为 OkHttp 的 ResponseBody 类型，并且只能接受 @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);
自定义转换器
如果您需要与使用特殊格式内容的 API 进行通信，而这种内容格式是 Retrofit 不支持的(例如YAML、txt、定制格式)，或者您希望使用不同的库来实现现有的格式，那么您可以轻松地创建自己的转换器。
创建一个类继承 Converter.Factory class 并在构建适配器时传入实例就可以了。
开发环境配置
MAVEN
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>2.5.0</version>
</dependency>
GRADLE
implementation 'com.squareup.retrofit2:retrofit:2.5.0'
```
