Retrofit

Retrofit

標籤（空格分隔）： 第三方&開源

---

Retrofit是一套RESTful架構的Android(Java)客戶端實現，基於註解，提供JSON to POJO(Plain Ordinary Java Object,簡單Java對象)，POJO to JSON，網絡請求(POST，GET,PUT，DELETE等)封裝。

相關資料：

RESTful百度百科
RESTful API設計
Retrofit 原理
Retrofit 簡單使用
Retrofit Github工程地址

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 接口的實現；

RestAdapter restAdapter = new RestAdapter.Builder()
    .setEndpoint("https://api.github.com")
    .build();
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 同步

每一個函數能夠定義爲異步或者同步。

5.一、具備返回值的函數爲同步執行的

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

5.二、異步執行函數沒有返回值而且要求函數最後一個參數爲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接口指定

// 經過返回值指定要轉換的Java的對象的類型
@GET("/users/list")
List<User> userList();

// 經過Callback的泛型參數來制定要轉換的Java對象的類型
@GET("/users/list")
void userList(Callback<List<User>> cb);

七、若是要直接獲取HTTP返回的對象，使用Response對象。

// 經過返回值的方式指定
@GET("/users/list")
Response userList();

// 經過Callback的泛型參數指定
@GET("/users/list")
void userList(Callback<Response> cb);

八、Retrofit涉及的重要知識點

• 動態代理
• 註解
• Handler + MessageQueue + Thread + Looper機制
• OKHttp請求網絡
• GSON用來轉換Java POJO和解析JSON