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請求和文件上傳
具體使用文檔
函數和函數參數上的注解聲明了請求方式
1、請求方式
每個函數都必須帶有 HTTP 注解來表明請求方式和請求的URL路徑。類庫中有5個HTTP注解:GET, POST, PUT,DELETE和HEAD。注解中的參數為請求的相對URL路徑。
@GET("/users/list")
在URL路徑中也可以指定URL參數
@GET("/users/list?sort=desc")
2、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);
3、請求體（Request Body）
通過@Body注解可以聲明一個對象作為請求體發送到服務器。
@POST("/users/new")
void createUser(@Body User user, Callback<User> cb);
對象將被RestAdapter使用對應的轉換器轉換為字符串或者字節流提交到服務器。
4、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來自己處理序列化。
5、異步 VS 同步
每個函數可以定義為異步或者同步。
5.1、具有返回值的函數為同步執行的
@GET("/user/{id}/photo")
Photo listUsers(@Path("id") int id);
5.2、異步執行函數沒有返回值並且要求函數最后一個參數為Callback對象
@GET("/user/{id}/photo")
void listUsers(@Path("id") int id, Callback<Photo> cb);
- 在 Android 上，callback對象會在主(UI)線程中調用。
- 在普通Java應用中，callback在請求執行的線程中調用。
6、服務器結果轉換為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);
7、如果要直接獲取HTTP返回的對象，使用Response對象。
// 通過返回值的方式指定
@GET("/users/list")
Response userList();
// 通過Callback的泛型參數指定
@GET("/users/list")
void userList(Callback<Response> cb);
8、Retrofit涉及的重要知識點
- 動態代理
- 注解
- Handler + MessageQueue + Thread + Looper機制
- OKHttp請求網絡
- GSON用來轉換Java POJO和解析JSON