后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载RestSharp 的拦截器Interceptors是一种在请求发送前后、响应返回前后对 HTTP 消息进行统一改造的机制可用来动态添加 Header、修改请求体、读取或改写响应甚至提前取消请求。本文围绕 RestSharp v114 版本文档 advanced/interceptors.md 展开结合 Interceptor.cs、RestClient.Async.cs 及集成测试源码讲解拦截器的五种钩子方法、客户端级与请求级两种挂载方式、执行顺序以及从旧版OnBeforeRequest等 Hook 迁移到拦截器的完整路径让你能直接在自己的 RestClient 项目中落地这套管线能力。拦截器是什么在请求管线的关键时刻介入拦截器是 RestSharp 提供的一套面向请求/响应生命周期的扩展点。它的核心价值在于你不需要改动 RestClient 或 RestRequest 的既有逻辑就能在请求被发送、响应被接收的各个阶段插入自定义代码用于添加 Header、修改请求体、改写响应甚至抛出异常来中断请求流程。从源码结构看拦截器体系由两个核心类型构成Interceptor抽象基类所有拦截器的父类将五个钩子方法全部实现为virtual默认直接返回一个已完成的ValueTask因此派生类只需按需重写CompatibilityInterceptor兼容迁移类把 v110 及更早版本的请求 Hook 属性包装成拦截器方便平滑升级。拦截器与 RestClientOptions、RestRequest 均通过Interceptors列表属性关联客户端级拦截器定义在 RestClientOptions.cs 中请求级拦截器定义在 RestRequest.cs 中。两者在执行前会被合并这一点在集成测试 Should_call_both_client_and_request_interceptors 中有直接验证。五个可重写的钩子方法按照文档定义继承Interceptor后可以重写以下五个方法它们全部要求返回ValueTask方法签名触发时机能拿到的对象BeforeRequest(RestRequest request, CancellationToken cancellationToken)请求消息组装之前完整的RestRequest含全部参数、Cookie、认证器等BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken)HttpRequestMessage被发送之前底层 HTTP 消息与原始 HeaderAfterHttpRequest(HttpResponseMessage responseMessage, CancellationToken cancellationToken)收到远端服务器的原始HttpResponseMessage之后原始 HTTP 响应AfterRequest(RestResponse response, CancellationToken cancellationToken)响应被包装成RestResponse之后高层响应对象BeforeDeserialization(RestResponse response, CancellationToken cancellationToken)反序列化之前仅泛型 ExecuteAsync 会触发RestResponse可用于修改响应后再交给反序列化器其中前四个方法在 Interceptor.cs 中都有完整的 XML 注释说明触发语义BeforeDeserialization的注释特别强调如果使用非泛型的ExecuteAsync该方法不会被调用因为只有泛型执行路径需要反序列化。生命周期执行顺序从 RestClient.Async.cs 的执行流程可以确认五个钩子的实际调用顺序CombineInterceptors先把客户端级与请求级拦截器合并见 RestClient.Async.cs调用OnBeforeRequest逐个执行各拦截器的BeforeRequestRestClient.Async.cs此时还可对RestRequest本身做修改经过参数校验、认证器执行、URL 构建与内容构建后在message.AddHeaders(headers)之后调用OnBeforeHttpRequestRestClient.Async.cs此时可操作最终的HttpRequestMessageSendWithRedirectsAsync发送请求拿到HttpResponseMessage后调用OnAfterHttpRequestRestClient.Async.cs响应包装成RestResponse后调用OnAfterRequestRestClient.Async.cs若走泛型反序列化路径RestSerializers会在调用反序列化器前执行BeforeDeserialization见 RestSerializers.cs。异常传播语义拦截器中抛出的异常会沿执行链向上传播。集成测试 InterceptorTests.cs 中的四个ThrowExceptionIn_*测试用例精确验证了这一行为在BeforeRequest中抛异常只有BeforeRequestCalled为 true请求根本不会继续InterceptorTests.cs在BeforeHttpRequest中抛异常BeforeRequest已执行请求不会发送InterceptorTests.cs在AfterHttpRequest中抛异常请求已发出响应不会继续包装InterceptorTests.cs在AfterRequest中抛异常后续的BeforeDeserialization不会执行InterceptorTests.cs。这组测试同时说明了一个实用技巧可以通过在某个钩子中抛出异常来主动中断请求例如在BeforeHttpRequest中根据业务规则拒绝发送。实现一个拦截器文档给出的最小示例是添加 Header 的HeaderInterceptor这里结合源码给出完整可运行的实现并补充一个说明由于请求级拦截器挂载的是ListInterceptor推荐显式写出using RestSharp.Interceptors;或全限定名using RestSharp.Interceptors; // 在 HttpRequestMessage 发送前追加一个自定义 Header // 实际项目中通常不需要手写这个拦截器RestSharp 自带 AddHeader 能力 class HeaderInterceptor(string headerName, string headerValue) : Interceptor { public override ValueTask BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken) { requestMessage.Headers.Add(headerName, headerValue); return ValueTask.CompletedTask; } }这里有几个值得注意的源码级细节基类所有方法默认返回Completed在 NET 平台即ValueTask.CompletedTask见 Interceptor.cs所以即使不重写也无需额外返回值因为钩子方法返回ValueTask方法体可以直接写成async从而使用await执行异步逻辑。例如在发送前异步拉取令牌class TokenInjectingInterceptor(TokenProvider provider) : Interceptor { public override async ValueTask BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken) { var token await provider.GetTokenAsync(cancellationToken); requestMessage.Headers.Authorization new System.Net.Http.Headers.AuthenticationHeaderValue(Bearer, token); } }五个钩子拿到的对象层级不同想修改 RestRequest 层面的参数如AddHeader、AddParameter用BeforeRequest想直接操纵底层 HTTP 消息用BeforeHttpRequest/AfterHttpRequest想在响应返回给调用方之前统一加工如补全字段、记录状态码用AfterRequest/BeforeDeserialization。挂载拦截器客户端级与请求级文档明确拦截器可以任意添加多个既可以在客户端上也可以在请求上并且按添加顺序执行。集成测试 TestInterceptor.cs 中的实现类同时重写了五个钩子正好可作为验证执行顺序的参考。客户端级拦截器通过RestClientOptions.Interceptors集合添加对该客户端发起的所有请求生效var options new RestClientOptions(https://api.example.com) { Interceptors [new HeaderInterceptor(Authorization, token)] }; var client new RestClient(options);在源码中客户端级拦截器最终会被读取为只读集合ReadOnlyRestClientOptions.cs 在快照选项时会把RestClientOptions.Interceptors拷贝成ReadOnlyCollectionInterceptor。请求级拦截器只对某一个RestRequest生效适合一次性、局部性的改造var request new RestRequest(resource) { Interceptors [new HeaderInterceptor(Authorization, token)] };两级同时存在时的合并行为两者的执行顺序有明确的实现依据。CombineInterceptors的逻辑是RestClient.Async.cs若请求没有设置Interceptors直接把客户端级拦截器列表整体赋给请求若请求已设置拦截器则在请求级拦截器之后追加客户端级拦截器request.Interceptors.AddRange(Options.Interceptors)。也就是说请求级拦截器先执行客户端级拦截器后执行。集成测试 Should_call_both_client_and_request_interceptors 验证了两级拦截器都会被执行Should_call_client_interceptor 则验证了客户端级拦截器只配置在 options 上时同样五个钩子全部触发。从旧版 Hook 迁移CompatibilityInterceptor为什么需要迁移RestSharp 在 111.0 版本开始用拦截器取代旧版请求 Hook。旧 Hook 仍然存在于 RestRequest.cs 中但已被标记为ObsoleteOnBeforeDeserializationRestRequest.csOnBeforeRequestRestRequest.csOnAfterRequestRestRequest.cs三个属性上的特性消息均为Use Interceptors instead。这些旧 Hook 会在未来版本中被移除因此文档建议尽快迁移。有意思的是从 RestClient.Async.cs 和 RestSerializers.cs 可以看到旧 Hook 的调用点目前仍然保留并用#pragma warning disable CS0618压制了过时警告说明 RestSharp 在迁移期内同时兼容两条路径为你逐步升级留出了时间窗口。使用 CompatibilityInterceptor 平移逻辑CompatibilityInterceptor继承了Interceptor并暴露了三个与旧 Hook 一一对应的属性CompatibilityInterceptor.cs旧 HookCompatibilityInterceptor 属性内部映射到OnBeforeRequestOnBeforeRequestFuncHttpRequestMessage, ValueTask?BeforeHttpRequestOnAfterRequestOnAfterRequestFuncHttpResponseMessage, ValueTask?AfterHttpRequestOnBeforeDeserializationOnBeforeDeserializationActionRestResponse?BeforeDeserialization其实现逻辑非常直接三个重写的钩子方法中如果对应属性非空就调用委托CompatibilityInterceptor.cs。因此迁移时只需把原来的 Hook 赋值语句原样搬进CompatibilityInterceptor的对象初始化器即可。文档给出的示例是迁移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) }] };逻辑完全平移行为一致该异常会在反序列化之前抛出。同理OnBeforeRequest与OnAfterRequest也可以按上面表格一一对应迁移// 迁移前 request.OnBeforeRequest msg { msg.Headers.Add(X-Trace, traceId); return ValueTask.CompletedTask; }; request.OnAfterRequest msg { Log(msg); return ValueTask.CompletedTask; }; // 迁移后 var request new RestRequest(success) { Interceptors [new CompatibilityInterceptor { OnBeforeRequest msg { msg.Headers.Add(X-Trace, traceId); return ValueTask.CompletedTask; }, OnAfterRequest msg { Log(msg); return ValueTask.CompletedTask; } }] };迁移策略建议综合文档与源码推荐按以下顺序完成迁移先引入CompatibilityInterceptor把旧 Hook 的委托原样平移确保行为零变化验证通过后逐步把CompatibilityInterceptor内的委托改写成Interceptor派生类中重写的钩子方法利用CancellationToken与ValueTask的原生异步能力最后删除旧的OnBeforeRequest/OnAfterRequest/OnBeforeDeserialization赋值代码消除编译警告。实战场景示例以下三个示例覆盖了拦截器最常见的用途均可在 v114 上直接编译运行。场景一统一注入认证头客户端级适合登录令牌动态刷新的场景配合async能力在每次请求前获取最新令牌class AuthInterceptor(FuncValueTaskstring tokenProvider) : Interceptor { public override async ValueTask BeforeHttpRequest(HttpRequestMessage requestMessage, CancellationToken cancellationToken) { var token await tokenProvider(); requestMessage.Headers.Authorization new(Bearer, token); } } var options new RestClientOptions(https://api.example.com) { Interceptors [new AuthInterceptor(async () await tokenService.GetAccessTokenAsync())] }; using var client new RestClient(options);场景二修改响应后再交给调用方请求级在AfterRequest中按业务规则改写RestResponse例如统一填充错误码说明字段class ErrorMessageInterceptor : Interceptor { public override ValueTask AfterRequest(RestResponse response, CancellationToken cancellationToken) { if (!response.IsSuccessful string.IsNullOrEmpty(response.ErrorMessage)) { response.ErrorMessage $HTTP {(int)response.StatusCode} {response.StatusDescription}; } return ValueTask.CompletedTask; } } var request new RestRequest(resource) { Interceptors [new ErrorMessageInterceptor()] };场景三在反序列化前干预原始内容BeforeDeserialization位于反序列化之前可用来做响应内容的预处理或校验。注意该钩子只在泛型ExecuteAsyncT路径上触发见 RestSerializers.csclass GuardInterceptor : Interceptor { public override ValueTask BeforeDeserialization(RestResponse response, CancellationToken cancellationToken) { if (response.StatusCode System.Net.HttpStatusCode.Unauthorized) { throw new UnauthorizedAccessException(Token expired, please re-authenticate); } return ValueTask.CompletedTask; } }小结RestSharp 的拦截器机制围绕五个ValueTask钩子方法构建覆盖了从RestRequest组装、HttpRequestMessage发送、HttpResponseMessage接收到RestResponse包装与反序列化的完整生命周期客户端级与请求级两种挂载方式配合请求级优先、客户端级随后的合并顺序使其既适合全局横切逻辑也适合单次请求的定制改造CompatibilityInterceptor则为旧版 Hook 提供了零成本迁移通道。若需深入验证上述行为可直接阅读 InterceptorTests.cs 与 TestInterceptor.cs 两处集成测试。赞分享后端API设计【免费下载链接】RestSharpSimple REST and HTTP API Client for .NET项目地址https://gitcode.com/gh_mirrors/re/RestSharp点击查看免费下载相关推荐RestSharp Interceptors 完全指南拦截请求与响应、生命周期与旧版 Hook 迁移RestSharp Interceptors 完全指南拦截请求与响应、生命周期与旧版 Hook 迁移 Interceptors拦截器是 RestSharp后端API设计Fastify Hooks 完整指南从请求生命周期钩子到应用级钩子的全解析Fastify Hooks 完整指南从请求生命周期钩子到应用级钩子的全解析 导读Fastify 通过 fastify.addHook 向开发者暴露一套完整的后端Web框架OpenClaw 插件钩子Plugin Hooks完全指南拦截、改写与生命周期控制OpenClaw 插件钩子Plugin Hooks完全指南拦截、改写与生命周期控制 OpenClaw 的插件钩子系统允许原生插件在 agent 运行、工具AI 应用AI Agent交互助手后端即时通讯网关上一篇Anime.js终极指南掌握现代JavaScript动画引擎的核心技术下一篇Relay 连接更新实战使用 ConnectionHandler 与声明式指令增删 Connection 边创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
