浅谈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 中添加依赖：

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

加入我们想要访问 GitHub 的 api 对，那么我们就定义一个接口：
接口当中的listRepos方法，就是我们想要访问的api了，在发起请求时，{user}会被替换为方法的第一个参数user。
Retrofit支持的协议包括GET/POST/PUT/DELETE/HEAD/PATCH，当然你也可以直接用HTTP来自定义请求。这些协议均以注解的形式进行配置例如下面GET：

public interface GitHubService { @GET("users/{user}/repos") Call<List<Repo>> 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:

Retrofit retrofit = new Retrofit.Builder.baseUrl("https://api.github.com/").build;GitHubService service = retrofit.create(GitHubService.class);//service发起请求Call<List<Repo>> repos = service.listRepos("octocat");

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

Lisg<Repo> data = repos.execute();//同步调用repos.enqueue(new Callback<List<repo>>(){@Overridepublic void onResponse(Call<List<rpo>> call, Response<List<Repo>> response){List<Repo> data = response.body();}@Overridepublic void onFailure(Call<List<Repo>> call,Throwable t){t.printStackTrace();}});

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

认识Query & QueryMap

@GET("/list") Call<ResponseBody> list(@Query("page") int page);

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

interface PrintlnServer{@GET("/") Call<String> cate(@Query("cate") String cate); }

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

认识Field & FieldMap

@FormUrlEncoded @POST("/") Call<ResponseBody> example( @Field("name") String name, @Field("occupation") String occupation);

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

认识Part & PartMap

public interface FileUploadService { @Multipart @POST("upload") Call<ResponseBody> upload(@Part("description") RequestBody description, @Part MultipartBody.Part file); }

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

//先创建ServiceFileUploadService service = retrofit.create(FileUploadService.class);//构建要上传的文件File file = new File(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<ResponseBody> call = service.upload(description,body);call.enqueue(new Callback<ResponseBody>(){@Overridepublic void onResponse(Call<ResponseBody call,Response<ResponseBody> response){Log.d("success","success");}@Overridepublic void onFailure(Call<ResponseBody> call,Throwable t){t.printStackTrace();}});

如果你需要上传多个文件，就声明多个Part参数，或者试试PartMap！
上面提供的上传文件的方式前后构造了三个对象：File-->RquestBody-->MultipartBody.part看起来其实是非常复杂的。
实际上Retrofit允许我们自己定义入参和返回的类型，不过，如果这些类型比较特别，我们还需要准备相应的 Converter，也正是因为 Converter 的存在，Retrofit在入参和返回类型上表现得非常灵活。该如何做呢，请看下面：

public interface FileUploadService { @Multipart @POST("upload") Call<ResponseBody> upload(@Part("description") RequestBody description, //注意这里的参数 "aFile" 之前是在创建 MultipartBody.Part 的时候传入的 @Part("aFile")File file); }static class FileRequestBodyConverterFactory extends Converter.Factory { @Overridepublic Converter<File, RequestBody> requestBodyConverter(Type type, Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) { return new FileRequestBodyConverter; } } static class FileRequestBodyConverter implements Converter<File, RequestBody> { @Override public RequestBody convert(File file) throws IOException { return RequestBody.create(MediaType.parse("application/otcet-stream"), file); } }

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

addConverterFactory(new FileRequestBodyConverterFactory)

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

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

public interface Call<T> extends Cloneable { //同步发起请求 Response<T> execute throws IOException; //异步发起请求，结果通过回调返回 void enqueue(Callback<T> callback); boolean isExecuted; void cancel; boolean isCanceled; Call<T> clone; //返回原始请求 Request request;}

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

Call<List<Repo>> repos = service.listRepos("octocat");List<Repo> data = repos.execute;

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

Response<T> parseResponse(okhttp3.Response rawResponse) throws IOException { ResponseBody rawBody = rawResponse.body; //略掉一些代码 try { //在这里完成了原始 Response 的解析，T 就是我们想要的结果，比如 GitHubService.listRepos 的 List<Repo> T body = serviceMethod.toResponse(catchingBody); return Response.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; throw e; } }

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

public interface GitHub { @GET("/repos/{owner}/{repo}/contributors") Observable<List<Contributor>> contributors( @Path("owner") String owner, @Path("repo") String repo); }

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

addCallAdapterFactory(RxJavaCallAdapterFactory.create)

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

/***  只给大家列出来比较重要的代码段*/public final class RxJavaCallAdapterFactory extends CallAdapter.Factory{@Overridepublic CallAdapger<?> get(Type returnType,Annotation[] annotations,Retrofit retrofit){//判断returnType是否为RxJava支持的类型Class<?> rawType = getRawType(returnType);String CanonicalName = RawType.getCanonicalName();boolean isSingle = "rx.Single".equals(CanonicalName);boolean isCompletable = "rx.Completable".equals(CanonicalName);if(rawType != Observable.class && !isSingle && !isCompletable){return null;}return Adapter;//"获取你需要的Adapter 返回"}static final class SimpleCallAdapter implements CallAdapter<Ovservable<?>>{private final Type responseType;private final Scheduler scheduler;SimpleCallAdpter(Type responseType ,Scheduler scheduler){this.responseType = responseType;this.scheduler = scheduler;}@Overridepublic Type responseType(){return responseType;}@Overridepublic <R> Observable<R> adapt(Call<R> call){//在这里创建需要作为返回值的Observable实例，并持有call实例，所以在Observable.subscribe触发时，call.execute将会被调用Observable<R> observable = Observable.create(new CallOnSubscribe<>(call)).lift(OperatorMapResponseToBodyOrError.<R>instance());if(scheduler != null){return observable.subscribeOn(scheduler);}return observable;}}}

总结：Retrofit是非常强大的，博客中通过一些示例向大家展示了Retrofit自身强大的功能以及扩展性，就算它本身功能不能满足你的需求，你也可以很容易的进行改造。这就是好的代码设计，能够让其拓展性强大到只有你想不到，没有它做不到的境界！