RestSharp：三步跑通带认证的 API 调用，完整上手指南

RestSharp三步跑通带认证的 API 调用完整上手指南【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址: https://gitcode.com/gh_mirrors/re/RestSharp什么场景需要 RestSharp 这个 HTTP 客户端.NET 服务要对接第三方 REST API——拉取用户列表、提交订单数据、校验访问令牌——用原生HttpClient写每次都要自己拼 URL、序列化 JSON、加认证头。RestSharp 是一个构建在HttpClient之上的 .NET REST/HTTP 客户端库把这些环节收敛成几行带类型的配置代码。项目速览HttpClient 之上的类型化封装层RestSharp 只要求你指定基础地址和请求参数剩下的 URL 组装、请求体序列化、响应反序列化、认证头注入都由它完成。核心代码位于 src/RestSharp/从netstandard2.0到net10.0含 .NET Framework 4.7.1/4.8全版本可用。三个核心能力类型化参数查询、URL 路径段、请求头、文件、JSON 体全部链式添加自动 URL 编码内置序列化默认System.Text.Json请求对象转 JSON/XML、响应转 .NET 类型无需手动转换可插拔认证器内置 Basic、JWT、OAuth1/OAuth2自定义继承AuthenticatorBase即可快速上手三步安装并发出首个类型化请求安装、建客户端、发请求三步完成。第 1 步装 NuGet 包dotnet add package RestSharp第 2 步创建客户端构造函数参数是基础地址using RestSharp; var client new RestClient(https://jsonplaceholder.typicode.com);第 3 步构建请求并取响应。ExecuteGetAsyncPost的泛型参数是响应模型调用后response.Data就是反序列化好的对象var request new RestRequest(posts/1); // 默认 GET var response await client.ExecuteGetAsyncPost(request); Console.WriteLine(${response.StatusCode} {response.Data?.Title}); record Post(int Id, string Title);jsonplaceholder 是一个返回稳定 JSON 的公开测试 API。请求发出后如果Data是 null别先怀疑网络往下看坑。核心场景实战完成一次真实的提交—查询—失败处理流程任务把 API 封装成可复用的类型化客户端——POST 提交一条记录、GET 按 ID 带条件查询、处理非 200 响应。这一个例子覆盖参数处理、序列化、错误处理三件事。1. 客户端配置与默认头。RestClientOptions集中管理基础地址和超时每个请求都要带的认证信息注册为默认头即可var options new RestClientOptions(https://jsonplaceholder.typicode.com) { Timeout TimeSpan.FromSeconds(10) }; var client new RestClient(options); client.AddDefaultHeader(X-Api-Key, your-key);真实项目里令牌需要动态获取时如 OAuth2 客户端凭证用内置的OAuth2ClientCredentialsAuthenticator替换默认头它会在首次请求时取令牌、缓存并在过期前刷新。2. POST 带 JSON 体。AddJsonBody直接把匿名对象序列化为请求体并自动设置Content-Type不用手工拼 JSONvar request new RestRequest(posts, Method.Post) .AddJsonBody(new { title hello, body world, userId 1 }); var created await client.ExecutePostAsyncPost(request); Console.WriteLine($Created: id{created.Data?.Id});文件上传同理链式加一个AddFile(file, path)就会切换为 multipart/form-data 提交3. GET 带 URL 段与查询参数。{id}是路径占位符由AddUrlSegment填充AddQueryParameter自动拼到 URL 并做编码var get new RestRequest(posts/{id}) .AddUrlSegment(id, created.Data.Id) .AddQueryParameter(userId, 1); var fetched await client.ExecuteGetAsyncPost(get);4. 错误处理。RestSharp 默认不对 4xx/5xx 抛异常从响应对象检查状态if (!fetched.IsSuccessful) { Console.WriteLine(${fetched.StatusCode}: {fetched.ErrorMessage}); }偏好异常风格的话改用GetAsyncPost失败直接抛或对响应调用ThrowIfError()。坑与取舍三个新手高频问题与适用边界三个最常见的坑都跟失败不抛异常有关先统一认识再排查具体现象。⚠️坑一Data 是 null却没有异常。现象response.Data为 null无任何堆栈。原因反序列化失败默认被吞掉模型和响应 JSON 对不上时不会报出来。解法先看IsSuccessful和原始Content确认响应本身没问题严格场景在RestClientOptions里设ThrowOnDeserializationError true让它直接抛。⚠️坑二GetAsync 和 ExecuteGetAsync 对失败的处理不一致。GetAsyncT返回TaskT没有响应对象承载错误状态所以失败直接抛异常ExecuteGetAsyncT不抛返回RestResponseT。同一服务里混用异常路径会不可预期。解法一个项目定一种风格并坚持。⚠️坑三手动加 Content-Type 头。AddJsonBody之后 RestSharp 已按内容类型设置了application/json再手动加头可能与序列化器实际产出冲突。内容类型由请求体类型决定非必要别碰请求头。什么时候不该用 RestSharp项目只有一两个简单 GETHttpClientSystem.Net.Http.Json就够少一个依赖需要对HttpMessageHandler、连接池做深度定制虽然可以注入自己的HttpClient但封装层的收益有限Blazor WASM 环境只能用接收HttpClient或HttpMessageHandler的构造函数默认构造会抛不支持的平台异常一页速查所有源码路径与文档链接集中在此正文不再重复。核心源码src/RestSharp/RestClient、请求/响应、认证器、序列化器入门与类型化客户端示例docs/docs/usage/basics.md、docs/docs/usage/example.md请求与响应细节docs/docs/usage/request.md、docs/docs/usage/response.md错误处理与序列化配置docs/docs/advanced/error-handling.md、docs/docs/advanced/serialization.md认证器与拦截器docs/docs/advanced/authenticators.md、docs/docs/advanced/interceptors.md集成测试与本地测试服务器test/RestSharp.Tests.Integrated/获取完整源码git clone https://gitcode.com/gh_mirrors/re/RestSharp【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址: https://gitcode.com/gh_mirrors/re/RestSharp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考