C#常用类库-详解RestSharp

C#常用类库-详解RestSharp

在C#后端开发、客户端开发中，HTTP请求是必不可少的核心场景——调用第三方API、对接微服务接口、获取远程数据等，都需要高效、可靠的HTTP客户端工具。原生HttpClient虽能满足基础需求，但在请求封装、响应处理、会话保持、异常重试等场景下，需要编写大量重复代码，开发效率低下且易出错。

而RestSharp作为.NET生态中最成熟、最流行的HTTP客户端类库，恰好解决了这一痛点。它封装了HTTP请求的全套流程，支持RESTful API的所有请求方式，内置序列化/反序列化、请求拦截、响应解析、异常处理等强大功能，一行代码即可发起复杂HTTP请求，大幅提升开发效率。

本文将从基础概念→核心用法→高级特性→企业级封装→性能优化→避坑指南，全方位、有深度地解析RestSharp，结合实际开发场景（对接第三方API、微服务调用），帮你彻底掌握这款HTTP请求“神器”，从基础使用到高级定制，覆盖90%以上的企业级开发需求。

一、前言：RestSharp的定位与核心价值

在讲解RestSharp之前，我们先明确两个核心问题：RestSharp解决了什么痛点？它与原生HttpClient、其他HTTP客户端类库（如Flurl.Http）的差异是什么？这是理解RestSharp设计理念、合理选型的基础。

1. 核心痛点：原生HttpClient的弊端

日常开发中，使用原生HttpClient发起HTTP请求，存在诸多繁琐且耗时的问题：

• 重复代码冗余：每次请求都需手动创建HttpRequestMessage、设置请求头、处理响应流、解析响应数据，代码重复率极高，无法复用。

• 序列化/反序列化繁琐：请求参数（JSON、Form表单）、响应数据的序列化/反序列化，需手动结合Newtonsoft.Json或System.Text.Json处理，易出现格式错误。

• 会话与Cookie管理复杂：对接需要登录验证、会话保持的接口时，需手动维护Cookie容器，逻辑繁琐且易出错。

• 异常处理不完善：原生HttpClient对HTTP错误（如404、500）、网络异常的处理不够友好，需手动捕获异常、判断响应状态码，代码臃肿。

• 高级功能缺失：不支持自动重试、请求拦截、响应拦截、超时控制细化等企业级常用功能，需额外编写大量扩展代码。

而RestSharp的出现，正是为了将开发者从这些繁琐的重复劳动中解放出来，专注于核心业务逻辑，同时提供更强大、更灵活的HTTP请求能力。

2. RestSharp的核心定位

RestSharp是一款**.NET平台的高性能HTTP客户端类库**，核心目标是“简化HTTP请求开发，提供企业级HTTP请求能力”。它基于原生HttpClient封装，兼容所有.NET平台（.NET Framework 4.5+、.NET Core 2.0+、.NET 5/6/7/8、.NET MAUI、Xamarin等），支持所有HTTP请求方式（GET、POST、PUT、DELETE、PATCH等），完美适配RESTful API开发。

RestSharp的核心优势是“简洁易用、功能全面、灵活可定制”，内置JSON/XML序列化、Cookie管理、请求/响应拦截、自动重试、超时控制、文件上传下载等功能，无需额外依赖第三方类库（可按需集成序列化工具），开箱即用。

3. RestSharp vs 原生HttpClient vs Flurl.Http（核心差异）

• 简单请求场景（如偶尔调用一次第三方API），可使用原生HttpClient，无需额外引入类库。

• 追求链式调用简洁性，且需求简单，可选择Flurl.Http。

• 企业级开发、频繁调用API、需要会话管理、拦截器、自动重试等高级功能，优先选择RestSharp，兼顾效率与扩展性。

4. 版本与安装

RestSharp最新稳定版本为110.2.0（本文基于此版本讲解），安装方式极其简单，通过NuGet安装核心包即可，根据需求选择对应扩展包：

• 核心包（必装）：Install-Package RestSharp（.NET CLI：dotnet add package RestSharp）

• Newtonsoft.Json序列化扩展（按需）：Install-Package RestSharp.Serializers.NewtonsoftJson（若需使用Newtonsoft.Json序列化）

