Retrofit用法详解

是Square公司开发的一款针对Android网络请求的框架,Retrofit2底层基于OkHttp实现的,现在已经得到Google官方认可,大量的app都采用OkHttp做网络请求,其源码详见[OkHttp Github]。

一、首先先来看一个完整Get请求是如何实现:

1、创建业务请求接口,具体代码如下:

   public interface ApiService {
           @GET("book/search")
            Call<BookSearch> getSearchBooks(@Query("name") String name);
    }

** 这里需要稍作说明,@GET注解就表示get请求,@Query表示请求参数,将会以key=value的方式拼接在url后面

2、需要创建一个Retrofit的示例,并完成相应的配置

    Retrofit retrofit = new Retrofit.Builder()
           .baseUrl(UrisServerDefine.API_BASE_URL)
           .addConverterFactory(GsonConverterFactory.create())
           .build();
    ApiService service = retrofit.create(ApiService.class);

**这里的baseUrl就是网络请求URL相对固定的地址,一般包括请求协议(如Http)、域名或IP地址、端口号等,当然还会有很多其他的配置,下文会详细介绍。还有addConverterFactory方法表示需要用什么转换器来解析返回值,GsonConverterFactory.create()表示调用Gson库来解析json返回值,具体的下文还会做详细介绍。

3、调用请求方法,并得到Call实例

        Call<BookSearch> call = service.getSearchBooks("小王子");

4、使用Call实例完成同步或异步请求

1、同步请求

          BookSearch response = call.execute().body();

**这里需要注意的是网络请求一定要在子线程中完成,不能直接在UI线程执行,不然会crash

2、异步请求

call.enqueue(new Callback<BookSearch>() {
    @Override
    public void onResponse(Call<BookSearch> call,Response<BookSearch> response) {
        asyncText.setText("异步请求结果: " + response.body().books.get(0).altTitle);
    }
    @Override
    public void onFailure(Call<BookSearchResponse> call, Throwable t){
        }
 });

二、如何使用

首先需要在build.gradle文件中引入需要的第三包,配置如下:

    1    compile 'com.squareup.retrofit2:retrofit:2.1.0'
    2    compile 'com.squareup.retrofit2:converter-gson:2.1.0'
    3    compile 'com.squareup.retrofit2:adapter-rxjava:2.1.0'

**引入完第三包接下来就可以使用Retrofit来进行网络请求了。接下来会对不同的请求方式做进一步的说明。
Get 方法

  1. @Query
    Get方法请求参数都会以key=value的方式拼接在url后面,Retrofit提供了两种方式设置请求参数。第一种就是像上文提到的直接在interface中添加@Query注解,还有一种方式是通过Interceptor实现,直接看如何通过Interceptor实现请求参数的添加。
  public class CustomInterceptor implements Interceptor {
        @Override
        public Response intercept(Chain chain) throws IOException {
                    Request request = chain.request();
                    HttpUrl httpUrl = request.url().newBuilder()
                    .addQueryParameter("token", "tokenValue")
                   .build();
         request = request.newBuilder().url(httpUrl).build();
         return chain.proceed(request);
          }
   }

addQueryParameter就是添加请求参数的具体代码,这种方式比较适用于所有的请求都需要添加的参数,一般现在的网络请求都会添加token作为用户标识,那么这种方式就比较适合。
创建完成自定义的Interceptor后,还需要在Retrofit创建client处完成添加。

