RestSharp 请求构建完全指南
前言
RestSharp 是一个功能强大的 .NET HTTP 客户端库，它简化了与 RESTful API 的交互过程。本文将深入讲解如何使用 RestSharp 构建各种类型的 HTTP 请求，包括 GET、POST 等常见请求方法，以及如何处理请求参数、请求体和文件上传等高级功能。
创建基础请求
在 RestSharp 中，构建请求的第一步是创建 RestRequest 实例：
// 创建基础 GET 请求
var request = new RestRequest("/api/resource");
// 创建指定方法的请求
var postRequest = new RestRequest("/api/resource", Method.Post);
RestRequest 构造函数接受资源路径作为参数，这个路径会附加到客户端的基础 URL 上。默认情况下，请求方法是 GET，但可以通过构造函数的第二个参数或设置 Method 属性来更改。
请求头处理
请求头是 HTTP 请求的重要组成部分，RestSharp 提供了多种方式来添加请求头：
// 添加单个请求头
request.AddHeader("X-API-Key", "your-api-key");
// 添加泛型值（自动转换为字符串）
request.AddHeader<int>("X-Retry-Count", 3);
// 更新已存在的请求头
request.AddOrUpdateHeader("X-API-Key", "new-api-key");
对于需要在所有请求中共享的请求头（如认证头），可以添加到客户端级别：
client.AddDefaultHeader("Authorization", "Bearer token");
重要提示：通常情况下，RestSharp 会自动设置正确的 Content-Type 头，除非有特殊需求，否则不建议手动设置。
请求参数详解
1. GET/POST 参数
GetOrPost 参数是 RestSharp 的默认参数类型，其行为会根据请求方法自动调整：
request
.AddParameter("username", "john.doe")
.AddParameter("password", "secret", false); // 第三个参数控制是否编码
- GET 请求：参数会附加到 URL 查询字符串中
- POST/PUT 请求：
- 无文件时：作为 URL 编码的表单数据发送
- 有文件时：作为 multipart/form-data 发送
2. 查询字符串参数
QueryString 参数总是附加到 URL 上，无论请求方法是什么：
request.AddQueryParameter("page", "1");
request.AddQueryParameter("filter", "active");
对于需要保留原始格式的参数，可以禁用编码：
request.AddQueryParameter("path", "/some/path", false);
3. URL 段参数
URL 段参数用于动态构建 URL 路径：
var request = new RestRequest("users/{id}/profile")
.AddUrlSegment("id", "12345");
执行后，实际请求的 URL 将是 users/12345/profile。
4. 使用对象添加参数
对于包含多个参数的复杂场景，可以使用对象一次性添加所有参数：
var searchParams = new {
keyword = "restsharp",
page = 1,
pageSize = 20
};
request.AddObject(searchParams);
这相当于分别添加了三个参数。对于自定义参数名称或格式，可以使用 RequestProperty 特性：
public class SearchRequest {
[RequestProperty(Name = "q")]
public string Keyword { get; set; }
[RequestProperty(Format = "D")]
public DateTime Date { get; set; }
}
请求体处理
RestSharp 支持多种类型的请求体：
1. JSON 请求体
var user = new User { Name = "John", Age = 30 };
request.AddJsonBody(user);
AddJsonBody 会自动：
- 序列化对象为 JSON
- 设置 Content-Type 为 application/json
- 设置数据类型为 Json
2. XML 请求体
var order = new Order { Id = 1001, Items = [...] };
request.AddXmlBody(order);
注意：不要直接将 XML 字符串传递给 AddXmlBody，它只接受对象进行序列化。
3. 原始字符串请求体
对于预序列化的内容，可以使用字符串形式：
const string json = "{ \"name\": \"John\" }";
request.AddStringBody(json, ContentType.Json);
文件上传
RestSharp 提供了简单的方式来上传文件：
// 从文件系统上传
request.AddFile("document", "path/to/file.pdf", "application/pdf");
// 上传字节数组
var bytes = File.ReadAllBytes("path/to/image.jpg");
request.AddFile("image", bytes, "image.jpg", "image/jpeg");
对于特殊字符的文件名，可以调整上传选项：
var options = new FileParameterOptions {
DisableFilenameEncoding = true, // 禁用文件名编码
DisableFilenameStar = false // 启用 filename* 参数
};
request.AddFile("file", "文件.txt", options: options);
Cookie 处理
虽然 RestSharp 支持 Cookie，但使用时需要谨慎：
// 添加单个 Cookie
request.AddCookie("sessionId", "abc123");
// 使用 Cookie 容器
var container = new CookieContainer();
container.Add(new Cookie("name", "value", "/", "example.com"));
request.CookieContainer = container;
最佳实践：对于需要跨请求共享 Cookie 的场景，建议在客户端级别配置 CookieContainer。
总结
本文详细介绍了 RestSharp 中构建 HTTP 请求的各种方法和技巧。从基础请求创建到复杂的参数处理，从 JSON/XML 请求体到文件上传，RestSharp 提供了丰富而灵活的 API 来满足各种 HTTP 交互需求。掌握这些技术点，将帮助开发者更高效地构建健壮的 REST API 客户端应用。
