Retrofit 指南

Question

这是一篇关于如何使用 Retrofit 写一个 Android 的 REST 客户端的小教程。

我为什么选择 Retrofit？

在使用 square 的 Retrofit 之前，我尝试过 Volley 和 AsyncTask。但在使用过 Retrofit 之后，我的工作变得更加简单了。在开始阅读教程之前，建议先阅读一下下面的几个话题。这是一个入门项目，可以让你了解如何使用 Retrofit 从 API 获取数据。

这个项目也加到了 我的 Github 中。

AsyncHttp ,Volley 和 Retrofit 的对比

与 Retrofit 相比，Volley 是一个小型的、缺乏正式文档说明库。Retrofit 是 Square 开发的，后者还开发过 okhttp，picasso...等一些著名的库（你可以在 这里 找到其他的库)。如果你需要 Volley 的指引，你可以在 Google Training 或者 Volley Plus from DWork 找到相关文档。

简介

Retrofit 是 Square 开发的一个 Android 和 Java 的 REST 客户端库。这个库非常简单并且具有很多特性，相比其他的网络库，更容易让初学者快速掌握。它可以处理 GET、POST、PUT、DELETE...等请求，还可以使用 picasso 加载图片。在使用 Picasso 或 Volley 之前，可以先来读读 这个 。

别纠结简介了，开始编码吧！

Demo 里使用是 Github 的 API : https://api.github.com/users/basil2style

你可以使用这个 Demo App 来搜索 github 的用户详细信息

• GITHUB
• Download APK
• qr code

1) 概述

1) POJO 或模型实体类 : 从服务器获取的 JSON 数据将被填充到这种类的实例中。

2) 接口 : 我们需要创建一个接口来管理像 GET,POST...等请求的 URL，这是一个服务类。

3) RestAdapter 类 : 这是一个 REST 客户端(RestClient) 类，retrofit 中默认用的是 Gson 来解析 JSON 数据，你也可以设置自己的 JSON 解析器，比如 jackson，我们将在下面的教程中详细解说明。

2) 添加 Retrofit 库到项目中

Gradle :

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

目前，1.9.0 是最新的版本. 你可以在 这里 获取更新的版本。

JAR：下载 Jar 包

3) 创建项目

1. 在 Android Studio 中创建新项目: File => New Project ，填写描述信息并点击 Next .
2. 填写 minimum SDK ，我用的是 4.0+ (Retrofit 支持 Android 2.3+ 或 Java 6 以上)
3. 选择 Blank Activity 然后填写 Activity Name 和 Layout Name ，最后点击 Finish .
4. Gradle : 你可以在 app =>build.gradle 中添加 Retrofit 的库文件。Jar 包的添加方式 : 将 jar 包添加到 libs 文件夹下，右键点击 Add as Library.
5. 创建两个包： API 和 model 。
6. 在 API 包下右键点击 New => Java Class , 填写 Name 为 gitapi 并设置为 Interface。
7. 在 API 包下创建名 gitapi 的接口。
8. 在 model 包下右键点击 New => Java Class , 填写 Name 为 gitmodel 并设置为 Class。

4) Android Manifest

1) 添加 INTERNET PERMISSION 权限

<uses-permission android:name="android.permission.INTERNET"/>

你的 Manifest 文件看起来应该是这样的 :

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"  
      package="com.makeinfo.flowerpi" >
   <uses-permission android:name="android.permission.INTERNET"/>
   <application android:allowBackup="true"
      android:icon="@mipmap/ic_launcher"
     android:label="@string/app_name"
     android:theme="@style/AppTheme" >
     <activity
       android:name=".MainActivity"
       android:label="@string/app_name" >
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
         <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
    </activity>
  </application>
 </manifest>

5) 模型类

首先，我们需要创建一个 POJO 或模型类。服务器返回的 JSON 数据不能在 Java 里直接使用，所以我们需要用模型类来做转换。

URL 的结构是这样的： https://api.github.com/users/ + “search term”

举个栗子： https://api.github.com/users/basil2style

我们的 JSON 返回数据是这样的：

这是一个 JSON Object ，如果你不了解 JSON Array 和 JSON Object 的区别，请看 这里 。

使用 jsonschema2pojo 来创建 POJO 更加简单，不要每一个 JSON 数据的 POJO 转换都用它，有时候会报错。选择源代码类型为 Json ，注解类型是 Gson ,然后点击 preview 。

点击 这里 (需翻墙) 查看 gitmodel.java 源代码。

6) gitapi.java

1) 现在我们需要使用接口调用 URL.

@GET("/users/{user}") , 添加这个注解会调用服务器，参数 url 基于 BASE URL，服务调用的参数以'/'开头，其中{user}是从 EditText 获取的字符串。

