前言

retrofit相信大家都或多或少的听说过了，作为一个程序猿新的技术框架出来了我们就不得不去学习它了，不然我们只会止步不前，渐渐的被人甩在后面，有时候还是有那么一点无奈的，不知道大家是不是有同样的感受呢？好了，进入正题，今天我们就来学习一下一个非常火的网络请求框架retrofit，那么为什么它会这么火呢？有一点很关键就是它支持RxJava哦，后面有时间的话我会介绍RxJava，这篇文章就介绍一下retrofit。

retrofit初识

Retrofit一个基于OkHttp的Restful API请求工具。它是Square推出的HTTP框架，主要用于Android和Java。Retrofit将网络请求变成方法的调用，使用起来非常简洁方便。官方对于它的描述是这样的：

A type-safe HTTP client for Android and Java

当我们要去学习一样新的框架时，还有什么是比官方的资料更好的呢？所以，我们可以打开retrofit官网一步步的进行学习。

retrofit使用前的准备

• 首先我们新建一个Android工程

• 如果你尚未设置Internet权限，请在您的AndroidManifest.xml定义中添加以下行：

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

• 在正式在代码中使用retrofit之前我们要在AndroidStudio（本文demo使用的开发工具是AndroidStudio）的Gradle来添加依赖：compile 'com.squareup.retrofit2:retrofit:2.1.0'
  下面就是它的源码：

  
  
  
  

  看起来代码并不是很多，这是因为retrofit把网络请求这部分功能全部交给了OkHttp了。以上源码请自行阅读，在此我就不再赘述了，在完成以上步骤之后我们就可以准备真正的使用它了。

retrofit官网简单使用方法

官网上关于retrofit的介绍非常简单粗暴，一开始就展示了如何使用Retrofit来进行一个最基本的网络请求。

我们来分析一下上图中的代码：
1、首先注意到了一个关键的说明信息：Retrofit会将你的HTTP API转换为Java中的interface的形式
2、然后关注的是它是通过new Retrofit.Builder()...build()进行Retrofit的构建，可以了解的是这里使用的是Builder模式。

在Android中，经常用到Builder模式的可能就是AlerDialog 了。Builder模式用于将一个复杂的对象的构建和它的表示分离，使得同样的构建过程可以创建不同的表示。这里Retrofit使用Builder模式支持了支持不同的转换（就是将HTTP返回的数据解析成Java对象，主要有Xml、Gson等）和返回（主要作用就是将Call对象转换成另一个对象，比如RxJava）。这里也就真正的达到了构建复杂对象和它的部件进行解耦。

3、接着通过GitHubService service = retrofit.create(GitHubService.class); create方法创建网络请求接口类GitHubService 的实例。也正是使用该对象的listRepos方法完成了Call<List<Repo>> repos = service.listRepos("octocat"); 获取到了数据。
至此一个简单的网络请求就结束了，就是这么简单粗暴！

运用retrofit编写自己的demo

学以致用，既然学习了新的知识，我们就赶紧的运用起来吧！下面我利用retrofit做一个简单的关于获取微信精选分类的网络请求Demo。该网络请求地址为：http://apicloud.mob.com/wx/article/category/query?key=1228b5a794dc8
首先我们为返回结果写一个实体类ResponseBean，代码如下：

public class ResponseBean {
    private String msg;
    private String retCode;
    private List<ResultBean> result;
    public String getMsg() {
        return msg;
    }
    public void setMsg(String msg) {
        this.msg = msg;
    }
    public String getRetCode() {
        return retCode;
    }
    public void setRetCode(String retCode) {
        this.retCode = retCode;
    }
    public List<ResultBean> getResult() {
        return result;
    }
    public void setResult(List<ResultBean> result) {
        this.result = result;
    }
    public static class ResultBean {
        private String cid;
        private String name;
        public String getCid() {
            return cid;
        }
        public void setCid(String cid) {
            this.cid = cid;
        }
        public String getName() {
            return name;
        }
        public void setName(String name) {
            this.name = name;
        }
    }
}

