自動型別安全的.NET標準REST庫refit

張善友發表於2017-12-16
型別REST

在SCOTT HANSELMAN 部落格上看到一個好東西《Exploring refit, an automatic type-safe REST library for .NET Standard》，他推薦了一個.NET標準1.4 的自動型別安全的REST庫refit。 refit 類似於Java的Retrofit，是一套RESTful架構的.NET客戶端實現，基於特性，提供把REST API返回的資料轉化為(Plain Ordinary C# Object,簡單C#物件)，POCO to JSON，網路請求(POST，GET,PUT，DELETE等)封裝，內部封裝使用HttpClient,前者專注於介面的封裝，後者專注於網路請求的高效，二者分工協作。我們的應用程式通過 refit請求網路，實際上是使用 refit介面層封裝請求引數、Header、Url 等資訊，之後由 HttpClient完成後續的請求操作，在服務端返回資料之後，HttpClient將原始的結果交給 refit，後者根據使用者的需求對結果進行解析的過程。

例如：

public interface IGitHubApi
{
    [Get("/users/{user}")]
    Task<User> GetUser(string user);
}

定義上面的一個REST API介面。 該介面定義了一個函式 GetUser,該函式會通過HTTP GET請求去訪問伺服器的/users/{user}路徑並把返回的結果封裝為User POCO 物件返回。

其中URL路徑中的{user}的值為GetUser函式中的引數 user的取值。

然後通過 RestService 類來生成一個 IGitHubApi 介面的實現，使用HttpClient 呼叫；

var gitHubApi = RestService.For<IGitHubApi>(https://api.github.com);
var octocat = await gitHubApi.GetUser("octocat");

從上面的示例可以看出， refit使用特性來宣告HTTP請求

  • 支援 URL 引數替換和查詢引數
  • 返回結果轉換為C#物件(返回結果可以為JSON)
  • 支援 Multipart請求和檔案上傳

具體使用文件

函式和函式引數上的特性宣告瞭請求方式

1、請求方式

每個函式都必須帶有 HTTP特性來表明請求方式和請求的URL路徑。類庫中有5個HTTP註解:GET, POST, PUT,DELETE和HEAD。註解中的引數為請求的相對URL路徑。

[Get("/users/list")]

在URL路徑中也可以指定URL引數:

[Get("/users/list?sort=desc")]
2、URL處理

請求的URL可以根據函式引數動態更新。一個可替換的區塊為用 { 和 } 包圍的字串，而函式引數必需用 @AliasAs特性標明，並且特性的引數為 同樣的字串

[Get("/group/{id}/users")]//注意 字串id
Task<List<User>> GroupList([AliasAs("id")] int groupId); //注意 AliasAs特性的引數要和前面的字串一樣 id
還支援查詢引數
[Get("/group/{id}/users")]
Task<List<User>> GroupList([AliasAs("id")] int groupId, [AliasAs("sort")] string sortOrder);

GroupList(4, "desc");
>>> "/group/4/users?sort=desc"
3、請求體（Request Body）

通過[Body]特性可以宣告一個物件作為請求體傳送到伺服器。

[Post("/users/new")]
Task CreateUser([Body] User user);
物件將被RestService 使用對應的轉換器轉換為字串或者位元組流提交到伺服器。
4、FORM ENCODED AND MULTIPART 表單和Multipart

函式也可以註解為傳送表單資料和multipart 資料

5、伺服器結果轉換為C# 物件

使用RestService 的轉換器把HTTP請求結果（預設為JSON）轉換為C#物件，C#物件通過函式返回值指定

6、新增請求頭

我們可以通過[Headers]來新增請求頭,支援動態的請求頭。

refit是非常強大的，本文通過豐富的示例和對原始碼的挖掘，向大家展示了 refit自身強大的功能以及擴充套件性

相關文章