Clean Architecture 学习之 Retrofit

前言

Retrofit 是 square 公司开源的一个非常著名的简化网络请求的框架，但是它不是网络框架，OkHttp 才是，Retrofit 相当于是将OkHttp封装了，方便我们使用。square公司还有很多其他非常著名的开源库，比如OkHttp,Otto 以及Dagger(Dagger2 是由google 维护的一个分支，专为移动设备开发的)。Bob大叔在Clean Architecture中使用了它，我们就来学习Retrofit的基本使用，学习完本文以后，你将能应付80%的日常开发工作。
最新版本的Retrofit 已经升级到2.1了，在2.0之前的版本，OkHttp是可选的，但是2.0之后是必须的了。2.0之前，Converter 是内置的，来自服务器的json字符串会自动转换为定义好的DAO(Data Access Object)，2.0之后你必须自己手动引入。

添加依赖库

想要在项目中使用Retrofit非常简单，在build.gradle的依赖中加入下面这行代码：

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

添加converter依赖库

正如前面所说，如果Retrofit 2.X 不再内置converter,如果你想要接收json 并解析成DAO,你必须把Gson Converter作为一个独立的依赖添加进来：

compile 'com.squareup.retrofit:converter-gson:2.1.1'

Square还提供了很多其他常见的converter，比如Jackson、Protobuf 等到，参看详情请移步这个链接

添加自定义converter

如果你想使用自己定义的Converter，你必须继承 Converter.Factory 这个abstract类,覆盖其中的requestBodyConverter 和 responseBodyConverter方法。以FastJson 为例：

FastJsonConverterFactory.java

public class FastJsonConverterFactory extends Converter.Factory{
    private Charset charset;
    private static final Charset UTF_8  = Charset.forName("UTF-8");

    public static FastJsonConverterFactory create() {
        return create(UTF_8);
    }

    public static FastJsonConverterFactory create(Charset charset) {
        return new FastJsonConverterFactory(charset);
    }

    public FastJsonConverterFactory(Charset charset) {
        this.charset = charset;
    }

    @Override
    public Converter requestBodyConverter(Type type, Annotation[] parameterAnnotations,
                                                          Annotation[] methodAnnotations, Retrofit retrofit) {
        return new FastJsonRequestBodyConverter<>(type, charset);
    }

    @Override
    public Converter responseBodyConverter(Type type, Annotation[] annotations, Retrofit retrofit) {
        return new FastJsonResponseBodyConverter<>(type, charset);
    }
}

FastJsonRequestBodyConverter.java

public class FastJsonRequestBodyConverter implements Converter {
    private Type type;
    private Charset charset;
    private static final MediaType MEDIA_TYPE = MediaType.parse("application/json; charset=UTF-8");

    public FastJsonRequestBodyConverter(Type type, Charset charset) {
        this.type = type;
        this.charset = charset;
    }

    @Override
    public RequestBody convert(T value) throws IOException {
        return RequestBody.create(MEDIA_TYPE, JSON.toJSONString(value).getBytes(charset));
    }
}

FastJsonResponseBodyConverter.java

public class FastJsonResponseBodyConverter  implements Converter {

    private Type type;
    private Charset charset;

    public FastJsonResponseBodyConverter() {
    }

    public FastJsonResponseBodyConverter(Type type, Charset charset) {
        this.type = type;
        this.charset = charset;
    }

    @Override
    public T convert(ResponseBody value) throws IOException {
        try {
            return JSON.parseObject(value.string(), type);
        } finally {
            value.close();
        }
    }
}

添加CallAdapter依赖库

Retrofit 2.x允许你自定义CallAdapter来满足您的特殊需求。 官方推出了支持RxJava的CallAdapter，要想在Retrofit的编程中使用响应式编程，你必须加入以下依赖库：

"com.squareup.retrofit2:adapter-rxjava:2.1.0"

添加完以上这些依赖库之后，我们就可以在项目中使用了,先看看怎么创建Retrofit 实例：

Retrofit retrofit = new Retrofit.Builder()
                .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
                .addConverterFactory(FastJsonConverterFactory.create())
                .baseUrl(BASE_URL)
                .build();

