1. Retrofit2 -- Getting Started and Create an Android Client

该篇讲述了 Retrofit 的基础知识，并讲述了如何创建 Android 客户端的 API 或 HTTP 请求。

但是，本篇不会覆盖太多起步知识。如果想知道这些信息，请参见 主页 的内容。

什么是 Retrofit

Retrofit 的官网是这样描述的：

A type-safe REST client for Android and Java

因此，在 Retrofit 中，默认使用注解来描述 HTTP 请求、URL 参数占位符等操作。此外，它还支持多个请求体，也提供了文件上传的能力。

如何申明请求

请访问 Retrofit 的主页 ，阅读 API 申明部分，以便获取如何创建请求的感觉。在那里，既有重要的说明，又有示例代码。

准备 Android 项目

如果你已经创建了 Android 项目，那请跳过本段。如果没有，就使用你最喜欢的 IDE 来创建一个 Android 项目。推荐使用 Gradle 作为构建系统，当然，也可以使用 Maven。

使用 Gradle 或 Maven 定义依赖

依赖于构建工具的不同，依赖定义的地方也不同，在 pom.xml 或 build.gradle 中定义依赖。

Retrofit 1.9 的依赖定义

pom.xml

<dependency>

    <groupId>com.squareup.retrofit</groupId>

    <artifactId>retrofit</artifactId>

    <version>1.9.0</version>

</dependency>

<dependency>

    <groupId>com.squareup.okhttp</groupId>

    <artifactId>okhttp</artifactId>

    <version>2.7.2</version>

</dependency>

build.gradle

dependencies {

    // Retrofit & OkHttp

    compile 'com.squareup.retrofit:retrofit:1.9.0'

    compile 'com.squareup.okhttp:okhttp:2.7.2'

}

Retrofit 2.0 的依赖定义

pom.xml

<dependency>

    <groupId>com.squareup.retrofit2</groupId>

    <artifactId>retrofit</artifactId>

    <version>2.1.0</version>

</dependency>

<dependency>

    <groupId>com.squareup.retrofit2</groupId>

    <artifactId>converter-gson</artifactId>

    <version>2.1.0</version>

</dependency>

build.gradle

dependencies {

    // Retrofit & OkHttp

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

    compile 'com.squareup.retrofit2:converter-gson:2.1.0'

}

Retrofit 2 默认使用 OKHttp 作为网络层，并且基于它进行构建。因此，在项目中不需要显示的定义这个依赖，除非你需要一个不同的版本。

到现在为止，你的 Android 项目已经为 Retrofit 做好准备了，让我们创建一个持久的 Android API/Http 的客户端吧。

持续发展的 Android 客户端

在对已经存在的 Android 客户端的调研中，由 Bart Kiers 创建的 example repository示例 崭露头角。其实，它是一个使用 Retrofit 进行 OAuth 认证的示例。但是，对于一个可持续发展的客户端来说，它提供了所有必要的元素。这就是为什么我们将把它当作一个稳定版来使用，并在后面的教程中给它扩展高级的认证功能。

下面的类：ServiceGenerator 定义了 Android 客户端的基础。

服务生成器

ServiceGenerator 是 API/HTTP 客户端的核心。在当前的状态中，它仅仅定义了一个方法，用于使用给定的类创建 REST 类型的适配器，下面是代码：

Retrofit 1.9

public class ServiceGenerator {

    public static final String API_BASE_URL = "http://your.api-base.url";

    private static RestAdapter.Builder builder = new RestAdapter.Builder()

                .setEndpoint(API_BASE_URL)

                .setClient(new OkClient(new OkHttpClient()));

    public static <S> S createService(Class<S> serviceClass) {

        RestAdapter adapter = builder.build();

        return adapter.create(serviceClass);

    }

}

Retrofit 2

public class ServiceGenerator {

    public static final String API_BASE_URL = "http://your.api-base.url";

    private static OkHttpClient.Builder httpClient = new OkHttpClient.Builder();

    private static Retrofit.Builder builder =

