自動(dòng)類型安全的REST.NET標(biāo)準(zhǔn)庫(kù)refit

更新時(shí)間：2022年04月08日 09:29:22 作者：暗斷腸

這篇文章介紹了自動(dòng)類型安全的REST.NET標(biāo)準(zhǔn)庫(kù)refit，文中通過示例代碼介紹的非常詳細(xì)。對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值，需要的朋友可以參考下

1.簡(jiǎn)介

Refit是一個(gè)受到Square的Retrofit庫(kù)（Java）啟發(fā)的自動(dòng)類型安全REST庫(kù)。通過HttpClient網(wǎng)絡(luò)請(qǐng)求(POST，GET,PUT，DELETE等封裝)把REST API返回的數(shù)據(jù)轉(zhuǎn)化為POCO(Plain Ordinary C# Object,簡(jiǎn)單C#對(duì)象) to JSON。我們的應(yīng)用程序通過Refit請(qǐng)求網(wǎng)絡(luò)，實(shí)際上是使用Refit接口層封裝請(qǐng)求參數(shù)、Header、Url等信息，之后由HttpClient完成后續(xù)的請(qǐng)求操作，在服務(wù)端返回?cái)?shù)據(jù)之后，HttpClient將原始的結(jié)果交給Refit，后者根據(jù)用戶的需求對(duì)結(jié)果進(jìn)行解析的過程。安裝組件命令行：

Install-Package refit

代碼例子：

[Headers("User-Agent: Refit Integration Tests")]//這里因?yàn)槟繕?biāo)源是GitHubApi，所以一定要加入這個(gè)靜態(tài)請(qǐng)求標(biāo)頭信息，讓其這是一個(gè)測(cè)試請(qǐng)求，不然會(huì)返回?cái)?shù)據(jù)異常。
public interface IGitHubApi
{
    [Get("/users/{user}")]
    Task<User> GetUser(string user);
}
public class GitHubApi
{
    public async Task<User> GetUser()
    {
        var gitHubApi = RestService.For<IGitHubApi>("https://api.github.com");
        var octocat = await gitHubApi.GetUser("octocat");
        return octocat;
    }
}
public class User
{
    public string login { get; set; }
    public int? id { get; set; }
    public string url { get; set; }
}
[HttpGet]
public async Task<ActionResult<IEnumerable<string>>> Get()
{
    var result = await new GitHubApi().GetUser();
    return new string[] { result.id.Value.ToString(), result.login };
}

注：接口中Headers、Get這些屬性叫做Refit的特性。
定義上面的一個(gè)IGitHubApi的REST API接口，該接口定義了一個(gè)函數(shù)GetUser，該函數(shù)會(huì)通過HTTP GET請(qǐng)求去訪問服務(wù)器的/users/{user}路徑把返回的結(jié)果封裝為User POCO對(duì)象并返回。其中URL路徑中的{user}的值為GetUser函數(shù)中的參數(shù)user的取值，這里賦值為octocat。然后通過RestService類來生成一個(gè)IGitHubApi接口的實(shí)現(xiàn)并供HttpClient調(diào)用。

2.API屬性

每個(gè)方法必須具有提供請(qǐng)求URL和HTTP屬性。HTTP屬性有六個(gè)內(nèi)置注釋：Get, Post, Put, Delete, Patch and Head，例：

[Get("/users/list")]

您還可以在請(qǐng)求URL中指定查詢參數(shù)：

[Get("/users/list?sort=desc")]

還可以使用相對(duì)URL上的替換塊和參數(shù)來動(dòng)態(tài)請(qǐng)求資源。替換塊是由{and，即&}包圍的字母數(shù)字字符串。如果參數(shù)名稱與URL路徑中的名稱不匹配，請(qǐng)使用AliasAs屬性，例：

[Get("/group/{id}/users")]
Task<List<User>> GroupList([AliasAs("id")] int groupId);

請(qǐng)求URL還可以將替換塊綁定到自定義對(duì)象，例：

[Get("/group/{request.groupId}/users/{request.userId}")]
Task<List<User>> GroupList(UserGroupRequest request);
class UserGroupRequest{
    int groupId { get;set; }
    int userId { get;set; }
}

未指定為URL替換的參數(shù)將自動(dòng)用作查詢參數(shù)。這與Retrofit不同，在Retrofit中，必須明確指定所有參數(shù)，例：

[Get("/group/{id}/users")]
Task<List<User>> GroupList([AliasAs("id")] int groupId, [AliasAs("sort")] string sortOrder);
GroupList(4, "desc");

輸出結(jié)果："/group/4/users?sort=desc"

3.動(dòng)態(tài)查詢字符串參數(shù)(Dynamic Querystring Parameters)

方法還可以傳遞自定義對(duì)象，把對(duì)象屬性追加到查詢字符串參數(shù)當(dāng)中，例如：

public class MyQueryParams
{
    [AliasAs("order")]
    public string SortOrder { get; set; }
    public int Limit { get; set; }
}
[Get("/group/{id}/users")]
Task<List<User>> GroupList([AliasAs("id")] int groupId, MyQueryParams params);
[Get("/group/{id}/users")]
Task<List<User>> GroupListWithAttribute([AliasAs("id")] int groupId, [Query(".","search")]MyQueryParams params);
params.SortOrder = "desc";
params.Limit = 10;
GroupList(4, params)

輸出結(jié)果："/group/4/users?order=desc&Limit=10"

GroupListWithAttribute(4, params)

輸出結(jié)果："/group/4/users?search.order=desc&search.Limit=10"
您還可以使用[Query]指定querystring參數(shù)，并將其在非GET請(qǐng)求中扁平化，類似于：

[Post("/statuses/update.json")]
Task<Tweet> PostTweet([Query]TweetParams params);

4.集合作為查詢字符串參數(shù)(Collections as Querystring Parameters)

方法除了支持傳遞自定義對(duì)象查詢，還支持集合查詢的，例：

[Get("/users/list")]
Task Search([Query(CollectionFormat.Multi)]int[] ages);
Search(new [] {10, 20, 30})

輸出結(jié)果："/users/list?ages=10&ages=20&ages=30"

[Get("/users/list")]
Task Search([Query(CollectionFormat.Csv)]int[] ages);
Search(new [] {10, 20, 30})

輸出結(jié)果："/users/list?ages=10%2C20%2C30"

5.轉(zhuǎn)義符查詢字符串參數(shù)(Unescape Querystring Parameters)

使用QueryUriFormat屬性指定查詢參數(shù)是否應(yīng)轉(zhuǎn)義網(wǎng)址，例：

[Get("/query")]
[QueryUriFormat(UriFormat.Unescaped)]
Task Query(string q);
Query("Select+Id,Name+From+Account")

輸出結(jié)果："/query?q=Select+Id,Name+From+Account"

6.Body內(nèi)容

通過使用Body屬性，可以把自定義對(duì)象參數(shù)追加到HTTP請(qǐng)求Body當(dāng)中。

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

根據(jù)參數(shù)的類型，提供Body數(shù)據(jù)有四種可能性：

如果類型為Stream，則內(nèi)容將通過StreamContent流形式傳輸。
如果類型為string，則字符串將直接用作內(nèi)容，除非[Body(BodySerializationMethod.Json)]設(shè)置了字符串，否則將其作為StringContent。
如果參數(shù)具有屬性[Body(BodySerializationMethod.UrlEncoded)]，則內(nèi)容將被URL編碼。
對(duì)于所有其他類型，將使用RefitSettings中指定的內(nèi)容序列化程序?qū)?duì)象序列化（默認(rèn)為JSON）。
緩沖和Content-Length頭

