浅谈Android网络封装框架Retrofit

开源框架地址:https://github.com/square/retrofit

英文文档官网:http://square.github.io/retrofit/

RxJava框架:https://github.com/ReactiveX/RxJava

okhttp框架:https://github.com/square/okhttp

在对Android 开发中，我们都是从原生的HttpUrlConnection到经典的 Apache公司的HttpClient，再到对前面这些网络基础框架的封装（比如Volley、AsyncHttpClient等）。Http请求相关开源框架还是很多的，今天我们讲解 Square 公司开源的Retrofit。Square 公司的框架总是一如既往的简洁优雅！Retrofit更是以其简易的接口配置、强大的扩展支持、优雅的代码结构受到大家的追捧。

Retrofit是一个 RESTful 的 HTTP 网络请求框架的封装。注意这里并没有说它是网络请求框架，主要原因在于网络请求的工作并不是Retrofit来完成的。Retrofit2.0 开始内置OkHttp，前者专注于接口的封装，后者专注于网络请求的高效，二者分工协作！

我们的应用程序通过Retrofit请求网络，实际上是使用Retrofit接口层封装请求参数、Header、Url 等信息，之后由OkHttp完成后续的请求操作，在服务端返回数据之后，OkHttp将原始的结果交给Retrofit，后者根据用户的需求对结果进行解析的过程。

Retrofit的使用就像它的编码风格一样，非常简单，首先你需要在你的 build.gradle 中添加依赖：

[java]view plaincopy

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

加入我们想要访问 GitHub 的 api 对，那么我们就定义一个接口：

接口当中的listRepos方法，就是我们想要访问的api了，在发起请求时，{user}会被替换为方法的第一个参数user。

Retrofit支持的协议包括GET/POST/PUT/DELETE/HEAD/PATCH，当然你也可以直接用HTTP来自定义请求。这些协议均以注解的形式进行配置例如下面GET：

[java]view plaincopy

publicinterfaceGitHubService {

@GET("users/{user}/repos")

Call> listRepos(@Path("user") String user);

}

这些注解都有一个参数 value，用来配置其路径，比如示例中的 users/{user}/repos，我们还注意到在构造Retrofit之时我们还传入了一个baseUrl("https://api.github.com/")，请求的完整 Url 就是通过baseUrl与注解的value（下面称 “path“ ） 整合起来的，具体整合的规则如下：

path是绝对路径的形式：

path = "/apath"，baseUrl = "http://host:port/a/b"

Url = "http://host:port/apath"

path是相对路径，baseUrl是目录形式：

path = "apath"，baseUrl = "http://host:port/a/b/"

Url = "http://host:port/a/b/apath"

path是相对路径，baseUrl是文件形式：

path = "apath"，baseUrl = "http://host:port/a/b"

Url = "http://host:port/a/apath"

path是完整的 Url：

path = "http://host:port/aa/apath"，baseUrl = "http://host:port/a/b"

Url = "http://host:port/aa/apath"

建议采用第二种方式来配置，并尽量使用同一种路径形式。

构造 Retrofit:

[java]view plaincopy

Retrofit retrofit =newRetrofit.Builder.baseUrl("https://api.github.com/").build;

GitHubService service = retrofit.create(GitHubService.class);

//service发起请求

Call> repos = service.listRepos("octocat");

返回的repos其实并不是真正的数据结果，它更像一条指令，你可以在合适的时机去执行它：

[java]view plaincopy

Lisg data = repos.execute();//同步调用

repos.enqueue(newCallback>(){

@Override

publicvoidonResponse(Call> call, Response> response){

List data = response.body();

}

@Override

publicvoidonFailure(Call> call,Throwable t){

t.printStackTrace();

}

});

是不是很简单，其中的接口定义方式就是我们前面有篇博客讲的（浅谈Java回调机制）http://blog.csdn.net/caihongdao123/article/details/51657840

认识Query & QueryMap

