Retrofit (1)

Retrofit https://square.github.io/retrofit/ 阅读
Android和Java的类型安全HTTP客户端
简介
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(Retrofit类生成接口的实现)的每个Call都可以向远程web服务器发出同步或异步HTTP请求。

Call<List<Repo>> repos = service.listRepos("octocat");

使用注释来描述HTTP请求:

1. URL参数替换和查询参数支持
2. 对象转换为请求体(例如JSON、协议缓冲区)
3. 多部分请求体和文件上传

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<List<User>> groupList(@Path("id") int groupId);

还可以添加查询参数

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);

复合的参数可以封装成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);

这个(User)对象将使用在Retrofit实例上指定的转换器进行转换。如果没有添加转换器，则只能使用RequestBody。

FORM ENCODED AND MULTIPART
方法也可以声明为发送表单编码和多部分数据。
当@ formurlencodes出现在方法中时，将发送表单编码的数据。
每个键-值对都用@Field注释，@Field包含名称和提供值的对象。

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

当方法上出现@Multipart时，将使用Multipart请求。使用@Part注解声明部件

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

多部分部件使用一个Retrofit的转换器，或者它们可以实现RequestBody来处理自己的序列化

HEADER MANIPULATION 头操作
可以使用@Headers注解为方法设置静态header

@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，则省略header。否则，将对值调用toString(),并使用这个结果。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

与查询参数类似，对于复杂的标题组合，可以使用map

@GET("user")
Call<User> getUser(@HeaderMap Map<String, String> headers)

需要添加到每个请求中的头可以使用OkHttp拦截器指定

同步与异步
call 实例可以同步执行，也可以异步执行。每个实例只能使用一次，但是调用clone()将创建一个可以使用的新实例。
在Android上，回调将在主线程上执行。在JVM上，回调将发生在执行HTTP请求的同一线程上。

Retrofit 配置
Retrofit是将API接口转换为可调用对象的类。默认情况下，Retrofit将为您的平台提供正常的默认设置，但它允许定制。
CONVERTERS 转换器
默认情况下，Retrofit只能将HTTP体反序列化为OkHttp的ResponseBody类型，并且只能接受@Body的RequestBody类型。
可以添加转换器来支持其他类型。六个同级模块改编了流行的序列化库，方便您使用
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);

CUSTOM CONVERTERS 自定义转换器
如果您需要与使用翻新不支持开箱即用的内容格式的API通信(例如YAML、txt、定制格式)，或者您希望使用不同的库来实现现有格式，那么您可以轻松地创建自己的转换器。继承 Converter.Factory，并在构建适配器时传入实例。

下载
GRADLE

implementation 'com.squareup.retrofit2:retrofit:(insert latest version)'

混淆
R8 /PROGUARD
如果您正在使用R8或ProGuard，请从该文件中添加选项。
您可能还需要OkHttp和Okio的规则，它们是这个库的依赖项。