默認(rèn)情況下，Refit重新調(diào)整流式傳輸正文內(nèi)容而不緩沖它。例如，這意味著您可以從磁盤流式傳輸文件，而不會(huì)產(chǎn)生將整個(gè)文件加載到內(nèi)存中的開銷。這樣做的缺點(diǎn)是沒有在請(qǐng)求上設(shè)置內(nèi)容長(zhǎng)度頭（Content-Length）。如果您的API需要您隨請(qǐng)求發(fā)送一個(gè)內(nèi)容長(zhǎng)度頭，您可以通過將[Body]屬性的緩沖參數(shù)設(shè)置為true來禁用此流行為：

Task CreateUser([Body(buffered: true)] User user);

6.1.JSON內(nèi)容

使用Json.NET對(duì)JSON請(qǐng)求和響應(yīng)進(jìn)行序列化/反序列化。默認(rèn)情況下，Refit將使用可以通過設(shè)置Newtonsoft.Json.JsonConvert.DefaultSettings進(jìn)行配置的序列化器設(shè)置：

JsonConvert.DefaultSettings =
    () => new JsonSerializerSettings() {
        ContractResolver = new CamelCasePropertyNamesContractResolver(),
        Converters = {new StringEnumConverter()}
    };
//Serialized as: {"day":"Saturday"}
await PostSomeStuff(new { Day = DayOfWeek.Saturday });

由于默認(rèn)靜態(tài)配置是全局設(shè)置，它們將影響您的整個(gè)應(yīng)用程序。有時(shí)候我們只想要對(duì)某些特定API進(jìn)行設(shè)置，您可以選擇使用RefitSettings屬性，以允許您指定所需的序列化程序進(jìn)行設(shè)置，這使您可以為單獨(dú)的API設(shè)置不同的序列化程序設(shè)置：

