Retrofit 入門基礎

<b>本文講的是Retrofit 入門基礎，</b>

<b></b>

這是Retrofit系列文章中的第一篇，這個系列前前後後有幾個用例，并且還分析了Retrofit的功能性和可擴充性。

— 2015.10.21日更新

除了之前已經有的關于Retrofit 1.9的代碼樣例，我們也已經添加了新的關于Retrofit 2（基于 2.0.0-beta2）的代碼樣例。 并且也已經釋出了一個擴充的Retrofit更新指南：在下述内容的 。

通過這篇部落格，我們會學到Retrofit的基本用法和實作一個針對API或者HTTP請求的Android用戶端。

官方的Retrofit首頁是這樣描述它的

用于Android和Java的一個類型安全(type-safe)的REST用戶端

你将會用注解去描述HTTP請求，同時Retrofit預設內建URL參數替換和查詢參數.除此之外它還支援 Multipart請求和檔案上傳。

現在，讓我們把手放回到鍵盤上來。如果你已經建了一個Android項目的話，你可以直接看下一條，否則，在你最熟悉的IDE上建立一個Android項目。我們更傾向于用Gradle建構項目，但是如果你用Maven也是可以的。

pom.xml

build.gradle

如果你正在用Retrofit2.0版，請用下面的依賴

Retrofit 2預設使用OKHttp作為網絡層,并且在它上面進行建構。 你不需要在你的項目中顯式的定義OkHttp依賴，除非你有一個特殊的版本需求。

現在你的項目已經內建了Retrofit,讓我們一起建立一個具有持久性的 Android API/HTTP用戶端吧。

接下來的這個類是我們的Android用戶端的主要成分：ServiceGenerator。

ServiceGenerator 是我們 API/HTTP用戶端的核心， 在目前的階段，它隻定義了一個對給定的類或者接口建立一個基本的REST擴充卡(adapter)的方法。

Retrofit 1.9

Retrofit 2

<code>ServiceGenerator</code>類 用Retrofit的 <code>RestAdapter</code>-Builder與給定的API基礎url來建立一個新的REST用戶端。例如，Github的API基礎url是<code>https://developer.github.com/v3/</code>。

<code>serviceClass</code>類定義了用于API請求的注解了的類或接口。接下來的章節會向我們展示Retrofit的實用的用法，還有如何寫出一個值得仿效的用戶端。

Retrofit 1.9 預設提供Google的GSON。你需要做的隻是定義好你的response對象，之後這個response将會被自動地映射。

當用Retrofit 2時，你需要對<code>Retrofit</code>對象顯式地添加一個轉換器(converter).這就是我們要在Retrofit的 builder上調用<code>.addConverterFactory(GsonConverterFactory.create())</code>去內建GSON作為預設的JSON轉換器的原因。

好的，讓我們寫一個 REST的 用戶端向Github請求資料。

首先，我們必須建立一個接口和定義需要的方法。

接下來的代碼定義了一個<code>GithubClient</code>和一個請求倉庫的貢獻者清單的方法。它也說明了Retrofit的參數替換功能（當調用對象的方法時，在定義的路徑中的{owner} 和 {repo}将會被所給的變量所替換）。

這裡定義了一個<code>Contributor</code>類，這個類包含了要映射到response資料的所有需要的屬性。

關于之前提到的JSON映射：<code>GithubClient</code> 定義了一個傳回類型是<code>List</code>的命名為<code>contributors</code>的方法。Retrofit確定服務端傳回的response 能夠得到正确的映射(在這裡 服務端傳回的response 比對所給的Contributor類)。

當執行Github的這個例子的時候，你需要手動地在<code>ServiceGenerator</code>中用<code>"https://developer.github.com/v3/"</code>作為基礎的url。另一個選擇是用額外的<code>createService()</code>方法接受兩個參數: 用戶端類名，和基礎的url。

下一篇文章主要解釋了如何用Retrofit去實作基本的認證。我們将會展示一些用 使用者名/郵箱 和密碼驗證webservices或者APIs的代碼樣例。進一步講，之後的文章主要會涉及到用tokens（包括OAuth）的API認證

我們希望你能對這個概覽感到滿意，也希望你能用Retrofit來發出你的第一個請求。

學會如何在Android上用Retrofit建立一個高效率的RSET用戶端，通過複雜的APIs提升你的效率，享受工作的樂趣。

<b>原文釋出時間為：2016年01月07日</b>

<b>本文來自雲栖社群合作夥伴掘金，了解相關資訊可以關注掘金網站。</b>