使用Retrofit

API 声明

按照Square官方的说明，我们需要按照一定的格式创建一个接口，定义我们将要使用的Client，比如下面这个REST github client:

public interface GitHubClient {  
    @GET("/repos/{owner}/{repo}/contributors")
    List contributors(
        @Path("owner") String owner,
        @Path("repo") String repo
    );
}

所有的client必须用interface的方式来定义。方法必须用@GET @POST等Http 方法注解。需要动态设定的URL，必须在方法的注解中用大括号中包起来，并在方法的参数中设定。下面详细介绍其使用方法

请求方法

每个方法必须包含一个HTTP 注解，注解中提供了请求方法和相关的URL，Retrofit 内置了五个方法：GET，POST，PUT，DELETE，HEAD。对应的URL在注解中指定，如上面的例子所示。你还可以在URL中指定query参数：

@GET("users/list?sort=desc")

参数化控制URL

我们可以通过占位符和方法中的参数来动态地更新请求的URL。占位符是用大括号包起来的，响应的参数必须用@path注解，并且使用跟占位符相同的字符串。如上面的例子所示。请求参数也可以同时添加在方法的参数中。

@GET("group/{id}/users")
Call> groupList(@Path("id") int groupId, @Query("sort") String sort);

对于比较复杂的query参数，我们还可以使用map:

@GET("group/{id}/users")
Call> groupList(@Path("id") int groupId, @QueryMap Map options);

请求体

我们可以使用@Body注解来指定一个对象作为http 请求体。

@POST("users/new")Call 
createUser(@Body User user);

Retrofit 会使用我们在创建Retrofit实例时指定的converter,将这个对象转换。如果没有指定，则只能使用RequestBody。

Form encode 和 MultiPart

我们也可以声明方法为使用form-encode 和 multipart data。
如果我们在方法上使用了@FormUrlEncoded注解，retrofit就会发送form-encode data。每个键值对都必须用@Field注解，包含name，值则通过对象提供。

@FormUrlEncoded
@POST("user/edit")
Call updateUser(@Field("first_name") String first, @Field("last_name") String last);

在方法上加上 @Multipart 注解来使用Multipart请求。Parts 则使用@Part注解来声明。

@Multipart
@PUT("user/photo")
Call updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

Multipart parts使用Retrofit的converter之一，或者可以通过实现 RequestBody 来处理序列化。

Header 控制

你可以通过 @Header 注解来设置静态的headers

@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call> widgetList();

你也可以 @Header 注解来动态更新。相应的参数必须提供给 @Header 注解。如果只为空，这个header就会被忽略。

@GET("user")
Call getUser(@Header("Authorization") String authorization)

URL定义方式

Retrofit 2.0使用了新的URL定义方式。Base URL与@Url 不是简单的组合在一起。

BASE_URL	@URL	RESULT
http://www.github.com/	list	http://www.github.com/list
http://www.github.com/base/level/	list/	http://www.github.com/base/level/list/
http://www.github.com/base/level	/list	http://www.github.com/list

从上面的表格可以看出，如果@URL以/开头的，会覆盖BASE_URL中的部分。所以，以下规则我们最好遵从

• BASE_URL: 总是以 /结尾
• Url: 不要以 / 开头

同步和异步请求

在Retrofit 2.x 中，所有的请求都被封装成一个Call对象。在retrofit 2.X中，同步和异步请求的定义不再有区别。他们只在执行的时候不一样。
同步方法在主线程中执行，而安卓的主线程是UI线程，是不允许在主线程中执行网络请求的。所以，在安卓应用开发中，我们不使用同步请求。不过我们还是来简单了解下同步请求的执行方法。
client 定义如下：

public interface TaskService {  
    @GET("/tasks")
    Call> getTasks();
}

同步请求：

TaskService taskService = ServiceGenerator.createService(TaskService.class);  
Call> call = taskService.getTasks();  
List> tasks = call.execute().body();  

通过执行Call对象的excute()方法就会调用同步请求，反序列化的response body 可通过 body()方法得到。

