RestSharp HTTP 请求客户端

RestSharp 适合在 .NET 项目里快速发起 REST / HTTP 请求。它的价值不在于“比所有方案都强”，而在于把请求参数、序列化和常见调用方式收得比较顺手，适合业务系统里常规接口对接。

一、RestSharp 适合解决什么问题

RestSharp 本质上是一个 .NET HTTP 客户端封装，适合做这些事情：

调用第三方 REST API
对接内部微服务接口
快速组织 Query、Header、Body、表单参数
自动处理 JSON / XML 的序列化与反序列化

它的优点主要有 4 个：

上手快：比原始 HttpClient 少写一些样板代码
参数组织清晰：Query、Header、Body、Form 都有明确入口
序列化省事：发 JSON、收 JSON 比较顺
兼容老项目：除了异步接口，也保留了同步风格，适合一些遗留系统

二、什么时候用，什么时候别用

适合用

项目里需要频繁调用 HTTP API
团队已经有 RestSharp 使用经验
想快速完成业务集成，不想自己封一层 HTTP 工具

不太适合用

项目已经有稳定的 HttpClient 封装
只调用一两个简单接口，没有必要额外引入依赖
需要非常底层、非常细的 HTTP 行为控制

结论很简单： RestSharp 适合“快速稳定接第三方接口”，不适合为了用而用。

三、基本使用方式

1. 创建客户端和请求

csharp

var client = new RestClient("https://api.example.com");
var request = new RestRequest("orders/{id}", Method.Get);
request.AddUrlSegment("id", 1001);

上面这一步一般就做了两件事：

RestClient 负责服务端地址和客户端配置
RestRequest 负责本次请求的路径、方法和参数

2. 添加 Query 参数

csharp

request.AddQueryParameter("status", "paid");
request.AddQueryParameter("page", 1);
request.AddQueryParameter("pageSize", 20);

适合列表查询、筛选和分页。

csharp

request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Accept", "application/json");

最常见就是鉴权 Token、自定义请求头、幂等键这类信息。

4. 发送 JSON 请求体

csharp

var body = new
{
    orderNo = "SO20260919001",
    amount = 99.50m
};

request.AddJsonBody(body);

这也是 RestSharp 最顺手的一点：直接传对象，库会帮你序列化成 JSON。

四、最常见的请求示例

1. GET 查询

csharp

var client = new RestClient("https://api.example.com");
var request = new RestRequest("orders/{id}", Method.Get);
request.AddUrlSegment("id", 1001);

var response = await client.ExecuteAsync(request);

2. POST 新增

csharp

var client = new RestClient("https://api.example.com");
var request = new RestRequest("orders", Method.Post);

request.AddJsonBody(new
{
    customerId = 2001,
    amount = 99.50m
});

var response = await client.ExecuteAsync(request);

3. 反序列化响应

如果接口返回结构稳定，可以直接定义 DTO：

csharp

public class OrderDto
{
    public long Id { get; set; }
    public string OrderNo { get; set; } = string.Empty;
    public decimal Amount { get; set; }
}

var response = await client.ExecuteAsync<OrderDto>(request);
var order = response.Data;

这样可以少写很多手动解析 JSON 的代码。

4. 文件上传 (File Upload)

RestSharp 处理 multipart/form-data 非常简单。

csharp

var request = new RestRequest("upload", Method.Post);
request.AddFile("file", "C:\\path\\to\\image.jpg", "image/jpeg");
request.AddParameter("description", "This is a test image");

var response = await client.ExecuteAsync(request);

五、进阶实践：性能与韧性

5.1 结合 Polly 实现重试机制

在分布式系统中，网络抖动是常态。建议结合 Polly 库为 RestSharp 增加重试和熔断能力。

csharp

var retryPolicy = Policy
    .Handle<HttpRequestException>()
    .OrResult<RestResponse>(r => r.StatusCode == HttpStatusCode.ServiceUnavailable)
    .WaitAndRetryAsync(3, i => TimeSpan.FromSeconds(Math.Pow(2, i)));

var response = await retryPolicy.ExecuteAsync(async () => {
    return await client.ExecuteAsync(request);
});

5.2 自定义序列化设置 (Newtonsoft.Json)

RestSharp 默认使用 System.Text.Json。如果需要使用 Newtonsoft.Json 的高级特性（如 JsonProperty），需要进行配置：

csharp

var options = new RestClientOptions("https://api.example.com");
var client = new RestClient(options, configureSerialization: s => s.UseNewtonsoftJson());

六、使用时最容易踩的点 (Deep Dive)

1. 客户端生命周期管理

错误：每次请求都 new RestClient()。原因：这会导致大量的 Socket 处于 TIME_WAIT 状态，最终耗尽服务器端口，引发 SocketException。 正确做法：

在单例服务中复用 RestClient。
如果需要动态配置，使用 RestClientOptions。

2. 区分“请求失败”和“业务失败”

接口返回 200 不代表业务一定成功。很多业务系统会在 200 里再返回错误码。

csharp

var response = await client.ExecuteAsync<ApiResponse<OrderDto>>(request);

if (!response.IsSuccessful || response.Data == null) {
    // HTTP 层失败或超时
    logger.LogError($"Network Error: {response.ErrorMessage}");
    return;
}

if (!response.Data.Success) {
    // 业务层失败
    logger.LogWarning($"Business Error: {response.Data.Message}");
    return;
}

3. 超时、重试和日志

调用外部接口时，必须显式设置超时时间，默认的无限等待是生产环境的杀手。

csharp

var options = new RestClientOptions("https://api.example.com") {
    MaxTimeout = 5000 // 5秒超时
};

七、与 HttpClient 的深度对比

特性	HttpClient	RestSharp
底层依赖	原生 .NET	基于 HttpClient (v107+)
代码量	较多样板代码	非常简洁
参数组织	手动拼接 URL/Body	链式调用 `AddParameter`
序列化	需手动调用 `JsonSerializer`	自动处理 `AddJsonBody`
推荐场景	高性能微服务、复杂代理	快速对接第三方 SDK、中小型项目

八、总结

RestSharp 的定位是 “易用性优先”。它在 HttpClient 的基础上封装了一套极度符合人类直觉的 API。如果你厌倦了 StringContent 和 ReadAsStringAsync 的繁琐，RestSharp 是最佳的替代方案。

九、参考资料

RestSharp 官方文档
GitHub: RestSharp Repository
C# 使用 RestSharp 简单示例 - 博客园
.NET HTTP 客户端性能基准测试快速接第三方接口、项目规模不大，RestSharp 用起来会更直接。

七、推荐的最小封装方式

如果项目里要长期用 RestSharp，建议至少包一层自己的调用方法：

统一基础地址
统一鉴权 Header
统一超时和日志
统一异常处理
统一响应结果转换

不要在每个业务方法里都重复写同样的客户端初始化和判断逻辑。

八、一句话判断是否值得引入

满足下面任意两条，就值得考虑：

需要频繁调用外部 HTTP API
接口参数类型多，手写拼装很烦
需要快速完成对接而不是造轮子
项目是 .NET 业务系统，目标是交付效率

RestSharp HTTP 请求客户端 ​

一、RestSharp 适合解决什么问题 ​

二、什么时候用，什么时候别用 ​

适合用 ​

不太适合用 ​

三、基本使用方式 ​

1. 创建客户端和请求 ​

2. 添加 Query 参数 ​

3. 添加 Header ​

4. 发送 JSON 请求体 ​

四、最常见的请求示例 ​

1. GET 查询 ​

2. POST 新增 ​

3. 反序列化响应 ​

4. 文件上传 (File Upload) ​

五、进阶实践：性能与韧性 ​

5.1 结合 Polly 实现重试机制 ​

5.2 自定义序列化设置 (Newtonsoft.Json) ​

六、使用时最容易踩的点 (Deep Dive) ​

1. 客户端生命周期管理 ​

2. 区分“请求失败”和“业务失败” ​

3. 超时、重试和日志 ​

七、与 HttpClient 的深度对比 ​

八、总结 ​

九、参考资料 ​

七、推荐的最小封装方式 ​

八、一句话判断是否值得引入 ​

参考资料 ​

RestSharp HTTP 请求客户端

一、RestSharp 适合解决什么问题

二、什么时候用，什么时候别用

适合用

不太适合用

三、基本使用方式

1. 创建客户端和请求

2. 添加 Query 参数

3. 添加 Header

4. 发送 JSON 请求体

四、最常见的请求示例

1. GET 查询

2. POST 新增

3. 反序列化响应

4. 文件上传 (File Upload)

五、进阶实践：性能与韧性

5.1 结合 Polly 实现重试机制

5.2 自定义序列化设置 (Newtonsoft.Json)

六、使用时最容易踩的点 (Deep Dive)

1. 客户端生命周期管理

2. 区分“请求失败”和“业务失败”

3. 超时、重试和日志

七、与 HttpClient 的深度对比

八、总结

九、参考资料

七、推荐的最小封装方式

八、一句话判断是否值得引入

参考资料