原文鏈接：https://futurestud.io/blog/retrofit-getting-started-and-android-client
本文是Retrofit系列文章的第一篇。本系列深入挖掘幾個使用案例并討論了Retrofit的功能和擴展性澈驼。
Retrofit 系列目錄
- 開始創(chuàng)建android客戶端
- Android上的基本認證[已翻譯]
- Android上的令牌認證[已翻譯]
- Android上的OAuth
- 多個 Query 參數(shù)使用同一名字[已翻譯]
- 同步與異步請求[已翻譯]
- 在請求體里發(fā)送對象[已翻譯]
- 自定義一個響應(yīng)轉(zhuǎn)換器[已翻譯]
- 添加自定義請求頭
- 可選的 Query 參數(shù)
- 如何集成 XML 轉(zhuǎn)換器
- 使用 Log Level 調(diào)試請求
- 如何上傳文件
- Series Round-Up
- Retrofit 2 — 1.9 升級指南
- Retrofit 2 — 如何上傳文件
- Retrofit 2 — Log 請求與響應(yīng)
- Retrofit 2 — Android 上的 Hawk 認證
- Retrofit 2 — 簡單錯誤處理
- 如何在 Retrofit 1 里使用 OkHttp 3
- Retrofit 2 — 圖書更新發(fā)布慶典
- 提交表單數(shù)據(jù) — Urlencoded
- 提交表單數(shù)據(jù) — Urlencoded 使用FieldMap
- Retrofit 2 — 在 OkHttp 攔截器里管理請求頭部
- Retrofit 2 — 如何給每一個請求添加 Query 參數(shù)
- Retrofit 2 — 使用QueryMap 添加多個 Query 參數(shù)
- Retrofit 2 — 如何在請求時使用動態(tài) Url
- Retrofit 2 — Url 處理，分辨和解析
- Retrofit 2 — POST 和PUT 請求里的常量, 默認值和邏輯值
- Retrofit 2 — 如何下載文件
- Retrofit 2 — 取消請求
- Retrofit 2 — 重用分析請求
- Retrofit 2 — 如何在運行時修改 API Base Url
- 可選Path參數(shù)
- 如何刷新 Access Token
- Retrofit 2 — 如何提交文本請求體
- Retrofit 2 — 使用 Query 參數(shù)來分頁
- Retrofit 2 — 使用 鏈接頭和動態(tài) Url 來分頁(比如GitHub)
- Retrofit 2 — 使用范圍頭字段來分頁 (比如 Heroku)
- Retrofit 2 — 轉(zhuǎn)換器介紹
- Retrofit 2 — 添加并自定義 Gson 轉(zhuǎn)換器
- Retrofit 2 — 實現(xiàn)自定義轉(zhuǎn)換器
- Retrofit 2 — 只在開發(fā)環(huán)境里啟用日志
- Retrofit 2 — 如何上傳多個文件
- Retrofit 2 — Passing Multiple Parts Along a File with @PartMap
- Retrofit 2 — 模仿服務(wù)端響應(yīng)基本概念
- Retrofit 2 — 模仿服務(wù)端響應(yīng)自定義網(wǎng)絡(luò)行為
- Retrofit 2 — 使用 @HeaderMap 定義動態(tài)請求頭
在本篇博客里我們將瀏覽 Retrofit 的基本概念灼伤，并創(chuàng)建 android 客戶端用來做 HTTP 請求.
但是請記住我們不會介紹過多入門知識和 Retrofit 是什么. 想知道更多請訪問官網(wǎng).
Retrofit 是什么
官網(wǎng)介紹如下：
A type-safe REST client for Android and Java.
（目前已改為A type-safe **HTTP client **for Android and Java，譯者注）
你將使用注解來描述 HTTP 請求, URL 參數(shù)替換迄损， 默認集成query 參數(shù)支持. 除此而外, 它還提供Multipart請求和文件上傳的功能.
如何聲明 (API) 請求
請訪問 Retrofit 主頁并閱讀 API 聲明部分來理解并找到如何做請求的感覺 . 在此你將發(fā)現(xiàn)所有重要信息坑质，它們在代碼示例里被清晰的描述.
準備你的 Android 項目
現(xiàn)在讓我們把手放到鍵盤上患雇。如果已經(jīng)創(chuàng)建過了Android項目，那么請繼續(xù)閱讀下一章節(jié)淮野。否則捧书，請使用你最喜歡的IDE創(chuàng)建一個新項目。我們傾向于使用 Gradle 做為構(gòu)建系統(tǒng)骤星，不過當(dāng)然你也可以繼續(xù)使用 Maven经瓷。
定義依賴: Gradle 或者 Maven
現(xiàn)在讓我們將 Retrofit 設(shè)為項目的一個依賴. 選擇你使用的構(gòu)建系統(tǒng)并在 pom.xml 或者build.gradle里定義 Refrofit 和它的依賴. 當(dāng)執(zhí)行構(gòu)建命令代碼時, 構(gòu)建系統(tǒng)將會下載并提供你項目的庫. 我們建議使用 Retrofit 聯(lián)合 OkHTTP, 它需要 Okio 做為依賴.
Retrofit 1.9
pom.xml
<dependency>
<groupId>com.squareup.retrofit</groupId>
<artifactId>retrofit</artifactId>
<version>1.9.0</version>
</dependency>
<dependency>
<groupId>com.squareup.okhttp</groupId>
<artifactId>okhttp</artifactId>
<version>2.7.2</version>
</dependency>
build.gradle
dependencies {
// Retrofit & OkHttp
compile 'com.squareup.retrofit:retrofit:1.9.0'
compile 'com.squareup.okhttp:okhttp:2.7.2'
}
Retrofit 2
如果你使用的 Retrofit 版本2 ,請使用如下依賴:
pom.xml
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>converter-gson</artifactId>
<version>2.1.0</version>
</dependency>
build.gradle
dependencies {
// Retrofit & OkHttp
compile 'com.squareup.retrofit2:retrofit:2.1.0'
compile 'com.squareup.retrofit2:converter-gson:2.1.0'
}
Retrofit 2 默認情況下利用OkHttp作為網(wǎng)絡(luò)層，是構(gòu)建在它之上. 你不必顯式定義 OkHttp 作為你項目的依賴, 除非你需要它的特定版本.
既然你的項目已經(jīng)準備好集成 Retrofit, 那么讓我們創(chuàng)建一個持久的 Android API/HTTP 客戶端.
可持續(xù)Android客戶端
在研究目前已有的 Retrofit 客戶端過程中, 出現(xiàn)了 Bart Kiers 的例子庫. 實際上他是關(guān)于用 Retrofit OAuth 認證的例子. 無論如何洞难，它提供了一個可持續(xù)發(fā)展的Andr??oid客戶端所有必要的基礎(chǔ)知識. 這就是為什么我們把它作為一個穩(wěn)定的基礎(chǔ)舆吮，并在未來的博客中做進一步的認證功能擴展.
接下來的類定義了我們android客戶端的基礎(chǔ): ServiceGenerator.
Service Generator
ServiceGenerator 是我們 API/HTTP 客戶端的核心. 當(dāng)前, 它只定義了一個方法, 就是給已有的類/接口創(chuàng)建基本的 REST 適配器. 代碼如下:
Retrofit 1.9
public class ServiceGenerator {
public static final String API_BASE_URL = "http://your.api-base.url";
private static RestAdapter.Builder builder = new RestAdapter.Builder()
.setEndpoint(API_BASE_URL)
.setClient(new OkClient(new OkHttpClient()));
public static <S> S createService(Class<S> serviceClass) {
RestAdapter adapter = builder.build();
return adapter.create(serviceClass);
}
}
Retrofit 2
public class ServiceGenerator {
public static final String API_BASE_URL = "http://your.api-base.url";
private static OkHttpClient.Builder httpClient = new OkHttpClient.Builder();
private static Retrofit.Builder builder =
new Retrofit.Builder()
.baseUrl(API_BASE_URL)
.addConverterFactory(GsonConverterFactory.create());
public static <S> S createService(Class<S> serviceClass) {
Retrofit retrofit = builder.client(httpClient.build()).build();
return retrofit.create(serviceClass);
}
}
ServiceGenerator 類使用 Retrofit 的 RestAdapter-Builder 結(jié)合提供的 API_BASE_URL來創(chuàng)建一個新的 REST 客戶端. 比如, GitHub 的 API_BASE_URL是 https://api.github.com/. serviceClass 定義API請求注解類或接口. 下面的章節(jié)將顯示 Retrofit 的具體使用和如何定義一個示范客戶端.
JSON 映射
Retrofit 1.9 默認附帶 Google的 GSON 庫. 你需要做的就是定義你響應(yīng)對象的類, 然后響應(yīng)將被自動映射.
然而到了 Retrofit 2, 你需要顯示添加一個轉(zhuǎn)換器到 Retrofit 對象上. 前面,我們已經(jīng)添加下列行到 build.gradle 文件來導(dǎo)入 Retrofit 2的 GSON 轉(zhuǎn)換器.
compile 'com.squareup.retrofit2:converter-gson:2.1.0'
現(xiàn)在你需要給你的 Retrofit 對象添加轉(zhuǎn)換. 在Retrofit 的 builder 調(diào)用 .addConverterFactory(GsonConverterFactory.create()) 來集成 GSON 作為默認的 JSON 轉(zhuǎn)換器.
Retrofit 實例
好吧，讓我們面對一個例子队贱，定義一個從GitHub請求數(shù)據(jù)的REST客戶端. 首先, 我們必須創(chuàng)建接口并定義需要的方法.
GitHub 客戶端
下面的代碼定義了 GitHubClient接口, 接口定義了一個請求存儲庫貢獻者列表的方法. 這也顯示了 Retrofit 的參數(shù)替換功能的使用 (路徑中的{owner} 和{repo} 在調(diào)用對象方法時將會被給定的變量替換).
Retrofit 1.9
public interface GitHubClient {
@GET("/repos/{owner}/{repo}/contributors")
List<Contributor> contributors(
@Path("owner") String owner,
@Path("repo") String repo
);
}
Retrofit 2
public interface GitHubClient {
@GET("/repos/{owner}/{repo}/contributors")
Call<List<Contributor>> contributors(
@Path("owner") String owner,
@Path("repo") String repo
);
}
這是定義的 Contributor 類. 這個類包含所需的類屬性來映射響應(yīng)數(shù)據(jù).
static class Contributor {
String login;
int contributions;
}
至于先前提到的JSON映射：GitHubClient 定義了返回類型為 List<Contributor>的方法 contributors . Retrofit 確保服務(wù)器的響應(yīng)被正確的映射（響應(yīng)匹配給定的類）.
API 請求示例
下面的片段顯示了 ServiceGenerator 的用法, 實例化客戶端(具體來說是GitHub 客戶端), 和用創(chuàng)建的 client 得到貢獻者的方法調(diào)用. 這個片段是所提供的 Retrofit github客戶端示例的修改后版本.
當(dāng)執(zhí)行GitHub 示例時, 你需要在ServiceGenerator接口手動定義基本url為 "https://api.github.com/". 另一種方法是再創(chuàng)建一個 createService()
方法, 接受兩個參數(shù): client 類和基本 url.
Retrofit 1.9
public static void main(String... args) {
// Create a very simple REST adapter which points the GitHub API endpoint.
GitHubClient client = ServiceGenerator.createService(GitHubClient.class);
// Fetch and print a list of the contributors to this library.
List<Contributor> contributors =
client.contributors("fs_opensource", "android-boilerplate");
for (Contributor contributor : contributors) {
System.out.println(
contributor.login + " (" + contributor.contributions + ")");
}
}
Retrofit 2
public static void main(String... args) {
// Create a very simple REST adapter which points the GitHub API endpoint.
GitHubClient client = ServiceGenerator.createService(GitHubClient.class);
// Fetch and print a list of the contributors to this library.
Call<List<Contributor>> call =
client.contributors("fs_opensource", "android-boilerplate");
try {
List<Contributor> contributors = call.execute().body();
} catch (IOException e) {
// handle errors
}
for (Contributor contributor : contributors) {
System.out.println(
contributor.login + " (" + contributor.contributions + ")");
}
}
接下來做什么
接下來的章節(jié)介紹了如何使用 Retrofit 完成基本身份認證. 我們將展示代碼例子使用用戶名/電子郵件和密碼來驗證web服務(wù)或api. 此外色冀，以后的文章將涵蓋令牌（其中包括OAuth）API認證.
我們希望你喜歡這個概述，以及如何使用 Retrofit 完成你的第一個請求:)
附加資源
- Retrofit 項目主頁
- Retrofit API 聲明文檔
- Retrofit 基于的 認證庫 作者 Bart Kiers
- Retrofit 示例
