Retrofit 2.0 官方文档

Retrofit 2.0 官方文档_第1张图片
Retrofit 2.0

前言##

来自移动支付公司square公司的作品,开源世界top5的最小公司,首先我自己是一个忠实广场粉,okhttp、picasso、greendao、okio等等~
据Square CTO Bob Lee的说法,Square已经将超过60个项目提交到开源社区,贡献了25万行左右的代码。

原文:Retrofit 2.0: The biggest update yet on the best HTTP Client Library for Android

因为其简单与出色的性能,Retrofit 是安卓上最流行的HTTP Client库之一。

不过它的缺点是在Retrofit 1.x中没有直接取消正在进行中任务的方法。如果你想做这件事必须手动杀死,而这并不好实现。

Square几年前曾许诺这个功能将在Retrofit 2.0实现,但是几年过去了仍然没有在这个问题上有所更新。

API 声明

接口函数的注解和参数表明如何去处理请求
请求方法

每一个函数都必须有提供请求方式和相对URL的Http注解,Retrofit提供了5种内置的注解:GET、POST、PUT、DELETE和HEAD,在注解中指定的资源的相对URL

@GET("users/list")

也可以在URL中指定查询参数

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

URL处理

请求的URL可以在函数中使用替换块和参数进行动态更新,替换块是{ and }包围的字母数字组成的字符串,相应的参数必须使用相同的字符串被@Path进行注释

@GET("group/{id}/users")
List groupList(@Path("id") int groupId);

也可以添加查询参数

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

复杂的查询参数可以使用Map进行组合

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

请求体

可以通过@Body注解指定一个对象作为Http请求的请求体

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

该对象将会被Retroofit实例指定的转换器转换,如果没有添加转换器,则只有RequestBody可用。(转换器的添加在后面介绍)
FORM ENCODED 和 MULTIPART

函数也可以声明为发送form-encoded和multipart数据。
当函数有@FormUrlEncoded注解的时候,将会发送form-encoded数据,每个键-值对都要被含有名字的@Field注解和提供值的对象所标注

@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的众多转换器之一或者实现RequestBody来处理自己的序列化。
Header处理

可以使用@Headers注解给函数设置静态的header

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

@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("users/{username}")
Call getUser(@Path("username") String username);

需要注意的是:header不能被互相覆盖。所有具有相同名字的header将会被包含到请求中。

可以使用@Header注解动态的更新一个请求的header。必须给@Header提供相应的参数,如果参数的值为空header将会被忽略,否则就调用参数值的toString()方法并使用返回结果

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

使用OkHttp拦截器可以指定需要的header给每一个Http请求

OkHttpClient client = new OkHttpClient();
client.networkInterceptors().add(new Interceptor() {
    @Override
    public com.squareup.okhttp.Response intercept(Chain chain) throws IOException {
        com.squareup.okhttp.Response response = chain.proceed(chain.request());
        // Do anything with response here

        return response;
    }
});
Retrofit retrofit = new Retrofit.Builder()
        .baseUrl(BASE_URL)
        ...
        .client(client)
        .build();

新的Service定义方式,不再有同步和异步之分
关于在Retrofit 1.9中service 接口的定义,如果你想定义一个同步的函数,你应该这样定义:

/* Synchronous in Retrofit 1.9 */
 
public interface APIService {
 
    @POST("/list")
    Repo loadRepo();
 
}

而定义一个异步的则是这样:

/* Asynchronous in Retrofit 1.9 */
 
public interface APIService {
 
    @POST("/list")
    void loadRepo(Callback cb);
 
}

但是在Retrofit 2.0上,只能定义一个模式,因此要简单得多。

import retrofit.Call;
 
/* Retrofit 2.0 */
 
public interface APIService {
 
    @POST("/list")
    Call loadRepo();
 
}

而创建service 的方法也变得和OkHttp的模式一模一样。如果要调用同步请求,只需调用execute;而发起一个异步请求则是调用enqueue。

同步请求

// Synchronous Call in Retrofit 2.0
 
Call call = service.loadRepo();
Repo repo = call.execute();

以上的代码会阻塞线程,因此你不能在安卓的主线程中调用,不然会面临NetworkOnMainThreadException。如果你想调用execute方法,请在后台线程执行。

异步请求

// Synchronous Call in Retrofit 2.0
 
Call call = service.loadRepo();
call.enqueue(new Callback() {
    @Override
    public void onResponse(Response response) {
        // Get result Repo from response.body()
    }
 
    @Override
    public void onFailure(Throwable t) {
 
    }
});

