Retrofit官方使用说明翻译——不准确之处请指出

Introduction（简介）

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

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

使用注解来描述HTTP请求：

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

API Declaration（API声明）

REQUEST METHOD（请求方法）

每一个方法必须有一个HTTP注解，这个注解提供请求方法和相对URL。Retrofit有5个内置注解：GET，POST，PUT，DELETE和HEAD。相对URL在注解中指定。

@GET("users/list")

同时也可以在URL中指定查询参数。

@GET("users/list?sort=desc")

URL MANIPULATION（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);

REQUEST BODY（请求主体）

可以用带有@Body注解的HTTP请求体来指定一个对象。

@POST("users/new")
Call<User> createUser(@Body User user);

这个对象也可以使用Retrofit实例指定的转换器进行转换。如果未添加转换器，只能使用RequestBody。

FORM ENCODED AND 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（HEADER处理）

你可以使用@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都将包含在请求中。

可以使用@Headers注解动态更新一个请求Header，必须为@Header提供相应的参数。如果该值为null，header可以被省略，否则将在值上调用toString，结果使用…

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

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

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

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

SYNCHRONOUS VS. ASYNCHRONOUS（同步与异步）

Call实例可以同步或异步执行。每个实例只能使用一次，但是调用clone()将创建一个可以使用的新实例。

在Android上，回调将在主线程上执行。在JVM中，回调将在执行HTTP请求的同一个线程上发生。

Retrofit Configuration（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（自定义转换器）

如果你需要与使用Retrofit不支持开箱的内容格式（例如：YAML，txt，自定义格式）的API进行通信，或者你希望使用其他库来实现现有格式，你可以轻松创建你自己的转换器。创建一个继承Converter.Factory的类，在构建适配器的时候传入示例。