Eugene's Blog
0%

[DotnetCore]Refit:API介紹及應用

發表於 分類於 ， 閱讀次數：
3.4k 6 分鐘

前情提要

筆者這篇就繼續來介紹Refit的各種用法，依照篇幅會再拆成數篇，筆者會參考官方Document的脈絡，加上筆者已經在工作場合上用到的一些技巧，詳細介紹其用法，好的套件會帶你飛，真的不是說說而已，Refit的API，完全足夠克服於工作場合中遇到的各種挑戰，讓你輕鬆完成Http Request的請求。

內容

API Atttribute

這一節就是設定Http Methods的套用，就很直覺地將Method當作Keyword套上，滿像dotnet mvc的Route設置，只是沒有Http這個Keyword，Refit這邊就只保留Get, Post，其餘跟Route設定十分相像。還有一些AliasAs，Route參數可以為Object的某一個屬性值等進階設定可以使用，筆者這邊目前沒用到就不做特別介紹，有需求的朋友可以到官方Docuement參考其用法

1
2
3
// 與Route設定一樣，Route參數則透過大括弧包住對應參數名稱
[Post("/postUrl/{apiToken}")]
Task<ApiResponse<ResponseModel>> Query(RequestModel requestModel, [Header("X-SecretKey")] string secretKey, string apiToken);

Request內容設定

如筆者在這系列文中的第一篇所說，筆者負責的系統特性，與第三方廠商串接，各種需求都會出現，Refit這邊都有對應的解法，能叫人不愛嗎?以筆者工作場合中用到的為主作介紹，目前碰到的將Request內容傳送的型式為

  • 塞於Body，最常見的一種
  • FormPost型式，比較老牌的廠商愛用
  • QueryParameters，偶爾有遇到查詢參數放置於QueryParameters中

Body

這就是最簡單也最常見的一種，以Refit來說，這也是預設的一種，因此沒有套上此Attribute，預設也會透過Body型式傳送，筆者這邊就為容易分辨Body參數或其他Route參數，都會套上[Body]，示意如下

1
2
[Post("/postUrl")]
Task<ApiResponse<ResponseModel>> QueryProcess([Body]RequestModel requestModel);

FormPost

若串接的Rest API為FormPost的型式塞入Request則，需再爾外設定，設定方式也是簡單，將[Body]上多加上設定，調整為[Body(BodySerializationMethod.UrlEncoded)]，示意如下

1
2
[Post("/postUrl")]
Task<ApiResponse<ResponseModel>> QueryProcess([Body(BodySerializationMethod.UrlEncoded)]RequestModel requestModel);

QueryParameters

若以QueryParameters的型式傳出Request內容則，需透過[Query]這個Attribute讓Refit知道，筆者這系列的第一篇即是Query的型式送出Request內容，如下

1
2
[Get("/WEBAPI/LandPrice/Lastest")]
Task<List<LandData>> GetLandPriceAsync([Query] LandPriceParameters parameters);

Header設定

如筆者在這系列文中第一篇提到的痛點，Header的值設定，在Refit世界中如此的簡單啊，靜態，動態皆可設定，示意如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// 靜態:該第三方API串接時固定帶入某一個值
[Headers("User-Agent: Awesome Octocat App")]
public interface IGitHubApi
{
    [Get("/users/{user}")]
    Task<User> GetUser(string user);

    [Post("/users/new")]
    Task CreateUser([Body] User user);
}

// 動態:呼叫時決定放入的token
[Get("/getUrl")]
Task<TemplatesModel> GetTemplateAsync([Header("Authorization")] string token);

ContentType設定

筆者這邊接觸到的就跟大家一般常見到的一樣，json及xml

application/json

這個是一般常見也是Refit的預設模式，若串接對象API為application/json則不用增加任何爾外設定。

application/xml

若串接對象API需要透過Xml格式則，需要再爾外安裝Refit的延伸套件: Refit.Xml

1
dotnet add package Refit.Xml

安裝完成後，Refit服務註冊時需爾外設定其RefitSettings

1
2
3
4
services.AddRefitClient<IxxApiRepository>(new RefitSettings()
{
    ContentSerializer = new XmlContentSerializer()
});

最後切記，若有需求是C# class中的PropertyName與傳出去的xml封包中的名稱不一樣則，套用Xml相關Attribute設定，而非System.Text.Json相關Attribute設定

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[XmlRoot("XML")]
public class QueryRequestModel
{
    [XmlElement("VER_NO")]
    public string VersionNumber { get; set; } = "1.0";

    [XmlElement("PROCESSCODE")]
    public string ProcessCode { get; set; };

    [XmlElement("SRC")]
    public string Source { get; set; }

    [XmlElement("ITEMS")]
    public QueryRequestItems Items { get; set; }
}

實際應用場景

筆者這邊使用方式為，HttpRequest當作是一種Repository來源，因此會把interface定義於Repository層，當然每一個獨立的Repository搭配一個ApiService，用意是甚麼呢，畢竟Refit幫你完成的是基礎又瑣碎的HttpRequest請求，但收到Response之後的解析，則算是商業邏輯層處理，HttpRequest相關的商業邏輯處理就寫在ApiService中，因此筆者針對一家第三方廠商的API串接，固定會有

  • IxxApiRepository
  • IxxApiService

最後附送一張實際開發中的專案，已經有數個第三方廠商的API串接，依照不同第三方廠商，就會建立一個獨立的IxxApiRepository

結論

這篇主要是以較常用到的API介紹為主，其中包含Http Methods及Route設定，Request的不同型式呈現，Content Type不同設定，了解到這邊，足以應付各種大大小小的Rest API串接了，下篇將介紹Refit的Respone回傳值相關說明。

參考

相關文章