Retrofit你想知道的一切之基础使用

Retrofit--相信大家都或多或少的听过和用过了，不知道是什么的证明你已经out了~我使用和研究Retrofit也有一段时间了，所以准备记录一下自己使用的一些成果。这篇将会介绍Retrofit的简单配置和使用。
注：本系列Retrofit版本为2.1.0，OkHttp版本为3.4.1；本系列的接口均为非RESTful接口

Retrofit初识

1.HTTP请求方法和简单的RESTful

Retrofit支持RESTful ，先来简单的说一下RESTful接口（由于我自己也对RESTful一脸懵逼，所以请小伙伴们自行Google了解更多）。首先在这里先来说一下HTTP的请求方法，HTTP请求方法包含get、post、delete、put、head、patch、trace、options总共8种。除get外，其他6种都是基于post方法衍生的，最常见的是get和post，而put、delete、post、get这四种最重要，分别对应数据库的增删改查。

我们先来看一下比较常见的接口地址：
对学生信息进行操作：1.查询学生数量 2.创建新学生 3.修改学生信息 4.删除学生。

请求方法	接口地址	接口说明
get	/api/student/index	查询接口
post	/api/student/ + 参数	创建接口
post	/api/student/update + 参数	修改接口
post	/api/student/delete + 参数	删除接口

而如果我们用了RESTful API就会变成这样：

请求方法	接口地址	接口说明
get	/api/student/index	查询接口
post	/api/student/ + 参数	创建接口
put	/api/student/ + 参数	修改接口
delete	/api/student/ + 参数	删除接口

大家是不是也看出两者的区别了？修改跟删除直接用HTTP的请求方法（Method）来指定，虽然url 一样，但仍然可以知道你的动作。这就是所谓的RESTful 概念（这部分出自百万讲师stormzhang，感谢张哥带我们飞~）

2.开启Retrofit旅程

导入Retrofit：

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

Retrofit通过接口来管理HTTP API，那么首先我们先定义一个API的接口：

public interface RetrofitApi{
    @GET("public")
    Call<BaseResult<User>>  getUser();
}

然后通过Retrofit.Builder获取到Retrofit实例，并通过create(clazz)方法获取到我们刚才创建的RetrofitApi接口实例：

Retrofit retrofit=new Retrofit.Builder()
        .baseUrl("http://192.168.1.79:8080/")
        .build();

RetrofitApi retrofitApi=retrofit.create(RetrofitApi.class);

有了RetrofitApi实例之后，我们就可以在需要网络请求的地方调用了：

Call<BaseResult<User>> userCall=retrofitApi.getUser();

以上是利用Retrofit向http://192.168.1.79:8080/public接口发送一个get请求，获取用户信息。

注：baseUrl("")中的url必须以'/'结尾，否则会报异常；@GET("public")中的url如果是需要拼接在baseUrl之后的则不要以‘/’开头

Retrofit的注解

Retrofit中有很多注解，这些注解总共分三类：HTTP请求方法、标记类、参数类

1.HTTP请求方法注解

Retrofit支持八种HTTP请求方法注解，分别是：GET，POST，PUT，DELETE，HEAD，PATCH，OPTIONS，HTTP，其中前7种分别对应HTTP请求方法（见Retrofit初识小节1），而HTTP注解可自定义请求方法，也就是说可以替换前面七种方法。

• GET：对应HTTP的get请求方法

  写法：

  @GET("public")
  Call<BaseResult<List<User>>> getUser();
  

• POST：对应HTTP的post请求方法

  写法：

     @POST("User")
     Call<BaseResult<String>> addUser();
  

• PUT：对应HTTP的put请求方法

  写法：

     @PUT("User")
     Call<BaseResult<String>> updateUser();
  

• DELETE：对应HTTP的delete请求方法

  写法：

     @DELETE("User")
     Call<BaseResult<String>> deleteUser();
  

• HEAD：对应HTTP的head请求方法

• PATCH：对应HTTP的patch请求方法

• OPTIONS：对应HTTP的options请求方法