1 addInterceptor(new CustomInterceptor())

  1. @QueryMap
    如果Query参数比较多,那么可以通过@QueryMap方式将所有的参数集成在一个Map统一传递,还以上文中的get请求方法为例

    public interface ApiService {
           @GET("book/search")
           Call<BookSearchResponse> getSearchBooks(@QueryMap 
           Map<String, String> options);
    }
    

    调用的时候将所有的参数集合在统一的map中即可

      Map<String, String> options = new HashMap<>();
      map.put("name", "小王子");
      Call<BookSearch> call = service.getSearchBooks(options);
    

    调用的时候将所有的参数集合在统一的map中即可

      Map<String, String> options = new HashMap<>();
      map.put("name", "小王子");
      Call<BookSearch> call = service.getSearchBooks(options);
    
  2. Query集合
    假如你需要添加相同Key值,但是value却有多个的情况,一种方式是
    添加多个@Query参数,还有一种简便的方式是将所有的value放置在
    列表中,然后在同一个@Query下完成添加,实例代码如下:

     public interface ApiService {
           @GET("book/search")
           Call<BookSearch> getSearchBooks(@Query("name") 
           List<String> name);
    }
    
  3. Query非必填
    如果请求参数为非必填,也就是说即使不传该参数,服务端也可以正 常解析,那么如何实现呢?其实也很简单,请求方法定义处还是需要完整的Query注解,某次请求如果不需要传该参数的话,只需填充null即可。针对文章开头提到的get的请求,加入按以下方式调用

     Call<BookSearch> call = service.getSearchBooks("小王子");
    
  4. @Path
    如果请求的相对地址也是需要调用方传递,那么可以使用@Path注解,示例代码如下:

      @GET("book/{id}")
      Call<BookResponse> getBook(@Path("id") String id);
    

    业务方想要在地址后面拼接书籍id,那么通过Path注解可以在具体的调用场景中动态传递,具体的调用方式如下:

         Call<BookResponse> call =service.getBook("1003078");
    

    @Path可以用于任何请求方式,包括Post,Put,Delete等等

    Post请求

    1. @field
      Post请求需要把请求参数放置在请求体中,而非拼接在url后面,先来看一个简单的例子

        @FormUrlEncoded
        @POST("book/reviews")
        Call<String> addReviews(@Field("book") String bookId,             
        @Field("title") String title,
        @Field("content") String content, @Field("rating") String rating);
      

    这里有几点需要说明的
    @FormUrlEncoded将会自动将请求参数的类型调整为application/x-www-form-urlencoded,假如content传递的参数为Good Luck,那么最后得到的请求体就是 content=Good+Luck

      FormUrlEncoded不能用于Get请求
    

    @Field注解将每一个请求参数都存放至请求体中,还可以添加encoded参数,该参数为boolean型,具体的用法为

       @Field(value = "book", encoded = true) String book
    

    encoded参数为true的话,key-value-pair将会被编码,即将中文和特殊字符进行编码转换

    1. @FieldMap
      上述Post请求有4个请求参数,假如说有更多的请求参数,那么通过一个一个的参数传递就显得很麻烦而且容易出错,这个时候就可以用FieldMap

        @FormUrlEncoded
        @POST("book/reviews")
        Call<String> addReviews(@FieldMap Map<String, String> fields);
      
    2. @Body
      如果Post请求参数有多个,那么统一封装到类中应该会更好,这样维护起来会非常方便

        @FormUrlEncoded
        @POST("book/reviews")
        Call<String> addReviews(@Body Reviews reviews);
         public class Reviews {
              public String book;
              public String title;
              public String content;
              public String rating;
          }
      

      其他请求方式
      除了Get和Post请求,Http请求还包括Put,Delete等等,用法和Post相似,所以就不再单独介绍了。

      上传

      上传因为需要用到Multipart,所以需要单独拿出来介绍,先看一个具体上传的例子首先还是需要新建一个interface用于定义上传方法

      public interface FileUploadService {  
                 // 上传单个文件
                @Multipart
                @POST("upload")
                Call<ResponseBody> uploadFile(
                @Part("description") RequestBody description,
                @Part MultipartBody.Part file);
      
                // 上传多个文件
                @Multipart
                @POST("upload")
                Call<ResponseBody> uploadMultipleFiles(
                @Part("description") RequestBody description,
                @Part MultipartBody.Part file1,
                @Part MultipartBody.Part file2);
      

      }
      接下来我们还需要在Activity和Fragment中实现两个工具方法,代码如下:

          public static final String MULTIPART_FORM_DATA = "multipart/form-data";
      
          @NonNull
          private RequestBody createPartFromString(String descriptionString) {  
                 return RequestBody.create(
                 MediaType.parse(MULTIPART_FORM_DATA), descriptionString);
           }
           @NonNull
           private MultipartBody.Part prepareFilePart(String partName, Uri fileUri) {  
                 File file = FileUtils.getFile(this, fileUri);
                // 为file建立RequestBody实例
                RequestBody requestFile =   RequestBody.create(MediaType.parse(MULTIPART_FORM_DATA), file);
      
                // MultipartBody.Part借助文件名完成最终的上传
                return MultipartBody.Part.createFormData(partName, file.getName(), requestFile);
            }
      

      好了,接下来就是最终的上传文件代码了

       Uri file1Uri = ... // 从文件选择器或者摄像头中获取 
       Uri file2Uri = ... 
      
       // 创建上传的service实例
        FileUploadService service = ServiceGenerator.createService(FileUploadService.class);
      
       // 创建文件的part (photo, video, ...)
        MultipartBody.Part body1 = prepareFilePart("video", file1Uri);  
        MultipartBody.Part body2 = prepareFilePart("thumbnail", file2Uri);
      
       // 添加其他的part
       RequestBody description = createPartFromString("hello, this is description speaking");
       // 最后执行异步请求操作
       Call<ResponseBody> call = service.uploadMultipleFiles(description, body1, body2);  
       call.enqueue(new Callback<ResponseBody>() {  
       @Override
       public void onResponse(Call<ResponseBody> call,
            Response<ResponseBody> response) {
             Log.v("Upload", "success");
         }
       @Override
       public void onFailure(Call<ResponseBody> call, Throwable t) {
               Log.e("Upload error:", t.getMessage());
          }
       });
      

    三、其他必须知道的事项

    1. 添加自定义的header
      Retrofit提供了两个方式定义Http请求头参数:静态方法和动态方法,静态方法不能随不同的请求进行变化,头部信息在初始化的时候就固定了。而动态方法则必须为每个请求都要单独设置。

      静态方法

       public interface ApiService {
           @Headers("Cache-Control: max-age=640000")
           @GET("book/search")
           Call<BookSearch> getSearchBooks(@Query("name") String     name);
        }
      

      当然你想添加多个header参数也是可以的,写法也很简单

       public interface ApiService {
            @Headers("Accept: application/vnd.yourapi.v1.full+json", "User-Agent: Your-App-Name })
            @GET("book/search")
            Call<BookSearch> getSearchBooks(@Query("name") String name);
        }
      

      此外也可以通过Interceptor来定义静态请求头

      public class RequestInterceptor implements Interceptor {
            @Override
            public Response intercept(Chain chain) throws IOException {
            Request original = chain.request();
            Request request = original.newBuilder()
            .header("User-Agent", "Your-App-Name")
            .header("Accept", "application/vnd.yourapi.v1.full+json")
            .method(original.method(), original.body())
            .build();
           return chain.proceed(request);
           }
      }
      

      添加header参数Request提供了两个方法,一个是header(key, value),另一个是.addHeader(key, value),两者的区别是,header()如果有重名的将会覆盖,而addHeader()允许相同key值的header存在然后在OkHttp创建Client实例时,添加RequestInterceptor即可

      private static OkHttpClient getNewClient(){
            return new OkHttpClient.Builder()
           .addInterceptor(new RequestInterceptor())
           .connectTimeout(DEFAULT_TIMEOUT, TimeUnit.SECONDS)
          .build();
      }
      

      动态方法

       public interface ApiService {
            @GET("book/search")
            Call<BookSearch> getSearchBooks(
            @Header("Content-Range") String contentRange, 
            @Query("name") String name);
      }
      
      1. 网络请求日志
        调试网络请求的时候经常需要关注一下请求参数和返回值,以便判断和定位问题出在哪里,Retrofit官方提供了一个很方便查看日志的Interceptor,你可以控制你需要的打印信息类型,使用方法也很简单。
        首先需要在build.gradle文件中引入logging-interceptor

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

        同上文提到的CustomInterceptor和RequestInterceptor一样,添加到OkHttpClient创建处即可,完整的示例代码如下:

        private static OkHttpClient getNewClient(){
                 HttpLoggingInterceptor logging = new  HttpLoggingInterceptor();
                 logging.setLevel(HttpLoggingInterceptor.Level.BODY);
                 return new OkHttpClient.Builder()
                .addInterceptor(new CustomInterceptor())
                .addInterceptor(logging)
                .connectTimeout(DEFAULT_TIMEOUT, TimeUnit.SECONDS)
                .build();
         }
        

        HttpLoggingInterceptor提供了4中控制打印信息类型的等级,分别是NONE,BASIC,HEADERS,BODY,接下来分别来说一下相应的打印信息类型。
        NONE
        没有任何日志信息
        Basic
        打印请求类型,URL,请求体大小,返回值状态以及返回值的大小

           D/HttpLoggingInterceptor$Logger: --> POST /upload HTTP/1.1 (277-byte body)  
           D/HttpLoggingInterceptor$Logger: <-- HTTP/1.1 200 OK (543ms, -1-byte body)
        

        Headers
        打印返回请求和返回值的头部信息,请求类型,URL以及返回值状态码

          <-- 200 OK https://api.douban.com/v2/book/search?q=%E5%B0%8F%E7%8E%8B%E5%AD%90&start=0&count=3&token=tokenValue (3787ms)
           D/OkHttp: Date: Sat, 06 Aug 2016 14:26:03 GMT
           D/OkHttp: Content-Type: application/json; charset=utf-8
           D/OkHttp: Transfer-Encoding: chunked
           D/OkHttp: Connection: keep-alive
           D/OkHttp: Keep-Alive: timeout=30
           D/OkHttp: Vary: Accept-Encoding
           D/OkHttp: Expires: Sun, 1 Jan 2006 01:00:00 GMT
           D/OkHttp: Pragma: no-cache
           D/OkHttp: Cache-Control: must-revalidate, no-cache, private
           D/OkHttp: Set-Cookie: bid=D6UtQR5N9I4; Expires=Sun, 06-          Aug-17 14:26:03 GMT; Domain=.douban.com; Path=/
           D/OkHttp: X-DOUBAN-NEWBID: D6UtQR5N9I4
           D/OkHttp: X-DAE-Node: dis17
           D/OkHttp: X-DAE-App: book
           D/OkHttp: Server: dae
           D/OkHttp: <-- END HTTP
        

        Body
        打印请求和返回值的头部和body信息

            <-- 200 OK https://api.douban.com/v2/book/search?q=%E5%B0%8F%E7%8E%8B%E5%AD%90&tag=&start=0&count=3&token=tokenValue (3583ms)
             D/OkHttp: Connection: keep-alive
             D/OkHttp: Date: Sat, 06 Aug 2016 14:29:11 GMT
             D/OkHttp: Keep-Alive: timeout=30
             D/OkHttp: Content-Type: application/json; charset=utf-8
             D/OkHttp: Vary: Accept-Encoding
             D/OkHttp: Expires: Sun, 1 Jan 2006 01:00:00 GMT
             D/OkHttp: Transfer-Encoding: chunked
             D/OkHttp: Pragma: no-cache
             D/OkHttp: Connection: keep-alive
             D/OkHttp: Cache-Control: must-revalidate, no-cache, private
             D/OkHttp: Keep-Alive: timeout=30
             D/OkHttp: Set-Cookie: bid=ESnahto1_Os; Expires=Sun, 06-Aug-17 14:29:11 GMT; Domain=.douban.com; Path=/
             D/OkHttp: Vary: Accept-Encoding
             D/OkHttp: X-DOUBAN-NEWBID: ESnahto1_Os
             D/OkHttp: Expires: Sun, 1 Jan 2006 01:00:00 GMT
             D/OkHttp: X-DAE-Node: dis5
             D/OkHttp: Pragma: no-cache
             D/OkHttp: X-DAE-App: book
             D/OkHttp: Cache-Control: must-revalidate, no-cache, private
             D/OkHttp: Server: dae
             D/OkHttp: Set-Cookie: bid=5qefVyUZ3KU; Expires=Sun, 06-Aug-17 14:29:11 GMT; Domain=.douban.com; Path=/
             D/OkHttp: X-DOUBAN-NEWBID: 5qefVyUZ3KU
             D/OkHttp: X-DAE-Node: dis17
             D/OkHttp: X-DAE-App: book
             D/OkHttp: Server: dae
             D/OkHttp: {"count":3,"start":0,"total":778,"books":[{"rating":{"max":10,"numRaters":202900,"average":"9.0","min":0},"subtitle":"","author":["[法] 圣埃克苏佩里"],"pubdate":"2003-8","tags":[{"count":49322,"name":"小王子","title":"小王子"},{"count":41381,"name":"童话","title":"童话"},{"count":19773,"name":"圣埃克苏佩里","title":"圣埃克苏佩里"}
             D/OkHttp: <-- END HTTP (13758-byte body)
        
      2. 为某个请求设置完整的URL
        假如说你的某一个请求不是以base_url开头该怎么办呢?别着急,办法很简单,看下面这个例子你就懂了

         public interface ApiService {  
                @GET
                public Call<ResponseBody> profilePicture(@Url String url);
        }
        
              Retrofit retrofit = Retrofit.Builder()  
              .baseUrl("https://your.api.url/");
              .build();
        
          ApiService service = retrofit.create(ApiService.class);  
          service.profilePicture("https://s3.amazon.com/profile-picture/path")
        

        直接用@Url注解的方式传递完整的url地址即可。

        4. 取消请求
        Call提供了cancel方法可以取消请求,前提是该请求还没有执行

          String fileUrl = "http://futurestud.io/test.mp4";  
          Call<ResponseBody> call = downloadService.downloadFileWithDynamicUrlSync(fileUrl);
          call.enqueue(new Callback<ResponseBody>() {  
          @Override
          public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {
                 Log.d(TAG, "request success");
         }
        
          @Override
         public void onFailure(Call<ResponseBody> call, Throwable t) {
         if (call.isCanceled()) {
               Log.e(TAG, "request was cancelled");
         } else {
            Log.e(TAG, "other larger issue, i.e. no network connection?");
              }
             }
           });
        }
        
              // 触发某个动作,例如用户点击了取消请求的按钮
                call.cancel();  
          }
        
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 206,126评论 6 481
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 88,254评论 2 382
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 152,445评论 0 341
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 55,185评论 1 278
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 64,178评论 5 371
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,970评论 1 284
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,276评论 3 399
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,927评论 0 259
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 43,400评论 1 300
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,883评论 2 323
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,997评论 1 333
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,646评论 4 322
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,213评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,204评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,423评论 1 260
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 45,423评论 2 352
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,722评论 2 345

推荐阅读更多精彩内容

  • Retrofit用法详解 一、简介 Retrofit是Square公司开发的一款针对Android网络请求的框架,...
    流水潺湲阅读 843评论 0 6
  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 134,599评论 18 139
  • Retrofit Retrofit是Square公司开发的一款针对Android网络请求的框架,Retrofit2...
    Reathin阅读 1,752评论 1 11
  • 百人计划过半,就算没有要求,也是时候做一次总结,做一次回顾。 当初报名的时候自己的想法是,做一个改变,这个改变最多...
    醒卯阅读 209评论 0 0
  • 题目2 : Composition 时间限制:10000ms 单点时限:1000ms 内存限制:256MB 描述A...
    认真学计算机阅读 449评论 0 0