有道翻譯的Retrofit官方文檔（需要翻墻才能看~）
一：定義：
用于Android和Java的類(lèi)型安全HTTP客戶(hù)機(jī)
二：介紹
1.改進(jìn)將您的HTTP API轉(zhuǎn)換為Java接口。
public interface GitHubService{
? ? @GET("users/{user}/repos")
? ?Call<List<Pro> listRepos(@Path("user") String user);
}
2.Retrofit類(lèi)生成一個(gè)GitHubService接口的實(shí)現(xiàn)。
Retrofit retrofit=new Retrofit.Builder()
? ? ?.baseUrl("https://api.github.com/")
? ? ?.build();
GitHubService service=retrofit.create(GitHubService.class);
3.來(lái)自創(chuàng)建的GitHubService的每個(gè)調(diào)用都可以向遠(yuǎn)程web服務(wù)器發(fā)出同步或異步的HTTP請(qǐng)求。
Call<List<Pero>> repos=service.listRepos("octocat");
4.使用注釋來(lái)描述HTTP請(qǐng)求:
URL參數(shù)替換和查詢(xún)參數(shù)支持
對(duì)象轉(zhuǎn)換為請(qǐng)求主體(例如、JSON、協(xié)議緩沖區(qū))
多部件請(qǐng)求體和文件上傳
三：API聲明：
接口方法及其參數(shù)上的注釋指示如何處理請(qǐng)求。
1.請(qǐng)求方法:
每個(gè)方法都必須有一個(gè)提供請(qǐng)求方法和相對(duì)URL的HTTP注釋。有5個(gè)內(nèi)置注釋:GET、POST、PUT、DELETE和HEAD。該資源的相對(duì)URL是在注釋中指定的。
@GET("users/list")
您還可以在URL中指定查詢(xún)參數(shù)。
@GET("users/list?sort=desc")
2.URL操作:
可以使用該方法的替換塊和參數(shù)動(dòng)態(tài)地更新請(qǐng)求URL。替換塊是由字母和數(shù)字包圍的字母數(shù)字字符串。一個(gè)相應(yīng)的參數(shù)必須使用相同的字符串對(duì)@path進(jìn)行注釋。
@GET("group/{id}/users")
Call<List<User> ? groupList(@Path("id") int groupId);
還可以添加查詢(xún)參數(shù)。
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);
對(duì)于復(fù)雜的查詢(xún)參數(shù)組合，可以使用映射。
@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String,String> options);
3.請(qǐng)求體
可以指定一個(gè)對(duì)象作為一個(gè)帶有@body注釋的HTTP請(qǐng)求體。
@POST("users/new")
Call<User>?createUser(@Body User user);
該對(duì)象還將使用Retrofit實(shí)例中指定的轉(zhuǎn)換器進(jìn)行轉(zhuǎn)換。如果不添加任何轉(zhuǎn)換器，則只能使用RequestBody。
4.表單編碼和多部分
方法也可以被聲明為發(fā)送表單編碼和多部分?jǐn)?shù)據(jù)。
表單編碼的數(shù)據(jù)是在該方法上出現(xiàn)@formurlen編碼時(shí)發(fā)送的。每個(gè)鍵值對(duì)都帶有@field的注釋?zhuān)渲邪Q(chēng)和提供該值的對(duì)象。
@FormUrlEncoded
@POST("user/edit")
Call<User>?updateUser(@Field("first_name")String first,@Field("last_name")String last);
當(dāng)@multi部件出現(xiàn)在該方法時(shí)，將使用多部件請(qǐng)求。部分是使用@part注釋聲明的。
@Multipart
@PUT("user/photo")
Call<User>?updateUser(@Part("photo") RequestBody photo,@Part("description") RequestBody description);
多部件部件使用一個(gè)Retrofit轉(zhuǎn)換器，或者他們可以實(shí)現(xiàn)請(qǐng)求體來(lái)處理他們自己的序列化。
5.頭操作
您可以使用@header注釋為方法設(shè)置靜態(tài)標(biāo)題。
@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);
注意，頭文件不會(huì)互相覆蓋。所有包含相同名字的標(biāo)題都將包含在請(qǐng)求中。
可以使用@Header注釋動(dòng)態(tài)地更新請(qǐng)求頭。必須將相應(yīng)的參數(shù)提供給@header。如果值為null，則將省略頭。否則，toString將調(diào)用該值，并使用該結(jié)果。
@GET("user")
Call<User>?getUser(@Header("Authorization")String authorization)
需要添加到每個(gè)請(qǐng)求的頭信息都可以使用OkHttp攔截器來(lái)指定。
6.同步或異步
調(diào)用實(shí)例可以同步或異步執(zhí)行。每個(gè)實(shí)例只能使用一次，但是調(diào)用克隆()將創(chuàng)建一個(gè)可以使用的新實(shí)例。
在Android上，回調(diào)將在主線(xiàn)程上執(zhí)行。在JVM上，回調(diào)將發(fā)生在執(zhí)行HTTP請(qǐng)求的同一線(xiàn)程上。
四：要改裝配置
Retrofit是將您的API接口轉(zhuǎn)化為可調(diào)用對(duì)象的類(lèi)。默認(rèn)情況下，Retrofit會(huì)為你的平臺(tái)提供合理的默認(rèn)值，但它允許定制。
1.轉(zhuǎn)換器
默認(rèn)情況下，Retrofit只能將HTTP主體反序列化為OkHttp的ResponseBody類(lèi)型，并且只能接受它的請(qǐng)求體類(lèi)型為@body。
可以添加轉(zhuǎn)換器來(lái)支持其他類(lèi)型。為了方便，6個(gè)兄弟模塊調(diào)整了流行的序列化庫(kù)。
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
這里有一個(gè)使用GsonConverterFactory類(lèi)來(lái)生成GitHubService接口的示例，該接口使用Gson進(jìn)行反序列化。
Retrofitretrofit=newRetrofit.Builder()
? ? .baseUrl("https://api.github.com")
? ?.addConverterFactory(GsonConverterFactory.create()
? ? .build();
GitHubService service=retrofit.create(GitHubService.class);
2.自定義轉(zhuǎn)換器
如果您需要使用一個(gè)API，該API使用的內(nèi)容格式并不支持box(例如YAML、txt、定制格式)，或者您希望使用不同的庫(kù)來(lái)實(shí)現(xiàn)現(xiàn)有的格式，那么您可以輕松地創(chuàng)建自己的轉(zhuǎn)換器。創(chuàng)建一個(gè)擴(kuò)展轉(zhuǎn)換器的類(lèi)。工廠(chǎng)類(lèi)，并在構(gòu)建適配器時(shí)傳入一個(gè)實(shí)例。
五：應(yīng)用？
以下為我項(xiàng)目中的應(yīng)用
compile'com.squareup.retrofit2:retrofit:2.2.0'
compile'com.squareup.retrofit2:converter-gson:2.2.0'
compile'com.squareup.retrofit2:adapter-rxjava:2.2.0'
compile'com.squareup.retrofit2:converter-scalars:2.2.0'
具體應(yīng)用查看：你真的會(huì)用Retrofit2嗎?Retrofit2完全教程