然后仿照官网写法把我们自己的HTTP API封装成interface，新建一个HttpService文件，代码如下：

public interface HttpService {
    @GET("category/query")
    Call<ResponseBean> getWxData(@Query("key") String key);
}

之后我们在MainActivity中书写逻辑代码：

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        Retrofit retrofit = new Retrofit.Builder()
                .baseUrl("http://apicloud.mob.com/wx/article/")
                .build();
        HttpService httpService = retrofit.create(HttpService.class);
        retrofit2.Call<ResponseBean> call = httpService.getWxData("1228b5a794dc8");
    }
}

好的，现在我就开始运行demo了，然而。。。。。。

程序竟然报错了！此时我的内心是崩溃的，既然报错了那我们就来看一看究竟是什么错吧，通过异常信息的描述，我们得知这似乎与类型的转换相关，然后带着这个疑问再去查看官方文档，于是发现：

从上述信息我们得知Retrofit默认只能将响应体转换为OkHttp中的ResponseBody，而我们之前为Call设置的泛型类型是自定义的类型ResponseBean 。将JSON格式的数据转换为JavaBean，很自然就会想到GSON。而Retrofit如果要执行这种转换是要依赖于另一个库的，所以我们还得在项目中配置另一个依赖：

compile 'com.squareup.retrofit2:converter-gson:2.1.0'

参照官方文档我们将代码修改为：

Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("http://apicloud.mob.com/wx/article/")
            .addConverterFactory(GsonConverterFactory.create())
            .build();

我们再一次运行，终于成功了！那么我们请求的结果在哪里呢？对于熟悉OkHttp的童鞋这个应该非常简单了，为了验证我们是否请求到了数据，我将请求结果打印出来进行验证，代码如下：

call.enqueue(new Callback<ResponseBean>() {

        @Override
        public void onResponse(Call<ResponseBean> call, Response<ResponseBean> response) {
            List<ResponseBean.ResultBean> resultList = response.body().getResult();
            if (resultList != null) {
                for (int i = 0; i < resultList.size(); i++) {
                    System.out.println(resultList.get(i).getCid() + "," + resultList.get(i).getName());
                }
            }
        }

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

        }
    });

运行之后的打印结果：

到此为止，经过我们的一番摸索和折腾，关于Retrofit很基本的一个demo就这么搞出来了。 现在我们对于Retrofit大致的使用，在心里已经有个大概了。

retrofit深入学习

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

  • GET：对应HTTP的get请求方法
    事实上前面我们已经使用到了注解@GET， 而对于@GET来说，我们知道HTTP-GET是可以将一些简单的参数信息直接通过URL进行上传的，所以上述Demo中的注解又可以像下面这样使用：

    
    

• POST、PUT、DELETE、HEAD、PATCH、OPTIONS：分别对应HTTP的post、put、delete、head、patch、options请求方法，使用方法和GET都是一样的：

  
  

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

  
  
• @Path
  不知道大家注意到官方示例和我们刚才自己写的demo中有一个细小的差别没，就是下面这样的东西：

@GET("users/{user}/repos")//官方的
@GET("category/query")//自己的

我们注意到官方的API的URL中有一个”{user}“这样的东西？它的作用是什么呢？从官方文档的介绍中，我们注意到一个叫做replacement blocks的东西。可以最简单的将其理解为路径替换块，用”{}”表示，与注解@path配合使用。当然我们自己实际去使用一下能够对其有一个更加深刻的理解，所以我们将我们之前的demo修改一下，变成下面这样：

此时我将调用的方法修改为下面所示：

retrofit2.Call<ResponseBean> call = httpService.getWxData("query", "1228b5a794dc8");

运行之后同样可以得到上述相同的结果，那么这样做的好处是什么？显然是为了解耦。以官方的例子来说：
https://api.github.com/users/{user}/repos 中的{user}就是为了针对不同的github用户解耦。因为这里假设随便代入某某人的gitthub，URL就将变成： https://api.github.com/users/XXX/repos ，而github的用户千千万万，如果使用我们之前的方式代码就会如下：

