Retrofit入門

Retrofit 

A type-safe HTTP client for Android and Java  。

下文基於 Retrofit 2.0.

介紹 

Retrofit將你的Http請求函數轉換成Java 接口

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

這是Retrofit請求gitHub用戶信息的例子。

GitHubService 接口的Retrofit的具體實現以下 ：

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

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

基於GitHubService建立的每個Call，能夠向遠程服務端發起一個同步或異步的請求。

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

應用註解來描述Http 請求

• 支持URL參數和Query參數的替換
• 對象轉換成request body （例如JSON 、 protocol buffers等）
• Multipart 請求和文件上傳

API聲明

在接口方法或它參數上的註解說明了一個請求將被怎麼處理

請求方法

每個方法必須有一個HTTP註解，來講明請求的方式和相對的URL，Retrofit提供了5個內嵌的註解：GET, POST, PUT, DELETE, and HEAD。 資源的相對URL經過註解指定。

@GET("users/list")

也能夠在地址中加入query參數

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

sort=desc就是 query參數。

URL處理

一個請求URL能夠動態更新，經過替換塊和方法中的參數。一個替換塊是一個由字母數字組成的字符串，被{}包裹。對應的參數必須經過@Path註解，且字符串相同。

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

{id} 爲可修改的請求參數，在方法參數的註解中 通樣有一個id被@Path註解。

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);

請求體（request body）

經過@Body註解能夠將一個對象做爲HTTP請求的請求體（request body）使用

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

表單和分塊請求

能夠聲明方法爲發送表單或分塊請求

表單請求經過@FormUrlEncoded註解，每個鍵值對經過@Field註解，包含key，參數具體值是value。

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

分塊請求經過@Multipart註解，每一個請求部分經過@Part註解

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

分塊請求使用Retrofit的轉換器或實現本身的RequestBody 來處理本身的串行化。

HEADER處理

經過@Headers註解來給方法增長header信息

@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不互相重寫，相同name的header都被包含在請求裏。

經過@Header能夠動態修改一個請求的頭信息。這時相應的參數必須提供@Header註解，若是值是null，將被忽略，不然，將調用toString()方法獲取具體的值。

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

經過OkHttp interceptor.能夠添加統一的頭信息。

同步和異步

Call實例能夠同步或異步執行，每一個實例只能執行一次。可是調用clone能夠建立新的實例來使用。

在Android平臺，回調將在主線程調用，在jvm平臺，回調在執行http請求的線程執行。

轉換器

默認狀況下，Retrofit只能序列化它的http bodies到 OkHttp's ResponseBody，它只能接受它的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 的例子。

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

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

自定義轉換器

若是你須要和API通訊經過一種Retrofit不支持的內容組織形式（好比YAML, txt, custom format），你能夠自定義轉換器。能夠容易的經過繼承 Converter.Factory class 來自定義轉換器。

 

原文地址 ：

http://square.github.io/retrofit/