后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载output_articleRestSharp 客户端配置完全指南RestClientOptions、自定义 HttpClient 与消息处理器深度解析导读本文围绕 RestSharp.NET 平台上的 REST/HTTP API 客户端在 v110 版本中的RestClient配置体系展开系统讲解四种构造器形态、RestClientOptions的全部客户端选项、RestRequest的请求级配置以及如何注入自定义HttpClient与HttpMessageHandler。读完本文你将掌握 RestSharp 客户端从默认可用到按需定制的完整配置路径并能结合源码理解各项配置在底层HttpClient上的真实作用位置。文中所有结论均以仓库内 v110 文档docs/versioned_docs/version-v110/advanced/configuration.md与当前源码src/RestSharp/RestClient.cs、src/RestSharp/Options/RestClientOptions.cs为依据。一、基础配置四种方式创建 RestClientRestClient的主构造器接收一个RestClientOptions实例。绝大多数场景下选项的默认值无需修改但当客户端需要差异化配置时就需要在代码中调整这些选项。构造器还提供了几个可选参数用于覆盖客户端选项之外的附加配置完整签名如下public RestClient( RestClientOptions options, ConfigureHeaders? configureDefaultHeaders null, ConfigureSerialization? configureSerialization null, bool useClientFactory false )各参数含义参数说明是否必填options客户端选项是configureDefaultHeaders配置请求头的函数用于为HttpClient配置默认请求头。大多数情况下更推荐使用client.AddDefaultHeader否configureSerialization配置客户端序列化器的函数可用于非默认序列化选项或切换其他序列化器详见 serialization.md否useClientFactory指示客户端使用SimpleClientFactory获取HttpClient实例详见 usage.md#simple-factory否从源码看这三个委托分别对应 RestClient.cs 中定义的类型ConfigureHeaders接收HttpRequestHeaders、ConfigureSerialization接收SerializerConfig与ConfigureRestClient接收RestClientOptions。1.1 使用选项对象创建var options new RestClientOptions(https://localhost:5000/api) { DisableCharset true }; var client new RestClient(options);RestClientOptions同时提供了Uri与string两种构造重载见 RestClientOptions.cs其中字符串重载会先执行Ensure.NotEmptyString校验再转换为Uri。1.2 简化构造器仅设置 BaseUrl当只需要设置基础地址时可直接传入 URL 字符串var client new RestClient(https://localhost:5000/api);该简化构造器内部会创建RestClientOptions实例并将传入的 base URL 设置为BaseUrl。从 RestClient.cs 的源码可以看到字符串重载最终委托给Uri重载再通过ConfigureOptions合并配置函数。1.3 配置函数方式覆盖默认选项最后一种方式是通过配置函数就地修改默认选项public RestClient( ConfigureRestClient? configureRestClient null, ConfigureHeaders? configureDefaultHeaders null, ConfigureSerialization? configureSerialization null, bool useClientFactory false )使用示例var client new RestClient(options { options.BaseUrl new Uri(https://localhost:5000/api); options.DisableCharset true; });也可以将 base URL 作为第一个参数传入再追加配置函数var client new RestClient(https://localhost:5000/api, options { options.DisableCharset true });上述两种形态在源码中殊途同归ConfigureOptions先调用configureRestClient修改传入的选项实例再统一进入主构造器完成后续初始化RestClient.cs。二、自定义 HttpClient接管连接池与生命周期默认情况下RestSharp 会根据客户端选项创建并持有HttpClient实例且与RestClient生命周期一致——当RestClient被释放时HttpClient也随之释放Dispose方法中仅在_disposeHttpClient为true时释放见 RestClient.cs。但在某些场景下你需要注入自己的HttpClient例如复用 HTTP 客户端工厂如 ASP.NET Core 的IHttpClientFactory创建的实例。RestSharp 为此提供了两组构造器// 使用现有 HttpClient 和 RestClientOptions可选创建客户端 public RestClient( HttpClient httpClient, RestClientOptions? options, bool disposeHttpClient false, ConfigureSerialization? configureSerialization null ) // 使用现有 HttpClient 和可选配置函数创建客户端 public RestClient( HttpClient httpClient, bool disposeHttpClient false, ConfigureRestClient? configureRestClient null, ConfigureSerialization? configureSerialization null )disposeHttpClient参数控制当RestClient自身被释放时是否连带释放HttpClient默认值为false。理由很直接外部传入的HttpClient通常应由外部负责释放避免重复释放或悬空引用。源码实现中还包含一个细节当httpClient.BaseAddress已设置而options.BaseUrl为空时会用前者回填后者RestClient.cs保证 URL 拼接逻辑一致。注意注入外部HttpClient后通过RestClientOptions配置的、仅在创建HttpClient时生效的选项将不再起作用。这也是文档中Reusing HttpClient一节强调不是所有选项都生效的原因——具体生效列表可参考 usage.md 中的说明。三、自定义消息处理器从 HttpMessageHandler 到中间件管道除非使用外部HttpClient实例否则RestClient在构造时都会自行创建HttpClient并使用由RestClientOptions配置的默认 HTTP 消息处理器。在现代 .NET 平台上通常是SocketHttpHandler在 .NET Framework 上则是WinHttpHandler。3.1 直接传入自定义 handler当需要自定义消息处理器例如加入一个 delegating handler时可使用如下构造器public RestClient( HttpMessageHandler handler, bool disposeHandler true, ConfigureRestClient? configureRestClient null, ConfigureSerialization? configureSerialization null )该构造器会用传入的 handler 创建新的HttpClient源码实现为new HttpClient(handler, disposeHandler)见 RestClient.cs。由于RestClient释放时会连带释放其创建的HttpClienthandler 也会被一并释放若想保留 handler 的生命周期由自己管理请将disposeHandler设为false。:::note 使用自定义消息处理器时RestSharp不会用客户端选项去配置它——这些选项只用于配置 RestSharp 自己创建的 handler。 :::3.2 通过 ConfigureMessageHandler 改造 RestSharp 创建的 handler另一种更灵活的定制方式是让 RestSharp 先创建 handler再用RestClientOptions.ConfigureMessageHandler属性对其改造或包装。该属性接收 RestSharp 创建的 handler返回经过设置的同一 handler 或全新的 handler。测试场景示例——使用 MockHttp 的 handler 拦截请求var mockHttp new MockHttpMessageHandler(); // 配置 MockHttp handler 执行断言 ... var options new RestClientOptions(Url) { ConfigureMessageHandler _ mockHttp }; using var client new RestClient(options);这里直接将 handler 替换为 MockHttpRestSharp 创建的 handler 被丢弃。而如果需要把 delegating handler 作为中间件叠加则应将 RestSharp 创建的 handler 传给 delegating handlervar options new RestClientOptions(Url) { ConfigureMessageHandler handler new MyDelegatingHandler(handler) }; using var client new RestClient(options);从源码可以确认这条调用链主构造器内部GetClient()方法先创建HttpClientHandler调用ConfigureHttpMessageHandler(handler, options)应用客户端选项随后执行options.ConfigureMessageHandler?.Invoke(handler) ?? handler完成用户自定义RestClient.cs。也就是说ConfigureMessageHandler是在 RestSharp 完成默认 handler 配置之后、HttpClient实例化之前执行的因此你拿到的 handler 已经带有RestClientOptions中与 handler 相关的全部设置。四、客户端选项RestClientOptions全景详解以下是 v110 文档中列出的全部客户端选项。建议结合 RestClientOptions.cs 阅读理解每个选项最终作用于 RestSharp 代码还是HttpMessageHandler。选项说明BaseUrl客户端基础 URL也可作为RestClientOptions构造参数传入ConfigureMessageHandler配置 HTTP 消息处理器见上一节CalculateResponseStatus用于根据HttpResponseMessage计算响应状态的函数。默认情况下返回成功状态码或 404 即视为请求完成Authenticator客户端级认证器详见 authenticators.mdInterceptors拦截器集合详见 interceptors.mdCredentials用于 NTLM 或 Kerberos 认证的ICredentials实例。浏览器平台不支持UseDefaultCredentials是否使用操作系统默认凭据进行 NTLM 或 Kerberos 认证。浏览器平台不支持DisableCharset设为true时Content-Type头不再包含charset部分。部分老旧 Web 服务器无法解析 header 中的charset部分而导致请求失败AutomaticDecompression自定义支持的解压方式。默认值为All.NET Framework 仅支持GZip。浏览器平台不支持MaxRedirects跟随重定向的次数上限。浏览器平台不支持ClientCertificates用于认证的 X.509 客户端证书集合。浏览器平台不支持Proxy当客户端需要显式非默认代理时使用。浏览器、iOS 与 tvOS 平台不支持CachePolicy设置默认Cache-Control头的快捷方式FollowRedirects指示客户端是否跟随重定向默认trueExpect100Continue获取或设置 HTTP 请求的Expect头是否包含ContinueUserAgent覆盖默认的User-Agent头值默认为RestSharp/{version}PreAuthenticate指示客户端是否随请求发送Authorization头。浏览器平台不支持RemoteCertificateValidationCallback自定义服务端证书校验函数。通常用于服务端使用了默认不受信任的证书时BaseHost每次请求发送的Host头值CookieContainer客户端级自定义 Cookie 容器会在客户端的所有调用间共享。通常不需要——RestSharp 在不使用客户端级容器的情况下也能处理 CookieMaxTimeout客户端级超时毫秒。若同时设置了请求级超时则该值不生效Encoding默认请求编码。仅在不使用 UTF-8 时才需要覆盖ThrowOnDeserializationError强制客户端在响应反序列化失败时抛出异常。注意并非所有反序列化问题都会导致序列化器抛出。默认false此时客户端返回携带反序列化异常信息的RestResponse。仅对Execute...系列函数有效FailOnDeserializationError设为true时反序列化失败会使响应对象状态变为Failed即便 HTTP 调用本身成功。默认trueThrowOnAnyError设为true时客户端会重新抛出HttpClient产生的任何异常。默认false。仅适用于Execute...系列函数AllowMultipleDefaultParametersWithSameName默认不允许添加同名的默认参数可设true覆盖此行为EncodeURL 编码函数默认是 RestSharp 基于Uri.EscapeDataString()的自定义实现。需要不同编码方式时替换它EncodeQueryURL 查询参数编码函数默认与Encode属性相同4.1 哪些选项只作用于 HttpMessageHandler上表中有一部分选项由 RestSharp 代码直接使用另一部分仅用于配置HttpMessageHandlerCredentialsUseDefaultCredentialsAutomaticDecompressionPreAuthenticateMaxRedirectsRemoteCertificateValidationCallbackClientCertificatesFollowRedirectsProxy:::note 如果将这些选项设置为非默认值却未产生预期效果请确认你的框架与平台是否支持它们。RestSharp 本身不会根据这些选项的取值改变行为。 :::源码中ConfigureHttpMessageHandlerRestClient.cs清晰地展示了这一映射它将UseDefaultCredentials、Credentials、AutomaticDecompression、PreAuthenticate、RemoteCertificateValidationCallback、ClientCertificates、Proxy逐一写入HttpClientHandler的属性同时把AllowAutoRedirect硬编码为false——重定向由 RestSharp 内部处理而非委托给HttpClient。另外无论 handler 支持与否UseCookies都被设为falseCookie 管理同样由 RestSharp 自行完成。4.2 选项的不可变性为什么实例化后不能修改IRestClient接口暴露了Options属性因此任何选项都可在运行时检查。但 RestSharp 会把传入构造器的选项对象转换为不可变对象ReadOnlyRestClientOptions见 ReadOnlyRestClientOptions.cs所以客户端实例化之后任何客户端选项都无法再修改。原因有二在并发环境中运行时修改选项会引入竞态问题使客户端不再线程安全修改用于创建消息处理器的选项需要重建 handler 以及HttpClient这不应在运行时进行。// 正确用法实例化前完成全部配置 var options new RestClientOptions(https://api.example.com) { MaxTimeout 10_000, UserAgent MyApp/1.0 }; var client new RestClient(options); // 错误用法实例化后无法修改Options 为只读视图 // client.Options.BaseUrl new Uri(https://other.example.com); // 不可行五、请求级配置RestRequest 的细粒度调优客户端选项作用于该客户端发起的所有请求。当某个请求需要定制执行方式时可通过RestRequest的属性完成类定义见 RestRequest.cs属性说明AlwaysMultipartFormData设为true时强制以 multipart 表单发送请求即使并不需要。默认情况下RestSharp 仅在请求包含多个附件时才以 multipart 表单发送。默认falseAlwaysSingleFileAsContent设为true时带文件附件的请求不再以 multipart 表单发送而是作为纯内容发送。默认false。当AlwaysMultipartFormData为true或请求包含POST参数时不能设为trueMultipartFormQuoteBoundary默认true即表单 boundary 字符串会被引号包裹。若服务器无法处理设false移除 boundary 周围的引号FormBoundary指定自定义 multipart 表单 boundary替代默认随机字符串RequestParameters请求参数集合。通常不需要直接使用——参数通过Add...系列方法添加到请求CookieContainer请求级自定义 Cookie 容器默认null。仍可通过AddCookie设置请求 Cookie并从响应对象获取响应 Cookie无需容器Authenticator覆盖客户端级认证器Files文件参数集合只读。使用AddFile添加文件Method请求 HTTP 方法默认GET。仅在使用Execute或ExecuteAsync时需要ExecutePostAsync等方法会覆盖请求方法TImeout覆盖客户端级超时原文拼写实际属性为TimeoutResource远程端点 URL 的资源部分。例如客户端 base URL 为https://localhost:5000/api、Resource为weather时请求发往https://localhost:5000/api/weather。可包含资源占位符配合AddUrlSegment使用RequestFormat标识请求为 JSON、XML、二进制或无。很少使用——使用AddJsonBody或AddXmlBody时客户端会根据 body 类型自动设置请求格式RootElement供默认反序列化器确定反序列化起点。仅支持 XML 响应不适用于请求OnBeforeDeserialization已过时反序列化前调用的函数允许在调用反序列化器前修改内容。请改用拦截器见 interceptors.mdOnBeforeRequest已过时在HttpClient执行请求前调用的函数接收HttpRequestMessage实例。请改用拦截器OnAfterRequest已过时在HttpClient执行请求后调用的函数接收HttpResponseMessage实例。请改用拦截器Attempts请求被重发以进行重试时该值递增CompletionOption指示客户端何时认为请求完成。默认ResponseContentRead使用异步下载函数或流式传输时会自动改为ResponseHeadersReadCachePolicy覆盖客户端缓存策略ResponseWriter自定义响应流处理函数接收原始响应流并返回另一个流或null。不能与AdvancedResponseWriter同时使用AdvancedResponseWriter自定义响应处理函数接收HttpResponseMessage与RestRequest必须返回RestResponse即完全覆盖 RestSharp 创建响应的默认逻辑Interceptors为请求添加拦截器。客户端级与请求级拦截器都会被调用从源码可以验证几个实现细节RestRequest默认构造将Method初始化为Method.GetRestRequest.csResponseWriter与AdvancedResponseWriter互斥——设置其中一个时若另一个已存在会抛出ArgumentExceptionRestRequest.csAttempts的 setter 为private只能通过内部方法IncreaseNumberOfAttempts递增RestRequest.cs。关于请求参数的添加方式AddHeader、AddParameter、AddUrlSegment、AddJsonBody等详见 usage.md#create-a-request。六、选项在请求执行链中的实际作用理解选项如何落地有助于排查配置了却不生效的问题。以 v110 的ExecuteAsync链路为例RestClient.Async.cs拦截器合并CombineInterceptors将客户端级拦截器与请求级拦截器合并认证器选择优先使用request.Authenticator为空时回退到Options.Authenticator超时计算MaxTimeout在 v110 中作为客户端级超时若请求级Timeout已设置则优先使用请求级异常策略ThrowOnAnyError为true时通过response.ThrowIfError()重新抛出异常反序列化相关异常则由ThrowOnDeserializationError/FailOnDeserializationError控制。// 请求级覆盖客户端级该请求独享 60 秒超时 var client new RestClient(https://api.example.com) { // v110 使用毫秒客户端默认 10 秒 }; var request new RestRequest(slow-endpoint) { Timeout TimeSpan.FromSeconds(60) };版本差异提示v110 文档中客户端级超时选项为MaxTimeout毫秒。在更新的版本中可参考主分支源码 RestClientOptions.cs该选项已演进为TimeoutTimeSpan?支持Timeout.InfiniteTimeSpan永不超时、TimeSpan.Zero立即取消等取值。编写针对 v110 的代码时请继续使用MaxTimeout。七、HttpClient 复用与 SimpleClientFactory除手动注入HttpClient外v110 还提供了内置的SimpleClientFactory源码见 SimpleClientFactory.cs。启用方式是在构造器中传入useClientFactory: truevar client new RestClient(https://api.twitter.com/2, useClientFactory: true);其原理是以BaseUrl为 key将HttpClient实例缓存于ConcurrentDictionaryGetOrAdd。每个不同的 base URL 对应一个HttpClient实例其他选项不参与缓存键。这意味着同一 base URL 使用不同选项时得到的HttpClient是同一个且不会按新选项重新配置。首次实例化后不再生效的选项包括CredentialsUseDefaultCredentialsAutomaticDecompressionPreAuthenticateFollowRedirectsRemoteCertificateValidationCallbackClientCertificatesMaxRedirectsMaxTimeoutUserAgentExpect100Continue此外用于配置HttpMessageHandler的构造参数与默认HttpClient请求头的配置也会被忽略——工厂只在首次创建时配置一次 handler。同时注意启用useClientFactory且未设置BaseUrl时构造器会直接抛出ArgumentExceptionRestClient.cs因为缓存必须以 base URL 为键。八、常见配置组合速查8.1 生产环境 API 客户端var options new RestClientOptions(https://api.example.com) { UserAgent MyCompany.Client/2.1, MaxTimeout 30_000, AutomaticDecompression DecompressionMethods.GZip | DecompressionMethods.Deflate, FollowRedirects true, MaxRedirects 5, FailOnDeserializationError true, ThrowOnDeserializationError false, AllowMultipleDefaultParametersWithSameName false }; var client new RestClient(options);8.2 接受自签名证书的客户端开发环境var options new RestClientOptions(https://dev-server.local) { RemoteCertificateValidationCallback (_, _, _, _) true }; var client new RestClient(options);8.3 通过代理访问外网var options new RestClientOptions(https://api.example.com) { Proxy new WebProxy(http://proxy.corp:8080) }; var client new RestClient(options);说明Proxy、RemoteCertificateValidationCallback等仅作用于 RestSharp 自建 handler 的选项在注入外部HttpClient或启用SimpleClientFactory缓存命中后不会生效请结合前文选择合适方式。结语RestSharp 的配置体系可以归纳为三个层次构造器形态决定HttpClient/handler 的来源与生命周期RestClientOptions决定客户端级全局行为含 handler 底层配置RestRequest决定单次请求的局部行为。理解哪些选项作用于 RestSharp 代码、哪些作用于HttpMessageHandler以及选项实例化后不可变这两个关键约束就能在并发、代理、认证、超时、重定向等场景下写出正确且可维护的客户端配置。若需深入了解认证器、拦截器与序列化配置可继续阅读仓库中的 authenticators.md、interceptors.md 与 serialization.md。 /output_article赞分享后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载相关推荐在YAML前端设置中切换背景在YAML前端设置中切换背景 banner: ! faroukhomepage.png 白天模式 banner: ! faroukhomepage2.p后端API设计RestSharp 高级配置完全指南从 RestClientOptions 到重定向与超时控制RestSharp 高级配置完全指南从 RestClientOptions 到重定向与超时控制 导读 本文以 RestSharp v114 官方配置文档为骨架后端API设计RestSharp v110 快速上手从安装到首个 HTTP 请求的完整实战指南RestSharp v110 快速上手从安装到首个 HTTP 请求的完整实战指南 本篇指南以 RestSharp v110 版本文档中的《Quick star后端API设计上一篇HyperAI超神经一站式AI技术探索与实践平台全解析下一篇s2n-tls安全更新策略如何保持你的TLS实现始终处于最安全状态创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考