• HTTP：可替换以上七种，也可以扩展请求方法

  写法：

     /**
  * method 表示请的方法，不区分大小写
  * path表示路径
  * hasBody表示是否有请求体
  */
  @HTTP(method = "get", path = "public", hasBody = false)
  Call<BaseResult<List<User>>> getUser();
  

2.标记类注解

Retrofit支持三种标记类注解，分别是：FormUrlEncoded、Multipart、Streaming。

• FormUrlEncoded：指请求体是一个Form表单，Content-Type=application/x-www-form-urlencoded，需要和参数类注解@Field，@FieldMap搭配使用（详见下节）

  写法：

  @FormUrlEncoded
  @POST("public")
  Call<BaseResult> addUser(@Field("userName") String userName);
  

• Multipart：指请求体是一个支持文件上传的Form表单，Content-Type=multipart/form-data，需要和参数类注解@Part，@PartMap搭配使用（详见下节）

  写法：

  @Multipart
  @POST("public")
  Call<BaseResult> uploadFile(@Part MultipartBody.Part file);
  

• Streaming：指响应体的数据以流的形式返回，如果不使用默认会把数据全部加载到内存，所以下载文件时需要加上这个注解

  写法：

  @Streaming
  @GET("download")
  Call<ResponseBody> downloadFile();
  

3.参数类注解

• Headers：添加请求头，作用于方法

  写法：

  @Headers("Cache-Control: max-age=640000")
  @GET("public")
  Call<BaseResult<List<User>>> getUser();
  

  或

  @Headers({
      "Cache-Control: max-age=640000"
      "User-Agent: Retrofit-Sample-App"
  })
  @GET("public")
  Call<BaseResult<List<User>>> getUser();
  

  ​

• Header：用于动态添加头部，作用于方法参数

  写法：

  @GET("public")
  Call<BaseResult<List<User>>> getUser(@Header("Token") String token);
  

• Body：用于非表单请求体，作用于方法参数

  写法：

  @POST("user")
  Call<BaseResult<String>> addUser(@Body User user);
  

• Url：用于动态改变Url，作用于方法参数

  写法：

  @GET("public")
  Call<BaseResult<List<User>>> getUser(@Url String url);
  

  请求的时候，url会替换掉public

• Path：用于替换请求地址，作用于方法参数

  写法：

  @GET("{path}")
  Call<BaseResult<List<User>>> getUser(@Path("path") String path);
  

• Field：用于表单字段参数，（需要配合FormUrlEncoded使用）作用于方法参数

  写法：

  @FormUrlEncoded
  @POST("public")
  Call<BaseResult> addUser(@Field("userName") String userName);
  

• FieldMap：用于表单字段参数，接收Map实现多个参数，（需要配合FormUrlEncoded使用）作用于方法参数

  写法：

  @FormUrlEncoded
  @POST("public")
  Call<BaseResult> addUser(@FieldMap Map<String,String> fieldMap);
  

• Part：用于表单字段参数，适用于文件上传，（需要配合Multipart使用）作用于方法参数

  写法：

  @Multipart
  @POST("public")
  Call<BaseResult> uploadFile(@Part MultipartBody.Part file);
  

• PartMap：用于表单字段参数，适用于文件上传，（需要配合Multipart使用）作用于方法参数

  写法：

  @Multipart
  @POST("public")
  Call<BaseResult> uploadFile(@PartMap Map<String,RequestBody> RequestBodyMap);
  

• Query：用于条件字段参数，作用于方法参数

  写法：

  @GET("public")
  Call<BaseResult<List<User>>> getUser(@Query("userId") String userId);
  

• QueryMap：用于条件字段参数，作用于方法参数

  写法：

  @GET("public")
  Call<BaseResult<List<User>>> getUser(@QueryMap Map<String,String> map);
  

注：如果使用Post请求方式，建议使用Field或FieldMap+FormUrlEncoded传递参数，虽然Query或QueryMap也可以实现，但是Query或QueryMap都是将参数拼接在url后面的，而@Field或@FieldMap传递的参数时放在请求体的

Retrofit的配置

1.为Retrofit添加Converter

