Retrofit 2.0

前言##

來(lái)自移動(dòng)支付公司square公司的作品，開源世界top5的最小公司，首先我自己是一個(gè)忠實(shí)廣場(chǎng)粉，okhttp、picasso、greendao、okio等等~
據(jù)Square CTO Bob Lee的說(shuō)法，Square已經(jīng)將超過(guò)60個(gè)項(xiàng)目提交到開源社區(qū)，貢獻(xiàn)了25萬(wàn)行左右的代碼。

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

因?yàn)槠浜?jiǎn)單與出色的性能，Retrofit 是安卓上最流行的HTTP Client庫(kù)之一。

不過(guò)它的缺點(diǎn)是在Retrofit 1.x中沒有直接取消正在進(jìn)行中任務(wù)的方法。如果你想做這件事必須手動(dòng)殺死，而這并不好實(shí)現(xiàn)。

Square幾年前曾許諾這個(gè)功能將在Retrofit 2.0實(shí)現(xiàn)，但是幾年過(guò)去了仍然沒有在這個(gè)問(wèn)題上有所更新。

API 聲明

接口函數(shù)的注解和參數(shù)表明如何去處理請(qǐng)求
請(qǐng)求方法

每一個(gè)函數(shù)都必須有提供請(qǐng)求方式和相對(duì)URL的Http注解，Retrofit提供了5種內(nèi)置的注解：GET、POST、PUT、DELETE和HEAD，在注解中指定的資源的相對(duì)URL

@GET("users/list")

也可以在URL中指定查詢參數(shù)

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

URL處理

請(qǐng)求的URL可以在函數(shù)中使用替換塊和參數(shù)進(jìn)行動(dòng)態(tài)更新，替換塊是{ and }包圍的字母數(shù)字組成的字符串，相應(yīng)的參數(shù)必須使用相同的字符串被@Path進(jìn)行注釋

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

也可以添加查詢參數(shù)

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

復(fù)雜的查詢參數(shù)可以使用Map進(jìn)行組合

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

請(qǐng)求體

可以通過(guò)@Body注解指定一個(gè)對(duì)象作為Http請(qǐng)求的請(qǐng)求體

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

該對(duì)象將會(huì)被Retroofit實(shí)例指定的轉(zhuǎn)換器轉(zhuǎn)換，如果沒有添加轉(zhuǎn)換器，則只有RequestBody可用。（轉(zhuǎn)換器的添加在后面介紹）
FORM ENCODED 和 MULTIPART

函數(shù)也可以聲明為發(fā)送form-encoded和multipart數(shù)據(jù)。
當(dāng)函數(shù)有@FormUrlEncoded注解的時(shí)候，將會(huì)發(fā)送form-encoded數(shù)據(jù)，每個(gè)鍵-值對(duì)都要被含有名字的@Field注解和提供值的對(duì)象所標(biāo)注

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

當(dāng)函數(shù)有@Multipart注解的時(shí)候，將會(huì)發(fā)送multipart數(shù)據(jù)，Parts都使用@Part注解進(jìn)行聲明

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

Multipart parts要使用Retrofit的眾多轉(zhuǎn)換器之一或者實(shí)現(xiàn)RequestBody來(lái)處理自己的序列化。
Header處理

可以使用@Headers注解給函數(shù)設(shè)置靜態(tài)的header

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

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

需要注意的是：header不能被互相覆蓋。所有具有相同名字的header將會(huì)被包含到請(qǐng)求中。

可以使用@Header注解動(dòng)態(tài)的更新一個(gè)請(qǐng)求的header。必須給@Header提供相應(yīng)的參數(shù)，如果參數(shù)的值為空header將會(huì)被忽略，否則就調(diào)用參數(shù)值的toString()方法并使用返回結(jié)果

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

使用OkHttp攔截器可以指定需要的header給每一個(gè)Http請(qǐng)求

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定義方式，不再有同步和異步之分
關(guān)于在Retrofit 1.9中service 接口的定義，如果你想定義一個(gè)同步的函數(shù)，你應(yīng)該這樣定義：

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

而定義一個(gè)異步的則是這樣：

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

但是在Retrofit 2.0上，只能定義一個(gè)模式，因此要簡(jiǎn)單得多。

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

而創(chuàng)建service 的方法也變得和OkHttp的模式一模一樣。如果要調(diào)用同步請(qǐng)求，只需調(diào)用execute；而發(fā)起一個(gè)異步請(qǐng)求則是調(diào)用enqueue。

同步請(qǐng)求

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

以上的代碼會(huì)阻塞線程，因此你不能在安卓的主線程中調(diào)用，不然會(huì)面臨NetworkOnMainThreadException。如果你想調(diào)用execute方法，請(qǐng)?jiān)诤笈_(tái)線程執(zhí)行。

異步請(qǐng)求

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

以上代碼發(fā)起了一個(gè)在后臺(tái)線程的請(qǐng)求并從response 的response.body()方法中獲取一個(gè)結(jié)果對(duì)象。注意這里的onResponse和onFailure方法是在主線程中調(diào)用的。

我建議你使用enqueue，它最符合 Android OS的習(xí)慣。

取消正在進(jìn)行中的業(yè)務(wù)
service 的模式變成Call的形式的原因是為了讓正在進(jìn)行的事務(wù)可以被取消。要做到這點(diǎn)，你只需調(diào)用call.cancel()。

call.cancel();
事務(wù)將會(huì)在之后立即被取消。好簡(jiǎn)單嘿嘿！

Converter現(xiàn)在從Retrofit中刪除
在Retrofit 1.9中，GsonConverter 包含在了package 中而且自動(dòng)在RestAdapter創(chuàng)建的時(shí)候被初始化。這樣來(lái)自服務(wù)器的son結(jié)果會(huì)自動(dòng)解析成定義好了的Data Access Object（DAO）

但是在Retrofit 2.0中，Converter 不再包含在package 中了。你需要自己插入一個(gè)Converter 不然的話Retrofit 只能接收字符串結(jié)果。同樣的，Retrofit 2.0也不再依賴于Gson 。

如果你想接收json 結(jié)果并解析成DAO，你必須把Gson Converter 作為一個(gè)獨(dú)立的依賴添加進(jìn)來(lái)。

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

然后使用addConverterFactory把它添加進(jìn)來(lái)。注意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列表。選擇一個(gè)最滿足你需求的。

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

你也可以通過(guò)實(shí)現(xiàn)Converter.Factory接口來(lái)創(chuàng)建一個(gè)自定義的converter 。

我比較贊同這種新的模式。它讓Retrofit對(duì)自己要做的事情看起來(lái)更清晰。

自定義Gson對(duì)象
為了以防你需要調(diào)整json里面的一些格式，比如，Date Format。你可以創(chuàng)建一個(gè)Gson 對(duì)象并把它傳遞給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 不是簡(jiǎn)單的組合在一起而是和"<a href="...">"的處理方式一致。用下面的幾個(gè)例子闡明。

1、ps：貌似第二個(gè)才符合習(xí)慣。

對(duì)于 Retrofit 2.0中新的URL定義方式，這里是我的建議：

• Base URL: 總是以 /結(jié)尾

• @Url: 不要以 / 開頭

比如

public interface APIService {
 
    @POST("user/list")
    Call<Users> 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會(huì)從 http://api.nuuneoi.com/base/user/list獲取數(shù)據(jù)。

而且在Retrofit 2.0中我們還可以在@Url里面定義完整的URL：

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

這種情況下Base URL會(huì)被忽略。

可以看到在URL的處理方式上發(fā)生了很大變化。它和前面的版本完全不同。如果你想把代碼遷移到Retrofit 2.0，別忘了修正URL部分的代碼。

現(xiàn)在需要OkHttp的支持
OkHttp 在Retrofit 1.9里是可選的。如果你想讓Retrofit 使用OkHttp 作為HTTP 連接接口，你需要手動(dòng)包含okhttp 依賴。

但是在Retrofit 2.0中，OkHttp 是必須的，并且自動(dòng)設(shè)置為了依賴。下面的代碼是從Retrofit 2.0的pom文件中抓取的。你不需要再做任何事情了。

<dependencies>
  <dependency>
    <groupId>com.squareup.okhttp</groupId>
    <artifactId>okhttp</artifactId>
  </dependency>
 
