如何用 Retrofit 2 在安卓上实现 HTTP 访问？

最近，笔者对安卓开发的兴趣愈发浓厚，而且不断尝试了许多传闻很棒的开发库 -- 大部分也真的很不错。于是打算写一个系列文章，介绍使用这些让人惊叹的库建立安卓示例应用的实践。这样，读者可以自行判断，这些库有多好用。本文是该系列的第一篇。

今天，笔者要研究对应用来说，使用 Retrofit 2 的 HTTP 客户端有多复杂，以及能带来什么好处。Retrofit是Square Inc.发布在开源社区的一款令人叹为观止的工具。它是一个类型安全的 HTTP 客户端，适用于安卓和 Java 应用。

类型安全 HTTP 客户端主要意味着，你只需关心发送出去的网络请求的语义，而不必考虑 URL 构建的细节，以及参数设定是否正确之类的事。Retrofit应对这些易如反掌，你只需写几个接口即可。就是这么简单！

我们通过一个例子来看看它是怎么实现的。笔者已经把这里所有的代码都放在了 Github 的 资源库里。如你所知，最好的学习方法就是查看这些代码，自己调试调试。

首先，笔者在 Android Studio 里建了一个空项目。老实说，每次看到欢迎界面上出现的那堆有关兼容性、以及应用所支持的 API 的选项，笔者都会感到非常迷茫。

好在我们只是弄个“玩具”项目而已，因此我们可以大胆地选择最新的 SDK，然后快速掠过项目向导，进入我们伟大的「hello world」安卓应用。

如果你自己不想纠结这些选项，可以直接点击这个 Github 的链接，导入笔者提交的现成项目：Floating button app skeleton.

通常，笔者在所有项目中都会启用 JRebel for Android。这是一个 Android Studio 的插件。“启用它”基本上意味着，只需点击一下自定义按钮就能运行应用，其余所有工作都交给它了。JRebel for Android 对安卓开发者来说是一款提升效率的工具，它可以在运行着的设备和模拟器上即时更新代码。这本质上意味着在开发应用时，你不必浪费宝贵的时间来等待应用重启，并因此而中途放弃这些应用的状态记录。总之特别棒！

说明一下，我在 ZeoTurnaround 公司工作，也就是创造JRebel for Android的公司。但它真的很好用，你值得一试。

Android Studio 2.0附带的新模拟器用着也很爽。现在，MainActivity 类的模拟器屏幕被激活了。

点一下浮动按钮，出现 snackbar。看起来不错。让我们随意更改一段代码，检验一下代码重新加载的功能。笔者首先想到的是修改 snackbar 的字符串值。

FloatingActionButton fab = (FloatingActionButton) findViewById(R.id.fab);
fab.setOnClickListener(new View.OnClickListener() {

  @Override
  public void onClick(View view) {
    Snackbar.make(view, “Super fast hello world”, Snackbar.LENGTH_LONG)
      .setAction(“Action”, null).show();
  }
});

注意看，我们保存了一个文件，点击了一下按钮，接着模拟器上的代码就重新加载了。现在一切就绪！也就是说，我们可以研究 Retrofit 2 到底有什么用处了。

Retrofit 2 是一个类型安全的 HTTP 客户端，适用于安卓（及 Java）。但首先，它也是一个库。所以我们要先声明依赖。这个容易。不过，请注意，我们需要显式依赖gson 转换器，将 JSON 应答转换为 model 类。这与Retrofit 1不同。所以需要注意一下。
Add these two lines to the build.gradle file:
将这两行代码加到 build.gradle 文件中去：

compile ‘com.squareup.retrofit2:retrofit:2.0.0-beta2’
compile ‘com.squareup.retrofit2:gson-converter:2.0.0-beta2’

Retrofit 的主要功能是可以在运行时生成代码，发送 HTTP服务查询请求。开发者只需写一个“说明”接口即可。假设我们有如下的一个 model 类：

通过这个我们可以创建一个名为GithubService的接口，用于实现 HTTP 通信。

public interface GitHubService {
  @GET(“repos/{owner}/{repo}/contributors”)
  Call<List<Contributor>> repoContributors(
      @Path(“owner”) String owner,
      @Path(“repo”) String repo);
}

This is the simplest example, we add the @GET annotation on an interface method and provide the path part of the URL that we want to expose it on. Conveniently, the method parameters can be referenced in the path string so you won’t need to jump through hoops to set those. Additionally, with other annotations you can specify query parameters, POST request body and so on:

• @Query(“key”) — for GET request query parameter

• @QueryMap — for the map of parameters

• @Body — use it with the @POST annotation to provide the query body content.

这是一个最简单的例子。我们在接口方法中加入 @GET 注解，并且提供想要展示的 URL 的path部分。方便的是，由于可以在 path 字符串中引用方法参数，因此我们无需跳出循环再重新设定。另外，通过这些注解，你可以设定查询参数，以及 POST 请求主体等等：

• @Query(“key”)  -- 用于GET请求查询参数

• @QueryMap -- 用于参数映射

• @Body -- 与@POST注解一起使用，提供查询主体内容

下面，为了能在运行时使用这个接口，我们需要构建一个 Retrofit 对象：

interface GitHubService {
    @GET("repos/{owner}/{repo}/contributors")
    Call<List<Contributor>> repoContributors(
            @Path("owner") String owner,
            @Path("repo") String repo);


    public static final Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("https://api.github.com/")
            .addConverterFactory(GsonConverterFactory.create())
            .build();
}