var gitHubApi = RestService.For<IGitHubApi>("https://api.github.com",
    new RefitSettings {
        ContentSerializer = new JsonContentSerializer(
            new JsonSerializerSettings {
                ContractResolver = new SnakeCasePropertyNamesContractResolver()
        }
    )});
var otherApi = RestService.For<IOtherApi>("https://api.example.com",
    new RefitSettings {
        ContentSerializer = new JsonContentSerializer(
            new JsonSerializerSettings {
                ContractResolver = new CamelCasePropertyNamesContractResolver()
        }
    )});

還可以使用Json.NET的JsonProperty屬性來自定義屬性序列化/反序列化：

public class Foo
{
    //像[AliasAs(“ b”)]一樣會(huì)在表單中發(fā)布
    [JsonProperty(PropertyName="b")]
    public string Bar { get; set; }
}

6.2XML內(nèi)容

XML請(qǐng)求和響應(yīng)使用System.XML.Serialization.XmlSerializer進(jìn)行序列化/反序列化。默認(rèn)情況下，Refit只會(huì)使用JSON將內(nèi)容序列化，若要使用XML內(nèi)容，請(qǐng)將ContentSerializer配置為使用XmlContentSerializer：

var gitHubApi = RestService.For<IXmlApi>("https://www.w3.org/XML",
    new RefitSettings {
        ContentSerializer = new XmlContentSerializer()
});

屬性序列化/反序列化可以使用System.Xml.serialization命名空間中的屬性進(jìn)行自定義：

public class Foo
{
   [XmlElement(Namespace = "https://www.w3.org/XML")]
   public string Bar { get; set; }
}

System.Xml.Serialization.XmlSerializer提供了許多序列化選項(xiàng)，可以通過向XmlContentSerializer構(gòu)造函數(shù)提供XmlContentSerializer設(shè)置來設(shè)置這些選項(xiàng)：

var gitHubApi = RestService.For<IXmlApi>("https://www.w3.org/XML",
    new RefitSettings {
        ContentSerializer = new XmlContentSerializer(
            new XmlContentSerializerSettings
            {
                XmlReaderWriterSettings = new XmlReaderWriterSettings()
                {
                    ReaderSettings = new XmlReaderSettings
                    {
                        IgnoreWhitespace = true
                    }
                }
            }
        )
});

6.3.表單發(fā)布(Form posts)

對(duì)于以表單形式發(fā)布（即序列化為application/x-www-form-urlencoded）的API，請(qǐng)使用初始化Body屬性BodySerializationMethod.UrlEncoded屬性，參數(shù)可以是IDictionary字典，例：

public interface IMeasurementProtocolApi
{
    [Post("/collect")]
    Task Collect([Body(BodySerializationMethod.UrlEncoded)] Dictionary<string, object> data);
}
var data = new Dictionary<string, object> {
    {"v", 1},
    {"tid", "UA-1234-5"},
    {"cid", new Guid("d1e9ea6b-2e8b-4699-93e0-0bcbd26c206c")},
    {"t", "event"},
};
// Serialized as: v=1&tid=UA-1234-5&cid=d1e9ea6b-2e8b-4699-93e0-0bcbd26c206c&t=event
await api.Collect(data);

如果我們傳遞對(duì)象跟請(qǐng)求表單中字段名稱不一致時(shí)，可在對(duì)象屬性名稱上加入[AliasAs("你定義字段名稱")] 屬性，那么加入屬性的對(duì)象字段都將會(huì)被序列化為請(qǐng)求中的表單字段：

public interface IMeasurementProtocolApi
{
    [Post("/collect")]
    Task Collect([Body(BodySerializationMethod.UrlEncoded)] Measurement measurement);
}
public class Measurement
{
    // Properties can be read-only and [AliasAs] isn't required
    public int v { get { return 1; } }
    [AliasAs("tid")]
    public string WebPropertyId { get; set; }
    [AliasAs("cid")]
    public Guid ClientId { get; set; }
    [AliasAs("t")]
    public string Type { get; set; }
    public object IgnoreMe { private get; set; }
}
var measurement = new Measurement {
    WebPropertyId = "UA-1234-5",
    ClientId = new Guid("d1e9ea6b-2e8b-4699-93e0-0bcbd26c206c"),
    Type = "event"
};
// Serialized as: v=1&tid=UA-1234-5&cid=d1e9ea6b-2e8b-4699-93e0-0bcbd26c206c&t=event
await api.Collect(measurement);

7.設(shè)置請(qǐng)求頭

7.1靜態(tài)頭(Static headers)

您可以為將headers屬性應(yīng)用于方法的請(qǐng)求設(shè)置一個(gè)或多個(gè)靜態(tài)請(qǐng)求頭：

[Headers("User-Agent: Awesome Octocat App")]
[Get("/users/{user}")]
Task<User> GetUser(string user);

