Retrofit的簡易教程

本文算不上原創，只是大概翻譯了 Retrofit 的英文文檔，權當作是本身的筆記而已。

英文原地址：http://square.github.io/retrofit/

1.介紹

　　Retrofit 把你的 HTTP API 轉換爲一個Java 接口。

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

 

　　Retrofit生成了 GithubService 接口的一個實現類。

1 Retrofit retrofit = new Retrofit.Builder()
2     .baseUrl("https://api.github.com")
3     .build();
4 
5 GitHubService service = retrofit.create(GitHubService.class);

　　

　　從生成的 GitHubService 發出的每個 Call 均可以向遠程的 Web服務器發出一個同步或者異步的HTTP請求。

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

 

　　使用 annotations 描述 HTTP 請求:

• 支持 URL 參數替換和請求參數

• 支持對象轉爲請求體 (e.g.,JSON, protocol buffers)

• 支持多個 request body 和 文件上傳

2.API 的聲明

　　接口方法上的 Annotations 和它的參數標明瞭這個請求是如何被處理的。

　　

　　a.請求方法

　　每一個方法必須有一個提供了 request method 和 releative URL 的 HTTP annotation。Retrofit 內置了五種 annotations ：GET, POST, PUT, DELETE, 和HEAD。在 annotation 中資源的 relative URL 是被指定的。

 1 @GET("/users/list") 

你也能夠在 URL 中指定請求參數。

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

 

　　b.URL處理

　　一個請求 URL 能夠被其中的 replacement block 和方法上的參數動態的替換。replacement block 是一個被「{ }」包裹的含有字母或數字的字符串。相對應的參數必須是一個帶有 @Path 的相同的字符串。即：

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

 

　　查詢的參數也能夠被添加進來。

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

 

　　對於複雜的查詢參數能夠組合成一個 Map 來使用。

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

 

　　c.請求體

　　一個帶有 @Body 註解的對象能夠被當作 HTTP 的請求體。

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

這個對象能夠被 Retrofit 指定的轉換器轉換。若是沒有指定，只有在 RequestBody 才能被使用。

　　

　　d.Form Encoded and Multipart

　　Methods 也能夠被聲明發送 form-encoded 和 MutiPart 數據。

　　使用 form-encoded 時要在 Method 上面添加 @FormUrlEncoded 註解。每個鍵值對使用 @Field註解包裹 key。即：

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

　　使用多個請求時，要在 Method 上添加 @Multipart 註解，每部分使用 @Part  添加聲明。即：

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

　　多個請求部分使用 Retrofit 的轉換器或者本身實現 RequestBody 處理本身的序列化。

　　

　　e.請求頭的操縱

　　你可使用 @Headers 爲一個請求方法設置靜態的請求頭。

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

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

　　須要注意的是，全部的 Headers 之間不會重寫，全部相同名字的 Headers 都會包含在請求裏面。

　　一個請求的 Headers 可使用 @Headers 註解動態的更新。必需要爲 @Headers 設置一個字母或者數字的參數。若是真實的值是 null ，這個請求頭會被忽略，不然會調用 toString() 方法，而且在請求中使用。

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

　　Headers that need to be added to every request can be specified using an OkHttp interceptor.

 

　　f.同步 VS. 異步

　　Call 實例能夠再同步或者異步中執行。每一個實例只能使用一次，可是如否使用 clone() 方法就能再建立一個可使用的實例了。

　　在 Android 中，回調會在主線程中執行。在 JVM 中回調會在發起 HTTP request 的同一線程中執行。

 

3.Retrofit 參數配置

　　Retrofit 是一個經過你的 API 接口轉換爲 可回調對象的類。Retrofit 爲你提供了默認的配置，可是也容許你自定義配置。

 

　　a.轉換器

　　默認狀況下，Retrofit 只能講 HTTP bodies 發序列化爲 OkHttp 的 ResponeBody 類型，對於 @Body 來講也只能在接收 ResponeBody 類型。

　　轉換器也能夠支持下面類型：

• 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

　　b.自定義轉換器

　　你也能夠經過繼承 Converter.Factory class 自定義轉換器，而後在建立 adapter 是傳入這個類得實例。

 

4.集成方式

　　最新的 jar 包，請點擊這裏。

　　Retrofit 源碼與示例程序 On Github。

　　Maven

<dependency>
  <groupId>com.squareup.retrofit</groupId>
  <artifactId>retrofit</artifactId>
  <version>(insert latest version)</version>
</dependency>

　　Gradle

compile 'com.squareup.retrofit:retrofit:(insert latest version)'

　　Retrofit 須要的環境：Java 7 以上及 Android 2.3以上。

　　ProGuard

1 -dontwarn retrofit.**
2 -keep class retrofit.** { *; }
3 -keepattributes Signature
4 -keepattributes Exceptions