Retrofit

Android和Java平臺下型別安全的HTTP客戶端
寫在前面：1.如果發現問題歡迎Issue；2.有些不知道對不對的地方給出了原文；3.如果你有更好的建議歡迎Issue；

• Retrofit
  • 翻譯之前
  • 簡介
  • API說明
    • 請求型別
    • URL變更
    • 請求體
    • 表單和多組資料
    • Header變更
    • 同步VS非同步
  • Retrofit配置
    • 轉換器
    • 自定義轉換器
  • 下載
    • MAVEN
    • GRADLE
    • 混淆
  • 貢獻
  • 許可

翻譯之前

1. 例項化Retrofit時必須呼叫addRetrofitFactory()制定轉換器
2. 如果需要用到轉換器GsonConverterFactory的話需要依賴compile 'com.squareup.retrofit2:converter-gson:2.0.1'
3. Retrofit使用例項Demo下載

簡介

Retrofit將HTTP API轉換為Java介面

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

Retrofit類生成GitHubService介面的一個例項

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

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

例項化後的GitHubService中每個Call都會發起一個同步或非同步的HTTP請求到遠端伺服器

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

使用註解來描述HTTP請求:
- URL引數替換與請求引數支援
- 請求體型別轉換（如JSON，協議快取）
- 多請求體與檔案上傳

注意：本文仍舊用來說明2.0APIs。

API說明

介面中的註解和引數哦表明一個請求如何被處理。

請求型別

每個方法必須有一個HTTP註解來說明請求型別與相對URL。已提供的5種註解：GET，POST，PUT，DELETE，HEAD。相對URL需要在註解內容中被指定。

@GET("users/list")

可以在URL中指定請求引數

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

URL變更

可以在方法中使用佔位符和引數動態更新URL。佔位符是被{}包裹的字串表示式。相應的引數必須用同樣的字串通過@Path註解。

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

也可以新增請求引數

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

對於複雜的請求引數可以用Map組織起來

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

請求體

一個物件可以通過@Body註解在HTTP請求體中指定。

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

這個物件同樣會被在Retrofit例項中指定的轉換器轉換。如果沒有新增轉換器，則只會使用RequestBody。

表單和多組資料

同樣可以定義方法來發送表單和多組資料。
如果方法前有@FormUrlEncoded註解，則可以傳送表單資料。每個鍵值對都包含在@Field註解中，註解中需要包含名稱和物件提供的值。（本句原文：Each key-value pair is annotated with @Field containing the name and the object providing the value.）

@FormUrlEncoded
@Post("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

如果方法前有@Multipart註解，則可以傳送多組資料。資料組使用@Part註解宣告。

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

多組資料的資料組使用Retrofit的轉換器進行序列化，可以通過實現RequestBody來自行處理序列化。

Header變更

可以給方法設定靜態headers通過@Headers註解。

@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();

@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("user/{username}")
Call<User> getUser(@Path("username") String username);

注意headers不會相互覆蓋。所有使用相同name的headers都會被包含到請求中。
可以使用@Header註解動態更新請求頭，相應的引數必須用@Header提供。如果該值為空，則對應header會被省略。否則該值會通過toString轉換為字串被使用。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

需要被新增到每個請求的Headers會通過OkHttp interceptor被指定。

同步VS非同步

Call例項用同步非同步都可以執行。每個例項都只能被用一次，但呼叫clone()將建立一個可用的新例項。
在Android上，回撥將在主執行緒中執行。在JVM上，回撥執行所線上程與HTTP請求執行執行緒相同。

Retrofit配置

Retrofit是通過API介面轉換得到的可呼叫物件。預設情況下，Retrofit將根據所用平臺自動配置，但也允許自定義。

轉換器

預設情況下，Retrofit只能將HTTP實體反序列化為OkHttp的ResponseBody型別，並且只通過@Body來接受它的RequestBody型別。（本句原文：By default, Retrofit can only deserialize HTTP bodies into OkHttp’s ResponseBody type and it can only accept its RequestBody type for @Body.）
可以新增指示器來支援其他型別。下面提供6個流行的序列化庫。
- 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

下面給出一個在反序列化時通過Gson使用GsonConverterFactory來例項化GitHubService的例子。

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

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

自定義轉換器

如果你需要通過使用了Retrofit不支援的格式化內容（如YAML、txt、自定義格式）呼叫API，或者需要用一個不同的庫來使用已有的格式化規則。建立一個繼承自Converter.Factory的類並在繫結adapter的時候傳遞一個例項。

下載

下載最新JAR包
Retrofit的原始碼、例子、本網站都在能在GitHub上找到。

MAVEN

<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>(寫上最新版本)</version>
</dependency>

GRADLE

compile 'com.squareup.retrofit2:retrofit:(寫上最新版本)'

Retrofit需要Java7以上或Android2.3以上。

混淆

如果在project中使用混淆需要將如下內容新增到配置中：

-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions

貢獻

如果你想貢獻程式碼，你可以再GitHub上fork一下然後pull下來。
當提交程式碼時，請保證儘可能遵從現有約定和格式來保證保持程式碼可讀性。同時請保證你的程式碼通過執行mvn clean verfy來編譯。
在你的程式碼被接納之前，你必須簽上CLA.

許可

Copyright 2013 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.