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>，而是只返回反序列化的响应。这些扩展方法会在远程服务器返回错误时抛出异常。异常详情包含服务器返回的状态代码。