Android Retrofit框架解析

随着Google对HttpClient的摒弃,和Volley的逐渐没落,OkHttp开始异军突起,而Retrofit则对okHttp进行了强制依赖。Retrofit也是Square公司开发的一款针对Android网络请求的框架，其实质就是对okHttp的封装，使用面向接口的方式进行网络请求，利用动态生成的代理类封装了网络接口。retrofit非常适合于RESTful url格式的请求，更多使用注解的方式提供功能。

既然是RESTful架构,那么我们就来看一下什么是REST吧。

REST(REpresentational State Transfer)是一组架构约束条件和原则。RESTful架构都满足以下规则：

（1）每一个URI代表一种资源；

（2）客户端和服务器之间，传递这种资源的某种表现层；

（3）客户端通过四个HTTP动词（GET，POST，PUT，DELETE），对服务器端资源进行操作，实现”表现层状态转化”。

更多关于REST的介绍

使用Retrofit2.0

Eclipse的用户，添加Jar包和网络访问权限

下载最新的jar：我将整理的所有jar包已上传

注意：

1.Retrofit必须使用okhttp请求了，如果项目中没有okhttp的依赖的话，肯定会出错 。

2.okhttp内部依赖okio所以也要添加。

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

用法介绍

创建API接口

在retrofit中通过一个Java接口作为http请求的api接口。

//定以接口public interface GitHubService {  @GET("users/{user}/repos")  Call<List<Repo>> listRepos(@Path("user") String user);}

创建retrofit实例

/**获取实例*/Retrofit retrofit = new Retrofit.Builder()    //设置OKHttpClient,如果不设置会提供一个默认的    .client(new OkHttpClient())    //设置baseUrl    .baseUrl("https://api.github.com/")    //添加Gson转换器    .addConverterFactory(GsonConverterFactory.create())    .build();

注：

1.retrofit2.0后：BaseUrl要以/结尾；@GET 等请求不要以/开头；@Url: 可以定义完整url，不要以 / 开头。

2.addConverterFactory提供Gson支持，可以添加多种序列化Factory，但是GsonConverterFactory必须放在最后,否则会抛出异常。

调用API接口

GitHubService service = retrofit.create(GitHubService.class);//同步请求//https://api.github.com/users/octocat/reposCall<List<Repo>> call = service.listRepos("octocat");try {     Response<List<Repo>> repos  = call.execute();} catch (IOException e) {     e.printStackTrace();}//不管同步还是异步，call只能执行一次。否则会抛 IllegalStateExceptionCall<List<Repo>> clone = call.clone();//异步请求clone.enqueue(new Callback<List<Repo>>() {        @Override        public void onResponse(Response<List<Repo>> response, Retrofit retrofit) {            // Get result bean from response.body()            List<Repo> repos = response.body();            // Get header item from response            String links = response.headers().get("Link");            /**            * 不同于retrofit1 可以同时操作序列化数据javabean和header            */        }        @Override        public void onFailure(Throwable throwable) {            showlog(throwable.getCause().toString());           }});

取消请求

我们可以终止一个请求。终止操作是对底层的httpclient执行cancel操作。即使是正在执行的请求，也能够立即终止。

call.cancel();

retrofit注解

• 方法注解，包含@GET、@POST、@PUT、@DELETE、@PATH、@HEAD、@OPTIONS、@HTTP。

• 标记注解，包含@FormUrlEncoded、@Multipart、@Streaming。

• 参数注解，包含@Query、@QueryMap、@Body、@Field，@FieldMap、@Part，@PartMap。

• 其他注解，包含@Path、@Header、@Headers、@Url。

(1)一般的get请求

public interface IWeatherGet {    @GET("GetMoreWeather?cityCode=101020100&weatherType=0")    Call<Weather> getWeather();}