[java]view plaincopy

@GET("/list") Call list(@Query("page")intpage);

Query其实就是 Url 中 ‘?’ 后面的 key-value，比如：这里的 cate=android就是一个Query，而我们在配置它的时候只需要在接口方法中增加一个参数，即可：

[java]view plaincopy

interfacePrintlnServer{

@GET("/")

Call cate(@Query("cate") String cate);

}

当面临参数很多的情况，我们就采用QueryMap！

认识Field & FieldMap

[java]view plaincopy

@FormUrlEncoded

@POST("/")

Call example(@Field("name") String name,@Field("occupation") String occupation);

我们用 Field声明了表单的项，这样提交表单就跟普通的函数调用一样简单直接了，表单项不确定个数就试用FieldMap。

认识Part & PartMap

[java]view plaincopy

publicinterfaceFileUploadService {

@Multipart@POST("upload")

Call upload(@Part("description") RequestBody description,@PartMultipartBody.Part file);

}

如果你需要上传文件，和我们前面的做法类似，定义一个接口方法，需要注意的是，这个方法不再有 @FormUrlEncoded这个注解，而换成了@Multipart，后面只需要在参数中增加Part就可以了。也许你会问，这里的Part和Field究竟有什么区别，其实从功能上讲，无非就是客户端向服务端发起请求携带参数的方式不同，并且前者可以携带的参数类型更加丰富，包括数据流。也正是因为这一点，我们可以通过这种方式来上传文件，下面我们就给出这个接口的使用方法：

[java]view plaincopy

//先创建Service

FileUploadService service = retrofit.create(FileUploadService.class);

//构建要上传的文件

File file =newFile(filename);

RequestBody requestFile = RequestBody.crate(MediaType.parse("application/otcet-stream"),file);

MultipartBody.Part body = MultipartBody.Part.crateFormData("aFile",file.getNmae(),requestFile);

String description = RequestBody.create(MediaType.parse("multipart/form-data"),descriptionString);

Call call = service.upload(description,body);

call.enqueue(newCallback(){

@Override

publicvoidonResponse(Call response){

Log.d("success","success");

}

@Override

publicvoidonFailure(Call call,Throwable t){

t.printStackTrace();

}

});

如果你需要上传多个文件，就声明多个Part参数，或者试试PartMap！

上面提供的上传文件的方式前后构造了三个对象：File-->RquestBody-->MultipartBody.part看起来其实是非常复杂的。

实际上Retrofit允许我们自己定义入参和返回的类型，不过，如果这些类型比较特别，我们还需要准备相应的 Converter，也正是因为 Converter 的存在，Retrofit在入参和返回类型上表现得非常灵活。该如何做呢，请看下面：

[java]view plaincopy

publicinterfaceFileUploadService {

@Multipart@POST("upload")

Call upload(@Part("description") RequestBody description,//注意这里的参数 "aFile" 之前是在创建 MultipartBody.Part 的时候传入的 @Part("aFile")

File file);

}

