如果本文幫助到你磺箕，本人不勝榮幸，如果浪費(fèi)了你的時(shí)間抛虫，本人深感抱歉松靡。
希望用最簡(jiǎn)單的大白話來(lái)幫助那些像我一樣的人。如果有什么錯(cuò)誤建椰，請(qǐng)一定指出雕欺，以免誤導(dǎo)大家、也誤導(dǎo)我棉姐。
本文來(lái)自：http://www.reibang.com/users/320f9e8f7fc9/latest_articles
感謝您的關(guān)注屠列。

聲明：本文是轉(zhuǎn)載的
轉(zhuǎn)自：http://blog.csdn.net/leilba/article/details/50685205
很好奇這么好的東西，為什么沒人看谅海。

Retrofit：Square提供的開源產(chǎn)品脸哀，為Android平臺(tái)的應(yīng)用提供一個(gè)類型安全的REST客戶端。據(jù)說網(wǎng)絡(luò)請(qǐng)求非常的快扭吁。
這個(gè)是官方文檔（英文）：http://square.github.io/retrofit/

開始正文撞蜂。

1. 介紹

Retrofit可以將你的HTTP API轉(zhuǎn)化為JAVA的接口的形式。例如：

public interface GitHubService {
  @GET("users/{user}/repos")
  Call<List<Repo>> listRepos(@Path("user") String user);
}

而Retrofit類能夠生成對(duì)應(yīng)接口的實(shí)現(xiàn)侥袜。例如：

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

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

每一個(gè)由接口返回的Call對(duì)象都可以與遠(yuǎn)程web服務(wù)端進(jìn)行同步或者異步的HTTP請(qǐng)求通信蝌诡。例如：

Call<List<Repo>> repos = service.listRepos("octocat");

Retrofit使用注解來(lái)描述HTTP請(qǐng)求：
1.URL參數(shù)的替換和query參數(shù)的支持
2.對(duì)象轉(zhuǎn)化為請(qǐng)求體（如：JSON，protocol buffers等）
3.多重請(qǐng)求體和文件上傳
注意：本站仍在為2.0擴(kuò)展新的API

2. API說明

Retrofit需要注解接口的請(qǐng)求方法和方法的參數(shù)來(lái)表明該請(qǐng)求需要怎么樣的處理枫吧。

2.1請(qǐng)求方法
每一個(gè)方法必須要有一個(gè)HTTP注解來(lái)標(biāo)明請(qǐng)求的方式和相對(duì)URL浦旱。有五種內(nèi)置的注解方式：GET、POST九杂、PUT颁湖、DELETE以及HEAD。資源的相對(duì)URL需要在注解里面明確給出：

  @GET("users/list")

當(dāng)然你也可以將query參數(shù)直接寫在URL里：

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

2.2 URL操作
一個(gè)請(qǐng)求的URL可以通過替換塊和請(qǐng)求方法的參數(shù)來(lái)進(jìn)行動(dòng)態(tài)的更新例隆。替換塊是由被{}包裹起來(lái)的數(shù)字或字母組成的字符串構(gòu)成的甥捺，相應(yīng)的方法參數(shù)需要由@Path來(lái)注解同樣的字符串。例如：

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

Query參數(shù)也能同時(shí)添加镀层。

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

復(fù)雜的query參數(shù)可以用Map來(lái)構(gòu)建

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

2.3請(qǐng)求主體
能夠通過@Body注解來(lái)指定一個(gè)方法作為HTTP請(qǐng)求主體

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

這個(gè)參數(shù)對(duì)象會(huì)被Retrofit實(shí)例中的converter進(jìn)行轉(zhuǎn)化镰禾。如果沒有給Retrofit實(shí)例添加任何converter的話則只有RequestBody可以作為參數(shù)使用。

