RestSharp 拦截器（Interceptor）完全指南：从请求拦截到兼容迁移

后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载本指南基于 RestSharp v111 文档体系中的拦截器Interceptors主题系统讲解拦截器机制的五个可重写生命周期方法、在客户端与请求两个层面的注册方式、执行顺序规则以及从旧版请求钩子Request Hooks向拦截器迁移的兼容方案。读完本文你将能够自定义请求头、改写请求体、提前取消请求、在反序列化前修正响应内容并顺畅完成旧钩子代码的升级。拦截器是什么请求与响应生命周期中的挂载点拦截器Interceptor是 RestSharp 提供的一套请求/响应生命周期钩子机制允许开发者在请求被发送之前和响应被返回给调用方之前介入并修改请求与响应。典型用途包括为请求附加自定义 Header如 Authorization、X-Request-Id修改请求体Body内容在请求发出前直接取消请求在响应返回给调用方之前改写响应内容。从源码结构看拦截器的核心实现位于 src/RestSharp/Interceptors/Interceptor.cs它是所有拦截器的抽象基类配套的兼容迁移类位于 src/RestSharp/Interceptors/CompatibilityInterceptor.cs。拦截器在 RestClient.Async.cs 的请求执行管线中被依次调用是 RestSharp 请求流程中一处统一、可组合的扩展点。实现一个拦截器继承 Interceptor 基类要实现拦截器只需创建一个继承Interceptor抽象基类的类即可。基类将所有拦截方法实现为virtual因此你可以按需只重写关心的方法未重写的方法不会干扰请求流程。可重写的五个生命周期方法方法签名要点触发时机BeforeRequestValueTask BeforeRequest(RestRequest request, CancellationToken cancellationToken)在组装HttpRequestMessage之前此时仍可操作RestRequest对象BeforeHttpRequestValueTask BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken)在HttpRequestMessage即将被发送之前可修改消息头、内容等AfterHttpRequestValueTask AfterHttpRequest(HttpResponseMessage responseMessage, CancellationToken cancellationToken)在收到远程服务器的HttpResponseMessage之后AfterRequestValueTask AfterRequest(RestResponse response, CancellationToken cancellationToken)在由HttpResponseMessage构造出RestResponse之后BeforeDeserializationValueTask BeforeDeserialization(RestResponse response, CancellationToken cancellationToken)在反序列化之前使用非泛型ExecuteAsync时不会被调用见 Interceptor.cs 的注释说明这五个方法全部要求返回ValueTask实例因此实现时可以同步返回ValueTask.CompletedTask也可以在方法体内使用async/await编写异步逻辑。最小示例为请求添加 Header// 该拦截器向请求添加一个 Header // 通常情况下你不必如此做因为 RestSharp 本身已提供添加 Header 的方法 class HeaderInterceptor(string headerName, string headerValue) : Interceptors.Interceptor { public override ValueTask BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken) { requestMessage.Headers.Add(headerName, headerValue); return ValueTask.CompletedTask; } }进阶示例异步逻辑与取消请求由于方法返回ValueTask内部完全可以使用async/await。例如在BeforeRequest中做异步校验并在失败时抛异常中断请求class ValidatingInterceptor : Interceptors.Interceptor { public override async ValueTask BeforeRequest(RestRequest request, CancellationToken cancellationToken) { // 这里可以执行异步校验逻辑 await Task.Delay(10, cancellationToken); if (request.Resource ! /allowed) { throw new InvalidOperationException(该资源不允许访问); } } }值得注意的细节拦截器方法抛出异常会直接终止该请求的执行链。集成测试 test/RestSharp.Tests.Integrated/Interceptor/InterceptorTests.cs 中的ThrowExceptionIn_InterceptBeforeRequest等用例验证了这一点——在BeforeRequest抛出异常后后续的BeforeHttpRequest、AfterHttpRequest、AfterRequest、BeforeDeserialization均不会被调用异常会向调用方传播详见 InterceptorTests.cs。使用拦截器客户端级与请求级注册拦截器既可以注册在客户端Client上也可以注册在单个请求Request上两者可以同时使用且数量不限。拦截器按照被添加的顺序依次执行。通过客户端选项注册作用于该客户端的每一次请求var options new RestClientOptions(https://api.example.com) { Interceptors [new HeaderInterceptor(Authorization, token)] }; var client new RestClient(options);RestClientOptions.Interceptors属性的类型为ListInterceptor默认初始化为空列表定义见 RestClientOptions.cs。注册到客户端的拦截器会应用于该客户端发起的每一个请求。通过请求属性注册仅作用于单个请求var request new RestRequest(resource) { Interceptors [new HeaderInterceptor(Authorization, token)] };此场景下拦截器只会对该特定请求生效。RestRequest.Interceptors的类型同样为ListInterceptor见 RestRequest.cs。客户端拦截器与请求拦截器的组合逻辑当客户端与请求同时配置了拦截器时RestSharp 在请求执行时会先合并两者。核心逻辑位于 RestClient.Async.cs 的CombineInterceptors方法若请求自身没有拦截器则直接使用客户端的拦截器列表副本若请求自身有拦截器则将客户端的拦截器追加到请求拦截器列表末尾。也就是说最终执行顺序为请求级拦截器先执行客户端级拦截器后执行。集成测试中的Should_call_both_client_and_request_interceptors用例同时验证了两者都会被依次调用见 InterceptorTests.cs。拦截器在请求管线中的实际调用顺序结合 RestClient.Async.cs 的ExecuteRequestAsyncL94-L165与五个静态分发方法L359-L389一次泛型请求的完整拦截器调用链如下CombineInterceptors合并客户端级与请求级拦截器L105OnBeforeRequest→ 逐个调用BeforeRequest(RestRequest, ...)L106校验参数、执行认证器Authenticator构建HttpRequestMessage与请求体OnBeforeHttpRequest→ 逐个调用BeforeHttpRequest(HttpRequestMessage, ...)L148发送请求并跟随重定向OnAfterHttpRequest→ 逐个调用AfterHttpRequest(HttpResponseMessage, ...)L163构造RestResponseOnAfterRequest→ 逐个调用AfterRequest(RestResponse, ...)若是泛型请求如ExecuteAsyncT在反序列化前由 RestSerializers.cs 中的OnBeforeDeserialization逐个调用BeforeDeserialization(RestResponse, ...)。其中第 10 步只有通过泛型执行方法ExecuteAsyncT/ExecuteGetAsyncT等触发反序列化时才会发生这与 Interceptor.cs 中对该方法的注释一致而旧的OnBeforeDeserialization钩子则仍在 RestSerializers.cs 中以兼容模式被调用。弃用通知从旧请求钩子迁移到拦截器RestSharp v111.0 之前的版本提供的请求钩子Request Hooks已被标记Obsolete未来将被移除。拦截器旨在取代这套旧机制。如果你仍在用旧钩子官方建议尽快迁移到拦截器。当前 RestRequest.cs 中标记弃用的旧钩子包括OnBeforeDeserialization反序列化前回调OnBeforeRequest发送请求前回调OnAfterRequest请求完成后回调。使用 CompatibilityInterceptor 平滑迁移为降低迁移成本RestSharp 提供了CompatibilityInterceptor类。它把旧钩子包装成拦截器属性让你不必改动既有业务逻辑即可迁移。该类定义见 CompatibilityInterceptor.cs其暴露的属性与基类重写方法的对应关系如下CompatibilityInterceptor 属性类型内部映射到的拦截器方法OnBeforeDeserializationActionRestResponse?BeforeDeserializationOnBeforeRequestFuncHttpRequestMessage, ValueTask?BeforeHttpRequestOnAfterRequestFuncHttpResponseMessage, ValueTask?AfterHttpRequest该类的内部实现CompatibilityInterceptor.cs正是将上述三个旧钩子委托给对应的新拦截器方法OnBeforeDeserialization被同步调用OnBeforeRequest与OnAfterRequest被await后调用。迁移示例旧钩子 → 拦截器迁移前使用旧钩子var request new RestRequest(success); request.OnBeforeDeserialization _ throw new Exception(exceptionMessage);迁移后使用拦截器逻辑完全等价var request new RestRequest(success) { Interceptors [new CompatibilityInterceptor { OnBeforeDeserialization _ throw new Exception(exceptionMessage) }] };这套兼容方案可以逐请求、渐进式地完成迁移把旧的OnBeforeRequest、OnAfterRequest赋值迁移为CompatibilityInterceptor内对应属性即可保留原有逻辑并接入新的拦截器管线之后再按需拆分或替换为自定义拦截器类。实际应用场景与最佳实践结合仓库源码与集成测试以下几个场景最能发挥拦截器价值统一注入认证头将HeaderInterceptor注册到客户端为客户端的所有请求统一附加 Token避免在每个请求上重复添加请求级特殊处理对特定请求单独注册拦截器如临时调试、指定接口的特殊 Header不影响其他请求响应后置处理在AfterHttpRequest或AfterRequest中读取响应状态、统计耗时、记录日志或对错误响应做统一处理反序列化前修正数据在BeforeDeserialization中基于原始响应内容如占位符替换、格式清洗修正数据再交给反序列化器取消请求在任意前置阶段根据业务条件抛出异常或检查CancellationToken中断请求流程。实践建议拦截器按添加顺序执行因此注册顺序即执行顺序对顺序敏感的逻辑如先加认证头再签名要注意排列BeforeDeserialization仅在泛型执行方法ExecuteAsyncT中触发非泛型ExecuteAsync不会调用勿依赖它在非泛型场景生效拦截器中抛出的异常会中断后续拦截器与请求发送集成测试 InterceptorTests.cs 的多个ThrowExceptionIn_*用例可作为行为参考旧钩子虽然当前仍可用但已被标记Obsolete新代码应直接使用拦截器旧代码应通过CompatibilityInterceptor尽快迁移。相关资源本文档对应的当前版本docs/docs/advanced/interceptors.md拦截器基类源码src/RestSharp/Interceptors/Interceptor.cs兼容迁移类源码src/RestSharp/Interceptors/CompatibilityInterceptor.cs客户端选项与拦截器注册src/RestSharp/Options/RestClientOptions.cs请求级拦截器属性src/RestSharp/Request/RestRequest.cs拦截器调用管线实现src/RestSharp/RestClient.Async.cs反序列化前拦截src/RestSharp/Serializers/RestSerializers.cs集成测试test/RestSharp.Tests.Integrated/Interceptor/InterceptorTests.cs、test/RestSharp.Tests.Integrated/Interceptor/TestInterceptor.cs赞分享后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载相关推荐RestSharp 拦截器Interceptor完整指南在请求发送前后拦截、修改与取消 HTTP 调用RestSharp 拦截器Interceptor完整指南在请求发送前后拦截、修改与取消 HTTP 调用 RestSharp 的 Interceptors后端API设计Puppeteer 请求拦截完全指南从基础拦截到 Cooperative Intercept Mode 协作式拦截Puppeteer 请求拦截完全指南从基础拦截到 Cooperative Intercept Mode 协作式拦截 /DSMLtool /DS浏览器控制测试网页爬虫开发工具Hutool请求拦截HTTP请求响应拦截Hutool请求拦截HTTP请求响应拦截 还在为HTTP请求的全局处理而烦恼每次都要手动添加相同的header、记录日志、处理异常Hutool的HTTP拦后端开发工具上一篇RackTables性能优化大规模部署的实战经验下一篇技术深度解析Slidev的虚拟模块架构与实时编译机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考