Retrofit初探

前言

Retrofit现在真的是炒鸡火，前不久用了之后，并且与rxjava配合得简直天衣无缝，我便深深的爱上了这个框架。

概述

Retrofit是Square公司开发，针对Android网络请求的框架。通过文档http://square.github.io/retrofit/可以看到它的介绍

A type-safe HTTP client for Android and Java

简单的说它就是一个HTTP请求工具，这里提到了类型安全，而Retrofit就是通过声明泛型来实现类型安全的，也就是说通过声明泛型能够约束最终我们想要的对象是什么。

用法

Retrofit 可以利用接口，方法和注解参数（parameter annotations）来声明式定义一个请求应该如何被创建。这里酷炫的注解参数也是我深深喜爱这个框架的原因之一。比如我们需要请求以下的API

https://api.github.com/repos/{owner}/{repo}/contributors

查看GitHub上"owner"的"repo"中的contributors，首先要创建一个以下的接口：

public interface GitHubService {
    @GET("/repos/{owner}/{repo}/contributors")
    Call> repoContributors(
        @Path("owner") String owner,
        @Path("repo") String repo);
}

然后通过Retrofit生成一个此接口的实现类：

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

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

默认的，Retrofit只能接收OkHttp'sRequestBody并转换成OkHttp'sResponseBody，不过在这里在创建Retrofit对象时，可以根据需要加入Converters，同时还需要在build.gradle中添加依赖。

• 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

这里获取的是json数据，那么修改代码成：

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build();

接着获取接口中Call的实例：

Call> call = service.repoContributors("square", "retrofit");

最后就可以通过执行call获取到数据了：

call.enqueue(new Callback>() {
    @Override
    public void onResponse(Response> response) {
        for (Contributor contributor : response.body()) {
            System.out.println(contributor.login + ":" + contributor.contributions );
        }
    }
    @Override
    public void onFailure(Throwable t) {
    }
});

这里的Contributor就是我们创建的数据bean类，在此例子的api中，我们可以获取到很多数据，但是我们只需要筛选自己需要的数据创建一个bean类传入就可以了。

public class Contributor{
    String login;
    int contributions;
}

支持rxjava

当然，Retrofit还支持rxjava，这时我们需要在创建Retrofit实例的时候再加入一个adapter:

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
    .build();

之前的接口也需要修改，这时候我们需要返回的不再是Call，而是Observable

public interface GitHubService {
    @GET("/repos/{owner}/{repo}/contributors")
    Observable> repoContributors(
        @Path("owner") String owner,
        @Path("repo") String repo);
}

获取到Observable实例之后就是一连串的rxjava的代码，比如子线程生产数据，主线程消费数据，更新UI等等。

service.repoContributors("square", "retrofit")
        .subscribeOn(Schedulers.io())
        .observeOn(AndroidSchedulers.mainThread())
        .subscribe(new Subscriber>() {
            @Override
            public void onStart() {
                showProgressBar();
            }

            @Override
            public void onCompleted() {
                dismissProgressBar();
            }

            @Override
            public void onError(Throwable e) {
                Log.i(">>>", "onError " + e.toString());
            }

            @Override
            public void onNext(List list) {
                for (Contributor contributor : list) {
                        System.out.println(contributor.login + ":" + contributor.contributions );
                }
            }
        });

注解词

前面说到了Retrofit可以通过注解参数的方式来声明定义一个请求，一下就来介绍其中重要的注解词用法。

GET请求

1. @Query

   Get方法请求参数都会以key=value的方式拼接在url后面。

    Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("https://api.douban.com/v2/")
            .addConverterFactory(GsonConverterFactory.create())
            .build();
   
    Call call = retrofit.create(DemoService.class).queryDemo(1);
    String url = call.request().url().toString();
    Log.i(">>>", "onCreate :" + url);
   

打印结果：

https://api.douban.com/list?page=1

2. @QueryMap

   如果拼接在后面的参数过多，可以通过QueryMap方式将所有的参数集成在一个Map集合中传递。

    Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("https://api.douban.com/v2/")
            .addConverterFactory(GsonConverterFactory.create())
            .build();
   
    Map options = new HashMap<>();
    options.put("start", "0");
    options.put("count", "3");
   
    Call call = retrofit.create(DemoService.class).queryMapDemo(options);
    String url = call.request().url().toString();
    Log.i(">>>", "onCreate :" + url);
   

打印结果：

https://api.douban.com/v2/book/search?count=3&start=0

3. @Path

   在url中的参数需要请求方提供的时候，可以利用path。

    Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("https://api.douban.com/v2/")
            .addConverterFactory(GsonConverterFactory.create())
            .build();
   
    Call call = retrofit.create(DemoService.class).pathDemo(1);
    String url = call.request().url().toString();
    Log.i(">>>", "onCreate :" + url);
   

打印结果：

https://api.douban.com/image/1

POST请求

1. @Field

   POST请求需要把参数放置在请求体中，而不是拼接在url后面。

    Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("https://api.douban.com/v2/")
            .addConverterFactory(GsonConverterFactory.create())
            .build();
   
    Call call = retrofit.create(DemoService.class).fieldDemo("zhangsan", "businessman");
   

   • 这里的注解还需要一个@FormUrlEncoded，将会自动将请求参数的类型调整为application/x-www-form-urlencoded。

2. @FieldMap

   如果有更多的请求参数的时候，通过一个一个的参数传递就显得很麻烦而且容易出错，那么这个时候就可以用FieldMap

    Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("https://api.douban.com/v2/")
            .addConverterFactory(GsonConverterFactory.create())
            .build();
   
    Map fields = new HashMap<>();
    fields.put("start", "0");
    fields.put("count", "3");
   
    Call call = retrofit.create(DemoService.class).fieldMapDemo(fields);
   

Demo GitHub:https://github.com/cgzysan/RetrofitDemo

同时我也用Retrofit写了一个Gnak.io：https://github.com/cgzysan/Gank.io

Retrofit未完待续！