以上代码发起了一个在后台线程的请求并从response 的response.body()方法中获取一个结果对象。注意这里的onResponse和onFailure方法是在主线程中调用的。

我建议你使用enqueue,它最符合 Android OS的习惯。

取消正在进行中的业务
service 的模式变成Call的形式的原因是为了让正在进行的事务可以被取消。要做到这点,你只需调用call.cancel()。

call.cancel();
事务将会在之后立即被取消。好简单嘿嘿!

Converter现在从Retrofit中删除
在Retrofit 1.9中,GsonConverter 包含在了package 中而且自动在RestAdapter创建的时候被初始化。这样来自服务器的son结果会自动解析成定义好了的Data Access Object(DAO)

但是在Retrofit 2.0中,Converter 不再包含在package 中了。你需要自己插入一个Converter 不然的话Retrofit 只能接收字符串结果。同样的,Retrofit 2.0也不再依赖于Gson 。

如果你想接收json 结果并解析成DAO,你必须把Gson Converter 作为一个独立的依赖添加进来。

compile 'com.squareup.retrofit:converter-gson:2.0.0-beta1'

然后使用addConverterFactory把它添加进来。注意RestAdapter的别名仍然为Retrofit。

Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("http://api.nuuneoi.com/base/")
        .addConverterFactory(GsonConverterFactory.create())
        .build();
 
service = retrofit.create(APIService.class);

这里是Square提供的官方Converter modules列表。选择一个最满足你需求的。

Gson: com.squareup.retrofit:converter-gson
Jackson: com.squareup.retrofit:converter-jackson
Moshi: com.squareup.retrofit:converter-moshi
Protobuf: com.squareup.retrofit:converter-protobuf
Wire: com.squareup.retrofit:converter-wire
Simple XML: com.squareup.retrofit:converter-simplexml

你也可以通过实现Converter.Factory接口来创建一个自定义的converter 。

我比较赞同这种新的模式。它让Retrofit对自己要做的事情看起来更清晰。

自定义Gson对象
为了以防你需要调整json里面的一些格式,比如,Date Format。你可以创建一个Gson 对象并把它传递给GsonConverterFactory.create()。

Gson gson = new GsonBuilder()
        .setDateFormat("yyyy-MM-dd'T'HH:mm:ssZ")
        .create();
 
Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("http://api.nuuneoi.com/base/")
        .addConverterFactory(GsonConverterFactory.create(gson))
        .build();
 
service = retrofit.create(APIService.class);

完成。

新的URL定义方式
Retrofit 2.0使用了新的URL定义方式。Base URL与@Url 不是简单的组合在一起而是和""的处理方式一致。用下面的几个例子阐明。

1、ps:貌似第二个才符合习惯。

对于 Retrofit 2.0中新的URL定义方式,这里是我的建议:

  • Base URL: 总是以 /结尾

  • @Url: 不要以 / 开头

比如

public interface APIService {
 
    @POST("user/list")
    Call loadUsers();
 
}
 
public void doSomething() {
    Retrofit retrofit = new Retrofit.Builder()
            .baseUrl("http://api.nuuneoi.com/base/")
            .addConverterFactory(GsonConverterFactory.create())
            .build();
 
    APIService service = retrofit.create(APIService.class);
}

以上代码中的loadUsers会从 http://api.nuuneoi.com/base/user/list获取数据。

而且在Retrofit 2.0中我们还可以在@Url里面定义完整的URL:

public interface APIService {
 
    @POST("http://api.nuuneoi.com/special/user/list")
    Call loadSpecialUsers();
 
}

这种情况下Base URL会被忽略。

可以看到在URL的处理方式上发生了很大变化。它和前面的版本完全不同。如果你想把代码迁移到Retrofit 2.0,别忘了修正URL部分的代码。

现在需要OkHttp的支持
OkHttp 在Retrofit 1.9里是可选的。如果你想让Retrofit 使用OkHttp 作为HTTP 连接接口,你需要手动包含okhttp 依赖。

但是在Retrofit 2.0中,OkHttp 是必须的,并且自动设置为了依赖。下面的代码是从Retrofit 2.0的pom文件中抓取的。你不需要再做任何事情了。


  
    com.squareup.okhttp
    okhttp
  
 
  ...

为了让OkHttp 的Call模式成为可能,在Retrofit 2.0中OkHttp 自动被用作HTTP 接口。