staticclassFileRequestBodyConverterFactoryextendsConverter.Factory {

@Override

publicConverter requestBodyConverter(Type type, Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {

returnnewFileRequestBodyConverter;

}

}

staticclassFileRequestBodyConverterimplementsConverter {

@Override

publicRequestBody convert(File file)throwsIOException {

returnRequestBody.create(MediaType.parse("application/otcet-stream"), file);

}

}

在创建 Retrofit的时候记得配置上它，这样，我们的文件内容就能上传了：

[java]view plaincopy

addConverterFactory(newFileRequestBodyConverterFactory)

注意：Retrofit在选择合适的 Converter 时，主要依赖于需要转换的对象类型，在添加 Converter 时，注意 Converter 支持的类型的包含关系以及其顺序。

总结上面的技术知识，我们来看完整的请求：

前面我们已经看到 Retrofit为我们构造了一个OkHttpCall，实际上每一个OkHttpCall都对应于一个请求，它主要完成最基础的网络请求，而我们在接口的返回中看到的 Call 默认情况下就是OkHttpCall了，如果我们添加了自定义的callAdapter，那么它就会将OkHttp适配成我们需要的返回值，并返回给我们。

先看下call接口代码：

[java]view plaincopy

publicinterfaceCallextendsCloneable {

//同步发起请求

Response executethrowsIOException;

//异步发起请求，结果通过回调返回

voidenqueue(Callback callback);

booleanisExecuted;

voidcancel;

booleanisCanceled;

Call clone;

//返回原始请求

Request request;

}

接下来执行repos其实就是一个OkHttpCall实例，execute就是要发起网络请求：

[java]view plaincopy

Call> repos = service.listRepos("octocat");

List data = repos.execute;

parseResponse主要完成了由okhttp3.Response向retrofit.Response的转换，同时也处理了对原始返回的解析：

[java]view plaincopy

Response parseResponse(okhttp3.Response rawResponse)throwsIOException {

ResponseBody rawBody = rawResponse.body;//略掉一些代码

try{

//在这里完成了原始 Response 的解析，T 就是我们想要的结果，比如 GitHubService.listRepos 的 List T body = serviceMethod.toResponse(catchingBody);

returnResponse.success(body, rawResponse);

}catch(RuntimeException e) {

// If the underlying source threw an exception, propagate that rather than indicating it was // a runtime exception. catchingBody.throwIfCaught;

throwe;

}

}

处理结果时我想要接入 RxJava，让接口的返回结果改为 Observable：

[java]view plaincopy

publicinterfaceGitHub {

@GET("/repos/{owner}/{repo}/contributors")

Observable> contributors(@Path("owner") String owner,@Path("repo") String repo);

}

只需要提供一个 Adapter，将 OkHttpCall转换为Observable即可。Retrofit提供了相应的 Adapter（RxJavaCallAdapterFactory）我们只需要在构造 Retrofit时，添加它：

[java]view plaincopy

addCallAdapterFactory(RxJavaCallAdapterFactory.create)

我们来看看RxJavaCallAdapterFactory是如何工作的：

我们只需要实现 CallAdapter类来提供具体的适配逻辑，并实现相应的Factory，用来将当前的CallAdapter注册到Retrofit当中，并在Factory.get方法中根据类型来返回当前的CallAdapter即可。知道了这些，我们再来看RxJavaCallAdapterFactory：

[java]view plaincopy

/**

*  只给大家列出来比较重要的代码段

*/

publicfinalclassRxJavaCallAdapterFactoryextendsCallAdapter.Factory{

@Override

publicCallAdapger get(Type returnType,Annotation[] annotations,Retrofit retrofit){

//判断returnType是否为RxJava支持的类型

Class rawType = getRawType(returnType);

String CanonicalName = RawType.getCanonicalName();

booleanisSingle ="rx.Single".equals(CanonicalName);

booleanisCompletable ="rx.Completable".equals(CanonicalName);

if(rawType != Observable.class&& !isSingle && !isCompletable){

returnnull;

}

returnAdapter;//"获取你需要的Adapter 返回"

}

staticfinalclassSimpleCallAdapterimplementsCallAdapter>{

privatefinalType responseType;

privatefinalScheduler scheduler;

SimpleCallAdpter(Type responseType ,Scheduler scheduler){

this.responseType = responseType;

this.scheduler = scheduler;

}

@Override

publicType responseType(){

returnresponseType;

}

@Override

public Observable adapt(Call call){

//在这里创建需要作为返回值的Observable实例，并持有call实例，所以在Observable.subscribe触发时，call.execute将会被调用

Observable observable = Observable.create(newCallOnSubscribe<>(call)).lift(OperatorMapResponseToBodyOrError.instance());

if(scheduler !=null){

returnobservable.subscribeOn(scheduler);

}

returnobservable;

}

}

}