Retrofit 官方文档

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

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

使用注释来描述 HTTP 请求：

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

API说明

接口方法及其参数的注释表示如何处理请求。

请求方法

每个方法都必须具有提供请求方法和相对 URL 的 HTTP 注释。 有五个内置注释：GET，POST，PUT，DELETE 和 HEAD。资源的相对 URL 在注释中指定。

@GET("users/list")

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

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

URL 操作

可以使用方法上的替换块和参数动态更新请求URL。 替换块是由{and}包围的字母数字字符串。使用相同的字符串，必须使用 @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);

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

HEADER 操作

您可以使用 @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，则头将被省略。 否则，将调用toString的值，并使用结果。

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

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

同步 VS 异步

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

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

转换器

默认情况下，Retrofit 只能反序列化 HTTP 身份到 OkHttp 的 ResponseBody 类型，它只能接受 @Body 的 RequestBody 类型。

可以添加转换器来支持其他类型。六个兄弟模块适应流行的序列化库，方便您使用。

[Gson][3]: com.squareup.retrofit2:converter-gson
[Jackson][4]: com.squareup.retrofit2:converter-jackson
[Moshi][5]: com.squareup.retrofit2:converter-moshi
[Protobuf][6]: com.squareup.retrofit2:converter-protobuf
[Wire][7]: com.squareup.retrofit2:converter-wire
[Simple XML][8]: com.squareup.retrofit2:converter-simplexml
Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars

以下是使用 GsonConverterFactory 类生成使用 Gson 进行反序列化的 GitHubService 接口的实现的示例。

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com")
    .addConverterFactory(GsonConverterFactory.create())
    .build();
GitHubService service = retrofit.create(GitHubService.class);

自定义转换器

如果您需要与使用 Retrofit不支持的内容格式（例如YAML，txt，自定义格式）或希望使用不同的库来实现现有格式的 API 进行通信，则可以轻松创建 你自己的转换器 创建一个扩展 Converter.Factory 类，并在构建适配器时传递一个实例。

项目导入

GitHub 提供了 Retrofit 示例和源代码

MAVEN

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>2.2.0</version>
</dependency>

GRADLE

compile 'com.squareup.retrofit2:retrofit:2.2.0'

Retrofit 需要至少 Java 7 或 Android 2.3。

PROGUARD

如果您在项目中使用 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

Retrofit 如果使用了 Okio，可以参考 ProGuard 规则。