RestSharp 拦截器（Interceptor）完整指南：在请求与响应生命周期中嵌入自定义逻辑

RestSharp 拦截器Interceptor完整指南在请求与响应生命周期中嵌入自定义逻辑【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址: https://gitcode.com/gh_mirrors/re/RestSharp导读RestSharp 的拦截器Interceptor机制允许开发者在请求发送前、响应返回后的各个生命周期节点插入自定义逻辑用于统一添加请求头、改写请求体、校验或修正响应甚至中止一次请求。本指南以 RestSharp 113 及后续版本文档为核心结合仓库源码与集成测试讲解拦截器的五种可重写方法、客户端级与请求级的注册方式、执行顺序以及如何利用CompatibilityInterceptor平滑迁移旧版请求钩子。读完本文你将能够在自己的 .NET 项目中熟练编写、注册并调试 RestSharp 拦截器。什么是拦截器贯穿请求生命周期的钩子RestSharp 的拦截器是一组在 HTTP 请求组装、发送、响应接收与反序列化等阶段被回调的钩子。它相比传统请求参数能力更通用——不仅可以修改请求本身还可以访问并修改底层HttpRequestMessage/HttpResponseMessage这是普通参数 API 无法触及的层面。文档明确列出了拦截器的适用场景在请求发出前添加自定义 Header修改请求体Body取消请求在响应返回给调用方之前修改响应。拦截器的基类位于 Interceptor.cs是RestSharp.Interceptors命名空间下的一个抽象类所有钩子方法均以virtual声明并带有空实现因此你只需要继承它并按需覆写感兴趣的方法即可。五种可重写方法及其生命周期位置根据 Interceptor.cs 的源码与 XML 注释你可以覆写以下方法方法触发时机参数BeforeRequest在组装请求消息compose request message之前即请求参数校验、认证与 URL 构建之前RestRequest request, CancellationTokenBeforeHttpRequestHttpRequestMessage发送给服务器之前HttpRequestMessage, CancellationTokenAfterHttpRequest从远程服务器收到HttpResponseMessage之后、尚未包装成RestResponse之前HttpResponseMessage, CancellationTokenAfterRequestRestResponse从HttpResponseMessage构建完成之后RestResponse, CancellationTokenBeforeDeserialization反序列化开始之前仅使用泛型ExecuteAsyncT等泛型执行方法时触发RestResponse, CancellationToken所有方法都必须返回ValueTask实例。在源码中的实际调用点将上述方法映射到请求执行主链路可以从 RestClient.Async.cs 的ExecuteRequestAsync中看到它们的真实执行位置与先后顺序CombineInterceptors(request)——合并客户端级与请求级拦截器见下文执行顺序OnBeforeRequest(request, ct)——调用所有拦截器的BeforeRequest请求参数校验、认证器执行构建 URL 与HttpRequestMessage含 Content、Host、CacheControl、Headers 等旧版request.OnBeforeRequestObsolete 钩子执行OnBeforeHttpRequest(request, message, ct)——调用BeforeHttpRequest发送请求含重定向处理SendWithRedirectsAsync旧版request.OnAfterRequestObsolete 钩子执行OnAfterHttpRequest(request, responseMessage, ct)——调用AfterHttpRequest组装RestResponseOnAfterRequest(response, ct)——调用AfterRequest。反序列化阶段则位于 RestSerializers.cs泛型反序列化前先调用所有拦截器的BeforeDeserialization再执行旧版request.OnBeforeDeserialization最后进入DeserializeContentT。需要特别留意的是BeforeDeserialization的触发条件基类注释明确说明wont be called if using non-generic ExecuteAsync即只有使用ExecuteAsyncT这类泛型执行方法、真正发生反序列化时才会回调这与测试用例InterceptorTests中使用ExecutePostAsyncTestResponse验证该方法的做法一致。实现一个拦截器从加 Header 的示例说起文档给出了一个最经典的示例——在请求发出前为HttpRequestMessage添加 Header// This interceptor adds a header to the request // Youd not normally use this interceptor, as RestSharp already has a method // to add headers to the request class HeaderInterceptor(string headerName, string headerValue) : Interceptors.Interceptor { public override ValueTask BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken) { requestMessage.Headers.Add(headerName, headerValue); return ValueTask.CompletedTask; } }几个值得展开的要点主构造函数示例使用了 C# 12 的主构造函数语法string headerName, string headerValue直接把配置参数注入拦截器让拦截器实例可复用、可配置直接操作HttpRequestMessage.HeadersBeforeHttpRequest拿到的是即将发送的真实 HTTP 消息因此可以修改 Headers、改写 Content、甚至调整 URI返回ValueTask.CompletedTask同步逻辑用ValueTask.CompletedTask表示已完成因为方法返回ValueTask你完全可以在方法体内使用async/await把异步操作如调用远程配置服务、读取密钥嵌入生命周期命名空间示例中的Interceptors.Interceptor即RestSharp.Interceptors.Interceptor仓库里 RestSharp.csproj 下该命名空间默认可用。说明文档特意提醒普通场景下添加请求头不必写拦截器——RestSharp 本身就提供了AddHeader等参数 API。拦截器的价值在于横切逻辑多个请求、多个客户端共享同一套处理规则。一个完整的日志 校验拦截器示例结合源码中TestInterceptorTestInterceptor.cs的覆写风格一个同时覆盖多个阶段、使用异步逻辑的拦截器大致如下class LoggingInterceptor : Interceptors.Interceptor { public override async ValueTask BeforeRequest(RestRequest request, CancellationToken cancellationToken) { Console.WriteLine($[BeforeRequest] {request.Method} {request.Resource}); await Task.CompletedTask; } public override async ValueTask BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken) { Console.WriteLine($[BeforeHttpRequest] {requestMessage.Method} {requestMessage.RequestUri}); // 例如在这里改写请求体 // requestMessage.Content new StringContent(..., Encoding.UTF8, application/json); await Task.CompletedTask; } public override ValueTask AfterHttpRequest(HttpResponseMessage responseMessage, CancellationToken cancellationToken) { Console.WriteLine($[AfterHttpRequest] {(int)responseMessage.StatusCode}); return base.AfterHttpRequest(responseMessage, cancellationToken); } public override ValueTask AfterRequest(RestResponse response, CancellationToken cancellationToken) { Console.WriteLine($[AfterRequest] {response.ResponseStatus}); return base.AfterRequest(response, cancellationToken); } public override ValueTask BeforeDeserialization(RestResponse response, CancellationToken cancellationToken) { Console.WriteLine($[BeforeDeserialization] content length: {response.Content?.Length}); return base.BeforeDeserialization(response, cancellationToken); } }这里体现了基类设计的一个重要细节每个虚方法默认返回一个已完成的ValueTask所以只覆写你关心的方法即可其余阶段自动空转覆写后如果不需要自定义返回值直接return base.XXX(...)是安全且推荐的做法与TestInterceptor的实现一致。注册拦截器客户端级、请求级与执行顺序文档强调拦截器可以按需添加任意多个既可以挂在客户端上也可以挂在单个请求上所有拦截器按照添加顺序执行。客户端级注册作用于该客户端的所有请求通过RestClientOptions.Interceptors集合注入var options new RestClientOptions(https://api.example.com) { Interceptors [new HeaderInterceptor(Authorization, token)] }; var client new RestClient(options);在 RestClientOptions.cs 中Interceptors被定义为ListInterceptor默认值为空集合[]。客户端级拦截器会对该客户端发起的每一个请求生效——典型的全局横切逻辑如统一鉴权、统一日志、统一错误上报都应放在这里。请求级注册仅作用于单个请求var request new RestRequest(resource) { Interceptors [new HeaderInterceptor(Authorization, token)] };在 RestRequest.cs 中请求级Interceptors是ListInterceptor?默认可为空。此方式适合只对特定请求生效的一次性逻辑。两者组合时的真实执行顺序当请求同时存在请求级与客户端级拦截器时两者的合并逻辑在 RestClient.Async.cs 的CombineInterceptors中实现void CombineInterceptors(RestRequest request) { if (request.Interceptors null) { if (Options.Interceptors null) return; request.Interceptors Options.Interceptors.ToList(); return; } if (Options.Interceptors ! null) { request.Interceptors.AddRange(Options.Interceptors); } }从源码可以推断出两条规则若请求未设置拦截器则直接使用客户端拦截器列表的副本ToList()保证不共享引用、避免并发修改问题若请求已设置拦截器则把客户端拦截器追加到请求拦截器之后。因此实际执行顺序为先按添加顺序执行请求级拦截器再按添加顺序执行客户端级拦截器。每个阶段BeforeRequest、BeforeHttpRequest等都是按这个合并后的顺序逐一遍历执行见 RestClient.Async.cs 中四个OnXXX静态方法的foreach循环。集成测试 InterceptorTests.cs 的Should_call_both_client_and_request_interceptors用例专门验证了客户端与请求拦截器会被同时调用。关于取消请求文档提到拦截器可以取消请求。从执行链路看所有拦截器方法都接收CancellationToken且每个阶段的回调是顺序await的——如果某个拦截器抛出异常例如抛出一个OperationCanceledException或业务异常执行链路会立即中断。测试ThrowExceptionIn_InterceptBeforeRequestInterceptorTests.cs证实在BeforeRequest中抛异常后BeforeHttpRequest、AfterHttpRequest、AfterRequest、BeforeDeserialization均不会被调用。你可以在拦截器中结合业务条件抛出异常来达到中止本次请求的效果。BeforeDeserialization反序列化前的最后一道关卡BeforeDeserialization是五个方法中最特殊的一个它在反序列化真正发生之前回调可以拿到尚未转换为目标类型的原始RestResponse。适用场景包括在解析前校验响应状态决定是否丢弃或改写内容对响应内容做预处理如解密、解包、字符集修正记录原始响应以便调试。其源码执行点在 RestSerializers.cs泛型反序列化入口DeserializeT中先await OnBeforeDeserialization(raw, ct)再进入内容解析。需要再次强调只有泛型执行方法如ExecuteAsyncT、ExecuteGetAsyncT才会触发此钩子非泛型的ExecuteAsync不会走反序列化路径因此该钩子不会被调用。从旧版请求钩子迁移CompatibilityInterceptorRestSharp 111.0 之前的请求钩子OnBeforeRequest、OnAfterRequest、OnBeforeDeserialization已在源码中标记为Obsolete见 RestRequest.cs弃用信息统一为Use Interceptors instead并将在未来版本移除。为了降低迁移成本RestSharp 提供了 CompatibilityInterceptor.cs它把旧钩子包装成拦截器属性让你在不改变原有业务逻辑的前提下完成迁移。迁移前后对照文档给出的例子——旧代码使用OnBeforeDeserialization钩子var request new RestRequest(success); request.OnBeforeDeserialization _ throw new Exception(exceptionMessage);迁移为拦截器写法var request new RestRequest(success) { Interceptors [new CompatibilityInterceptor { OnBeforeDeserialization _ throw new Exception(exceptionMessage) }] };CompatibilityInterceptor 支持的三个属性从源码可以看到CompatibilityInterceptor提供了与旧钩子一一对应的三个属性并在内部把它们桥接到对应阶段的拦截器方法旧钩子已弃用CompatibilityInterceptor 属性桥接的拦截器方法OnBeforeRequestFuncHttpRequestMessage, ValueTaskOnBeforeRequestBeforeHttpRequestOnAfterRequestFuncHttpResponseMessage, ValueTaskOnAfterRequestAfterHttpRequestOnBeforeDeserializationActionRestResponseOnBeforeDeserializationBeforeDeserialization注意一个易混淆点旧OnBeforeRequest的签名参数是HttpRequestMessage对应的是新拦截器的BeforeHttpRequest而非BeforeRequest旧OnAfterRequest参数是HttpResponseMessage对应AfterHttpRequest。迁移时请对照上表避免把委托挂错阶段。BeforeRequest与AfterRequest这两个操作RestRequest/RestResponse的阶段是拦截器新增的能力旧钩子中没有直接对应物。验证与调试仓库中的测试与实现路径如果你希望在集成到自己的项目前理解拦截器的完整行为仓库里已经有现成的测试与示例可参考拦截器基类Interceptor.cs —— 五个虚方法的默认实现与触发时机注释兼容迁移类CompatibilityInterceptor.cs —— 旧钩子到拦截器的桥接实现执行链路RestClient.Async.cs 与 RestSerializers.cs —— 各阶段回调的真实调用位置配置入口RestClientOptions.cs客户端级、RestRequest.cs请求级集成测试InterceptorTests.cs 与 TestInterceptor.cs —— 覆盖客户端级与请求级同时调用异常中断后续阶段等关键行为可直接作为你编写自测用例的模板。小结RestSharp 拦截器是围绕请求生命周期设计的横切扩展点BeforeRequest→BeforeHttpRequest→发送→AfterHttpRequest→AfterRequest→BeforeDeserialization五个阶段分别覆盖了高层请求对象底层 HTTP 消息原始响应消息包装后的 RestResponse和反序列化前五个视角配合客户端级与请求级两级注册、按添加顺序执行的规则足以应对鉴权、日志、改写、校验、中止请求等绝大多数横切需求。若你的代码仍在使用 111.0 之前的旧钩子应尽快通过CompatibilityInterceptor迁移为旧钩子的最终移除提前做好准备。【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址: https://gitcode.com/gh_mirrors/re/RestSharp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考