Retrofit中提供了Converter的概念，直译为转换器，Retrofit正常请求下来后，响应体为ResponseBody类型，我们需要将ResponseBody解析后才能得到我们想要的数据，那么如果我们想要直接在响应的时候拿到我们想要的数据怎么办呢？这时候我们就需要Converter来帮我们进行转换了。Retrofit提供了几个转换器，如下表：

依赖库	Gradle引用	来源
Gson	com.squareup.retrofit2:converter-gson	官方
Jackson	com.squareup.retrofit2:converter-jackson	官方
Moshi	com.squareup.retrofit2:converter-moshi	官方
Protobuf	com.squareup.retrofit2:converter-protobuf	官方
Wire	com.squareup.retrofit2:converter-wire	官方
Simple Framework	com.squareup.retrofit2:converter-simpleframework	官方
Scalars	com.squareup.retrofit2:converter-scalars	官方
LoganSquare	com.github.aurae.retrofit2:converter-logansquare	第三方
FastJson	org.ligboy.retrofit2:converter-fastjson 或org.ligboy.retrofit2:converter-fastjson-android	第三方

我们用Gson来介绍一下如何使用，首先引入Gson的Converter：

 com.squareup.retrofit2:converter-gson:2.1.0

然后通过Retrofit.Builder()配置添加Converter：

Retrofit retrofit=new Retrofit.Builder()
        .addConverterFactory(GsonConverterFactory.create())
        .baseUrl("http://192.168.1.79:8080/")
        .build();

RetrofitApi retrofitApi=retrofit.create(RetrofitApi.class);

接着让我们来测试一下吧：

接口返回数据格式为：

{
    "status": "1",
    "message": "success",
    "data": {
        "name": "zyyoona7",
        "age": "18",
        "height": "180cm"
    }
}

两个实体类分别为BaseResult和User：

//BaseResult类
public class BaseResult<T> {

    public static final int FAILURE = 0; // 失败
    public static final int SUCCESS = 1; // 成功

    private int status;  // 返回状态：0 失败   1 成功
    private String message;  // 返回信息
    private T data;  // 包装的对象
    //...省略getter setter
}

//User类
public class User implements Parcelable {

    private String name;
    private int age;
    private String height;
  
    //省略getter setter
}

请求接口：

@GET("public")
Call<BaseResult<User>> getUser();

代码调用：

RetrofitApi retrofitApi=retrofit.create(RetrofitApi.class);

Call<BaseResult<User>> userCall=retrofitApi.getUser();
userCall.enqueue(new Callback<BaseResult<User>>() {
            @Override
            public void onResponse(Call<BaseResult<User>> call, Response<BaseResult<User>> response) {
                //直接解析出我们想要的数据
            }

            @Override
            public void onFailure(Call<BaseResult<User>> call, Throwable t) {

            }
        });

2.为Retrofit添加RxJava支持

支持RxJava简直就是Retrofit的大招哇，用起来超级酷，如果你对RxJava还不了解请移步RxJava学习资料链接，是时候用起RxJava了。我们来配置一下，使Retrofit支持RxJava：

首先导入：

compile 'com.squareup.retrofit2:adapter-rxjava:2.1.0'
compile 'io.reactivex:rxandroid:1.2.1'
compile 'io.reactivex:rxjava:1.1.6'

然后通过Retrofit.Builder配置：

Retrofit retrofit=new Retrofit.Builder()
        .addConverterFactory(GsonConverterFactory.create())
       //RxJava支持
      .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
      .baseUrl("http://192.168.1.79:8080/")
        .build();

RetrofitApi retrofitApi=retrofit.create(RetrofitApi.class);

接着接口的返回值需要转变一下：

@GET("public")
Observable<BaseResult<User>> getUser();

这时候就可以开车了：

retrofitApi.getUser()
        .flatMap(new Func1<BaseResult<User>, Observable<User>>() {
            @Override
            public Observable<User> call(BaseResult<User> userBaseResult) {
                return Observable.just(userBaseResult.getData());
            }
        })
        .subscribeOn(Schedulers.io())
        .observeOn(AndroidSchedulers.mainThread())
        .subscribe(new Subscriber<User>() {
            @Override
            public void onCompleted() {

            }

            @Override
            public void onError(Throwable e) {

            }

            @Override
            public void onNext(User user) {
                Log.e(TAG, "onNext: " + user);
            }
        });

