RestSharp 中文文檔詳解

一、什麼是 RestSharp?

RestSharp 是一個輕量級的 HTTP 客戶端庫，主要用於對 RESTful API 進行訪問。它是基於 .NET 平台的開源項目，採用了 MIT 許可證，可以在商業項目中免費使用。RestSharp 是對 HttpClient 的封裝，提供了更加友好和簡單的 API 介面，可以方便地完成 GET、POST、PUT、DELETE、PATCH 等 HTTP 訪問操作。

RestSharp 主要用於消費 Web API，它可以處理 JSON、XML 等數據格式，並且支持參數綁定。因此，它特別適用於與基於 RESTful 架構的後端伺服器進行通信的客戶端程序，例如，通過 RestSharp 我們可以調用 GitHub、Twitter、Facebook 等網站的 API。

二、如何使用 RestSharp？

使用 RestSharp 非常簡單，只需通過 NuGet 安裝 RestSharp 庫，然後在代碼中引用。

var client = new RestClient("https://jsonplaceholder.typicode.com");
var request = new RestRequest("posts/{postid}", Method.GET);
request.AddParameter("postid", 1);
var response = client.Execute(request);
Console.WriteLine(response.Content);

上述代碼中，我們首先創建了一個 RestClient 對象，並指定 Web API 的基礎 URL。然後，我們使用 RestRequest 創建了一個 GET 請求，指定了請求路徑，以及一個 Path parameter，表示文章編號。接下來，使用 Execute 方法發送請求，並獲取響應。

三、如何安裝 RestSharp？

要在你的項目中使用 RestSharp，需要首先將它安裝到你的項目中。目前既可通過 NuGet 包管理器來安裝，也可以手動下載最新版本的源代碼。

在 Visual Studio 中使用 NuGet 包管理器安裝 RestSharp 時，可以在「工具」菜單下的「NuGet 包管理器」的「解決方案的 NuGet 包管理器…」中搜索 RestSharp，或者在 NuGet 界面搜索 RestSharp 並選擇安裝。

Install-Package RestSharp -Version 106.13.0

四、如何發送請求並處理響應？

使用 RestSharp 創建請求時，主要需要指定 API 的 URL、請求方式和參數。其中，URL 必須是完整的 HTTP 或 HTTPS URL，參數可以包括 headers、query parameters、form data、 path parameters 等，請求方式則可以是 GET、POST、PUT、DELETE、PATCH 等。

在發送請求時，可以通過 Execute 方法執行，這個方法返回一個 IRestResponse 的對象，用於表示 HTTP 響應結果。通過響應對象可以獲取 HTTP 狀態碼, 響應內容、響應頭、Cookies 等信息。

var client = new RestClient("https://jsonplaceholder.typicode.com");
var request = new RestRequest("posts/{postid}", Method.GET);
request.AddParameter("postid", 1);
var response = client.Execute(request);
Console.WriteLine(response.Content);

五、如何配置 RestSharp?

在使用 RestSharp 時，可以通過 RestClient 的屬性來配置一些參數。例如，可以定義超時時間、User Agent、自定義序列化器、自定義參數處理等。以下是一些示例:

超時時間

var client = new RestClient("https://jsonplaceholder.typicode.com") {
    Timeout = 5000
};

User Agent

var client = new RestClient("https://jsonplaceholder.typicode.com")
    .UserAgent("MyApp/1.0");

自定義序列化器

var client = new RestClient("https://api.example.com")
    .AddHandler("application/json", () => new CustomJsonSerializer());

自定義參數處理

public class CustomQueryParameter {
    public string Name {get;set;}
    public object Value {get;set;}
}

var client = new RestClient("https://jsonplaceholder.typicode.com")
    .AddHandler("application/json", () => new CustomQueryParameterSerializer())
    .AddQueryParameterSerializer((queryParameter, serializer) => {
        serializer.WriteParameter(queryParameter.Name, queryParameter.Value.ToString());
    });

六、如何處理異常?

在使用 RestSharp 發送請求時，可能會發生網路異常或伺服器出錯等情況。為了保證代碼的穩定性，應該對這些異常進行處理。以下是一些示例：

網路異常

try {
   var response = client.Execute(request);
} catch (Exception ex) {
   Console.WriteLine(ex.Message);
}

HTTP 狀態碼

var response = client.Execute(request);
if (response.StatusCode == HttpStatusCode.OK) {
   Console.WriteLine("成功");
}
else if (response.StatusCode == HttpStatusCode.NotFound) {
   Console.WriteLine("資源不存在");
}
else if (response.StatusCode == HttpStatusCode.BadRequest) {
   Console.WriteLine("請求不合法");
}
//...

七、如何使用 RestSharp 執行非同步請求?

RestSharp 支持非同步操作，可以通過 ExecuteAsync 方法執行非同步請求，然後等待響應。

var client = new RestClient("https://jsonplaceholder.typicode.com");
var request = new RestRequest("posts/{postid}", Method.GET);
request.AddParameter("postid", 1);
var response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);

在上述代碼中，我們使用 await 關鍵字等待響應結果，並通過非同步回調方法處理響應結果。

八、如何上傳文件?

在使用 RestSharp 發送請求時，如果需要上傳文件，可以通過 AddFile 和 AddFileBytes 方法上傳文件。以下是一些示例：

上傳單個文件

var client = new RestClient("https://api.example.com");
var request = new RestRequest("upload", Method.POST);
request.AddFile("file", "path/to/file");
var response = client.Execute(request);
Console.WriteLine(response.Content);

上傳多個文件

var client = new RestClient("https://api.example.com");
var request = new RestRequest("upload", Method.POST);
request.AddFile("file1", "path/to/file1");
request.AddFile("file2", "path/to/file2");
request.AddFile("file3", "path/to/file3");
var response = client.Execute(request);
Console.WriteLine(response.Content);

九、總結

本文介紹了 RestSharp 的基礎知識，包括它的作用、使用方法、安裝方式、配置參數、異常處理、非同步請求和文件上傳等內容。通過本文的學習，讀者可以掌握如何使用 RestSharp 和如何利用其來消費 RESTful API。