Retrofit – Java(Android) 的REST 接口封裝類庫

Retrofit   和Java領域的ORM概念類似， ORM把結構化數據轉換爲Java對象，而Retrofit 把REST API返回的數據轉化爲Java對象方便操作。同時還封裝了網絡代碼的調用。

例如：

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

定義上面的一個REST API接口。 該接口定義了一個函數 listRepos ,  該函數會通過HTTP GET請求去訪問服務器的/users/{user}/repos路徑並把返回的結果封裝爲List<Repo> Java對象返回。

其中URL路徑中的{user}的值爲listRepos 函數中的參數 user的取值。

然後通過  RestAdapter  類來生成一個  GitHubService  接口的實現；

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

獲取接口的實現後就可以調用接口函數來和服務器交互了；

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

從上面的示例可以看出， Retrofit 使用註解來聲明HTTP請求

• 支持 URL 參數替換和查詢參數
• 返回結果轉換爲Java對象(返回結果可以爲  JSON, protocol buffers)
• 支持 Multipart請求和文件上傳

具體使用文檔

函數和函數參數上的註解聲明瞭請求方式

請求方式

每個函數都必須帶有 HTTP 註解來表明請求方式和請求的URL路徑。類庫中有5個HTTP註解:  GET ,  POST ,  PUT ,  DELETE , 和  HEAD。 註解中的參數爲請求的相對URL路徑。

@GET("/users/list")

在URL路徑中也可以指定URL參數

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

URL處理

請求的URL可以根據函數參數動態更新。一個可替換的區塊爲用 {  和  } 包圍的字符串，而函數參數必需用  @Path 註解表明，並且註解的參數爲同樣的字符串

@GET("/group/{id}/users") //注意 字符串id
List<User> groupList(@Path("id") int groupId); //注意 Path註解的參數要和前面的字符串一樣 id

還支持查詢參數

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

請求體（Request Body）

通過   @Body  註解可以聲明一個對象作爲請求體發送到服務器。

@POST("/users/new")
void createUser(@Body User user, Callback<User> cb);

對象將被  RestAdapter 使用對應的轉換器轉換爲字符串或者字節流提交到服務器。

FORM ENCODED AND MULTIPART 表單和Multipart

函數也可以註解爲發送表單數據和multipart 數據

使用  @FormUrlEncoded  註解來發送表單數據；使用  @Field 註解和參數來指定每個表單項的Key，value爲參數的值。

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

使用  @Multipart  註解來發送multipart數據。使用  @Part  註解定義要發送的每個文件。

@Multipart
@PUT("/user/photo")
User updateUser(@Part("photo") TypedFile photo, @Part("description") TypedString description);

Multipart 中的Part使用  RestAdapter  的轉換器來轉換，也可以實現  TypedOutput  來自己處理序列化。

異步 VS 同步

每個函數可以定義爲異步或者同步。

具有返回值的函數爲同步執行的。

@GET("/user/{id}/photo")
Photo listUsers(@Path("id") int id);

而異步執行函數沒有返回值並且要求函數最後一個參數爲Callback對象

@GET("/user/{id}/photo")
void listUsers(@Path("id") int id, Callback<Photo> cb);

在 Android 上，callback對象會在主(UI)線程中調用。而在普通Java應用中，callback在請求執行的線程中調用。

服務器結果轉換爲Java對象

使用RestAdapter的轉換器把HTTP請求結果（默認爲JSON）轉換爲Java對象，Java對象通過函數返回值或者Callback接口定義

@GET("/users/list")
List<User> userList();

@GET("/users/list")
void userList(Callback<List<User>> cb);

如果要直接獲取HTTP返回的對象，使用  Response  對象。

@GET("/users/list")
Response userList();

@GET("/users/list")
void userList(Callback<Response> cb);

項目主頁：  http://square.github.io/retrofit/

參考項目： http://square.github.io/okhttp/

Android 示例項目：  https://github.com/goodev/RetrofitDemo