Android Retrofit使用指南

翻译 2016年05月31日 10:02:04

Retrofit简介

Retrofit是大名鼎鼎的 Square 公司开源的适用于AndroidJava的网络请求库,官方的介绍非常简短

A type-safe HTTP client for Android and Java

Retrofit使用注解,能够极大的简化网络请求,在2.0版本默认使用Square自家的OkHttp作为底层Http Client,关于如何使用OkHttp配合Retrofit本文后面也会讲到。首先在build.gradle中加入

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

定义一个网络请求:

public interface ZhiHuApi {
@GET("users")
Call<List<Repo>> listRepos(@Path("user") String user);
}

Retrofit将网络请求转变成了Java interface的形式,interface要获得实例调用listRepos(String user),需要借助Retrofit.java这个类,通过Retrofit.Builder来配置Retrofit,再通过retrofit.create(final Class<T> service)获取接口的实例

class Factory {

  public static ZhiHuApi create() {
    Retrofit retrofit = new Retrofit.Builder()
                    .baseUrl("http://news-at.zhihu.com/")
                    .build();
            return retrofit.create(ZhiHuApi.class);
        }
}

@GET注解表示请求方式为GET,其中的字符串表示相对URL,而scheme host port被认为是BaseUrl设置到Retrofit中,注意BaseUrl需要以/结尾,这样每个接口定义的相对URL就不需要以/开始。如果在接口中定义的URL为全路径,将用这个全路径作为请求URLBaseUrl将不起作用。@Path标识get请求的请求参数,上面的listRepos可以认为是在请求http://news-at.zhihu.com/users?user=user
@POST注解表示请求方式为POST,通常和@FormUrlEncoded注解一起使用,在使用@FormUrlEncoded时可以使用@Field标识表单字段

@FormUrlEncoded
@POST("user/login.do")
Call<User> login(@Field("username") String userName, @Field("password") String password);

或者使用@FieldMap提交整个map

@FormUrlEncoded
@POST("user/login.do")
Call<User> login(@FieldMap Map<String, String> formMap);

当然你也可以把整个表单封装为一个实体,使用@Body一次提交

@FormUrlEncoded
@POST("user/login.do")
Call<User> login(@Body User user);

Multipart请求时使用@Multipart注解,用@Part标识每个RequestBody

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

定义好请求之后就可以调用call.enqueue()来执行请求,需要传入Callback<T>,其中T的类型编译器会根据Call<T>中的类型来判断,Retrofit和其他网络请求库一样对于Android平台做了线程切换,请求在后台执行,Callback<T>会回到main (UI) thread,如果是Java程序Callback<T>会继续回到调用它的线程。

ZhiHuApi zhiHuApi = BaseNetwork.Factory.create(ZhiHuApi.class);
        Call<User> call = zhiHuApi.login("username", "pwd");
        call.enqueue(new Callback<User>() {
            @Override
            public void onResponse(Call<User> call, Response<User> response) {

            }

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

            }
        });

为请求添加请求头时使用@Headers,这里就不做举例,因为app中通常是每个请求都需要携带请求头,不建议在Retrofit定义请求时传入,而是使用OkHttp来实现统一请求头。

Converter

Retrofit在默认情况下只能将Http的响应体反序列化到OkHttpResponseBody中,加入Converter可以将返回的数据直接格式化成你需要的样子,现有6个Converter可以直接使用:

  • 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 XML: com.squareup.retrofit2:converter-simplexml
  • Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars

之后在代码里加入(此处以GsonConverterFactory为例)

  Retrofit retrofit =new Retrofit.Builder()
                    .baseUrl(Constants.BASE_HTTP_URL)
                    .addConverterFactory(GsonConverterFactory.create())
                    .build();