@GET("users/XXX/repos")

这二者的优劣一目了然，我们肯定不会想要为了获取不同的user的repos去写N多个套路完全相同的API接口吧。

• @Query
  从前面的demo中我们大概已经知道了@Query的作用了吧，它就是我们进行网络请求时需要传入的请求参数

@GET("category/query")
Call<ResponseBean> getWxData(@Query("key") String key);

调用方法：

retrofit2.Call<ResponseBean> call = httpService.getWxData("1228b5a794dc8");

• @QueryMap
  Query可以代表一个参数，那如果我们要传入的参数有10个呢？100个呢？这意味着我要在方法中声明10个、100个@Query参数？当然不是！Retrofit也考虑到了这点，所以针对于复杂的参数上传，为我们准备了@QueryMap。现在来修改我们自己的demo：

@GET("category/query")
Call<ResponseBean> getWxData(@QueryMap Map<String,String> params);

调用方法：

    Map<String, String> params = new HashMap<>();
    params.put("param1", "value1");
    params.put("param2", "value2");
    retrofit2.Call<ResponseBean> call = httpService.getWxData(params);

• @Headers与@Header
  Headers：添加请求头，作用于方法
  Header：用于动态添加头部，作用于方法参数

@Headers使用示例

@Headers("Content-type:application/x-www-form-urlencoded;charset=UTF-8")
@GET("category/query")
Call<ResponseBean> getWxData(@Query("key") String key);

或

@Headers({
   "Content-type:application/x-www-form-urlencoded;charset=UTF-8",
   "User-Agent: Retrofit-Sample-App"
})
@GET("category/query")
Call<ResponseBean> getWxData(@Query("key") String key);

@Header使用示例

@GET("category/query")
Call<ResponseBean> getWxData(@Header("Token") String token);

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

@GET("category/query")
Call<ResponseBean> getWxData(@Url String url, @Query("key") String key);

请求的时候，url会替换掉category/query

• @FormUrlEncoded
  FormUrlEncoded：指请求体是一个Form表单，Content-Type=application/x-www-form-urlencoded，需要和参数类注解@Field，@FieldMap搭配使用
• @Field
  Field：用于表单字段参数，（需要配合FormUrlEncoded使用）作用于方法参数

@FormUrlEncoded
@POST("category/query")
Call<ResponseBean> getWxData(@Field("key") String key);

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

@FormUrlEncoded
@POST("category/query")
Call<ResponseBean> getWxData(@FieldMap Map<String,String> fieldMap);

• @Multipart
  Multipart：指请求体是一个支持文件上传的Form表单，Content-Type=multipart/form-data，需要和参数类注解@Part，@PartMap搭配使用
• @Part
  Part：用于表单字段参数，适用于文件上传，（需要配合Multipart使用）作用于方法参数

@Multipart
@POST("category/query")
Call<ResponseBean> getWxData(@Part File file);

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

@Multipart
@POST("category/query")
Call<ResponseBean> getWxData(@PartMap Map<String, File> fileMap);

好了，这些常用的注解就介绍到这里了，如果还想了解更多的大家可以查看源码或前往官网进行查阅。

为Retrofit添加Converter

在上面的Demo中我们曾经遇到过一次程序报错的问题，最后发现是转换器的问题所致，Retrofit中提供了Converter的概念，直译为转换器，Retrofit正常请求下来后，响应体为ResponseBody类型，我们需要将ResponseBody解析后才能得到我们想要的数据，那么如果我们想要直接在响应的时候拿到我们想要的数据怎么办呢？这时候我们就需要Converter来帮我们进行转换了。Retrofit提供了几个转换器，如下表所示：

结语

关于retrofit的探索之路到此就暂时告一段落了，其实支持RxJava才是Retrofit的大招哇，用起来超级酷，后面有时间的话再和大家一起学习一下RxJava，由于本人水平有限，此文如有不足之处还望大家指出哦！