Retrofit使用详解

Retrofit：适用于Android和Java的类型安全的HTTP客户端

介绍

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都可以向远程Web服务器发出同步或异步HTTP请求。

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

使用注释来描述HTTP请求：

• URL参数替换和查询参数支持
• 对象请求正文的转换（例如，JSON，协议缓冲区）
• 多部分请求正文和文件上传

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> 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);

该对象也将使用Retrofit实例上指定的转换器进行转换。如果未添加转换器，则只能使用RequestBody。

• 来自编码和多部分的请求

还可以声明方法以发送表单编码和多部分数据。 当方法上存在@FormUrlEncoded时，将发送表单编码数据。每个键值对都使用包含名称的@Field和提供值的对象进行注释。

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

当方法中存在@Multipart时，将使用多部分请求。使用@Part注释声明部件。

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

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

• 头部多部分请求
  您可以使用@Headers批注为方法设置静态标头。

@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注释动态更新请求标头。必须为@Header提供相应的参数。如果该值为null，则将省略标头。否则，将在值上调用toString，并使用结果。

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

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

@GET("user")
Call getUser(@HeaderMap Map headers)

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

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

Retrofit 构造

Retrofit是将API接口转换为可调用对象的类。默认情况下，Retrofit会为您的平台提供合理的默认值，但它允许自定义。
转换器
默认情况下，Retrofit只能将HTTP主体反序列化为OkHttp的ResponseBody类型，并且它只能接受@Body的RequestBody类型。
可以添加转换器以支持其他类型。六个兄弟模块适应流行的序列化库，方便你使用。

1. Gson: com.squareup.retrofit2:converter-gson
2. Jackson: com.squareup.retrofit2:converter-jackson
3. Moshi: com.squareup.retrofit2:converter-moshi
4. Protobuf: com.squareup.retrofit2:converter-protobuf
5. Wire: com.squareup.retrofit2:converter-wire
6. 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

    com.squareup.retrofit2
    retrofit
    (insert latest version)

GRADLE

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