笔者倾向于在包含网站请求的接口内使用 Retrofit builder。这么做并不是想让它变得复杂难懂。而是处于通用配置的考虑。例如，我们有默认的转换器，将 JSON 响应对象转为 Java 对象，但是，即使在每个 service 中复制粘贴一遍，也好过使用单一的抽象类，后者很容易造成泄漏。

With these pieces in place, we just need to perform the network call:

• the specification of our queries

• the Retrofit object builder
  准备好这些代码后，我们只需发出网络请求：

• 请求的说明

• Retrofit对象builder

为了实现GitHubService接口，需要初始化一个用于执行 HTTP 查询请求的 Call 对象。

GitHubService gitHubService = GitHubService.retrofit.create(GitHubService.class);
Call<List<Contributor>> call = gitHubService.repoContributors(“square”, “retrofit”);
List<Contributor> result = call.execute().body();

另外，有人可能也会选择设定请求的时间，让它成为异步请求，同时在执行完毕后提供 callback。

call.enqueue(new Callback<List<Contributor>>() {
  @Override
  public void onResponse(Response<List<Contributor>> response, Retrofit retrofit) {
    // handle success
  }

  @Override
  public void onFailure(Throwable t) {
    // handle failure
  }
});

听起来超简单！我们来处理一下 UI，然后写入代码。在浮动按钮的应用模板下，我们需要修改 content_main.xml 文件。笔者添加了一个发起请求查询的按钮，以及一个用以显示请求结果的文本区域：

<Button
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:text="Fetch"
  android:id="@+id/button"
  android:layout_alignParentBottom="true"
  android:layout_centerHorizontal="true"
  android:layout_marginBottom="151dp" />

<TextView
  android:layout_width="wrap_content"
  android:layout_height="wrap_content"
  android:textAppearance="?android:attr/textAppearanceLarge"
  android:text=""
  android:id="@+id/textView"
  android:layout_above="@+id/button"
  android:layout_alignParentEnd="true"
  android:layout_alignParentStart="true"
  android:layout_alignParentTop="true"
  android:textIsSelectable="false" />

第一次执行时，你的网络请求代码看起来可能是这样的：

Button button = (Button) findViewById(R.id.button);
button.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
    GitHubService gitHubService = GitHubService.retrofit.create(GitHubService.class);
    Call<List<Contributor>> call = gitHubService.repoContributors(“square”, “retrofit”);
    String result = call.execute().body().toString();
    TextView textView = (TextView) findViewById(R.id.textView);
    textView.setText(result);
  }
});

这段代码自然无法运行。安卓框架不允许用户在 UI 线程中执行网络请求。UI 线程只应该用来处理一些用户输入。在这个线程中执行任何引起长时间阻塞的操作都会让用户体验变得非常糟糕。

因此，我们需要重构这段代码，把网络请求移入后台线程。使用 JRebel for Android 可以不费任何时间就搞定这事。我们将代码提取到 AsyncTask -- 这是一个在安卓上运行大型运算的默认框架。AsyncTask不太好看，它的具体运行方式也不算清洁，例如每次我们点击按钮时它都会去创建一个 Retrofit 对象。但是能用就行。

private class NetworkCall extends AsyncTask<Call, Void, String> {
  @Override
  protected String doInBackground(Call… params) {
    try {
      Call<List<Contributor>> call = params[0];
      Response<List<Contributor>> response = call.execute();
      return response.body().toString();
    } catch (IOException e) {
      e.printStackTrace();
    }
    return null;
  }

  @Override
  protected void onPostExecute(String result) {
    final TextView textView = (TextView) findViewById(R.id.textView);
    textView.setText(result);
  }
}

接着，从 EventListener 中调用它：

Button button = (Button) findViewById(R.id.button);
button.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View view) {
    GitHubService gitHubService = GitHubService.retrofit.create(GitHubService.class);
    final Call<List<Contributor>> call = gitHubService.repoContributors("square", "retrofit");
    new NetworkCall().execute(call);
  }
});

好啦，现在代码可以运行了。文本视图会根据 HTTP 请求的结果实时刷新。

现在，这个框架应用程序已经完成了，代码顺利构建并运行完毕。你可以自己去试试 Retrofit和JRebel for Android 。随意修改一些代码，检查一下新代码构成的应用程序运行效果如何，也不会浪费任何时间。尝试为 Contributor 类增加几个区域，替换 contributor 组件的 文本视图，更改 HTTP 的端点，将请求发往另一个站点。一切尽在你掌握！

在本文中，我们了解了如何使用 Retrofit 2 创建一个发送网络请求的简易框架应用程序。程序的代码可以在 Github 上找到。对本文的最佳使用方式是，将它看作一篇快速指导，根据你的侧重点写一段自己的代码，接着复制这个应用程序的代码，导入 Android studio，然后试试你自己的代码吧！

今后，笔者会扩展这个框架应用程序，加入一些依赖注入框架，把UI代码与其他代码区分开来，以及使用RxAndroid来响应式处理一些网络请求等等。另外，你在安卓项目中默认使用的库是哪一个？研究一下这个问题也许也会很有意思呢！在Twitter上联系我：@shelajev。期待与你们互动！

OneAPM Mobile Insight 以真实用户体验为度量标准进行 Crash 分析，监控网络请求及网络错误，提升用户留存。访问 OneAPM 官方网站感受更多应用性能优化体验，想阅读更多技术文章，请访问 OneAPM 官方技术博客。

本文转自 OneAPM 官方博客