@Path("user") String user 就是我们从 EditText 获取的字符串。

服务器端响应的数据则会被存储到 POJO 实例中去。

public interface gitapi {

  @GET("/users/{user}")    // here is the other url part.best way is to start using /
  public void getFeed(@Path("user") String user, Callback<gitmodel> response);
   // string user is for passing values from edittext for eg: user=basil2style,google
    // response is the response from the server which is now in the POJO
}

7) RestAdapter

现在该主要部分了，你需要设置 Rest Adapter 和 service 类.

1) API 就是 Base URL .

2) 我们需要设置 Endpoint(API) 并调用 buid() 方法来创建一个 RestAdapter 对象。

3) 使用我们的 gitapi 来创建一个服务适配器(service for adapter)。

4) 调用函数并获得响应数据，回调接口是用来异步的获取模型实例的，我们的回调接口需要实现成功回调方法(success request) 和错误处理方法(error handling)。

5) 我们解析好的 json 数据的现在就存在于 POJO 实例中了，你可以每次调用一条。

String API = "https://api.github.com";

RestAdapter restAdapter = new RestAdapter.Builder().setLogLevel(RestAdapter.LogLevel.FULL).setEndpoint(API).build(); 

gitapi git = restAdapter.create(gitapi.class);

git.getFeed(user, new Callback<gitmodel>() {
  @Override
  public void success(gitmodel gitmodel, Response response) {
    tv.setText("Github Name :" + gitmodel.getName() + 
           "\nWebsite :" + gitmodel.getBlog() + 
           "\nCompany Name :" + gitmodel.getCompany());

    pbar.setVisibility(View.INVISIBLE); // disable progressbar
   }

   @Override
  public void failure(RetrofitError error) {
     tv.setText(error.getMessage());
     pbar.setVisibility(View.INVISIBLE); //disable progressbar
   }
 });

完整的 MainActivty.java 代码：

package com.makeinfo.flowerpi;

import android.support.v7.app.ActionBarActivity;
import android.os.Bundle;
import android.view.Menu;
import android.view.MenuItem;
import android.view.View;
import android.widget.Button;
import android.widget.EditText;
import android.widget.ProgressBar;
import android.widget.TextView;

import com.makeinfo.flowerpi.API.gitapi;
import com.makeinfo.flowerpi.model.gitmodel;

import retrofit.Callback;
import retrofit.RestAdapter;
import retrofit.RetrofitError;
import retrofit.client.Response;


public class MainActivity extends ActionBarActivity {

  Button click;
  TextView tv;
  EditText edit_user;
  ProgressBar pbar;
  String API = "https://api.github.com";  // BASE URL

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    click = (Button) findViewById(R.id.button);
    tv = (TextView) findViewById(R.id.tv);
    edit_user = (EditText) findViewById(R.id.edit);
    pbar = (ProgressBar) findViewById(R.id.pb);
    pbar.setVisibility(View.INVISIBLE);

    click.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        String user = edit_user.getText().toString();
        pbar.setVisibility(View.VISIBLE);

        // Retrofit section start from here...
        // create an adapter for retrofit with base url
        RestAdapter restAdapter = new RestAdapter.Builder().setEndpoint(API).build(); 

        // creating a service for adapter with our GET class     
        gitapi git = restAdapter.create(gitapi.class);  

        // Now ,we need to call for response
        // Retrofit using gson for JSON-POJO conversion

        git.getFeed(user,new Callback<gitmodel>() {
          @Override
          public void success(gitmodel gitmodel, Response response) {
            // we get json object from github server to our POJO or model class

            tv.setText("Github Name :" + gitmodel.getName() + 
                  "\nWebsite :"+gitmodel.getBlog() + 
                  "\nCompany Name :"+gitmodel.getCompany());

            pbar.setVisibility(View.INVISIBLE);  // disable progressbar
          }

          @Override
          public void failure(RetrofitError error) {
             tv.setText(error.getMessage());
            pbar.setVisibility(View.INVISIBLE);  // disable progressbar
          }
        });
      }
    });
  }


  @Override
  public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the menu; this adds items to the action bar if it is present.
    getMenuInflater().inflate(R.menu.menu_main, menu);
    return true;
  }

  @Override
  public boolean onOptionsItemSelected(MenuItem item) {
    // Handle action bar item clicks here. The action bar will
    // automatically handle clicks on the Home/Up button, so long
    // as you specify a parent activity in AndroidManifest.xml.
    int id = item.getItemId();

    //noinspection SimplifiableIfStatement
    if (id == R.id.action_settings) {
      return true;
    }

    return super.onOptionsItemSelected(item);
  }
}