Retrofit2使用中文文档

介绍

将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的每个回调都可以向远程webserver发出同步或异步HTTP请求

Call<List<Repo>> 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<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);

该对象还将使用在改进实例上指定的转换器进行转换。如果没有添加转换器，则只能使用RequestBody

FORM ENCODED 和 MULTIPART
在方法上还可以声明发送form-encoded和multipart
在方法上注释@FormUrlEncoded时发送Form-encoded数据。每个键值对都带有@Field，其中包含名称和提供值的对象

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

当@Multipart出现在方法上时，将使用Multipart请求。part使用@Part注释声明

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

Multipart使用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);

注意，header并不覆盖彼此。所有具有相同名称的标题将包含在请求中。

可以使用@Header注释动态更新请求报头。必须向@Header提供相应的参数。如果该值为空，则将省略头。否则，将调用toString值，并使用结果

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

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

同步 vs 异步

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

Retrofit配置

Retrofit是通过将API接口转化为可调用对象的类。默认情况下，Retrofit将使您的平台有正常的默认值，但它允许定制

Converter

默认情况下，Retrofit只能将HTTP主体反序列化为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);

如果您在项目中使用ProGuard，请在配置中添加以下几行

# Platform calls Class.forName on types which do not exist on Android to determine platform.
-dontnote retrofit2.Platform
# Platform used when running on Java 8 VMs. Will not be used at runtime.
-dontwarn retrofit2.Platform$Java8
# Retain generic type information for use by reflection by converters and adapters.
-keepattributes Signature
# Retain declared checked exceptions for use by a Proxy instance.
-keepattributes Exceptions