异步请求：

TaskService taskService = ServiceGenerator.createService(TaskService.class);  
Call> call = taskService.getTasks();  
call.enqueue(new Callback>() {  
    @Override
    public void onResponse(Call> call, Response> response) {
        if (response.isSuccessful()) {
            // tasks available
        } else {
            // error response, no access to resource?
        }
    }

    @Override
    public void onFailure(Call> call, Throwable t) {
        // something went completely south (like no internet connection)
        Log.d("Error", t.getMessage());
    }
}

实现CallBack类，并执行Call对象的enqueue()方法，我们就能执行异步请求。

我们前面也提到过，Retrofit 支持响应式编程。因为我们可以使用RxJava来写出优雅而又逻辑简单的代码：
client定义：

public interface GoodsService {
    @POST("categories.do")
    Observable getGoodsCategories(@Body GoodsCategoriesReq req);
}

请求的返回值，不再是Call对象，而变成了Observable对象了。因为我们在创建Retrofit实例的时候，已经添加了CallAdapter了。

GoodsCategoriesReq req = new GoodsCategoriesReq();
req.setId(id);
Retrofit retrofit = new Retrofit.Builder()
                .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
                .addConverterFactory(FastJsonConverterFactory.create())
                .baseUrl(BASE_URL)
                .build();
retrofit
    .create(GoodsService.class)
    .getGoodsCategories(req)
    .flatMap(categoriesResp->{
        if (categoriesResp.getCode() != 200){
            return Observable.error(new BusinessException(categoriesResp.getCode(),categoriesResp.getMsg()));
        }
        return Observable.just(categoriesResp);
    })
    .map(resp->{
        List categories = new ArrayList<>();

        for(GoodsCategoriesResp.Category item: resp.getCategories()) {
            GoodsCategory category = new GoodsCategory();
            category.setId(item.getId());
            category.setParentId(id);
            category.setName(item.getName());
            category.setImg(item.getImg());
            category.setHasNext(item.getHasNext() == 1);

            categories.add(category);
        }
        return categories;
    })
    .subscribe(new BaseSubscriber>() {
                    @Override
                    public void onCompleted() {

                    }

                    @Override
                    public void onError(Throwable e) {

                    }

                    @Override
                    public void onNext(List categories) {
                    }
        });

在上面的代码中，当Retrofit异步执行完getGoodsCategories(req)之后，我们就得到了一个Observable对象，但这个对象并不能直接提供给上层UI使用，我们我们需要进行一次转换，将其转换成List对象。如果有错误发生，Subscriber的onError方法就会被调用，我们在里面进行出错处理。我们用了一系列的链式操作，就完成了出错处理和数据转换等工作，逻辑简单明了。

上传和下载文件

上传文件

在Retrofit 2.x中，由于舍弃了1.x的TypedFile方式，所以只能借助OkHttp库来执行与网络有关的操作。在2.x中有两种方式可以选择，OkHttp的RequestBody或者MultipartBody.Part,把你的文件封装进request body中。先看看上传文件的接口定义

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

@description只是包含在RequestBody实例中的一个字符串。而第二个参数才是真正的文件。使用@MultipartBody.Part类的原因是它允许我们发送文件的真正的名字，而不是request中的二进制文件的数据。
下面这段代码展示了在Android 客户端中上传文件，每个步骤都包含了注释。这个方法需要一个文件的URI。

private void uploadFile(Uri fileUri) {  
    // create upload service client
    FileUploadService service =
            ServiceGenerator.createService(FileUploadService.class);

    // https://github.com/iPaulPro/aFileChooser/blob/master/aFileChooser/src/com/ipaulpro/afilechooser/utils/FileUtils.java
    // use the FileUtils to get the actual file by uri
    File file = FileUtils.getFile(this, fileUri);

    // create RequestBody instance from file
    RequestBody requestFile =
            RequestBody.create(MediaType.parse("multipart/form-data"), file);

    // MultipartBody.Part is used to send also the actual file name
    MultipartBody.Part body =
            MultipartBody.Part.createFormData("picture", file.getName(), requestFile);

    // add another part within the multipart request
    String descriptionString = "hello, this is description speaking";
    RequestBody description =
            RequestBody.create(
                    MediaType.parse("multipart/form-data"), descriptionString);

    // finally, execute the request
    Call call = service.upload(description, body);
    call.enqueue(new Callback() {
        @Override
        public void onResponse(Call call,
                               Response response) {
            Log.v("Upload", "success");
        }

        @Override
        public void onFailure(Call call, Throwable t) {
            Log.e("Upload error:", t.getMessage());
        }
    });
}

一个需要注意的地方是Content-Type。如果你拦截了OkHttp Client 并且将其修改为 application/json,服务器在反序列化你的文件的时候就会有问题。所以务必要确定Request Header 使用的是multipart/form-data,而不是application/json。

下载文件

下载文件与其他普通的Request并没有区别，唯一需要注意的是返回值类型必须是ResponseBody类型，否则Retrofit就会去尝试解析和转换，无疑这会引起异常。

FileDownloadService downloadService = ServiceGenerator.create(FileDownloadService.class);

Call call = downloadService.downloadFileWithDynamicUrlSync(fileUrl);

call.enqueue(new Callback() {  
    @Override
    public void onResponse(Call call, Response response) {
        if (response.isSuccess()) {
            Log.d(TAG, "server contacted and has file");

            boolean writtenToDisk = writeResponseBodyToDisk(response.body());

            Log.d(TAG, "file download was a success? " + writtenToDisk);
        } else {
            Log.d(TAG, "server contact failed");
        }
    }

    @Override
    public void onFailure(Call call, Throwable t) {
        Log.e(TAG, "error");
    }
});

此外，由于Retrofit默认在下载文件的时候是将其放在内存中的，所以在下载大文件的时候，我们需要：

1. 在Client的方法上加上@Streaming注解。
2. 将网络请求放在另一个后台线程中，否则Android会触发android.os.NetworkOnMainThreadException异常。

使用Interceptor

Interceptor即拦截器，意味着我们可以在进行网络请求的时候对这些请求进行拦截，对Request或者Response进行预先处理，最常见的莫过于模拟网络返回值了。

public class MockInterceptor implements Interceptor {

    private String responeJsonPath;

    @Inject
    public MockInterceptor() {
    }

    @Override
    public Response intercept(Chain chain) throws IOException {
        String responseString = createResponseBody(chain);

        return new Response.Builder()
                .code(200)
                .message(responseString)
                .request(chain.request())
                .protocol(Protocol.HTTP_1_0)
                .body(ResponseBody.create(MediaType.parse("application/json"), responseString.getBytes()))
                .addHeader("content-type", "application/json")
                .build();
    }

    private String createResponseBody(Chain chain) {

        String responseString = null;

        HttpUrl uri = chain.request().url();
        String path = uri.url().getPath();

        if (path.equals("login.do")) {
            responseString = UserJson.getContent();
        } else if (path.contains("logout.do")) {

        } else if (path.contains("register.do")) {

        }else if (path.contains("categories.do")) {
            responseString = CategoryJson.getContent();
        }
        return responseString;
    }

}

这里定义的拦截器是模拟网络请求的返回，所有的网络请求都将返回200，response body 则是文件解析得到的内容。
接下来，我们需要定义OkHttp Client，将我们定义的Interceptor设置进去：

public OkHttpClient provideOkHttpClient(MockInterceptor intercepter){

        return new OkHttpClient.Builder()
                .addInterceptor(intercepter)
                .connectTimeout(30, TimeUnit.SECONDS)
                .build();
}

最后就是把自定义的client设置到Retrofit中去了：

public Retrofit provideRetrofit(OkHttpClient client){
    return new Retrofit.Builder()
            .client(client)
            .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
            .addConverterFactory(FastJsonConverterFactory.create())
            .baseUrl(BASE_URL)
            .build();
}

总结

本文只是对Retrofit的简单介绍，只涵盖了最基本的使用。更多的内容需要在以后的工作中遇到了再去学习了。更多教程请戳这个链接