Retrofit的使用 (1)，retrofit使用

Retrofit的使用 (1)，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