RestSharp 引言
RestSharp 的主要目的是通过 HTTP 同步或异步调用远程资源。如名称所示,RestSharp 的主要目标是使用 REST API 的开发人员。然而,只要您有想要发送的资源 URI 和参数,并且这些符合 W3C HTTP 标准,RestSharp 可以通过 HTTP 调用任何 API。
对于 .NET 开发人员来说,使用 HTTP API 面临的主要挑战之一是处理不同类型的请求和响应,并将其转换为复杂的 C# 类型。RestSharp 可以负责将请求体序列化为 JSON 或 XML,以及解码响应。它还可以根据不同的参数类型(路径、查询、表单或主体)形成有效的请求 URI。
快速开始
在您的应用程序中使用 RestSharp 之前,您需要添加 NuGet 包。您可以使用 IDE 或命令行来完成:
dotnet add package RestSharp
基本用法
如果您只需要执行少量的一次性 API 请求,可以像这样使用 RestSharp:
using RestSharp;
using RestSharp.Authenticators;
var options = new RestClientOptions("https://api.twitter.com/1.1") {
Authenticator = new HttpBasicAuthenticator("username", "password")
};
var client = new RestClient(options);
var request = new RestRequest("statuses/home_timeline.json");
// 取消令牌来自调用者。即使没有它,您仍然可以发起调用。
var response = await client.GetAsync(request, cancellationToken);
它将返回一个 RestResponse
,其中包含从远程服务器返回的所有信息。
您可以访问头信息、内容、HTTP 状态等。
您还可以使用泛型重载,如 Get<T>
,自动将响应解码为 .NET 类。
例如:
using RestSharp;
using RestSharp.Authenticators;
var options = new RestClientOptions("https://api.twitter.com/1.1") {
Authenticator = new HttpBasicAuthenticator("username", "password")
};
var client = new RestClient(options);
var request = new RestRequest("statuses/home_timeline.json");
// 取消令牌来自调用者。即使没有它,您仍然可以发起调用。
var timeline = await client.GetAsync<HomeTimeline>(request, cancellationToken);
上述两段代码都使用了 GetAsync
扩展方法,它是 ExecuteGetAsync
的包装器,而 ExecuteAsync
又是 ExecuteAsync
的包装器。
所有 ExecuteAsync
的重载都会返回 RestResponse
或 RestResponse<T>
。
最重要的区别在于,使用以 HTTP 方法命名的异步方法(如 GetAsync
或 PostAsync
)会返回 Task<T>
,而不是 Task<RestResponse<T>>
。这意味着如果请求失败,您不会收到错误响应,因为这些方法会在请求失败时抛出异常。为了保持 API 一致性,如 GetAsync
或 PostAsync
这样的非泛型函数在请求失败时也会抛出异常,尽管它们返回的是 Task<RestResponse>
。
有关 RestSharp 如何处理异常的详细信息,请参阅 这里。
RestSharp 还提供了简单的方法来调用接受和返回 JSON 数据包的 API。您可以使用 GetJsonAsync
和 PostJsonAsync
扩展方法,它们将自动将请求体序列化为 JSON 并将响应解码为指定类型。
var client = new RestClient(options);
var timeline = await client.GetJsonAsync<HomeTimeline>("statuses/home_timeline.json", cancellationToken);
要详细了解不准备请求对象进行 JSON 调用,请参阅 这里。
内容类型
RestSharp 支持将 XML 或 JSON 身份验证作为请求的一部分发送。要向 RestRequest
对象添加主体,只需调用 AddJsonBody
或 AddXmlBody
方法。
当使用这些方法时,无需设置 Content-Type
或在请求中添加 DataFormat
参数,RestSharp 将为您处理。
RestSharp 也将处理 XML 和 JSON 响应,并根据服务器响应类型执行所有必要的反序列化任务。因此,如果您想手动反序列化响应,只需要添加 Accept
头。
例如,仅需以下几行即可使用 JSON 身份验证发出请求:
var request = new RestRequest("address/update").AddJsonBody(updatedAddress);
var response = await client.PostAsync<AddressUpdateResponse>(request);
您也可以使用更简短的语法 PostAsync
来执行相同的调用:
var response = await PostJsonAsync<AddressUpdateRequest, AddressUpdateResponse>(
"address/update", request, cancellationToken
);
有关序列化和反序列化的更多信息,请参阅 这里。
响应
使用 ExecuteAsync
时,您会得到一个 RestResponse
实例。响应对象具有 Content
属性,其中包含响应字符串。您可以在那里找到其他有用属性,如 StatusCode
、ContentType
等。如果请求不成功,您会收到一个响应,其中 IsSuccessful
属性设置为 false
,并且错误信息会在 ErrorException
和 ErrorMessage
属性中解释。
使用泛型 ExecuteAsync<T>
时,您会得到一个 RestResponse<T>
实例,它与 RestResponse
相同,但还包含 T Data
属性,其中包含已反序列化的响应。
ExecuteAsync
的所有重载都不会在远程服务器返回错误时抛出。您可以检查响应并找到状态代码、错误消息,以及潜在的异常。
扩展方法如 GetAsync<T>
不会返回整个 RestResponse<T>
,而是只返回反序列化的响应。这些扩展方法会在远程服务器返回错误时抛出异常。异常详情包含服务器返回的状态代码。