<p>本文中的Retrofit均指代Retrofit2.0。</p>    <p>本文涉及到的代码以及测试使用的接口可在 Github 上找到。</p>    <p>测试接口服务器在 server 项目下，直接运行 RESTServer.main() 即可启动测试服务器，所面代码示例均使用该接口</p>    <p>当然你也可以自己借助 json-server 或 最新开源的Parse 搭建一个REST API，不过都需要安装Node.js，有兴趣的可以去试试。</p>    <p>接口列表：</p>    <p style="text-align:center"><img src="https://simg.open-open.com/show/5f6278402ba466848b8722ea0a6052b7.png"></p>    <p>注：以上的接口的{id}和{page}均代表一个纯数字，/blog/{id} 可以用 /blog?id=XXX 代替，page同理。</p>    <p>前面写了 你应该知道的HTTP基础知识 介绍了HTTP的相关知识，不知道那些想了解Retrofit的同鞋是不是去看了 <a href="/misc/goto?guid=4958837204152834453" rel="nofollow,noindex">Retrofit的官方教程</a> ，曾经我在你真的会用Gson吗? Gson使用指南（四） 中说当你了解了注解、反射、泛型、HTTP的内容只需要看一篇Retrofit的代码示例就可以轻松玩转Retrofit，不知道你玩转了没?</p>    <p>当然注解、反射、泛型的内容还没有写，Retrofit的内容却先来了！毕竟看懂Retrofit也只需要会使就行，你准备好了吗？</p>    <h2><strong>1、Retrofit入门</strong></h2>    <p>Retrofit 其实相当简单，简单到源码只有37个文件，其中22个文件是注解还都和HTTP有关，真正暴露给用户的类并不多,所以我看了一遍 官方教程 大多数情景就可以无障碍使用，如果你还没有看过，可以先去看看,虽然是英文，但代码才是最好的教程不是么?当然本篇文章会介绍得详细一点，不能写一篇水文。</p>    <h3><strong>1.1、创建Retrofit实例</strong></h3>    <pre>  <code class="language-java">Retrofit retrofit = new Retrofit.Builder()          .baseUrl("http://localhost:4567/")          .build();</code></pre>    <p>创建Retrofit实例时需要通过Retrofit.Builder,并调用baseUrl方法设置URL。</p>    <p>注： Retrofit2 的baseUlr 必须以 /（斜线） 结束，不然会抛出一个IllegalArgumentException,所以如果你看到别的教程没有以 / 结束，那么多半是直接从Retrofit 1.X 照搬过来的。</p>    <h3><strong>1.2、接口定义</strong></h3>    <p>以获取指定id的Blog为例:</p>    <pre>  <code class="language-java">public interface BlogService {      @GET("blog/{id}")      Call<ResponseBody> getFirstBlog(@Path("id") int id);  }</code></pre>    <p>注意，这里是interface不是class，所以我们是无法直接调用该方法，我们需要用Retrofit创建一个BlogService的代理对象。</p>    <pre>  <code class="language-java">BlogService service = retrofit.create(BlogService.class);</code></pre>    <p>拿到代理对象之后，就可以调用该方法啦。</p>    <h3><strong>1.3、接口调用</strong></h3>    <pre>  <code class="language-java">Call<ResponseBody> call = service.getFirstBlog(2);  // 用法和OkHttp的call如出一辙,  // 不同的是如果是Android系统回调方法执行在主线程  call.enqueue(new Callback<ResponseBody>() {      @Override      public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {          try {              System.out.println(response.body().string());          } catch (IOException e) {              e.printStackTrace();          }      }        @Override      public void onFailure(Call<ResponseBody> call, Throwable t) {          t.printStackTrace();      }  });</code></pre>    <p>打印结果:</p>    <pre>  <code class="language-java">{    "code": 200,    "msg": "OK",    "data": {      "id": 2,      "date": "2016-04-15 03:17:50",      "author": "怪盗kidou",      "title": "Retrofit2 测试2",      "content": "这里是 Retrofit2 Demo 测试服务器2"    },    "count": 0,    "page": 0  }</code></pre>    <p>示例源码见 <a href="/misc/goto?guid=4959720024315310040" rel="nofollow,noindex">Example01.java</a></p>    <h2><strong>2、Retrofit注解详解</strong></h2>    <p>上面提到Retrofit 共22个注解，这节就专门介绍这22个注解，为帮助大家更好理解我将这22个注解分为三类，并用表格的形式展现出来,表格上说得并不完整，具体的见源码上的例子注释。</p>    <h3><strong>第一类：HTTP请求方法</strong></h3>    <p style="text-align:center"><img src="https://simg.open-open.com/show/4479b19258a9f74157d0f70f26123104.png"></p>    <p>以上表格中的除HTTP以外都对应了HTTP标准中的请求方法，而HTTP注解则可以代替以上方法中的任意一个注解,有3个属性：method、path,hasBody,下面是用HTTP注解实现上面 Example01.java 的例子。</p>    <pre>  <code class="language-java">public interface BlogService {      /**       * method 表示请的方法，不区分大小写       * path表示路径       * hasBody表示是否有请求体       */      @HTTP(method = "get", path = "blog/{id}", hasBody = false)      Call<ResponseBody> getFirstBlog(@Path("id") int id);  }</code></pre>    <h3><strong>第二类：标记类</strong></h3>    <p style="text-align:center"><img src="https://simg.open-open.com/show/ed0b78864ef6d5b7a22303c4586e512b.png"></p>    <h3><strong>第三类：参数类</strong></h3>    <p style="text-align:center"><img src="https://simg.open-open.com/show/5b3bd932d7933fefa6053c075a261e55.png"></p>    <p>注1：{占位符}和PATH尽量只用在URL的path部分，url中的参数使用Query和QueryMap 代替，保证接口定义的简洁</p>    <p>注2：Query、Field和Part这三者都支持数组和实现了Iterable接口的类型，如List，Set等，方便向后台传递数组。</p>    <pre>  <code class="language-java">Call<ResponseBody> foo(@Query("ids[]") List<Integer> ids);  //结果：ids[]=0&ids[]=1&ids[]=2</code></pre>    <p>Path 示例源码见 Example01.java</p>    <p>Field、FieldMap、Part和PartMap 示例源码见 Example03.java</p>    <p>Header和Headers </p>    <p>Query、QueryMap、Url </p>    <h2><strong>3、Gson与Converter</strong></h2>    <p>在默认情况下Retrofit只支持将HTTP的响应体转换换为ResponseBody,</p>    <p>这也是什么我在前面的例子接口的返回值都是 Call</p>    <p>，</p>    <p>但如果响应体只是支持转换为ResponseBody的话何必要引用泛型呢，</p>    <p>返回值直接用一个Call就行了嘛，既然支持泛型，那说明泛型参数可以是其它类型的，</p>    <p>而Converter就是Retrofit为我们提供用于将ResponseBody转换为我们想要的类型，</p>    <p>有了Converter之后我们就可以写把我们的第一个例子的接口写成这个样子了：</p>    <p> </p>    <pre>  <code class="language-java">public interface BlogService {    @GET("blog/{id}") //这里的{id} 表示是一个变量    Call<Result<Blog>> getFirstBlog(/** 这里的id表示的是上面的{id} */@Path("id") int id);  }</code></pre>    <p>当然只改变泛型的类型是不行的，我们在创建Retrofit时需要明确告知用于将ResponseBody转换我们泛型中的类型时需要使用的Converter</p>    <p>引入Gson支持:</p>    <pre>  <code class="language-java">compile 'com.squareup.retrofit2:converter-gson:2.0.2'</code></pre>    <p>通过GsonConverterFactory为Retrofit添加Gson支持：</p>    <pre>  <code class="language-java">Gson gson = new GsonBuilder()        //配置你的Gson        .setDateFormat("yyyy-MM-dd hh:mm:ss")        .create();    Retrofit retrofit = new Retrofit.Builder()        .baseUrl("http://localhost:4567/")        //可以接收自定义的Gson，当然也可以不传        .addConverterFactory(GsonConverterFactory.create(gson))        .build();</code></pre>    <p>这样Retrofit就会使用Gson将ResponseBody转换我们想要的类型。</p>    <p>这是时候我们终于可以演示如使创建一个Blog了！</p>    <pre>  <code class="language-java">@POST("blog")  Call<Result<Blog>> createBlog(@Body Blog blog);</code></pre>    <p>被@Body注解的的Blog将会被Gson转换成RequestBody发送到服务器。</p>    <pre>  <code class="language-java">BlogService service = retrofit.create(BlogService.class);  Blog blog = new Blog();  blog.content = "新建的Blog";  blog.title = "测试";  blog.author = "怪盗kidou";  Call<Result<Blog>> call = service.createBlog(blog);</code></pre>    <p>结果：</p>    <pre>  <code class="language-java">Result{    code=200,    msg='OK',    data=Blog{      id=20,      date='2016-04-21 05:29:58',      author='怪盗kidou',      title='测试',      content='新建的Blog'    },    count=0,    page=0  }</code></pre>    <h2><strong>4、RxJava与CallAdapter</strong></h2>    <p>说到Retrofit就不得说到另一个火到不行的库RxJava，网上已经不少文章讲如何与Retrofit结合，但这里还是会有一个RxJava的例子，不过这里主要目的是介绍使用CallAdapter所带来的效果。</p>    <p>第3节介绍的Converter是对于Call 中T的转换，而CallAdapter则可以对Call转换，这样的话Call 中的Call也是可以被替换的，而返回值的类型就决定你后续的处理程序逻辑，同样Retrofit提供了多个CallAdapter，这里以RxJava的为例，用Observable代替Call：</p>    <p>引入RxJava支持:</p>    <pre>  <code class="language-java">compile 'com.squareup.retrofit2:adapter-rxjava:2.0.2'</code></pre>    <p>通过RxJavaCallAdapterFactory为Retrofit添加RxJava支持：</p>    <pre>  <code class="language-java">Retrofit retrofit = new Retrofit.Builder()        .baseUrl("http://localhost:4567/")        .addConverterFactory(GsonConverterFactory.create())        .addCallAdapterFactory(RxJavaCallAdapterFactory.create())        .build();</code></pre>    <p>接口设计：</p>    <pre>  <code class="language-java">public interface BlogService {    @POST("/blog")    Observable<Result<List<Blog>>> getBlogs();  }</code></pre>    <p>使用：</p>    <pre>  <code class="language-java">BlogService service = retrofit.create(BlogService.class);  service.getBlogs(1)    .subscribeOn(Schedulers.io())    .subscribe(new Subscriber<Result<List<Blog>>>() {        @Override        public void onCompleted() {          System.out.println("onCompleted");        }          @Override        public void onError(Throwable e) {          System.err.println("onError");        }          @Override        public void onNext(Result<List<Blog>> blogsResult) {          System.out.println(blogsResult);        }    });</code></pre>    <p>结果：</p>    <pre>  <code class="language-java">Result{    code=200,    msg='OK',    data=[      Blog{        id=1,        date='2016-04-15 03:17:50',        author='怪盗kidou',        title='Retrofit2 测试1',        content='这里是 Retrofit2 Demo 测试服务器1'      },      .....    ],    count=20,    page=1  }</code></pre>    <p>「补充」：像上面的这种情况最后我们无法获取到返回的Header和响应码的，如果我们需要这两者，提供两种方案：</p>    <ol>     <li>用Observable >``Observable ,这里的Response指retrofit2.Response</li>     <li>用Observable > 代替Observable ，这里的Result是指retrofit2.adapter.rxjava.Result,这个Result中包含了Response的实例</li>    </ol>    <h2><strong>5、自定义Converter</strong></h2>    <p>本节的内容是教大家实现在一简易的Converter，这里以返回格式为Call 为例。</p>    <p>在此之前先了解一下Converter接口及其作用：</p>    <pre>  <code class="language-java">public interface Converter<F, T> {    // 实现从 F(rom) 到 T(o)的转换    T convert(F value) throws IOException;      // 用于向Retrofit提供相应Converter的工厂    abstract class Factory {      // 这里创建从ResponseBody其它类型的Converter，如果不能处理返回null      // 主要用于对响应体的处理      public Converter<ResponseBody, ?> responseBodyConverter(Type type, Annotation[] annotations,      Retrofit retrofit) {        return null;      }        // 在这里创建 从自定类型到ResponseBody 的Converter,不能处理就返回null，      // 主要用于对Part、PartMap、Body注解的处理      public Converter<?, RequestBody> requestBodyConverter(Type type,      Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {        return null;      }        // 这里用于对Field、FieldMap、Header、Path、Query、QueryMap注解的处理      // Retrfofit对于上面的几个注解默认使用的是调用toString方法      public Converter<?, String> stringConverter(Type type, Annotation[] annotations,      Retrofit retrofit) {        return null;      }      }  }</code></pre>    <p>我们要想从Call 转换为 Call 那么对应的F和T则分别对应ResponseBody和String，我们定义一个StringConverter并实现Converter接口。</p>    <pre>  <code class="language-java">public static class StringConverter implements Converter<ResponseBody, String> {      public static final StringConverter INSTANCE = new StringConverter();      @Override    public String convert(ResponseBody value) throws IOException {      return value.string();    }  }</code></pre>    <p>我们需要一个Fractory来向Retrofit注册StringConverter</p>    <pre>  <code class="language-java">public static class StringConverterFactory extends Converter.Factory {      public static final StringConverterFactory INSTANCE = new StringConverterFactory();      public static StringConverterFactory create() {      return INSTANCE;    }      // 我们只关实现从ResponseBody 到 String 的转换，所以其它方法可不覆盖    @Override    public Converter<ResponseBody, ?> responseBodyConverter(Type type, Annotation[] annotations, Retrofit retrofit) {      if (type == String.class) {        return StringConverter.INSTANCE;      }      //其它类型我们不处理，返回null就行      return null;    }  }</code></pre>    <p>使用Retrofit.Builder.addConverterFactory向Retrofit注册我们StringConverterFactory：</p>    <pre>  <code class="language-java">Retrofit retrofit = new Retrofit.Builder()        .baseUrl("http://localhost:4567/")        // 如是有Gson这类的Converter 一定要放在其它前面        .addConverterFactory(StringConverterFactory.create())        .addConverterFactory(GsonConverterFactory.create())        .build();</code></pre>    <p>注：addConverterFactory是有先后顺序的，如果有多个ConverterFactory都支持同一种类型，那么就是只有第一个才会被使用，而GsonConverterFactory是不判断是否支持的，所以这里交换了顺序还会有一个异常抛出，原因是类型不匹配。</p>    <p>只要返回值类型的泛型参数就会由我们的StringConverter处理,不管是Call 还是Observable</p>    <p>有没有很简单?如果你有其它的需求处理的就自己实现吧。</p>    <p>示例源码见 <a href="/misc/goto?guid=4959720024406492187" rel="nofollow,noindex">Example09.java</a></p>    <h2><strong>6、自定义CallAdapter</strong></h2>    <p>本节将介绍如何自定一个CallAdapter，并验证是否所有的String都会使用我们第5节中自定义的Converter。</p>    <p>先看一下CallAdapter接口定义及各方法的作用：</p>    <pre>  <code class="language-java">public interface CallAdapter<T> {      // 直正数据的类型 如Call<T> 中的 T    // 这个 T 会作为Converter.Factory.responseBodyConverter 的第一个参数    // 可以参照上面的自定义Converter    Type responseType();      <R> T adapt(Call<R> call);      // 用于向Retrofit提供CallAdapter的工厂类    abstract class Factory {      // 在这个方法中判断是否是我们支持的类型，returnType 即Call<Requestbody>和`Observable<Requestbody>`      // RxJavaCallAdapterFactory 就是判断returnType是不是Observable<?> 类型      // 不支持时返回null      public abstract CallAdapter<?> get(Type returnType, Annotation[] annotations,      Retrofit retrofit);        // 用于获取泛型的参数 如 Call<Requestbody> 中 Requestbody      protected static Type getParameterUpperBound(int index, ParameterizedType type) {        return Utils.getParameterUpperBound(index, type);      }        // 用于获取泛型的原始类型 如 Call<Requestbody> 中的 Call      // 上面的get方法需要使用该方法。      protected static Class<?> getRawType(Type type) {        return Utils.getRawType(type);      }    }  }</code></pre>    <p>了解了CallAdapter的结构和其作用之后，我们就可以开始自定义我们的CallAdapter了，本节以CustomCall 为例。</p>    <p>在此我们需要定义一个CustomCall，不过这里的CustomCall作为演示只是对Call的一个包装，并没有实际的用途。</p>    <pre>  <code class="language-java">public static class CustomCall<R> {      public final Call<R> call;      public CustomCall(Call<R> call) {      this.call = call;    }      public R get() throws IOException {      return call.execute().body();    }  }</code></pre>    <p>有了CustomCall，我们还需要一个CustomCallAdapter来实现 Call 到 CustomCall 的转换，这里需要注意的是最后的泛型，是我们要返回的类型。</p>    <pre>  <code class="language-java">public static class CustomCallAdapter implements CallAdapter<CustomCall<?>> {      private final Type responseType;      // 下面的 responseType 方法需要数据的类型    CustomCallAdapter(Type responseType) {      this.responseType = responseType;    }      @Override    public Type responseType() {      return responseType;    }      @Override    public <R> CustomCall<R> adapt(Call<R> call) {      // 由 CustomCall 决定如何使用      return new CustomCall<>(call);    }  }</code></pre>    <p>提供一个CustomCallAdapterFactory用于向Retrofit提供CustomCallAdapter：</p>    <pre>  <code class="language-java">public static class CustomCallAdapterFactory extends CallAdapter.Factory {    public static final CustomCallAdapterFactory INSTANCE = new CustomCallAdapterFactory();      @Override    public CallAdapter<?> get(Type returnType, Annotation[] annotations, Retrofit retrofit) {      // 获取原始类型      Class<?> rawType = getRawType(returnType);      // 返回值必须是CustomCall并且带有泛型      if (rawType == CustomCall.class && returnType instanceof ParameterizedType) {        Type callReturnType = getParameterUpperBound(0, (ParameterizedType) returnType);        return new CustomCallAdapter(callReturnType);      }      return null;    }  }</code></pre>    <p>使用addCallAdapterFactory向Retrofit注册CustomCallAdapterFactory</p>    <pre>  <code class="language-java">Retrofit retrofit = new Retrofit.Builder()        .baseUrl("http://localhost:4567/")        .addConverterFactory(Example09.StringConverterFactory.create())        .addConverterFactory(GsonConverterFactory.create())        .addCallAdapterFactory(CustomCallAdapterFactory.INSTANCE)        .build();</code></pre>    <p>注： addCallAdapterFactory与addConverterFactory同理，也有先后顺序。</p>    <p>示例源码见 <a href="/misc/goto?guid=4959720024493044595" rel="nofollow,noindex">Example10.java</a></p>    <h2><strong>7、其它说明</strong></h2>    <h3><strong>7.1 Retrofit.Builder</strong></h3>    <p>前面用到了 Retrofit.Builder 中的baseUrl、addCallAdapterFactory、addConverterFactory、build方法，还有callbackExecutor、callFactory、client、validateEagerly这四个方法没有用到，这里简单的介绍一下。</p>    <p style="text-align:center"><img src="https://simg.open-open.com/show/d75150e4f80f68477e80dfd4ce339cd7.png"></p>    <h3><strong>7.2 Retrofit的Url组合规则</strong></h3>    <p style="text-align:center"><img src="https://simg.open-open.com/show/6c77b25cfc06406fa5593619490acd17.png"></p>    <p>从上面不能难看出以下规则：</p>    <ul>     <li> <p>如果你在注解中提供的url是完整的url，则url将作为请求的url。</p> </li>     <li> <p>如果你在注解中提供的url是不完整的url，且不以 / 开头，则请求的url为baseUrl+注解中提供的值</p> </li>     <li> <p>如果你在注解中提供的url是不完整的url，且以 / 开头，则请求的url为baseUrl的主机部分+注解中提供的值</p> </li>    </ul>    <h3><strong>7.3 Retrofit提供的Converter</strong></h3>    <p style="text-align:center"><img src="https://simg.open-open.com/show/959b1fd0ea5eaca7d8ec42d8661799e9.png"></p>    <h3><strong>7.4 Retrofit提供的CallAdapter：</strong></h3>    <p style="text-align:center"><img src="https://simg.open-open.com/show/74dd3d8bf327f876b2d06e5700c9a76b.png"></p>    <h3> </h3>    <p> </p>    <p>来自：http://ocnyang.com/2016/10/10/Retrofit2/</p>    <p> </p>