Retrofit 2 0很是簡單的入門（翻譯官方文檔）

若是本文幫助到你，本人不勝榮幸，若是浪費了你的時間，本人深感抱歉。 但願用最簡單的大白話來幫助那些像我同樣的人。若是有什麼錯誤，請必定指出，以避免誤導你們、也誤導我。 本文來自：www.jianshu.com/users/320f9… 感謝您的關注。

聲明：本文是轉載的 轉自：blog.csdn.net/leilba/arti… 很好奇這麼好的東西，爲何沒人看。

Retrofit：Square提供的開源產品，爲Android平臺的應用提供一個類型安全的REST客戶端。聽說網絡請求很是的快。 這個是官方文檔（英文）：square.github.io/retrofit/

開始正文。

---

1. 介紹

Retrofit能夠將你的HTTP API轉化爲JAVA的接口的形式。例如：

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

而Retrofit類可以生成對應接口的實現。例如：

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

GitHubService service = retrofit.create(GitHubService.class);
複製代碼

每個由接口返回的Call對象均可以與遠程web服務端進行同步或者異步的HTTP請求通訊。例如：

Call<List<Repo>> repos = service.listRepos("octocat");
複製代碼

Retrofit使用註解來描述HTTP請求： 1.URL參數的替換和query參數的支持 2.對象轉化爲請求體（如：JSON，protocol buffers等） 3.多重請求體和文件上傳 注意：本站仍在爲2.0擴展新的API

2. API說明

Retrofit須要註解接口的請求方法和方法的參數來代表該請求須要怎麼樣的處理。

2.1請求方法 每個方法必需要有一個HTTP註解來標明請求的方式和相對URL。有五種內置的註解方式：GET、POST、PUT、DELETE以及HEAD。資源的相對URL須要在註解裏面明確給出：

@GET("users/list")
複製代碼

固然你也能夠將query參數直接寫在URL裏：

@GET("users/list?sort=desc")
複製代碼

2.2 URL操做 一個請求的URL能夠經過替換塊和請求方法的參數來進行動態的更新。替換塊是由被{}包裹起來的數字或字母組成的字符串構成的，相應的方法參數須要由@Path來註解一樣的字符串。例如：

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

Query參數也能同時添加。

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

複雜的query參數能夠用Map來構建

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

---

2.3請求主體 可以經過@Body註解來指定一個方法做爲HTTP請求主體

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

這個參數對象會被Retrofit實例中的converter進行轉化。若是沒有給Retrofit實例添加任何converter的話則只有RequestBody能夠做爲參數使用。

**2.4 form encode 和 multipart ** 方法也能夠經過聲明來發送form-encoded和multipart類型的數據。 能夠經過@FormUrlEncoded註解方法來發送form-encoded的數據。每一個鍵值對須要用@Filed來註解鍵名，隨後的對象須要提供值。

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

也能夠經過@Multipart註解方法來發送Mutipart請求。每一個部分須要使用@Part來註解。

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

多個請求部分須要使用Retrofit的converter或者是本身實現 RequestBody來處理本身內部的數據序列化。

2.5頭部操做 你能夠經過使用@Headers註解來設置請求靜態頭。

@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 註解。若是這個值是空（null）的話，那麼這個頭部參數就會被忽略。不然的話， 值的 toString 方法將會被調用，而且使用調用結果。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
複製代碼

固然你能夠經過OkHttp interceptor來指定每個須要的頭部參數。

2.6同步 VS 異步 你能夠同步或者異步地來執行實例。每一個示例只能使用一次，可是可使用 clone() 來建立一個可使用的新的實例。 在Android環境中，callback將會在主線程中執行；而在JVM環境中，callback將會在和Http請求的同一個線程中執行。

3. Retrofit配置

Retrofit類會經過你定義的API接口轉化爲可調用的對象。默認狀況下，Retrofit會返還給你合理的默認值，但也容許你進行指定。

3.1轉化器（Converters） 默認狀況下，Retrofit只能將HTTP體反序列化爲OKHttp的 ResonseBody 類型，並且只能接收 RequestBody類型做爲 @Body。 轉化器的加入能夠用於支持其餘的類型。如下六個同級模塊採用了經常使用的序列化庫來爲你提供方便。

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

下面提供一個使用GsonConverterFactory類生成 GitHubService的接口實現gson反序列化的例子。

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

GitHubService service = retrofit.create(GitHubService.class);
複製代碼

3.2自定義轉化器 若是你須要與沒有使用Retrofit提供的內容格式的API進行交互的話或者是你但願使用一個不一樣的庫來實現現有的格式，你也能夠輕鬆建立使用本身的轉化器。你須要建立一個繼承自Converter.Factory的類而且在構建適配器的時候加入到實例裏面。

4. 下載

↓ Latest JAR

源代碼、例子和網站在 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
複製代碼