3.为Retrofit添加日志拦截器

Retrofit是很强大，但是调试的时候想要看到请求和响应的信息怎么办呢？Retrofit是一个封装，它依赖了OkHttp作为客户端，从源码中可以看出：

 public Retrofit build() {
      if (baseUrl == null) {
        throw new IllegalStateException("Base URL required.");
      }

      okhttp3.Call.Factory callFactory = this.callFactory;
      if (callFactory == null) {
        callFactory = new OkHttpClient();
      }
   //...省略
 }

从方法中看出，如果callFactory为null则会创建新的OkHttpClient，而且在Builder中提供了client()方法，可以让我们重新设置Client。这样我们可以通过给OkHttpClient添加拦截器来实现打印日志。

官方给我们提供了一个拦截器：

compile 'com.squareup.okhttp3:logging-interceptor:3.4.1'

在Retrofit2.1.0的版本中，如果我们的项目不导入OkHttp，默认将会导入OkHttp-3.3.0和okio-1.8.0，我们可以导入最新的OkHttp：

compile 'com.squareup.okhttp3:okhttp:3.4.1'

创建HttpLoggingInterceptor对象：

HttpLoggingInterceptor loggingInterceptor = new HttpLoggingInterceptor();
loggingInterceptor.setLevel(HttpLoggingInterceptor.Level.BODY);

打印日志有四个级别：

• Level.BODY：打印请求头，请求体和响应头，响应体的所有内容
• Level.HEADERS：打印请求和响应的头部信息
• Level.BASIC：打印基本信息
• Level.NONE：无打印

配置到Retrofit中：

Retrofit retrofit=new Retrofit.Builder()
        .addConverterFactory(GsonConverterFactory.create())
        .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
        //配置OkHttpClient
        .client(new OkHttpClient().newBuilder().addInterceptor(loggingInterceptor).build())
        .baseUrl("http://192.168.1.79:8080/")
        .build();

RetrofitApi retrofitApi=retrofit.create(RetrofitApi.class);

这样我们就可以畅爽的看日志信息了~~~

4.为Retrofit添加请求头

在项目中或多或少都会用到请求头，比如登录的token之类的，具体看服务器端如何规定，上面再介绍注解的时候我们已经看到了可以通过@Headers或者@Header来添加头部信息（具体写法请看Retrofit的注解第3小节）。这两种写法只是给特定的接口添加，如果接口多的话那手指就得抽筋了，有没有统一添加头部的方法呢？答案是肯定的。依然通过给OkHttp添加拦截器的方式。

自定义HeaderInterceptor：

public class HeaderInterceptor implements Interceptor {

    private Map<String, String> headers = new HashMap<>();

    public HeaderInterceptor(Map<String, String> headers) {
        this.headers = headers;
    }

    @Override
    public Response intercept(Chain chain) throws IOException {

        Request.Builder builder = chain.request().newBuilder();
        for (String key : headers.keySet()) {
            builder.addHeader(key, headers.get(key));
        }
        Request request = builder.build();
        return chain.proceed(request);
    }

然后就可以愉快的使用了：

Map<String,String> headerMap=new HashMap<>();
headerMap.put("token","123456");
//...more
HeaderInterceptor headerInterceptor=new HeaderInterceptor();

Retrofit retrofit=new Retrofit.Builder()
        .addConverterFactory(GsonConverterFactory.create())
        .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
        //配置OkHttpClient
        .client(new OkHttpClient().newBuilder()
                .addInterceptor(loggingInterceptor)
                .addInterceptor(headerInterceptor)
                .build())
        .baseUrl("http://192.168.1.79:8080/")
        .build();

RetrofitApi retrofitApi=retrofit.create(RetrofitApi.class);

更多使用可以猛戳：https://github.com/square/retrofit/wiki/Retrofit-Tutorials

Demo努力赶制中...其他篇幅努力编写中...

参考

如何使用Retrofit请求非Restful API
你真的会用Retrofit2吗?Retrofit2完全教程
Retrofit官网
Retrofit Wiki