通過將headers屬性應(yīng)用于接口，還可以將靜態(tài)頭添加到API中的每個(gè)請(qǐng)求：

[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);
}

7.2動(dòng)態(tài)頭(Dynamic headers)

如果需要在運(yùn)行時(shí)設(shè)置頭的內(nèi)容，則可以通過將頭屬性應(yīng)用于參數(shù)來向請(qǐng)求添加具有動(dòng)態(tài)值的頭：

[Get("/users/{user}")]
Task<User> GetUser(string user, [Header("Authorization")] string authorization);
// Will add the header "Authorization: token OAUTH-TOKEN" to the request
var user = await GetUser("octocat", "token OAUTH-TOKEN");

7.3授權(quán)(動(dòng)態(tài)頭redux)

使用頭的最常見原因是為了授權(quán)。而現(xiàn)在大多數(shù)API使用一些oAuth風(fēng)格的訪問令牌，這些訪問令牌會(huì)過期，刷新壽命更長(zhǎng)的令牌。封裝這些類型的令牌使用的一種方法是，可以插入自定義的HttpClientHandler。這樣做有兩個(gè)類：一個(gè)是AuthenticatedHttpClientHandler，它接受一個(gè)Func<Task<string>>參數(shù)，在這個(gè)參數(shù)中可以生成簽名，而不必知道請(qǐng)求。另一個(gè)是authenticatedparameteredhttpclienthandler，它接受一個(gè)Func<HttpRequestMessage，Task<string>>參數(shù)，其中簽名需要有關(guān)請(qǐng)求的信息（參見前面關(guān)于Twitter的API的注釋），
例如：

class AuthenticatedHttpClientHandler : HttpClientHandler
{
    private readonly Func<Task<string>> getToken;
    public AuthenticatedHttpClientHandler(Func<Task<string>> getToken)
    {
        if (getToken == null) throw new ArgumentNullException(nameof(getToken));
        this.getToken = getToken;
    }
    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        // See if the request has an authorize header
        var auth = request.Headers.Authorization;
        if (auth != null)
        {
            var token = await getToken().ConfigureAwait(false);
            request.Headers.Authorization = new AuthenticationHeaderValue(auth.Scheme, token);
        }
        return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }
}

或者：

class AuthenticatedParameterizedHttpClientHandler : DelegatingHandler
    {
        readonly Func<HttpRequestMessage, Task<string>> getToken;
        public AuthenticatedParameterizedHttpClientHandler(Func<HttpRequestMessage, Task<string>> getToken, HttpMessageHandler innerHandler = null)
            : base(innerHandler ?? new HttpClientHandler())
        {
            this.getToken = getToken ?? throw new ArgumentNullException(nameof(getToken));
        }

        protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
            // See if the request has an authorize header
            var auth = request.Headers.Authorization;
            if (auth != null)
            {
                var token = await getToken(request).ConfigureAwait(false);
                request.Headers.Authorization = new AuthenticationHeaderValue(auth.Scheme, token);
            }
            return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
        }
    }

雖然HttpClient包含一個(gè)幾乎相同的方法簽名，但使用方式不同。重新安裝未調(diào)用HttpClient.SendAsync。必須改為修改HttpClientHandler。此類的用法與此類似（示例使用ADAL庫(kù)來管理自動(dòng)令牌刷新，但主體用于Xamarin.Auth或任何其他庫(kù)：

class LoginViewModel
{
    AuthenticationContext context = new AuthenticationContext(...);
    private async Task<string> GetToken()
    {
        // The AcquireTokenAsync call will prompt with a UI if necessary
        // Or otherwise silently use a refresh token to return
        // a valid access token    
        var token = await context.AcquireTokenAsync("http://my.service.uri/app", "clientId", new Uri("callback://complete"));
        return token;
    }
    public async Task LoginAndCallApi()
    {
        var api = RestService.For<IMyRestService>(new HttpClient(new AuthenticatedHttpClientHandler(GetToken)) { BaseAddress = new Uri("https://the.end.point/") });
        var location = await api.GetLocationOfRebelBase();
    }
}
interface IMyRestService
{
    [Get("/getPublicInfo")]
    Task<Foobar> SomePublicMethod();
    [Get("/secretStuff")]
    [Headers("Authorization: Bearer")]
    Task<Location> GetLocationOfRebelBase();
}

在上面的示例中，每當(dāng)調(diào)用需要身份驗(yàn)證的方法時(shí)，AuthenticatedHttpClientHandler將嘗試獲取新的訪問令牌。由應(yīng)用程序提供，檢查現(xiàn)有訪問令牌的過期時(shí)間，并在需要時(shí)獲取新的訪問令牌。

以上就是本文的全部?jī)?nèi)容，希望對(duì)大家的學(xué)習(xí)有所幫助，也希望大家多多支持腳本之家。

您可能感興趣的文章: