Android和Java的REST接口調用封裝類庫：Retrofit

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請求和文件上傳
</ul>

具體使用文檔

函數和函數參數上的注解聲明了請求方式

請求方式

每個函數都必須帶有 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);</pre> 
如果要直接獲取HTTP返回的對象，使用Response對象。 

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

@GET("/users/list")
void userList(Callback<Response> cb);</pre> 
項目主頁： http://square.github.io/retrofit/ 

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

Android 示例項目： https://github.com/goodev/RetrofitDemo 
來自：http://blog.chengyunfeng.com/?p=491