Retrofit 2.x REST client教程

目录：
1-- 关于Retrofit
2--前提
3--建立一个Retrofit客户端
4--Retrofit 转换器和适配器
5--Retrofit 授权
6--在Java中用Retrofit 去查询Gerrit
7--用Retrofit 转换从RSS得到到XML的响应
8--做一个可以在StackOverflow搜索的程序
9--在Android中用Retrofit去访问Github API

1. 关于Retrofit：

1.1 什么是Retfofit

Retrofit 是一个用来服务于Java和Android的REST 客户端。 用它可以非常容易的去接收和上传json数据（或是其他数据），通过一个建立在REST上面的web服务器。在Retrofit中可以配置转换器来进行数据序列化。特别是用GSon来转换json数据，同时一个你也定制你的转换器，别入来进行解析XML数据或是其他相关协议的数据。Retrofit的HTTP 请求部分用的是OkHttp 库。

1.2 Retrofit的用法：

一般情况下，你会跟Retrofit的三个类打交道：

• JSON 模块
• 定义一个接口，在接口里面做跟HTTP相关的操作
• Retrofit.Builder Class ，它的实例接口和其相关的API可以允许你去定义用URL只想的HTTP操作

接口中的每个方法代表一个API调用。他们必须有一个HTTP注解（GET,POST等）去指定一个请求类型和相关的URL.返回的值包装了一个response 结果（如果不清楚注解，请参考我的博文）

@GET("users")
Call> getUsers();

你可以用"替换块"和查询参数去调整你的URL.替换块必须由{}来包裹。在函数参数中的@Path的值会和你指定的替换块绑定到一起。

@GET("users/{name}/commits")//{name}即使替换块
Call> getCommitsByName(@Path("name") String name);

查询参数在函数参数中用注解@Query来进行包装，他们会自动的被添加到URL的末端。

@GET("users")
Call getUserById(@Query("id") Integer id);

函数参数中的@Body注解来告诉Retrofit，用这个对象来作为请求体（注意HTTP的三部分：请求头，请求行，请求体）

@POST("users")

Call postUser(@Body User user)//这里，User的对象user就是请求体

2. 前提

以下例子需要你了解Gradle build 系统或是在Eclipse中使用Gradle，当然你在Visual Studio中用Gradle那也没有啥错。

3. 建立一个Retrofit客户端（小例子）

在这个例子中你会知道如何创建一个标准的REST 客户端。我们接收Resopose的服务器为mock server。

3.1 创建项目并设置

增加远程依赖，创建一个新的Project，名字是com.vogella.retrofitgerrit. 并在src/main/java下创建一个名字为com.vogella.retrofitgerrit的包.

// retrofit
//Android studio setup--最新版本
implementation 'com.squareup.retrofit2:retrofit:2.5.0'
// Junit
testImplementation("org.junit.jupiter:junit-jupiter-api:5.0.0")
testRuntime("org.junit.jupiter:junit-jupiter-engine:5.0.0")
// to run JUnit 3/4 tests:
testImplementation("junit:junit:4.12")
testRuntime("org.junit.vintage:junit-vintage-engine:4.12.0")

3.2 定义API和Retrofit适配器：

从Gerrit收到的JSON回复，我们仅仅需要关注它的主题变化，因此在默认的包中建立如下类：

package com.vogella.java.retrofitgerrit;

public class Change {
    String subject;

    public String getSubject() {
        return subject;
    }

    public void setSubject(String subject) {
        this.subject = subject;
    }
}

在以下接口中定义Retrofit的REST API：

package com.vogella.java.retrofitgerrit;

import java.util.List;

import retrofit2.Call;
import retrofit2.http.GET;
import retrofit2.http.Query;

public interface GerritAPI {

    @GET("changes/")
    Call> loadChanges(@Query("q") String status);
}

创建一个controller控制器类，这个类创造了Retrofit client， 调用Gerrit API以及处理结果（打印调用后返回的结果到console）

package com.vogella.java.retrofitgerrit;

import java.util.List;

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

import retrofit2.Call;
import retrofit2.Callback;
import retrofit2.Response;
import retrofit2.Retrofit;
import retrofit2.converter.gson.GsonConverterFactory;

public class Controller implements Callback> {

    static final String BASE_URL = "https://git.eclipse.org/r/";

    public void start() {
        Gson gson = new GsonBuilder()
                .setLenient()
                .create();

        Retrofit retrofit = new Retrofit.Builder()
                .baseUrl(BASE_URL)
                .addConverterFactory(GsonConverterFactory.create(gson))
                .build();

        GerritAPI gerritAPI = retrofit.create(GerritAPI.class);

        Call> call = gerritAPI.loadChanges("status:open");
        call.enqueue(this);

    }

    @Override
    public void onResponse(Call> call, Response> response) {
        if(response.isSuccessful()) {
            List changesList = response.body();
            changesList.forEach(change -> System.out.println(change.subject));
        } else {
            System.out.println(response.errorBody());
        }
    }

    @Override
    public void onFailure(Call> call, Throwable t) {
        t.printStackTrace();
    }
}

创建一个包含Java程序入口的类，从而启动这个控制器类

package com.vogella.java.retrofitgerrit;
public class Main {

    public static void main(String[] args) {
        Controller controller = new Controller();
        controller.start();
    }
}

4.Retrofit 转换器和适

4.1 Retrofit 转换器

Retrofit 可以配置一个特殊的转换器。用这个转换器来处理数据序列化。目前几个转换器已经可以使用于数据序列化。

• 从JSON转换
  Gson：com.squareup.retrofit:converter-gson
  Jackson:com.squareup.retrofit:converter-jackson
  Moshi:com.squareup.retrofit:converter-moshi
  除了上面列出的，当然你自己也可以通过Converter.Factory类的子集来定制自己的转换器，通过特殊的协议。

4.2 Retrofit 适配器

Retrofit本身也可以被继承，从而去和一些其他的库（RxJava2.x，Java8，Guava）一起协同工作（这点很重要，例如okHttp就不太适合去和RxJava去协同工作，这也是为什么既然选择okHttp就不如直接用Retrofit的一个原因）
关于适配器的一个概述，请参考Adaptersquare/retrofit/retrofit-adapters/.
例如，RxJava 2.下 adapter 可以从Gradle获得：
compile 'com.squareup.retrofit2:adapter-rxjava2:latest.version'
用Apache的远程仓库Maven：

 com.squareup.retrofit2
 adapter-rxjava2
 latest.version

如果你要添加一个适配器（Adapter），那么要用到以下这个方法
retrofit2.Retrofit.Builder.addCallAdapterFactory(Factory)

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com")
    .addCallAdapterFactory(RxJava2CallAdapterFactory.create())//添加适配器
    .build()

再Retrofit添加这个适配器后就会返回一个RxJava2.x 的一个类型。Observable，Flowable和Single 等等。

@GET("users")
Observable> getUsers();

Retrofit 授权

---

回头完善内容多...