自動(dòng)類(lèi)型安全的REST.NET標(biāo)準(zhǔn)庫(kù)refit
1.簡(jiǎn)介
Refit是一個(gè)受到Square的Retrofit庫(kù)(Java)啟發(fā)的自動(dòng)類(lèi)型安全REST庫(kù)。通過(guò)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)用程序通過(guò)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ù)用戶(hù)的需求對(duì)結(jié)果進(jìn)行解析的過(guò)程。安裝組件命令行:
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ì)通過(guò)HTTP GET請(qǐng)求去訪問(wèn)服務(wù)器的/users/{user}路徑把返回的結(jié)果封裝為User POCO對(duì)象并返回。其中URL路徑中的{user}的值為GetUser函數(shù)中的參數(shù)user的取值,這里賦值為octocat。然后通過(guò)RestService類(lèi)來(lái)生成一個(gè)IGitHubApi接口的實(shí)現(xiàn)并供HttpClient調(diào)用。

2.API屬性
每個(gè)方法必須具有提供請(qǐng)求URL和HTTP屬性。HTTP屬性有六個(gè)內(nèi)置注釋?zhuān)篏et, Post, Put, Delete, Patch and Head,例:
[Get("/users/list")]您還可以在請(qǐng)求URL中指定查詢(xún)參數(shù):
[Get("/users/list?sort=desc")]還可以使用相對(duì)URL上的替換塊和參數(shù)來(lái)動(dòng)態(tài)請(qǐng)求資源。替換塊是由{and,即&}包圍的字母數(shù)字字符串。如果參數(shù)名稱(chēng)與URL路徑中的名稱(chēng)不匹配,請(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)用作查詢(xún)參數(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)查詢(xún)字符串參數(shù)(Dynamic Querystring Parameters)
方法還可以傳遞自定義對(duì)象,把對(duì)象屬性追加到查詢(xún)字符串參數(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)求中扁平化,類(lèi)似于:
[Post("/statuses/update.json")]
Task<Tweet> PostTweet([Query]TweetParams params);4.集合作為查詢(xún)字符串參數(shù)(Collections as Querystring Parameters)
方法除了支持傳遞自定義對(duì)象查詢(xún),還支持集合查詢(xún)的,例:
[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)義符查詢(xún)字符串參數(shù)(Unescape Querystring Parameters)
使用QueryUriFormat屬性指定查詢(xún)參數(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)容
通過(guò)使用Body屬性,可以把自定義對(duì)象參數(shù)追加到HTTP請(qǐng)求Body當(dāng)中。
[Post("/users/new")]
Task CreateUser([Body] User user)根據(jù)參數(shù)的類(lèi)型,提供Body數(shù)據(jù)有四種可能性:
- 如果類(lèi)型為Stream,則內(nèi)容將通過(guò)StreamContent流形式傳輸。
- 如果類(lèi)型為string,則字符串將直接用作內(nèi)容,除非[Body(BodySerializationMethod.Json)]設(shè)置了字符串,否則將其作為StringContent。
- 如果參數(shù)具有屬性[Body(BodySerializationMethod.UrlEncoded)],則內(nèi)容將被URL編碼。
- 對(duì)于所有其他類(lèi)型,將使用RefitSettings中指定的內(nèi)容序列化程序?qū)?duì)象序列化(默認(rèn)為JSON)。
- 緩沖和Content-Length頭
默認(rèn)情況下,Refit重新調(diào)整流式傳輸正文內(nèi)容而不緩沖它。例如,這意味著您可以從磁盤(pán)流式傳輸文件,而不會(huì)產(chǎn)生將整個(gè)文件加載到內(nèi)存中的開(kāi)銷(xiāo)。這樣做的缺點(diǎn)是沒(méi)有在請(qǐng)求上設(shè)置內(nèi)容長(zhǎng)度頭(Content-Length)。如果您的API需要您隨請(qǐng)求發(fā)送一個(gè)內(nèi)容長(zhǎng)度頭,您可以通過(guò)將[Body]屬性的緩沖參數(shù)設(shè)置為true來(lái)禁用此流行為:
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將使用可以通過(guò)設(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屬性來(lái)自定義屬性序列化/反序列化:
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),可以通過(guò)向XmlContentSerializer構(gòu)造函數(shù)提供XmlContentSerializer設(shè)置來(lái)設(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)求表單中字段名稱(chēng)不一致時(shí),可在對(duì)象屬性名稱(chēng)上加入[AliasAs("你定義字段名稱(chēng)")] 屬性,那么加入屬性的對(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);通過(guò)將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)容,則可以通過(guò)將頭屬性應(yīng)用于參數(shù)來(lái)向請(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)
使用頭的最常見(jiàn)原因是為了授權(quán)。而現(xiàn)在大多數(shù)API使用一些oAuth風(fēng)格的訪問(wèn)令牌,這些訪問(wèn)令牌會(huì)過(guò)期,刷新壽命更長(zhǎng)的令牌。封裝這些類(lèi)型的令牌使用的一種方法是,可以插入自定義的HttpClientHandler。這樣做有兩個(gè)類(lèi):一個(gè)是AuthenticatedHttpClientHandler,它接受一個(gè)Func<Task<string>>參數(shù),在這個(gè)參數(shù)中可以生成簽名,而不必知道請(qǐng)求。另一個(gè)是authenticatedparameteredhttpclienthandler,它接受一個(gè)Func<HttpRequestMessage,Task<string>>參數(shù),其中簽名需要有關(guān)請(qǐng)求的信息(參見(jiàn)前面關(guān)于Twitter的API的注釋?zhuān)?br />例如:
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。此類(lèi)的用法與此類(lèi)似(示例使用ADAL庫(kù)來(lái)管理自動(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將嘗試獲取新的訪問(wèn)令牌。由應(yīng)用程序提供,檢查現(xiàn)有訪問(wèn)令牌的過(guò)期時(shí)間,并在需要時(shí)獲取新的訪問(wèn)令牌。
以上就是本文的全部?jī)?nèi)容,希望對(duì)大家的學(xué)習(xí)有所幫助,也希望大家多多支持腳本之家。
相關(guān)文章
HttpWebRequest的常見(jiàn)錯(cuò)誤使用TcpClient可避免
有時(shí)使用HttpWebRequest對(duì)象會(huì)出現(xiàn)錯(cuò)誤有三種服務(wù)器提交了協(xié)議沖突/基礎(chǔ)連接已經(jīng)關(guān)閉:連接被意外關(guān)閉/無(wú)法發(fā)送具有此謂詞類(lèi)型的內(nèi)容正文,感興趣的朋友可以參考下本文2013-02-02
深入淺析ASP在線壓縮access數(shù)據(jù)庫(kù)的方法
這篇文章主要介紹了ASP在線壓縮access數(shù)據(jù)庫(kù)的方法,本文給大家介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友可以參考下2020-09-09
ASP.NET框架中的數(shù)據(jù)綁定概要與數(shù)據(jù)綁定表達(dá)式的使用
數(shù)據(jù)綁定是ASP.NET中操作數(shù)據(jù)的基礎(chǔ)方式,這里我們暫時(shí)拋開(kāi).NET提供的控件,來(lái)從基礎(chǔ)上講解ASP.NET框架中的數(shù)據(jù)綁定概要與數(shù)據(jù)綁定表達(dá)式的使用:2016-06-06
ASP.NET中的跳轉(zhuǎn) 200, 301, 302轉(zhuǎn)向?qū)崿F(xiàn)代碼
跳轉(zhuǎn)非常常用,在哪里都一樣,這里的一些說(shuō)明和用法也如此,不止適用于asp.net,其他語(yǔ)言也會(huì)用得到。跳轉(zhuǎn)的目的本來(lái)很簡(jiǎn)單,就是當(dāng)用戶(hù)或系統(tǒng)需要時(shí)從一個(gè)頁(yè)面轉(zhuǎn)向另一個(gè)頁(yè)面,但自從有了各種各樣的需求,還有那個(gè)什么SEO的東西之后,跳轉(zhuǎn)被搞得極其復(fù)雜2008-09-09
asp.net實(shí)現(xiàn)DropDownList,TreeView,ListBox的無(wú)限極分類(lèi)目錄樹(shù)
這篇文章主要介紹了asp.net實(shí)現(xiàn)DropDownList,TreeView,ListBox的無(wú)限極分類(lèi)目錄樹(shù),結(jié)合實(shí)例形式較為詳細(xì)的分析了asp.net常見(jiàn)控件實(shí)現(xiàn)無(wú)限極分類(lèi)目錄樹(shù)的具體實(shí)現(xiàn)步驟與相關(guān)操作技巧,需要的朋友可以參考下2016-06-06