• System.Text.Json序列化扩展（按需）：Install-Package RestSharp.Serializers.SystemTextJson（默认内置，可无需额外安装）

安装完成后，引入核心命名空间即可使用：using RestSharp;

注意：RestSharp 107+版本与旧版本（如106.x）API差异较大，本文基于最新版本讲解，避免使用过时API。

二、基础用法：从零开始使用RestSharp（核心场景）

RestSharp的API设计极其简洁，核心流程分为3步：创建RestClient实例→创建RestRequest实例→执行请求并处理响应。基础用法覆盖5个核心场景：GET请求、POST请求（JSON/Form表单）、PUT/DELETE请求、响应解析、请求参数传递，这5个场景几乎能满足80%的日常开发需求。

1. 核心基础：RestClient与RestRequest核心对象

RestSharp的所有请求操作，都围绕两个核心对象展开，理解这两个对象的作用，是掌握RestSharp的基础：

• RestClient：HTTP客户端实例，负责管理HTTP连接、会话（Cookie）、基础URL、全局配置（如超时、代理、序列化器），建议全局单例复用（避免频繁创建销毁，提升性能）。

• RestRequest：单个HTTP请求实例，负责配置请求方式（GET/POST等）、请求路径、请求参数、请求头、响应类型等，每个请求对应一个RestRequest实例。

基础示例（创建客户端与请求）：

using RestSharp;

// 1. 创建RestClient实例（基础URL，后续请求可省略基础部分）
var client = new RestClient("https://api.example.com");

// 2. 配置全局参数（可选，如超时、序列化器）
client.Options.Timeout = 5000; // 超时时间5秒
client.UseSystemTextJson(); // 使用System.Text.Json序列化（默认）
// 若需使用Newtonsoft.Json，需安装对应包并调用：client.UseNewtonsoftJson();

// 3. 创建RestRequest实例（请求路径、请求方式）
var request = new RestRequest("/api/user", Method.Get); // GET请求，路径拼接在基础URL后

2. GET请求（最常用场景）

GET请求用于获取数据，常见场景：查询列表、查询详情，支持路径参数、查询参数两种传递方式，RestSharp可自动拼接参数，无需手动处理。

（1）查询参数传递（推荐，适用于参数较多场景）

using RestSharp;

// 1. 创建客户端（全局单例复用）
var client = new RestClient("https://api.example.com")
{
Options = { Timeout = 5000 }
};

// 2. 创建GET请求，指定路径
var request = new RestRequest("/api/users", Method.Get);

// 3. 添加查询参数（自动拼接为 ?page=1&size=10&keyword=test）
request.AddParameter("page", 1);
request.AddParameter("size", 10);
request.AddParameter("keyword", "test");

// 4. 执行请求，获取响应（同步请求）
var response = client.Execute(request);

// 5. 处理响应
if (response.IsSuccessful) // 判断请求是否成功（HTTP状态码200-299）
{
string responseContent = response.Content; // 响应原始内容（JSON/XML）
Console.WriteLine("请求成功：" + responseContent);
}
else
{
Console.WriteLine($"请求失败：{response.StatusCode}，错误信息：{response.ErrorMessage}");
}

（2）路径参数传递（适用于ID查询等场景）

// 1. 创建客户端
var client = new RestClient("https://api.example.com");

// 2. 创建GET请求，路径中使用占位符 {id}
var request = new RestRequest("/api/users/{id}", Method.Get);

// 3. 添加路径参数（替换占位符）
request.AddUrlSegment("id", 1001); // 最终路径：/api/users/1001

// 4. 执行请求（异步请求，推荐使用异步，避免阻塞线程）
var response = await client.ExecuteAsync(request);

// 5. 处理响应
if (response.IsSuccessful)
{
// 解析JSON响应（后续详细讲解）
var user = JsonSerializer.Deserialize<User>(response.Content);
Console.WriteLine($"查询用户：{user.Name}");
}
else
{
Console.WriteLine($"请求失败：{response.StatusCode}");
}

注意：异步请求（ExecuteAsync）是企业级开发的推荐方式，避免同步请求阻塞主线程，尤其适用于Web应用、客户端应用。

3. POST请求（核心场景）

POST请求用于提交数据，常见场景：新增数据、登录验证，支持JSON格式、Form表单格式两种核心参数传递方式，RestSharp可自动处理序列化和请求头。