**2.4 form encode 和 multipart **
方法也可以通過聲明來(lái)發(fā)送form-encoded和multipart類型的數(shù)據(jù)。
可以通過@FormUrlEncoded注解方法來(lái)發(fā)送form-encoded的數(shù)據(jù)吴侦。每個(gè)鍵值對(duì)需要用@Filed來(lái)注解鍵名屋休，隨后的對(duì)象需要提供值。

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

也可以通過@Multipart注解方法來(lái)發(fā)送Mutipart請(qǐng)求备韧。每個(gè)部分需要使用@Part來(lái)注解劫樟。

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

多個(gè)請(qǐng)求部分需要使用Retrofit的converter或者是自己實(shí)現(xiàn) RequestBody來(lái)處理自己內(nèi)部的數(shù)據(jù)序列化。

2.5頭部操作
你可以通過使用@Headers注解來(lái)設(shè)置請(qǐng)求靜態(tài)頭盯蝴。

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

<br />

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

注意的是頭部參數(shù)并不會(huì)相互覆蓋毅哗，同一個(gè)名稱的所有頭參數(shù)都會(huì)被包含進(jìn)請(qǐng)求里面听怕。
當(dāng)然你可以通過 @Header 注解來(lái)動(dòng)態(tài)更新請(qǐng)求頭捧挺。一個(gè)相應(yīng)的參數(shù)必須提供給 @Header 注解。如果這個(gè)值是空（null）的話尿瞭，那么這個(gè)頭部參數(shù)就會(huì)被忽略闽烙。否則的話， 值的 toString 方法將會(huì)被調(diào)用声搁，并且使用調(diào)用結(jié)果黑竞。

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

當(dāng)然你可以通過OkHttp interceptor來(lái)指定每一個(gè)需要的頭部參數(shù)。

2.6同步 VS 異步
你可以同步或者異步地來(lái)執(zhí)行實(shí)例疏旨。每個(gè)示例只能使用一次很魂，但是可以使用 clone() 來(lái)創(chuàng)建一個(gè)可以使用的新的實(shí)例。
在Android環(huán)境中檐涝，callback將會(huì)在主線程中執(zhí)行遏匆；而在JVM環(huán)境中，callback將會(huì)在和Http請(qǐng)求的同一個(gè)線程中執(zhí)行谁榜。

3. Retrofit配置

Retrofit類會(huì)通過你定義的API接口轉(zhuǎn)化為可調(diào)用的對(duì)象幅聘。默認(rèn)情況下，Retrofit會(huì)返還給你合理的默認(rèn)值窃植，但也允許你進(jìn)行指定帝蒿。

3.1轉(zhuǎn)化器（Converters）
默認(rèn)情況下，Retrofit只能將HTTP體反序列化為OKHttp的 ResonseBody 類型巷怜，而且只能接收 RequestBody類型作為 @Body葛超。
轉(zhuǎn)化器的加入可以用于支持其他的類型。以下六個(gè)同級(jí)模塊采用了常用的序列化庫(kù)來(lái)為你提供方便延塑。

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類生成 GitHubService的接口實(shí)現(xiàn)gson反序列化的例子绣张。

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

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

3.2自定義轉(zhuǎn)化器
如果你需要與沒有使用Retrofit提供的內(nèi)容格式的API進(jìn)行交互的話或者是你希望使用一個(gè)不同的庫(kù)來(lái)實(shí)現(xiàn)現(xiàn)有的格式，你也可以輕松創(chuàng)建使用自己的轉(zhuǎn)化器页畦。你需要?jiǎng)?chuàng)建一個(gè)繼承自Converter.Factory的類并且在構(gòu)建適配器的時(shí)候加入到實(shí)例里面胖替。

4. 下載

↓ Latest JAR

源代碼、例子和網(wǎng)站在 available on GitHub

4.1 maven

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>2.0.0</version>
</dependency>

4.2 gradle

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

Retrofit支持最低 Java7 和 Android 2.3

4.3 混淆
如果你的工程中使用了代碼混淆，那么你的配置中需要添加一下的幾行

-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions