Retrofit：非常好用的 Java HTTP Client 工具

Retrofit

A type-safe HTTP client for Android and Java

首先，它是一個 HTTP Client，一個用於發送 Http 請求的工具；另外，它具有類型安全的特點，能夠定義結構化的請求接口，這樣的程序更易理解。

入門

將 HTTP API 轉換爲 Java 接口：

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

使用 Retrofit 來生成請求接口對應的 Implementation：

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

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

然後使用生成的 GitHubService 實例來進行 HTTP 請求的調用，可以同步調用，也可以異步調用：

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

通過註解來描述 HTTP 請求：

• URL 參數，支持路徑參數，queyr 參數；
• 將Java 對象映射爲請求 body （json，protocol buffers）
• multipart 請求，及文件上傳

API 聲明

通過 Java 接口方法的參數及註解來聲明一個 Restful 風格的 HTTP API；

註解主要定義 HTTP 方法和相對路徑，例如：

@GET("users/list")

有五個內置註解：GET，POST，PUT，DELETE，and HEAD。

對於不變的 query parameter，可以直接添加在 URL 中：

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

路徑參數的值，對應方法中添加了 @Path 註解的參數：

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

query 參數使用 @Query 來註解，@QueryMap 註解參數集合：

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

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

Post 請求的 Body 參數，通過 @Body 註解：

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

Java 對象會根據 Retrofit 上配置的 Converter 轉換爲指定的格式，如果沒有添加任何 converter，只能使用 RequestBody 對象。

同步，異步

Call 實例既可以同步執行，又可以異步執行，二選一，如果要同時支持兩種方式，需要使用 clone() 方法複製一個新的實例。

配置

默認情況下 Retrofit 只接受 RequestBody 對象實例，並返回 ResponseBody 對象實例。

要支持其他類型的 Request/Response，需要添加對應的 Converter：

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