原文鏈接 ： https://futurestud.io/tutorials/retrofit-2-basics-of-api-description

在上一篇教程 開始使用Rirtofit 中，我們已經(jīng)對一個 Git 端點實現(xiàn)了第一個請求。希望你正對使用 Retrofit 的更多功能感到躍躍欲試，在本篇教程中，你將學(xué)習(xí)到關(guān)于 Retrofit 如何描述 API 端點的更多細(xì)節(jié)。

如何描述API端點

正如我們上一個教程所學(xué)到的，我們在一個接口類中描述所有的Retrofit請求。我們的第一個例子向我們展示了Retrofit的多個功能。

public interface GitHubClient {  
    @GET("/users/{user}/repos")
    Call<List<GitHubRepo>> reposForUser(
        @Path("user") String user
    );
}

現(xiàn)在是時候讓我們進(jìn)一步了解這些功能的細(xì)節(jié)。

HTTP方法

我們已經(jīng)知道 Retrofit 通過在 Java 接口方法上使用注釋來描述各個 API 端點，最后才描述如何去處理這些請求。我們需要做的第一件事就是定義 HTTP 請求方法，如 GET, POST,PUT, DELETE 等等。Retrofit 為每個主要的標(biāo)準(zhǔn)請求方法提供了注釋，我們只需簡單的為每個HTTP方法使用對應(yīng)的注釋： @GET,@POST, @PUT, @DELETE, @PATCH 或者 @HEAD。

我們總是需要為程序使用的API指定請求方法。如果你對HTTP請求方法還不太了解，請參閱WIKI相關(guān)頁面。 一般情況下，你應(yīng)該可以從API文檔找到恰當(dāng)?shù)恼埱蠓椒ā?/p>

下面是使用了 @GET、@PUT 、 @DELETE 的幾個簡單例子 ：

public interface FutureStudioClient {  
    @GET("/user/info")
    Call<UserInfo> getUserInfo();

    @PUT("/user/info")
    Call<UserInfo> updateUserInfo(
        @Body UserInfo userInfo
    );

    @DELETE("/user")
    Call<Void> deleteUser();
}

HTTP資源地址

另外，我們需要把端點的相對 URL 作為 String 參數(shù)添加到注釋中，例如：@GET("/user/info")。在大多數(shù)情況下，我們只需傳入相對 URL，而不傳入完整 URL（如 http://futurestud.io/api/user/info ），這么做的好處是，Retrofit 只需要請求一次基本 URL（ http://futurestud.io ）。如果你需要改變 API 的基本 URl，只需要在一個地方進(jìn)行修改。此外，這使得一些先進(jìn)的東西，比如動態(tài)基礎(chǔ) URL，使用起來更加方便。不過你依然可以指定一個完整 URL。如果你希望學(xué)習(xí)更多關(guān)于 URl 的處理以及 基礎(chǔ) URL 與 相對 URL 的組合方式，請隨時閱讀我們的 URL 的處理和分析 指南。
再次給出幾個簡單例子：

public interface FutureStudioClient {  
    @GET("/user/info")
    Call<UserInfo> getUserInfo();

    @PUT("/user/info")
    Call<UserInfo> updateUserInfo(
        @Body UserInfo userInfo
    );

    @DELETE("/user")
    Call<Void> deleteUser();

    // example for passing a full URL
    @GET("https://futurestud.io/tutorials/rss/")
    Call<FutureStudioRssFeed> getRssFeed();
}

方法名與返回值類型

現(xiàn)在你已經(jīng)知道了如何使用HTTP請求方法注釋了，然而我們還沒有談到實際的 Java 方法聲明，Call<UserInfo> getUserInfo();，這包含了三個部分：

• 1 方法名
• 2 返回值類型
• 3 方法參數(shù)

我們從容易的一個開始：方法名。我們可以自由的定義方法名，Retrofit 不在意你如何定義方法名，且對功能沒有任何影響。不過，我們還是應(yīng)該定義一個有助于自己和其他開發(fā)者了解這是什么API請求的名稱。

