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