（1）JSON格式参数（最常用，适用于API接口）

using RestSharp;
using System.Text.Json;

// 1. 定义请求参数模型（与API接口字段对应）
public class UserRequest
{
public string Name { get; set; }
public int Age { get; set; }
public string Email { get; set; }
}

// 2. 创建客户端
var client = new RestClient("https://api.example.com")
{
Options = { Timeout = 5000 }
};

// 3. 创建POST请求
var request = new RestRequest("/api/users", Method.Post);

// 4. 设置请求体为JSON格式（自动序列化，无需手动转换）
var userRequest = new UserRequest
{
Name = "张三",
Age = 25,
Email = "zhangsan@example.com"
};
request.AddJsonBody(userRequest); // 自动设置Content-Type: application/json

// 5. 执行异步请求
var response = await client.ExecuteAsync(request);

// 6. 处理响应
if (response.IsSuccessful)
{
// 解析响应（新增成功后返回用户ID）
var result = JsonSerializer.Deserialize<ApiResponse>(response.Content);
Console.WriteLine($"新增用户成功，用户ID：{result.Data}");
}
else
{
Console.WriteLine($"新增失败：{response.StatusCode}，错误信息：{response.ErrorMessage}");
}

// 定义响应模型
public class ApiResponse
{
public int Code { get; set; } // 状态码（如200成功，500失败）
public string Message { get; set; } // 提示信息
public object Data { get; set; } // 响应数据
}

（2）Form表单格式参数（适用于表单提交、旧版API）

// 1. 创建客户端
var client = new RestClient("https://api.example.com");

// 2. 创建POST请求
var request = new RestRequest("/api/login", Method.Post);

// 3. 设置请求体为Form表单格式（自动设置Content-Type: application/x-www-form-urlencoded）
request.AddParameter("username", "admin");
request.AddParameter("password", "123456");
// 也可批量添加参数
// request.AddParameters(new Dictionary<string, string>
// {
// {"username", "admin"},
// {"password", "123456"}
// });

// 4. 执行请求
var response = await client.ExecuteAsync(request);

// 5. 处理响应（登录成功返回Token）
if (response.IsSuccessful)
{
var loginResult = JsonSerializer.Deserialize<LoginResponse>(response.Content);
Console.WriteLine($"登录成功，Token：{loginResult.Token}");
}

// 登录响应模型
public class LoginResponse
{
public string Token { get; set; } // 身份验证Token
public string ExpireTime { get; set; } // Token过期时间
}

4. PUT/DELETE请求（常用场景）

PUT请求用于更新数据，DELETE请求用于删除数据，用法与GET、POST类似，核心区别在于请求方式，参数传递支持路径参数、查询参数、JSON参数。

（1）PUT请求（更新数据）

// 1. 创建客户端
var client = new RestClient("https://api.example.com");

// 2. 创建PUT请求（路径参数传递用户ID）
var request = new RestRequest("/api/users/{id}", Method.Put);
request.AddUrlSegment("id", 1001); // 路径：/api/users/1001

// 3. 添加JSON格式的更新参数
var updateRequest = new UserRequest
{
Name = "张三（更新）",
Age = 26,
Email = "zhangsan_update@example.com"
};
request.AddJsonBody(updateRequest);

// 4. 执行请求
var response = await client.ExecuteAsync(request);

// 5. 处理响应
if (response.IsSuccessful)
{
Console.WriteLine("用户更新成功");
}
else
{
Console.WriteLine($"更新失败：{response.StatusCode}");
}

（2）DELETE请求（删除数据）

// 1. 创建客户端
var client = new RestClient("https://api.example.com");

// 2. 创建DELETE请求（路径参数传递用户ID）
var request = new RestRequest("/api/users/{id}", Method.Delete);
request.AddUrlSegment("id", 1001);

// 3. 执行请求
var response = await client.ExecuteAsync(request);

// 4. 处理响应
if (response.IsSuccessful)
{
Console.WriteLine("用户删除成功");
}
else
{
Console.WriteLine($"删除失败：{response.StatusCode}");
}

5. 响应解析（核心重点）

RestSharp执行请求后，返回的RestResponse对象包含响应的所有信息，核心解析场景包括：原始内容解析、JSON/XML序列化解析、响应头解析、状态码判断。

（1）核心响应属性

var response = await client.ExecuteAsync(request);

// 1. 基础信息
response.IsSuccessful; // 是否请求成功（HTTP 200-299）
response.StatusCode; // HTTP状态码（如HttpStatusCode.OK、HttpStatusCode.NotFound）
response.Content; // 响应原始内容（string类型，JSON/XML）
response.ErrorMessage; // 请求失败时的错误信息
response.ErrorException; // 请求失败时的异常对象

// 2. 响应头
var contentType = response.Headers.FirstOrDefault(h => h.Name == "Content-Type")?.Value; // 获取Content-Type
var token = response.Cookies.FirstOrDefault(c => c.Name == "token")?.Value; // 获取Cookie中的Token

// 3. 响应流（适用于大文件下载）
var responseStream = response.RawBytes; // 字节数组，可转换为文件、流等

（2）JSON响应解析（推荐方式）

RestSharp支持自动解析JSON响应，无需手动调用序列化工具，通过ExecuteAsync<T>方法，直接将响应内容反序列化为指定模型：

// 1. 创建请求
var request = new RestRequest("/api/users/1001", Method.Get);

// 2. 执行请求并自动反序列化为User模型（无需手动解析）
var response = await client.ExecuteAsync<User>(request);

// 3. 处理响应
if (response.IsSuccessful)
{
User user = response.Data; // 直接获取反序列化后的模型
Console.WriteLine($"用户名称：{user.Name}，年龄：{user.Age}");
}
else
{
Console.WriteLine($"请求失败：{response.StatusCode}");
}

// User模型（与JSON响应字段对应）
public class User
{
public int Id { get; set; }
public string Name { get; set; }
public int Age { get; set; }
public string Email { get; set; }
public DateTime CreateTime { get; set; }
}

注意：自动反序列化依赖于配置的序列化器（System.Text.Json或Newtonsoft.Json），若JSON字段与模型字段名称不一致，可通过特性配置（如[JsonPropertyName("user_name")]）。

（3）XML响应解析

若API返回XML格式响应，RestSharp同样支持自动解析，只需将模型配置为XML序列化特性，或手动指定XML序列化器：

// 1. 配置XML序列化器（若需手动指定）
client.UseXmlSerializer();

// 2. 创建请求
var request = new RestRequest("/api/users/xml/1001", Method.Get);

// 3. 自动反序列化为User模型（需给模型添加XML特性）
var response = await client.ExecuteAsync<User>(request);

// 4. User模型添加XML特性
[XmlRoot("User")]
public class User
{
[XmlElement("Id")]
public int Id { get; set; }

[XmlElement("Name")]
public string Name { get; set; }

[XmlElement("Age")]
public int Age { get; set; }
}

三、核心特性：RestSharp高级用法（深度重点）

基础用法能满足日常简单需求，而RestSharp的高级特性则能适配复杂企业级场景（如会话保持、请求拦截、自动重试、文件上传下载），这也是它区别于其他HTTP客户端类库的核心优势。

1. 会话保持与Cookie管理（登录验证场景必备）

对接需要登录验证的API时，通常需要保持会话（Cookie），RestSharp内置Cookie容器，自动维护Cookie，无需手动处理，适用于登录后后续请求无需重复携带Token/Cookie的场景。

using RestSharp;

// 1. 创建RestClient实例，内置Cookie容器（默认开启）
var client = new RestClient("https://api.example.com")
{
Options = { Timeout = 5000 }
};

// 2. 第一步：登录请求（获取Cookie/Token）
var loginRequest = new RestRequest("/api/login", Method.Post);
loginRequest.AddParameter("username", "admin");
loginRequest.AddParameter("password", "123456");
var loginResponse = await client.ExecuteAsync(loginRequest);

// 3. 登录成功后，Cookie会自动保存在client的Cookie容器中
// 第二步：后续请求（无需手动携带Cookie，自动发送）
var userListRequest = new RestRequest("/api/users", Method.Get);
var userListResponse = await client.ExecuteAsync<List<User>>(userListRequest);

// 4. 若需手动获取或设置Cookie
var cookie = client.CookieContainer.GetCookies(new Uri("https://api.example.com")).Cast<Cookie>().FirstOrDefault(c => c.Name == "token");
// 手动设置Cookie
client.CookieContainer.Add(new Uri("https://api.example.com"), new Cookie("token", "手动设置的Token值"));

// 5. 持久化Cookie（如保存到本地，下次启动无需重新登录）
// 序列化Cookie容器（需手动实现，可使用Newtonsoft.Json）
var cookies = client.CookieContainer.GetCookies(new Uri("https://api.example.com"));
var cookieJson = JsonSerializer.Serialize(cookies);
File.WriteAllText("cookies.json", cookieJson);

// 读取持久化的Cookie
var savedCookies = JsonSerializer.Deserialize<CookieCollection>(File.ReadAllText("cookies.json"));
client.CookieContainer.Add(savedCookies);

2. 请求头与授权设置（接口验证场景）

企业级API通常需要授权验证（如Token、Basic Auth、OAuth2.0），RestSharp支持灵活设置请求头，可全局设置（所有请求生效）或局部设置（单个请求生效）。

（1）局部请求头（单个请求生效）

var request = new RestRequest("/api/users", Method.Get);

// 1. 添加单个请求头
request.AddHeader("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…");
// 2. 添加多个请求头
request.AddHeaders(new Dictionary<string, string>
{
{"Content-Type", "application/json"},
{"User-Agent", "RestSharp/110.2.0"},
{"Accept", "application/json"}
});

var response = await client.ExecuteAsync(request);

（2）全局请求头（所有请求生效）

// 创建客户端时，全局设置请求头
var client = new RestClient("https://api.example.com")
{
Options = {
Timeout = 5000,
// 全局请求头（所有请求都会携带）
Headers = {
new Header("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"),
new Header("User-Agent", "RestSharp/110.2.0")
}
}
};

// 后续所有请求都会自动携带全局请求头
var request1 = new RestRequest("/api/users", Method.Get);
var request2 = new RestRequest("/api/orders", Method.Post);
// 无需再单独添加Authorization请求头

（3）常见授权方式支持

// 1. Basic Auth（基础认证，用户名+密码）
var client = new RestClient("https://api.example.com");
client.Authenticator = new HttpBasicAuthenticator("username", "password"); // 全局生效

// 2. OAuth2.0（Bearer Token，最常用）
// 方式1：全局设置
client.Authenticator = new OAuth2AuthorizationRequestHeaderAuthenticator("token", "Bearer");
// 方式2：局部设置（单个请求）
request.AddHeader("Authorization", "Bearer token");

// 3. OAuth1.0（适用于第三方平台，如Twitter API）
client.Authenticator = new OAuth1Authenticator("consumerKey", "consumerSecret", "token", "tokenSecret");

3. 请求/响应拦截器（企业级监控、日志场景）

企业级开发中，通常需要监控HTTP请求（记录请求参数、响应数据、耗时）、统一处理请求（如添加全局Token）、统一处理响应（如异常统一拦截），RestSharp的拦截器功能可完美实现这些需求。

（1）请求拦截器（发送请求前执行）

using RestSharp.Interceptors;

// 1. 自定义请求拦截器（实现IRequestInterceptor接口）
public class CustomRequestInterceptor : IRequestInterceptor
{
public void Intercept(IRestRequest request, RestClient client, CancellationToken cancellationToken)
{
// 1. 记录请求日志（请求方式、路径、参数）
var requestLog = $"请求方式：{request.Method}，请求路径：{request.Resource}，参数：{JsonSerializer.Serialize(request.Parameters)}";
Console.WriteLine(requestLog);

// 2. 统一添加Token（无需每个请求单独添加）
request.AddOrUpdateHeader("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…");

// 3. 统一设置请求超时（覆盖单个请求的设置）
request.Timeout = 5000;
}
}

// 2. 注册请求拦截器（全局生效）
var client = new RestClient("https://api.example.com")
{
Options = { Timeout = 5000 }
};
client.AddInterceptor(new CustomRequestInterceptor());

// 3. 发起请求，拦截器会自动执行
var request = new RestRequest("/api/users", Method.Get);
var response = await client.ExecuteAsync(request);

（2）响应拦截器（获取响应后执行）

// 1. 自定义响应拦截器（实现IResponseInterceptor接口）
public class CustomResponseInterceptor : IResponseInterceptor
{
public void Intercept(IRestResponse response, RestClient client, IRestRequest request, CancellationToken cancellationToken)
{
// 1. 记录响应日志（状态码、响应内容、耗时）
var responseLog = $"请求耗时：{response.ResponseStatus}，状态码：{response.StatusCode}，响应内容：{response.Content}";
Console.WriteLine(responseLog);

// 2. 统一处理异常响应（如401未授权、500服务器错误）
if (!response.IsSuccessful)
{
switch (response.StatusCode)
{
case HttpStatusCode.Unauthorized:
Console.WriteLine("Token过期，需要重新登录");
// 这里可添加自动刷新Token的逻辑
break;
case HttpStatusCode.InternalServerError:
Console.WriteLine("服务器错误，请联系管理员");
break;
default:
Console.WriteLine($"请求失败：{response.ErrorMessage}");
break;
}
}
}
}

// 2. 注册响应拦截器（全局生效）
client.AddInterceptor(new CustomResponseInterceptor());

4. 自动重试（提升请求可靠性）

网络波动、接口临时不可用等场景，会导致请求失败，RestSharp支持自动重试机制，可配置重试次数、重试间隔、重试条件，无需手动编写重试逻辑。

using RestSharp.Retry;

// 1. 配置自动重试策略（全局生效）
var client = new RestClient("https://api.example.com")
{
Options = { Timeout = 5000 },
// 重试策略：最多重试3次，每次间隔1秒，仅对5xx错误、网络错误重试
RetryPolicy = new ExponentialBackoffRetryPolicy(
maxRetries: 3, // 最大重试次数
initialDelay: TimeSpan.FromSeconds(1), // 初始重试间隔
maxDelay: TimeSpan.FromSeconds(5), // 最大重试间隔
// 重试条件：网络错误、HTTP 5xx错误
retryCondition: response =>
response.ResponseStatus == ResponseStatus.Error ||
(int)response.StatusCode >= 500
)
};

// 2. 发起请求，若失败会自动重试
var request = new RestRequest("/api/users", Method.Get);
var response = await client.ExecuteAsync(request);

常用重试策略：

• ExponentialBackoffRetryPolicy：指数退避重试（重试间隔逐渐增加，避免频繁请求服务器），推荐使用。

• LinearRetryPolicy：线性重试（固定重试间隔）。

• NoRetryPolicy：不重试（默认）。

5. 文件上传与下载（核心业务场景）

RestSharp支持文件上传（如图片、文档）和文件下载（如报表、附件），无需手动处理流，API简洁易用，适用于文件管理、报表导出等场景。

（1）文件上传（单文件/多文件）

// 1. 单文件上传
var client = new RestClient("https://api.example.com");
var request = new RestRequest("/api/upload", Method.Post);

// 添加文件（路径、参数名、内容类型）
request.AddFile(
parameterName: "file", // 与API接口的文件参数名一致
filePath: "D:\\\\test.jpg", // 本地文件路径
contentType: "image/jpeg" // 文件内容类型
);

// 执行上传请求
var response = await client.ExecuteAsync(request);
if (response.IsSuccessful)
{
Console.WriteLine("文件上传成功");
}

// 2. 多文件上传
var request2 = new RestRequest("/api/upload/multiple", Method.Post);
// 方式1：添加多个文件（指定路径）
request2.AddFile("file1", "D:\\\\test1.jpg", "image/jpeg");
request2.AddFile("file2", "D:\\\\test2.pdf", "application/pdf");

// 方式2：添加流文件（适用于内存中的文件）
byte[] fileBytes = File.ReadAllBytes("D:\\\\test3.txt");
request2.AddFile("file3", () => new MemoryStream(fileBytes), "test3.txt", "text/plain");

var response2 = await client.ExecuteAsync(request2);

（2）文件下载

// 1. 下载文件到本地路径
var client = new RestClient("https://api.example.com");
var request = new RestRequest("/api/download/file/1001", Method.Get);

// 执行下载请求，获取文件字节数组
var response = await client.ExecuteAsync(request);
if (response.IsSuccessful && response.RawBytes != null)
{
// 保存文件到本地
File.WriteAllBytes("D:\\\\downloaded_file.pdf", response.RawBytes);
Console.WriteLine("文件下载成功");
}

// 2. 下载大文件（分块下载，避免内存溢出）
var request2 = new RestRequest("/api/download/largefile", Method.Get);
// 配置分块下载（每次下载1024*1024字节，即1MB）
request2.AddHeader("Range", "bytes=0-1048575"); // 第一块
var response2 = await client.ExecuteAsync(request2);
// 后续分块下载逻辑（需根据文件大小计算分块数量，拼接字节数组）

6. 代理设置（企业内网场景）

企业内网环境中，通常需要通过代理服务器访问外部API，RestSharp支持配置HTTP代理、HTTPS代理，适配内网场景。

// 1. 配置HTTP代理
var client = new RestClient("https://api.example.com")
{
Options = {
Timeout = 5000,
// 代理服务器地址、端口、用户名、密码（若有）
Proxy = new WebProxy("http://proxy.example.com:8080")
{
Credentials = new NetworkCredential("proxyUser", "proxyPassword")
}
}
};

// 2. 配置HTTPS代理
client.Options.Proxy = new WebProxy("https://proxy.example.com:443");

// 3. 跳过代理（部分地址无需代理）
client.Options.Proxy = new WebProxy()
{
BypassList = new[] { "https://api.internal.com" } // 内网地址跳过代理
};

四、企业级最佳实践：RestSharp在项目中的规范用法

掌握了RestSharp的基础和高级用法后，更重要的是在实际项目中规范使用，避免滥用导致代码混乱、性能低下。以下是企业级项目中的最佳实践，帮你提升代码可维护性、可扩展性和可靠性。

1. 封装RestSharp工具类（全局复用，统一管理）

将RestSharp的客户端创建、请求配置、响应处理、异常处理等逻辑，封装为全局工具类，避免重复代码，同时便于后续维护和扩展（如统一修改序列化器、添加拦截器）。

using RestSharp;
using RestSharp.Interceptors;
using RestSharp.Retry;