另一方面，方法的返回值相當(dāng)關(guān)鍵。必須定義你預(yù)期從服務(wù)器獲得的數(shù)據(jù)類型。例如，當(dāng)你正在請求某些用戶信息時，你可能會像這樣指定： Call<UserInfo>。UserInfo 類包含了用于保存用戶數(shù)據(jù)的變量。Retrofit將會自動進(jìn)行映射，不需要進(jìn)行任何手動解析。如果您想要獲取原始響應(yīng)，可以使用 ResponseBody 替換 UserInfo 這樣的自定義類。如果完全不關(guān)心服務(wù)的響應(yīng)數(shù)據(jù)，你可以使用 Void。在這種情況下，必須將它包裝成一個 Retrofit 的 Call<> 類。

最后，你可以給方法傳遞參數(shù)，這很大程度取決于 API 端點的需要。方法參數(shù)存在非常多的選擇，所以這里只給出其中幾個例子：
@Body : 發(fā)送Java對象作為請求體
@Url : 使用動態(tài) URL
@Field : 發(fā)送表單數(shù)據(jù)

再次給出幾個用例：

public interface FutureStudioClient {  
    @GET("/user/info")
    Call<UserInfo> getUserInfo();

    @PUT("/user/info")
    Call<Void> updateUserInfo(
        @Body UserInfo userInfo
    );

    @GET
    Call<ResponseBody> getUserProfilePhoto(
        @Url String profilePhotoUrl
    );
}

路徑參數(shù)

REST標(biāo)準(zhǔn)的API是建立于動態(tài)URL上的，你可以通過替換URL的某部分來獲取資源，例如獲取我們頁面的第三篇教程的URl可能為 http://futurestud.io/api/tutorials/3，末尾的 3 指定了你想要訪問哪一篇教程。Retrofit提供了一種可以方便地替換這些路徑參數(shù)的方式。在入門教程中我們已經(jīng)看到過一個簡單的例子：

public interface GitHubClient {  
    @GET("/users/{user}/repos")
    Call<List<GitHubRepo>> reposForUser(
        @Path("user") String user
    );
}

在這里{user}告訴 Retrofit 這個值是動態(tài)的，且該值將在請求開始時配置。如果你使用的URl包含了一個路徑參數(shù)，那么你必須在方法中添加一個 @Path 參數(shù)，@Path的值會與URL中的占位符匹配（在上面的例子中為 @Path("user") ）。如果需要，你可以使用多個占位符，只要你能夠確保有合適的可供匹配的參數(shù)即可。你甚至可以使用可選路徑參數(shù)。

查詢參數(shù)

動態(tài)URl的另一大部分是查詢參數(shù)。如果你已經(jīng)使用過過濾器，你會在我們的頁面上看到 https://futurestud.io/tutorials?filter=video。其中 ?filter=video 就是進(jìn)一步描述所需查找資源的查詢參數(shù)。與路徑參數(shù)不同的是，你不需要將他們添加到URL注釋中。你可以非常方便地在方法中添加一個帶有 @Query() 和查詢參數(shù)名的參數(shù)，然后描述參數(shù)的類型就可以了。Retrofit會自動把它附加到請求中。如果將 null 作為值傳入查詢參數(shù)中，Retrofit會忽略它。你還可以添加多個查詢參數(shù)。

public interface FutureStudioClient {  
    @GET("/tutorials")
    Call<List<Tutorial>> getTutorials(
        @Query("page") Integer page
    );

    @GET("/tutorials")
    Call<List<Tutorial>> getTutorials(
            @Query("page") Integer page,
            @Query("order") String order,
            @Query("author") String author,
            @Query("published_at") Date date
    );
}    

在上面的例子中，你也可以刪除第一個 getTutorials() 方法，通過在第二個方法的后三個參數(shù)傳入 null 值的方式來實現(xiàn)和第一個方法一樣的效果。

接下來

現(xiàn)在你已經(jīng)學(xué)會了如何為接口添加新的API端點，調(diào)整URL地址，HTTP方法，返回值類型，路徑和查詢參數(shù)等，但是這僅僅是入門而已。
Retrofit 提供了非常多的選項來進(jìn)一步完善網(wǎng)絡(luò)數(shù)據(jù)請求。例如，我們還沒有聊到 Header 呢。要學(xué)習(xí)的還有很多，所以讓我們繼續(xù)更多的教程吧！
如果您有什么反饋或者問題，請在 Twitter 里 @futurestud_io。

Make it rock & enjoy coding!