            new Retrofit.Builder()

                    .baseUrl(API_BASE_URL)

                    .addConverterFactory(GsonConverterFactory.create());

    public static <S> S createService(Class<S> serviceClass) {

        Retrofit retrofit = builder.client(httpClient.build()).build();

        return retrofit.create(serviceClass);

    }

}

ServiceGenerator 基于一个基本的地址，使用 Retrofit 的 RestAdapter - Builder，创建了一个新的 REST 客户端。例如，GitHub 的基本地址是：https://api.github.com/。该类中定义了用于 API 请求的、有注解的类和接口。下面的章节显示了 Retrofit 具体的用法，并演示如何定义一个典范式的客户端。

JSON 映射

Retrofit 1.9 默认集成了 Google GSON。你要做的就是定义你所需的用于响应的对象类，响应将会被自动映射。

Retrofit 2 中，需要自己显式地为 Retrofit 对象添加转换器。上面的示例，在 build.gradle 文件中添加了下面的代码来引入 Retrofit 2 使用的 GSON 转换器：

compile 'com.squareup.retrofit2:converter-gson:2.1.0'

现在，需要给 Retrofit 对象添加转换器，给 Retrofit Builder 对象使用 addConverterFactory(GsonConverterFactory.create()) 方法来为对象集成 GSON 用为它的默认转换器。

使用 Retrofit

好了，现在让我们定义一个 REST 客户端从 GitHub 上请求数据。首先，得创建接口、定义方法。

GitHub 客户端

下面的代码定义了一个 GitHubClient，和一个用于获取某个仓库贡献者列表的方法。代码来演示了 Retrofit 参数占位符功能（定义在路径中的 {owner} 和 repo）的用法，它们的作用是：在方法被调用时，占位符将被替换为传入的变量。

Retrofit 1.9

public interface GitHubClient {

    @GET("/repos/{owner}/{repo}/contributors")

    List<Contributor> contributors(

        @Path("owner") String owner,

        @Path("repo") String repo

    );

}

Retrofit 2

public interface GitHubClient {

    @GET("/repos/{owner}/{repo}/contributors")

    Call<List<Contributor>> contributors(

        @Path("owner") String owner,

        @Path("repo") String repo

    );

}

下面是 Contributor 类的定义，类中必须的属性与响应数据映射相对应：

static class Contributor {

    String login;

    int contributions;

}

关于先前提到的 JSON 映射：GitHubClient 类定义了名为 contributors 的方法，它的返回类型是 List。Retrofit 确保了服务响应能被正确的匹配（也就是响应匹配为相应的类）。

Request 示例

下面的代码片断演示了使用 ServiceGenerator 类实例化客户端，具体就是 GitHubClient，使用创建的客户端可以获取贡献者。这里的片断显示的是一个改进版。

在运行 GitHub 示例中，需要手动给 ServiceGenerator 设置基本网址，示例中是 https://api.github.com：

Retrofit 1.9

public static void main(String... args) {

    // Create a very simple REST adapter which points the GitHub API endpoint.

    GitHubClient client = ServiceGenerator.createService(GitHubClient.class);

    // Fetch and print a list of the contributors to this library.

    List<Contributor> contributors =

        client.contributors("fs_opensource", "android-boilerplate");

    for (Contributor contributor : contributors) {

        System.out.println(

                contributor.login + " (" + contributor.contributions + ")");

    }

}

Retrofit 2

public static void main(String... args) {

    // Create a very simple REST adapter which points the GitHub API endpoint.

    GitHubClient client = ServiceGenerator.createService(GitHubClient.class);

    // Fetch and print a list of the contributors to this library.

    Call<List<Contributor>> call =

        client.contributors("fs_opensource", "android-boilerplate");

    try {

        List<Contributor> contributors = call.execute().body();

    } catch (IOException e) {

        // handle errors

    }

    for (Contributor contributor : contributors) {

        System.out.println(

                contributor.login + " (" + contributor.contributions + ")");

    }

}