可以看到有一个getWeather(）方法，通过@GET注解标识为get请求，@GET中所填写的value和baseUrl组成完整的路径，baseUrl在构造retrofit对象时给出。

Retrofit retrofit = new Retrofit.Builder()        /**http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101020100&weatherType=0*/        //注意baseurl要以/结尾                .baseUrl("http://weather.51wnl.com/weatherinfo/")                .addConverterFactory(GsonConverterFactory.create())                .build();IWeatherGet weather = retrofit.create(IWeatherGet.class);Call<Weather> call = weather.getWeather();call.enqueue(new Callback<Weather>() {    @Override    public void onResponse(Response<Weather> response, Retrofit retrofit) {        Weather weather = response.body();        WeatherInfo weatherinfo = weather.weatherinfo;        showlog("weather="+weatherinfo.toString());    }@Override    public void onFailure(Throwable throwable) {        showlog(throwable.getCause().toString());           }});

（2）动态url访问@PATH

上面说的@GET注解是将baseUrl和@GET中的value组成完整的路径。有时候我们可以将路径中某个字符串设置为不同的值来请求不同的数据，这时候怎么办呢？

譬如：

//用于访问上海天气http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101020100&weatherType=0//用于访问上海人口（这里只是假设，其实这个url并不能返回json）http://weather.51wnl.com/weatherinfo/GetMorePeople?cityCode=101010100&weatherType=0

即通过不同的请求字符串访问不同的信息，返回数据为json字符串。那么可以通过retrofit提供的@PATH注解非常方便的完成上述需求。

public interface IWeatherPath {    @GET("{info}?cityCode=101020100&weatherType=0")    Call<Weather> getWeather(@Path("info") String info);}

可以看到我们定义了一个getWeather方法，方法接收一个info参数，并且我们的@GET注解中使用{info}?cityCode=101020100&weatherType=0声明了访问路径，这里你可以把{info}当做占位符，而实际运行中会通过@PATH(“info”)所标注的参数进行替换。

Retrofit retrofit = new Retrofit.Builder()                .baseUrl("http://weather.51wnl.com/weatherinfo/")                .addConverterFactory(GsonConverterFactory.create())                .build();IWeatherPath weather = retrofit.create(IWeatherPath.class);Call<Weather> call = weather.getWeather("GetMoreWeather");call.enqueue(new Callback<Weather>() {    @Override    public void onResponse(Response<Weather> response, Retrofit retrofit) {        Weather weather = response.body();        WeatherInfo weatherinfo = weather.weatherinfo;        showlog("weather="+weatherinfo.toString());    }    @Override    public void onFailure(Throwable throwable) {        showlog(throwable.getCause().toString());           }});

（3）查询参数的设置@Query@QueryMap

文章开头提过，retrofit非常适用于restful url的格式，那么例如下面这样的url：

//用于访问上海天气http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101020100&weatherType=0//用于访问北京天气http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101010100&weatherType=0

即通过传参方式使用不同的citycode访问不同城市的天气，返回数据为json字符串。我们可以通过@Query注解方便的完成，我们再次在接口中添加一个方法：

public interface IWeatherQuery {    @GET("GetMoreWeather")    Call<Weather> getWeather(@Query("cityCode") String cityCode, @Query("weatherType") String weatherType);}/**省略retrofit的构建代码*/Call<Weather> call = weather.getWeather("101020100", "0");//Call<Weather> call = weather.getWeather("101010100", "0");/**省略call执行相关代码*/

当我们的参数过多的时候我们可以通过@QueryMap注解和map对象参数来指定每个表单项的Key，value的值，同样是上面的例子，还可以这样写：

public interface IWeatherQueryMap {    @GET("GetMoreWeather")    Call<Weather> getWeather(@QueryMap Map<String,String> map);}//省略retrofit的构建代码Map<String, String> map = new HashMap<String, String>();map.put("cityCode", "101020100");map.put("weatherType", "0");Call<Weather> call = weather.getWeather(map);//省略call执行相关代码

这样我们就完成了参数的指定，当然相同的方式也适用于POST，只需要把注解修改为@POST即可。

注：对于下面的写法：

@GET("GetMoreWeather?cityCode={citycode}&weatherType=0")Call<Weather> getWeather(@Path("citycode") String citycode);

乍一看可以啊，实际上运行是不支持的~估计是@Path的定位就是用于url的路径而不是参数，对于参数还是选择通过@Query来设置。

（4）POST请求体方式向服务器传入json字符串@Body

我们app很多时候跟服务器通信，会选择直接使用POST方式将json字符串作为请求体发送到服务器，那么我们看看这个需求使用retrofit该如何实现。

public interface IUser { @POST("add") Call<List<User>> addUser(@Body User user);}/省略retrofit的构建代码 Call<List<User>> call = user.addUser(new User("watson", "male", "28"));//省略call执行相关代码

可以看到其实就是使用@Body这个注解标识我们的参数对象即可，那么这里需要考虑一个问题，retrofit是如何将user对象转化为字符串呢？将实例对象根据转换方式转换为对应的json字符串参数，这个转化方式是GsonConverterFactory定义的。

对应okhttp，还有两种requestBody，一个是FormBody，一个是MultipartBody，前者以表单的方式传递简单的键值对，后者以POST表单的方式上传文件可以携带参数，retrofit也二者也有对应的注解，下面继续~

（5）表单的方式传递键值对@FormUrlEncoded + @Field@FieldMap

这里我们模拟一个登录的方法，添加一个方法：

public interface IUser {    @FormUrlEncoded    @POST("login")       Call<User> login(@Field("username") String username, @Field("password") String password);}//省略retrofit的构建代码Call<User> call = user.login("watson", "123");//省略call执行相关代码

看起来也很简单，通过@POST指明url，添加FormUrlEncoded，然后通过@Field添加参数即可。
当我们有很多个表单参数时也可以通过@FieldMap注解和Map对象参数来指定每个表单项的Key，value的值。

public interface IUser {    @FormUrlEncoded    @POST("login")       Call<User> login(@FieldMap Map<String,String> fieldMap);}//省略retrofit的构建代码Map<String, String> propertity = new HashMap<String, String>();positories.put("name", "watson");positories.put("password", "123");Call<User> call = user.login(propertity);//省略call执行相关代码

（6）文件上传@Multipart + @Part@PartMap

涉及到操作硬盘文件，首先需要添加权限：

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

1.下面先看一下单文件上传，依然是再次添加个方法：

public interface IUser {    @Multipart    @POST("register")    Call<User> registerUser(@Part MultipartBody.Part photo, @Part("username") RequestBody username, @Part("password") RequestBody password);}

这里@MultiPart的意思就是允许多个@Part了，我们这里使用了3个@Part，第一个我们准备上传个文件，使用了MultipartBody.Part类型，其余两个均为简单的键值对。

File file = new File(Environment.getExternalStorageDirectory(), "icon.png");RequestBody photoRequestBody = RequestBody.create(MediaType.parse("image/png"), file);MultipartBody.Part photo = MultipartBody.Part.createFormData("photos", "icon.png", photoRequestBody);Call<User> call = user.registerUser(photo, RequestBody.create(null, "abc"), RequestBody.create(null, "123"));

这里感觉略为麻烦。不过还是蛮好理解~~多个@Part，每个Part对应一个RequestBody。
注：这里还有另外一个方案也是可行的：

public interface ApiInterface {        @Multipart        @POST ("/api/Accounts/editaccount")        Call<User> editUser (@Header("Authorization") String authorization, @Part("photos\"; filename=\"icon.png") RequestBody file , @Part("FirstName") RequestBody fname, @Part("Id") RequestBody id);}

这个value设置的值不用看就会觉得特别奇怪，然而却可以正常执行，原因是什么呢？
当上传key-value的时候，实际上对应这样的代码：

builder.addPart(Headers.of("Content-Disposition", "form-data; name=\"" + key + "\""), RequestBody.create(null, params.get(key)));

也就是说，我们的@Part转化为了

Headers.of("Content-Disposition", "form-data; name=\"" + key + "\"")

这么一看，很随意，只要把key放进去就可以了。但是，retrofit2并没有对文件做特殊处理，文件的对应的字符串应该是这样的

Headers.of("Content-Disposition", "form-data; name="photos";filename="icon.png"");

与键值对对应的字符串相比，多了个\”; filename=\”icon.png，就因为retrofit没有做特殊处理，所以你现在看这些hack的做法

@Part("photos\"; filename=\"icon.png")==> key = photos\"; filename=\"icon.pngform-data; name=\"" + key + "\"拼接结果：==>form-data; name="photos"; filename="icon.png"

因为这种方式文件名写死了，我们上文使用的的是@Part MultipartBody.Part file,可以满足文件名动态设置。

2.如果是多文件上传呢？

public interface IUser {     @Multipart     @POST("register")     Call<User> registerUser(@PartMap Map<String, RequestBody> params, @Part("password") RequestBody password);}

这里使用了一个新的注解@PartMap，这个注解用于标识一个Map，Map的key为String类型，代表上传的键值对的key(与服务器接受的key对应),value即为RequestBody，有点类似@Part的封装版本。

File file = new File(Environment.getExternalStorageDirectory(), "local.png");RequestBody photo = RequestBody.create(MediaType.parse("image/png", file);Map<String, RequestBody> map = new HashMap<>(String, RequestBody);map.put("photos\"; filename=\"icon.png", photo);map.put("username",  RequestBody.create(null, "abc"));Call<User> call = user.registerUser(map, RequestBody.create(null, "123"));

可以看到，可以在Map中put进一个或多个文件，键值对等，当然你也可以分开，单独的键值对也可以使用@Part，这里又看到设置文件的时候，相对应的key很奇怪，例如上例”photos\”; filename=\”icon.png”,前面的photos就是与服务器对应的key，后面filename是服务器得到的文件名，ok，参数虽然奇怪，但是也可以动态的设置文件名，不影响使用。

（7）下载文件

下载文件还是推荐OkHttp方式，这里对retrofit下载也进行说明一下

@GET("download")Call<ResponseBody> downloadTest();Call<ResponseBody> call = user.downloadTest();call.enqueue(new Callback<ResponseBody>() {    @Override    public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {        InputStream is = response.body().byteStream();        //save file    }    @Override    public void onFailure(Call<ResponseBody> call, Throwable t){}});

可以看到这种方式下载非常鸡肋，onReponse回调虽然在UI线程，但是你还是要处理io操作，也就是说你在这里还要另外开线程操作，或者你可以考虑同步的方式下载。所以还是建议使用okhttp去下载。

（8）添加请求头@Header@Headers

@Header：header处理，不能被互相覆盖，所有具有相同名字的header将会被包含到请求中。

//静态设置Header值@Headers("Authorization: authorization")@GET("widget/list")Call<User> getUser()

@Headers 用于修饰方法,用于设置多个Header值。

@Headers({    "Accept: application/vnd.github.v3.full+json",    "User-Agent: Retrofit-Sample-App"})@GET("users/{username}")Call<User> getUser(@Path("username") String username);

还可以使用@Header注解动态的更新一个请求的header。必须给@Header提供相应的参数，如果参数的值为空header将会被忽略，否则就调用参数值的toString()方法并使用返回结果。

//动态设置Header值@GET("user")Call<User> getUser(@Header("Authorization") String authorization)

配置OkHttpClient

很多时候，比如你使用retrofit需要统一的log管理，缓存管理，给每个请求添加统一的header等，这些都应该通过okhttpclient去操作。Retrofit 2.0 底层依赖于okHttp，所以需要使用okHttp的Interceptors来对所有请求进行拦截。

OkHttpClient client = new OkHttpClient();client.networkInterceptors().add(new Interceptor() {    @Override    public com.squareup.okhttp.Response intercept(Chain chain) throws IOException {        com.squareup.okhttp.Response response = chain.proceed(chain.request());        // Do anything with response here        return response;    }});Retrofit retrofit = new Retrofit.Builder()        .baseUrl(BASE_URL)        ...        .client(client) //传入自己定义的client        .build();

或许你需要更多的配置，你可以单独写一个OkhttpClient的单例生成类，在这个里面完成你所需的所有的配置，然后将OkhttpClient实例通过方法公布出来，设置给retrofit。

Retrofit retrofit = new Retrofit.Builder()    .callFactory(OkHttpUtils.getClient())    .build();

callFactory方法接受一个okhttp3.Call.Factory对象，OkHttpClient即为一个实现类。

转换器Converter

在上面的例子中通过获取ResponseBody后，我们自己使用Gson来解析接收到的Json格式数据。在Retrofit中当创建一个Retrofit实例的时候可以为其添加一个Json转换器，这样就会自动将Json格式的响应体转换为所需要的Java对象。

Retrofit retrofit = new Retrofit.Builder()        .baseUrl(BASE_URL)        .addConverterFactory(GsonConverterFactory.create()) //转换器        .build();

默认转换器

默认情况下，Retrofit只能够反序列化Http体为OkHttp的ResponseBody类型，并且只能够接受ResponseBody类型的参数作为@body。
添加转换器可以支持其他的类型，为了方便的适应流行的序列化库，Retrofit提供了六个兄弟模块：

• Gson : com.squareup.retrofit:converter-gson

• Jackson: com.squareup.retrofit:converter-jackson

• Moshi: com.squareup.retrofit:converter-moshi

• Protobuf: com.squareup.retrofit:converter-protobuf

• Wire: com.squareup.retrofit:converter-wire

• Simple XML: com.squareup.retrofit:converter-simplexml

Retrofit2.0源码分析

因微信字数限制，请点击左下角原文链接查看

Demo下载地址也请点击原文链接查看