返回的数据会使用Gson解析为对应传入的实体类,你也可以自定义Converter来实现更复杂的需求,只需要extends Converter.Factory然后重写

  @Override
  public Converter<ResponseBody, ?> responseBodyConverter(Type type, Annotation[] annotations,
      Retrofit retrofit) {
        //your own implements
  }

  @Override
  public Converter<?, RequestBody> requestBodyConverter(Type type,
     Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {
       //your own implements
  }

Retrofit终归只是应用层的api,真正的执行器是OkHttp,较为复杂的需求都需要从执行层入手,可以做到Retrofit对外不变的多种自定义统一封装。

OkHttp配合Retrofit使用

前文已经提到在Retrofit 2.0中已经默认使用OkHttp作为网络请求执行器,关于OkHttp的优点简单提一下:(原文链接)

  • 1.支持HTTP2/SPDY黑科技
  • 2.socket自动选择最好路线,并支持自动重连
  • 3.拥有自动维护的socket连接池,减少握手次数
  • 4.拥有队列线程池,轻松写并发
  • 5.拥有Interceptors轻松处理请求与响应(比如透明GZIP压缩,LOGGING)
  • 6.基于Headers的缓存策略

想要使用OkHttpRetrofit提供更高的定制性,给Retrofit设置自定义的OkHttpClient就可以了

Retrofit retrofit = new Retrofit.Builder()
                  .baseUrl(Constants.BASE_HTTP_URL)
                  .client(client)
                  .build();

之后就是构建一个OkHttpClient

OkHttpClient client = new OkHttpClient.Builder()
           // 向Request Header添加一些业务相关数据,如APP版本,token
           .addInterceptor(new HeadInterceptor())
           //日志Interceptor,可以打印日志
           .addInterceptor(logging)
           // 连接超时时间设置
           .connectTimeout(10, TimeUnit.SECONDS)
           // 读取超时时间设置
           .readTimeout(10, TimeUnit.SECONDS)
           // 失败重试
           .retryOnConnectionFailure(true)
           // 支持Https需要加入SSLSocketFactory
           .sslSocketFactory(sslSocketFactory)
           // 信任的主机名,返回true表示信任,可以根据主机名和SSLSession判断主机是否信任
           .hostnameVerifier(new HostnameVerifier() {
               @Override
               public boolean verify(String hostname, SSLSession session) {
                   return true;
               }
           })
           // 使用host name作为cookie保存的key
           .cookieJar(new CookieJar() {
               private final HashMap<HttpUrl, List<Cookie>> cookieStore = new HashMap<>();

               @Override
               public void saveFromResponse(HttpUrl url, List<Cookie> cookies) {
                   cookieStore.put(HttpUrl.parse(url.host()), cookies);
               }

               @Override
               public List<Cookie> loadForRequest(HttpUrl url) {
                   List<Cookie> cookies = cookieStore.get(HttpUrl.parse(url.host()));
                   return cookies != null ? cookies : new ArrayList<Cookie>();
               }
           })
           .build();

如果设置了sslSocketFactory却没有配置对应的hostnameVerifier,那么Https请求是无法成功的。上面用到两个Interceptor分别是HeadInterceptorHttpLoggingInterceptor,分别是用来添加请求头和打印请求日志的拦截器,OkHttp支持自定义拦截器,例如下面代码自定义的HeadInterceptor为请求加入Headers

public class HeadInterceptor implements Interceptor {

    @Override
    public Response intercept(Chain chain) throws IOException {
        Request originalRequest = chain.request();
        Request compressedRequest = originalRequest.newBuilder()
                .headers(Headers.of(getHeaders()))
                .build();
        return chain.proceed(compressedRequest);
    }
}

有时服务器会对POST提交的表单做参数校验,一种方式是在请求头里加入特定方式加密过的表单参数的Map,那么就需要先获取到请求的Map,通过FormBody可以实现

// if the server needs to verify post params, use this to get post params;
  RequestBody oidBody = originalRequest.body();
  Map<String, String> params = new HashMap<>();
  if (oidBody instanceof FormBody) {
    FormBody formBody = (FormBody) oidBody;
    for (int i = 0; i < formBody.size(); i++) {
        params.put(formBody.encodedName(i), formBody.encodedValue(i));
    }
  }

HttpLoggingInterceptor是_Square_ 提供的请求信息日志打印工具类,如果需要可以在build.gradle中加入

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

可以根据不同情况配置日志输出的Level

  • NONE 不输出日志
  • BASIC 只输出请求方式响应码等基本信息
  • HEADERS 只输出请求和响应的头部信息
  • BODY 输出请求和响应的头部和请求体信息

另外如果遇到两个接口有相互依赖关系,必须请求完第一个接口拿到数据后才知道第二个请求的URL,通常我们会定义两个Retrofit,因为RetrofitBaseUrl的统一配置的,不过现在可以通过实现动态BaseUrl来避免这个问题,先看DynamicBaseUrlInterceptor的代码

public class DynamicBaseUrlInterceptor implements Interceptor {
    private volatile String host;

    public void setHost(String host) {
        this.host = host;
    }

    @Override
    public Response intercept(Chain chain) throws IOException {
        Request originalRequest = chain.request();
        if (!TextUtils.isEmpty(host)) {
            HttpUrl newUrl = originalRequest.url().newBuilder()
                    .host(host)
                    .build();
            originalRequest = originalRequest.newBuilder()
                    .url(newUrl)
                    .build();
        }

        return chain.proceed(originalRequest);
    }
}

BaseUrl改变时只需要setHost()就可以让下次请求的Baseurl改变

Retrofit 与 RxJava 结合使用

本节需要对RxJava基本用法有了解,如果不了解可以忽略或者先去熟悉一下RxJavawiki,介绍的目的是因为两者结合使用确实很方便,关于RxJava之后会单独写。

RxJavaRx(全称Reactive Extensions)家族中的一员,是最近很火的响应式编程库,官方对于它的解释很简单

RxJava – Reactive Extensions for the JVM – a library for composing asynchronous and event-based programs using observable sequences for the Java VM.

一个异步的基于事件的观察者序列,可以理解为扩展的观察者模式,在Android中使用RxJava需要引入两个compileRxAndroid是专为Android平台打造来提供主线程切换等便利的工具项目。

   compile 'io.reactivex:rxandroid:1.2.0'
   // Because RxAndroid releases are few and far between, it is recommended you also
   // explicitly depend on RxJava's latest version for bug fixes and new features.
   compile 'io.reactivex:rxjava:1.1.5'

Retrofit提供了CallAdapterFactory,它是一个知道如何将call实例转换成其他类型的工厂类,目前支持的有:

  • RxJava
  • Guava
  • Java8

这些和Retrofit本身都是分离的,需要单独引入compile例如

compile 'com.squareup.retrofit2:adapter-rxjava:2.0.0'

在代码中配置CallAdapterFactory

Retrofit retrofit =new Retrofit.Builder()
                   .baseUrl(Constants.BASE_HTTP_URL)
                   .addConverterFactory(GsonConverterFactory.create())
                   .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
                   .build();

之后就可以把请求的返回改为Observable<T>

@GET("users")
Observable<List<Repo>> listRepos(@Path("user") String user);

请求时只需要

BaseNetwork.Factory.create(Foo.class)
                .listRepos("user")
                .observeOn(AndroidSchedulers.mainThread())//观察者所在的线程
                .subscribeOn(Schedulers.io())//请求执行的线程
                //如果正常执行会顺序调用onNext,onCompleted,如果出错则会调用onError
                .subscribe(new Observer<List<Repo>>() {
                    @Override
                    public void onCompleted() {

                    }

                    @Override
                    public void onError(Throwable e) {

                    }

                    @Override
                    public void onNext(List<Repo> list) {

                    }
                });

如果项需要服务器返回固定的格式用来定义一些业务上的错误如下

{
  "state":0,//状态码,0为业务正常
  "msg":"",//如果业务出错,携带错误信息
  "data":{}//包含实际业务实体
}

需要定义统一的响应实体,根据T传入的类型来获取业务实体真实的类型

public class BaseResult<T> {
    private int state;
    private String msg;
    private T data;

    public int getState() {
        return state;
    }

    public void setState(int state) {
        this.state = state;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }
}

请求中的泛型类型需要是BaseResult<T>

@GET("users")
Observable<BaseResult<List<Repo>>> listRepos(@Path("user") String user);

调用时也会有改变,需要经过一次拆解统一返回,处理错误的过程

BaseNetwork.Factory.create(Foo.class)
                .listRepos("user")
                .flatMap(new NetworkResultFunc1<List<Repo>>())
                .observeOn(AndroidSchedulers.mainThread())
                .subscribeOn(Schedulers.io())
                .subscribe(observer);

flatMap需要传入Func1<T, R>,Func1<T, R>继承了Function,只有一个方法,将泛型参数列表的第一个转换为第二个返回,它可以将Observable做一个展开,并返回一个新的Observable

public interface Func1<T, R> extends Function {
    R call(T t);
}

NetworkResultFunc1<List<Repo>>实现了Func1<T, R>,代码如下

public class NetworkResultFunc1<T> implements Func1<BaseResult<T>, Observable<T>> {

    @Override
    public Observable<T> call(final BaseResult<T> tBaseResult) {
        return Observable.create(new Observable.OnSubscribe<T>() {
            @Override
            public void call(Subscriber<? super T> subscriber) {
                int state = tBaseResult.getState();
                String msg = tBaseResult.getMsg();
                switch (state) {
                    case 0://if success, return data to client
                        subscriber.onNext(tBaseResult.getData());
                        break;
                    case 1000://if this means error
                        subscriber.onError(new ApiException(state, msg));
                        break;
                }
                subscriber.onCompleted();//no error, will execute onCompleted()
            }
        });
    }
}

如果state为0,则调用subscriber.onNext()向调用者返回数据,当state不等于0时意味着业务出错了,向subscriber.onError()中抛了一个ApiException,这样在Observer处会回调onError()终止整个事件流,调用者也能获得业务错误的相关信息。ApiException代码如下,就是一个自定义的RuntimeException

public class ApiException extends RuntimeException {
    private int state;
    private String msg;
    public ApiException(int state, String msg) {
        this.state = state;
        this.msg = msg;
    }

    public int getState() {
        return state;
    }

    public String getMsg() {
        return msg;
    }
}

对于Retrofit的介绍就先到这里,相信看到这里,你已经能够在项目中优雅的使用Retrofit了。

Retrofit使用指南

Retrofit使用指南 字数1991 阅读2678 评论18 喜欢48 Retrofit.jpg Retrofit简介 Retrofit是大名鼎鼎的 Squa...
  • weixin_36569761
  • weixin_36569761
  • 2016年12月13日 11:30
  • 214

【Android】Retrofit使用详解--有些相见恨晚

1.Retrofit介绍Retrofit,每次浏览各大网站总会看到它的身影,虽然感觉已经如此熟悉,但是确实又相当陌生,由于一直没有在项目中使用它,今天决定好好整理下,虽然Retrofit1.0的时代已...
  • wangkeke1860
  • wangkeke1860
  • 2016年07月27日 17:23
  • 3880

Android:手把手带你深入剖析 Retrofit 2.0 源码

前言 在Andrroid开发中,网络请求十分常用 而在Android网络请求库中,Retrofit是当下最热的一个网络请求库今天,我将手把手带你深入剖析Retrofit v2.0的源码,希望你们会喜欢...
  • carson_ho
  • carson_ho
  • 2017年06月26日 08:47
  • 10753

Android Retrofit2.0实现文件上传和下载

转载自:http://blog.csdn.net/Greathfs/article/details/51892499?locationNum=12 这篇主要介绍retrofit框架的上传文件到服...
  • lkx94
  • lkx94
  • 2016年10月25日 10:10
  • 5111

android Retrofit下载图片

Retrofit通过Url下载图片 1.首先工具类: /** * ClassName:DownloadImageUtils * Description TODO 下载图片 * created ...
  • u010326875
  • u010326875
  • 2017年05月27日 09:51
  • 1382

Android Studio导入Retrofit

dependencies中添加 这里是直接添加retrofit2.0版本 也可以按shift+ctrl+alt+s(as windows版) 搜索添加compile 'com.squareup....
  • yeyuyyy
  • yeyuyyy
  • 2016年09月23日 17:41
  • 1885

android开发之retrofit+okhttp+https+自有证书

由于开发中需要使用https与自有证书进行接口的请求。搜遍了google与baidu,出现最多的是“Android Https相关完全解析 当OkHttp遇到Https”这篇文章,结果我就依葫芦画瓢,...
  • abcwang1234
  • abcwang1234
  • 2016年12月22日 10:48
  • 536

Android 网络请求框架 Retrofit2.0实践使用总结

比较AsyncTask、Volley、Retrofit三者的请求时间 使用 单次请求 7个请求 25个请求 AsyncTask 941ms 4539ms 13957ms ...
  • xiongge358
  • xiongge358
  • 2016年03月27日 11:34
  • 5025

Android Retrofit下载网络图片

RetrofitUtil.getInstance().getImg().enqueue(new Callback() { @Override public void onRespons...
  • yijiaodingqiankun
  • yijiaodingqiankun
  • 2017年09月22日 11:28
  • 153

Android Retrofit+Okhttp断点续传

1.  断点续传原理 在本地下载过程中要使用数据库实时存储到底存储到文件的哪个位置了,这样点击开始继续传递时,才能通过HTTP的GET请求中的setRequestProperty()方法可以告诉服务...
  • taa1007
  • taa1007
  • 2017年11月10日 19:55
  • 668
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:Android Retrofit使用指南
举报原因:
原因补充:

(最多只允许输入30个字)