  ...
</dependencies>

為了讓OkHttp 的Call模式成為可能，在Retrofit 2.0中OkHttp 自動(dòng)被用作HTTP 接口。

即使response存在問(wèn)題onResponse依然被調(diào)用
在Retrofit 1.9中，如果獲取的 response 不能背解析成定義好的對(duì)象，則會(huì)調(diào)用failure。但是在Retrofit 2.0中，不管 response 是否能被解析。onResponse總是會(huì)被調(diào)用。但是在結(jié)果不能被解析的情況下，response.body()會(huì)返回null。別忘了處理這種情況。

如果response存在什么問(wèn)題，比如404什么的，onResponse也會(huì)被調(diào)用。你可以從response.errorBody().string()中獲取錯(cuò)誤信息的主體。

Response/Failure 邏輯和Retrofit 1.9差別很大。如果你決定遷移到Retrofit 2.0，注意小心謹(jǐn)慎的處理這些情況。

缺少INTERNET權(quán)限會(huì)導(dǎo)致SecurityException異常
在Retrofit 1.9中，如果你忘記在AndroidManifest.xml文件中添加INTERNET權(quán)限。異步請(qǐng)求會(huì)直接進(jìn)入failure回調(diào)方法，得到PERMISSION DENIED 錯(cuò)誤消息。沒有任何異常被拋出。

但是在Retrofit 2.0中，當(dāng)你調(diào)用call.enqueue或者call.execute，將立即拋出SecurityException，如果你不使用try-catch會(huì)導(dǎo)致崩潰。

這類似于在手動(dòng)調(diào)用HttpURLConnection時(shí)候的行為。不過(guò)這不是什么大問(wèn)題，因?yàn)楫?dāng)INTERNET權(quán)限添加到了 AndroidManifest.xml中就沒有什么需要考慮的了。

Use an Interceptor from OkHttp
在Retrofit 1.9中，你可以使用RequestInterceptor來(lái)攔截一個(gè)請(qǐng)求，但是它已經(jīng)從Retrofit 2.0 移除了，因?yàn)镠TTP連接層已經(jīng)轉(zhuǎn)為OkHttp。

結(jié)果就是，現(xiàn)在我們必須轉(zhuǎn)而使用OkHttp里面的Interceptor。首先你需要使用Interceptor創(chuàng)建一個(gè)OkHttpClient對(duì)象，如下：

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;
    }
});

然后傳遞創(chuàng)建的client到Retrofit的Builder鏈中。

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

以上為全部?jī)?nèi)容。

學(xué)習(xí)關(guān)于OkHttp Interceptor的知識(shí)，請(qǐng)到OkHttp Interceptors。

RxJava Integration with CallAdapter
除了使用Call模式來(lái)定義接口，我們也可以定義自己的type，比如MyCall。。我們把Retrofit 2.0的這個(gè)機(jī)制稱為CallAdapter。

Retrofit團(tuán)隊(duì)有已經(jīng)準(zhǔn)備好了的CallAdapter module。其中最著名的module可能是為RxJava準(zhǔn)備的CallAdapter，它將作為Observable返回。要使用它，你的項(xiàng)目依賴中必須包含兩個(gè)modules。

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

Sync Gradle并在Retrofit Builder鏈表中如下調(diào)用addCallAdapterFactory：

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

你的Service接口現(xiàn)在可以作為Observable返回了！

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

你可以完全像RxJava那樣使用它，如果你想讓subscribe部分的代碼在主線程被調(diào)用，需要把observeOn(AndroidSchedulers.mainThread())添加到鏈表中。

Observable<DessertItemCollectionDao> observable = service.loadDessertListRx();
 
observable.observeOn(AndroidSchedulers.mainThread())
    .subscribe(new Subscriber<DessertItemCollectionDao>() {
        @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的粉絲對(duì)這個(gè)變化相當(dāng)滿意。

總結(jié)
還有許多其他變化，你可以在官方的Change Log 中獲取更多詳情。不過(guò)，我相信我已經(jīng)在本文涵蓋了主要的issues。

你可能會(huì)好奇現(xiàn)在是否是切換到Retrofit 2.0 的時(shí)機(jī)？考慮到它仍然是beta階段，你可能會(huì)希望繼續(xù)停留在1.9除非你跟我一樣是一個(gè)喜歡嘗鮮的人。 Retrofit 2.0用起來(lái)很好據(jù)我的經(jīng)驗(yàn)來(lái)看還沒有發(fā)現(xiàn)bug。

注意Retrofit 1.9 的官方文檔現(xiàn)在已經(jīng)從Square的github主頁(yè)刪除。我建議你現(xiàn)在就開始學(xué)習(xí)Retrofit 2.0，盡快使用最新版本。