public static class RestSharpHelper
{
// 全局单例RestClient（避免频繁创建销毁，提升性能）
private static readonly RestClient _client;

// 静态构造函数，初始化客户端配置
static RestSharpHelper()
{
// 1. 基础配置
var options = new RestClientOptions("https://api.example.com")
{
Timeout = 5000, // 全局超时
MaxTimeout = 10000, // 最大超时（适用于大文件上传下载）
FollowRedirects = true // 自动跟随重定向
};

// 2. 创建客户端
_client = new RestClient(options);

// 3. 配置序列化器（使用System.Text.Json）
_client.UseSystemTextJson();

// 4. 注册拦截器（请求/响应日志、统一授权）
_client.AddInterceptor(new CustomRequestInterceptor());
_client.AddInterceptor(new CustomResponseInterceptor());

// 5. 配置自动重试策略
_client.RetryPolicy = new ExponentialBackoffRetryPolicy(
maxRetries: 3,
initialDelay: TimeSpan.FromSeconds(1),
maxDelay: TimeSpan.FromSeconds(5),
retryCondition: response =>
response.ResponseStatus == ResponseStatus.Error ||
(int)response.StatusCode >= 500
);

// 6. 配置全局授权（Token可从配置文件读取）
string token = AppSettings.GetValue<string>("ApiSettings:Token");
_client.Authenticator = new OAuth2AuthorizationRequestHeaderAuthenticator(token, "Bearer");
}

#region 通用请求方法（GET/POST/PUT/DELETE）
/// <summary>
/// GET请求（自动反序列化）
/// </summary>
public static async Task<ApiResponse<T>> GetAsync<T>(string resource, Dictionary<string, object> parameters = null)
{
return await ExecuteAsync<T>(resource, Method.Get, parameters);
}

/// <summary>
/// POST请求（JSON参数，自动反序列化）
/// </summary>
public static async Task<ApiResponse<T>> PostAsync<T>(string resource, object body = null)
{
return await ExecuteAsync<T>(resource, Method.Post, body: body);
}

/// <summary>
/// PUT请求（JSON参数，自动反序列化）
/// </summary>
public static async Task<ApiResponse<T>> PutAsync<T>(string resource, object body = null, Dictionary<string, object> parameters = null)
{
return await ExecuteAsync<T>(resource, Method.Put, parameters, body);
}

/// <summary>
/// DELETE请求
/// </summary>
public static async Task<ApiResponse<bool>> DeleteAsync(string resource, Dictionary<string, object> parameters = null)
{
return await ExecuteAsync<bool>(resource, Method.Delete, parameters);
}
#endregion

#region 核心执行方法（统一处理请求与响应）
/// <summary>
/// 统一执行请求，处理响应和异常
/// </summary>
private static async Task<ApiResponse<T>> ExecuteAsync<T>(
string resource,
Method method,
Dictionary<string, object> parameters = null,
object body = null)
{
try
{
// 1. 创建请求
var request = new RestRequest(resource, method);

// 2. 添加查询参数（若有）
if (parameters != null && parameters.Count > 0)
{
foreach (var param in parameters)
{
request.AddParameter(param.Key, param.Value);
}
}

// 3. 添加请求体（JSON格式，若有）
if (body != null)
{
request.AddJsonBody(body);
}

// 4. 执行请求
var response = await _client.ExecuteAsync<ApiResponse<T>>(request);

// 5. 处理响应（拦截器已处理日志和异常，此处返回结果）
return response.IsSuccessful ? response.Data : new ApiResponse<T>
{
Code = (int)response.StatusCode,
Message = response.ErrorMessage,
Success = false
};
}
catch (Exception ex)
{
// 记录异常日志
Console.WriteLine($"请求异常：{ex.Message}，堆栈信息：{ex.StackTrace}");
return new ApiResponse<T>
{
Code = 500,
Message = "请求异常，请稍后重试",
Success = false
};
}
}
#endregion

#region 文件上传/下载方法
/// <summary>
/// 单文件上传
/// </summary>
public static async Task<ApiResponse<string>> UploadFileAsync(string resource, string filePath, string parameterName = "file", string contentType = null)
{
try
{
var request = new RestRequest(resource, Method.Post);
request.AddFile(parameterName, filePath, contentType ?? MimeTypes.GetMimeType(filePath));
var response = await _client.ExecuteAsync<ApiResponse<string>>(request);
return response.IsSuccessful ? response.Data : new ApiResponse<string>
{
Code = (int)response.StatusCode,
Message = response.ErrorMessage,
Success = false
};
}
catch (Exception ex)
{
Console.WriteLine($"文件上传异常：{ex.Message}");
return new ApiResponse<string>
{
Code = 500,
Message = "文件上传失败，请稍后重试",
Success = false
};
}
}

/// <summary>
/// 文件下载
/// </summary>
public static async Task<ApiResponse<byte[]>> DownloadFileAsync(string resource)
{
try
{
var request = new RestRequest(resource, Method.Get);
var response = await _client.ExecuteAsync(request);
if (response.IsSuccessful && response.RawBytes != null)
{
return new ApiResponse<byte[]>
{
Success = true,
Data = response.RawBytes,
Message = "下载成功"
};
}
return new ApiResponse<byte[]>
{
Code = (int)response.StatusCode,
Message = response.ErrorMessage ?? "文件下载失败",
Success = false
};
}
catch (Exception ex)
{
Console.WriteLine($"文件下载异常：{ex.Message}");
return new ApiResponse<byte[]>
{
Code = 500,
Message = "文件下载失败，请稍后重试",
Success = false
};
}
}
#endregion
}

// 统一响应模型（适配所有API响应）
public class ApiResponse<T>
{
public bool Success { get; set; } = true;
public int Code { get; set; } = 200;
public string Message { get; set; } = "操作成功";
public T Data { get; set; }
}

使用方式（简洁高效，无需关注底层细节）：

// 1. GET请求（查询用户列表）
var userListParams = new Dictionary<string, object>
{
{"page", 1},
{"size", 10}
};
var userListResponse = await RestSharpHelper.GetAsync<List<User>>("/api/users", userListParams);
if (userListResponse.Success)
{
var userList = userListResponse.Data;
// 处理用户列表
}

// 2. POST请求（新增用户）
var userRequest = new UserRequest
{
Name = "张三",
Age = 25,
Email = "zhangsan@example.com"
};
var addResponse =