即使response存在问题onResponse依然被调用
在Retrofit 1.9中,如果获取的 response 不能背解析成定义好的对象,则会调用failure。但是在Retrofit 2.0中,不管 response 是否能被解析。onResponse总是会被调用。但是在结果不能被解析的情况下,response.body()会返回null。别忘了处理这种情况。

如果response存在什么问题,比如404什么的,onResponse也会被调用。你可以从response.errorBody().string()中获取错误信息的主体。

Response/Failure 逻辑和Retrofit 1.9差别很大。如果你决定迁移到Retrofit 2.0,注意小心谨慎的处理这些情况。

缺少INTERNET权限会导致SecurityException异常
在Retrofit 1.9中,如果你忘记在AndroidManifest.xml文件中添加INTERNET权限。异步请求会直接进入failure回调方法,得到PERMISSION DENIED 错误消息。没有任何异常被抛出。

但是在Retrofit 2.0中,当你调用call.enqueue或者call.execute,将立即抛出SecurityException,如果你不使用try-catch会导致崩溃。

这类似于在手动调用HttpURLConnection时候的行为。不过这不是什么大问题,因为当INTERNET权限添加到了 AndroidManifest.xml中就没有什么需要考虑的了。

Use an Interceptor from OkHttp
在Retrofit 1.9中,你可以使用RequestInterceptor来拦截一个请求,但是它已经从Retrofit 2.0 移除了,因为HTTP连接层已经转为OkHttp。

结果就是,现在我们必须转而使用OkHttp里面的Interceptor。首先你需要使用Interceptor创建一个OkHttpClient对象,如下:

OkHttpClient client = new OkHttpClient();
client.interceptors().add(new Interceptor() {
    @Override
    public Response intercept(Chain chain) throws IOException {
        Response response = chain.proceed(chain.request());
 
        // Do anything with response here
 
        return response;
    }
});

然后传递创建的client到Retrofit的Builder链中。

Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("http://api.nuuneoi.com/base/")
        .addConverterFactory(GsonConverterFactory.create())
        .client(client)
        .build();

以上为全部内容。

学习关于OkHttp Interceptor的知识,请到OkHttp Interceptors。

RxJava Integration with CallAdapter
除了使用Call模式来定义接口,我们也可以定义自己的type,比如MyCall。。我们把Retrofit 2.0的这个机制称为CallAdapter。

Retrofit团队有已经准备好了的CallAdapter module。其中最著名的module可能是为RxJava准备的CallAdapter,它将作为Observable返回。要使用它,你的项目依赖中必须包含两个modules。

compile 'com.squareup.retrofit:adapter-rxjava:2.0.0-beta1'
compile 'io.reactivex:rxandroid:1.0.1'

Sync Gradle并在Retrofit Builder链表中如下调用addCallAdapterFactory:

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

你的Service接口现在可以作为Observable返回了!

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

你可以完全像RxJava那样使用它,如果你想让subscribe部分的代码在主线程被调用,需要把observeOn(AndroidSchedulers.mainThread())添加到链表中。

Observable observable = service.loadDessertListRx();
 
observable.observeOn(AndroidSchedulers.mainThread())
    .subscribe(new Subscriber() {
        @Override
        public void onCompleted() {
            Toast.makeText(getApplicationContext(),
                    "Completed",
                    Toast.LENGTH_SHORT)
                .show();
        }
 
        @Override
        public void onError(Throwable e) {
            Toast.makeText(getApplicationContext(),
                    e.getMessage(),
                    Toast.LENGTH_SHORT)
                .show();
        }
 
        @Override
        public void onNext(DessertItemCollectionDao dessertItemCollectionDao) {
            Toast.makeText(getApplicationContext(),
                    dessertItemCollectionDao.getData().get(0).getName(),
                    Toast.LENGTH_SHORT)
                .show();
        }
    });

完成!我相信RxJava的粉丝对这个变化相当满意。

总结
还有许多其他变化,你可以在官方的Change Log 中获取更多详情。不过,我相信我已经在本文涵盖了主要的issues。

你可能会好奇现在是否是切换到Retrofit 2.0 的时机?考虑到它仍然是beta阶段,你可能会希望继续停留在1.9除非你跟我一样是一个喜欢尝鲜的人。 Retrofit 2.0用起来很好据我的经验来看还没有发现bug。

注意Retrofit 1.9 的官方文档现在已经从Square的github主页删除。我建议你现在就开始学习Retrofit 2.0,尽快使用最新版本。

你可能感兴趣的:(Retrofit 2.0 官方文档)