你有没有遇到过这种场景一个接口请求发出去要带token、要加签名、要打日志、要处理错误码、要考虑超时重试还得在页面跳转时带上来源参数。如果你在每个调用点都手动写一遍代码能臭到让人怀疑人生。我之前在某项目里就是活生生的例子——同一个请求函数里塞了七八层逻辑后来加了新需求想改超时策略愣是改了三天才把所有调用点找齐。后来我才彻底想明白这种事情就得用请求响应拦截器链来统一收口把横切逻辑从业务代码里剥出去让请求层变成一个可插拔、可组合、可调试的管道。这篇文章我从头到尾讲讲我设计和维护一条20级拦截器链条的完整思路包括链条怎么分、顺序怎么排、上下文怎么传、异常怎么兜底、性能怎么测以及我踩过的一堆坑。不管你是用框架自带的拦截器机制还是打算自研一套HTTP层中间件这里面大部分思路都能直接用。1. 拦截器链到底是什么以及它解决的三个核心问题1.1 一句话解释拦截器链拦截器链不是一个具体的库而是一种把“请求前处理”和“响应后处理”串成一条流水线的架构模式。你可以想象快递分拣线包裹请求进入传送带经过扫码鉴权、称重日志、贴单签名、安检校验等多个工位每个工位只做一件事做完传给下一个工位。响应回来之后反向再走一条质检通道。在这条链上每一个节点就是一个拦截器它负责接收上游传来的请求配置做自己的事情然后决定继续往下传还是直接短路返回。1.2 它解决的核心问题第一个问题是重复代码。没有拦截器的时候每个业务请求都要自己拼header、自己判断网络错误、自己弹toast。有了拦截器链这些横切逻辑收敛到一层业务代码里干干净净。第二个问题是顺序控制。真实项目中token刷新必须在签名之前日志埋点必须在鉴权之后重试逻辑必须在错误处理之前。拦截器链把顺序显式化每个环节的先后关系一目了然而不是散落在各种工具函数里靠命名约定维持。第三个问题是链路追踪能力。一条可编排的链意味着你可以知道请求在哪个环节耗时最长、在哪个环节被拦截了、为什么被拦截。排查问题的时候你能按图索骥而不是打开一堆日志靠猜。1.3 20条链是不是真的越多越好这里要说明一点。我当年设计的时候一开始只规划了7个拦截器后面业务扩张、安全需求增加慢慢加到了20条。很多人听到“20”会觉得夸张但我实际体会是只要每一条拦截器的职责足够单一链条长并不可怕可怕的是职责混杂、顺序混乱、上下文共享一团糟。真正合理的状态是每条链的命名就是它的职责你在链路配置里一眼就能看出来整个请求生命周期经历了什么。我做的那条链最终按功能分成四组前置基础组请求标识、超时控制、安全认证组token注入、签名、加密、语义处理组参数规范化、幂等键、防重复提交、响应后处理组状态码分流、错误映射、重试、埋点、兜底文案。每条链一个文件一个类一个职责。2. 拦截器链的总体设计与顺序决策2.1 分层拆解请求链与响应链怎么分我习惯把链路拆成请求链和响应链两条但它们在上下文上共享同一个对象。请求链按顺序执行一旦有拦截器抛出异常或主动中断后续请求链不再执行直接进入响应链的错误处理分支。响应链也不是只有成功路径。我把它分成成功处理链和异常处理链异常处理链会先经过错误归类器把网络异常、超时异常、业务码异常、序列化异常分别映射到不同类型的错误对象之后再走重试判断、用户提示、日志上报这些动作。这里有一个容易犯的错误把重试逻辑放在成功处理链里。我在项目里见过有人这么搞结果接口返回业务错误码时也触发了重试导致下单接口重复提交。重试逻辑只应该放在明确的异常分支里而且必须配合幂等键使用。2.2 顺序怎么定三个原则顺序设计我总结出三个原则。第一原则无依赖的靠前有依赖的靠后。比如请求标识生成不依赖任何其他信息就放在第一位。token注入依赖认证状态管理器所以放在登录态检查之后。第二原则凡是可能修改请求体的操作尽量靠前但要在签名之前完成。因为签名是对请求体做哈希的如果你在签名之后又改了请求体签名就失效了这个坑我们踩过不止一次。第三原则异常处理放在最外层重试放在异常处理之前。也就是说请求链执行完进入响应环节之后顺序是状态码判断 - 错误分类 - 重试判断 - 用户提示 - 全局日志。如果重试放在错误分类前面你就没法区分哪些错误值得重试比如参数校验错误也去重试那就是浪费资源。2.3 上下文传递用Context对象解决参数共享20条链之间怎么共享数据答案是不能用全局变量必须用请求级上下文对象。我定义了一个Context结构包含requestConfig、responseData、errorInfo、retryCount、startTime、duration、traceId、extraMap。每个拦截器只操作Context不直接修改原始请求对象。这样做的好处是你可以在不影响全局配置的前提下临时改动某次请求的行为。比如某个导出接口因为数据量大全局超时是10秒但这个请求需要60秒你就可以在这个请求初始化时往Context的extraMap里塞一个timeout字段超时拦截器会优先读取这个字段覆盖全局配置。这就是链路设计里“局部覆盖全局”的典型手法。3. 20条拦截器的具体职责拆解3.1 请求链的10个节点逐个说明我先说请求链这部分一共10个拦截器按执行顺序排列。第一个是请求标识生成器。它给每次请求生成全局唯一的traceId并写入header。这个traceId会透传到服务端服务端日志也打这个ID排查问题时可以一链到底。我们当时是基于UUID加上时间戳随机数生成避免并发冲突。第二个是超时控制器。它会读取Context里的自定义超时时间没有就用全局默认。这个拦截器实际做的事情是初始化一个超时信号在后续真正发请求时通过Promise.race来实现超时中断。第三个是请求序列化器。统一处理GET参数的序列化风格、POST的body编码格式。为啥要单独一条链因为后端接口风格不统一有的要form-data有的要JSON有的要query参数拼数组。序列化器根据每个接口声明的contentType来做转换。第四个是认证状态检查器。它检查当前请求是否需要登录态。白名单接口直接放行需要鉴权的接口如果本地没有token就走匿名异常通道不发请求直接返回401错误。第五个是token注入器。它从认证管理器拿accessToken放进Authorization头。这里有个细节token刷新逻辑不在这里因为刷新动作可能会失败失败之后需要重新走一遍请求链放这里是循环依赖。第六个是签名器。负责按照约定规则拼接请求参数生成签名串然后加进header。这个环节要求前面的序列化器已经把参数整理成最终形态。签名算法是公司内部约定的不做赘述但思路就是参数排序加盐加时间戳做哈希。第七个是请求加密器。针对敏感字段做加密比如身份证号、手机号。它只对配置了加密的接口生效。加密器在签名之后的原因是服务端校验签名时用的是密文字段如果先签名再加密服务端拿到的是加密后的原文签名就对不上。所以顺序不能随意换。第八个是幂等键生成器。对写操作接口生成一个基于用户ID加时间戳加随机数的幂等键存放在header里。这个是给后面重试用的关键凭据。第九个是防重复提交器。它维护一个滑动窗口记录最近N秒内的请求指纹。请求指纹是把URL、参数、幂等键做个哈希。如果窗口内命中相同的哈希直接终止链路并提示“操作太频繁”。第十个是最终请求发射器。其实它不算真正的拦截器而是一个终结节点它拿到经过前面所有拦截器加工后的Context执行真正的HTTP发送动作并把Promise传递给响应链。3.2 响应链的10个节点逐个说明响应链同样有10个节点其中7个是成功处理3个是异常处理但异常处理里有嵌套分支。我按优先级来排。响应链第一个是状态码分流器。它先看HTTP状态码200系列走成功链其余走异常链。但这个分流不是一下到底的它会把异常响应体缓存下来供后续错误映射使用。第二个是业务码解码器。进入成功链后并不是所有200都是真的成功业务码才代表语义成功。比如HTTP 200但body里code是5000这种属于业务逻辑异常需要把它转入特殊异常通道。第三个是数据解包器。如果接口做了统一包装比如data、message、traceId这种结构解包器在这里把外层剥掉只把业务数据传给下游。第四个是响应解密器。对应请求链的加密器如果某个接口的响应是密文这里做解密。解密失败会走异常通道并且不会触达业务层。第五个是数据转换器。统一处理字段命名转换比如下划线转驼峰、日期字符串转Date对象、分转元。这个环节放在解密之后确保业务层拿到的数据已经是可直接使用的形态。第六个是成功埋点器。记录接口耗时、状态、数据量异步上报给监控系统。埋点逻辑不能阻塞主流程我们用的是异步队列失败也不影响业务。第七个是缓存写入器。针对GET类型并且声明了可缓存的接口把响应数据写入本地缓存。写缓存也是异步的但回填的逻辑有一点复杂后面说坑。然后是异常链。异常链第一个是网络错误分类器。把断网、DNS解析失败、连接超时、服务端5xx、4xx等不同的错误类型归为不同的错误类。这个分类决定了后续是否值得重试。第二个是重试裁决器。它根据当前错误类型、请求方法、重试次数上限、幂等键是否存在综合判断要不要重试。重试不是无限重试我们会从Context读取retryCount超过上限就放弃。重试时会把当前Context的retryCount加一然后重新执行整条请求链而不是只重发HTTP请求这样签名、token都会重新生成保证一致性。第三个是用户提示映射器。把错误码映射成用户可以理解的中文提示比如“网络不给力请稍后再试”。这里有一个原则技术错误信息不能直接弹给用户必须经过映射。第四个兜底日志器。所有走到这里的请求统一错误日志包含请求链各节点耗时、哪一步中断、错误堆栈。这个日志是事后排查最重要的数据来源。4. 完整代码结构与核心实现要点4.1 拦截器接口与链路执行器先看拦截器的统一接口。我用的是TypeScript但去掉类型声明也一样。每个拦截器只需要实现两个方法intercept和getName。getName用来做链路标识排查问题时你能精确知道是哪一环出了问题。interface Interceptor { // 每个拦截器返回布尔值true表示继续false表示中断 // 也可以通过抛出异常中断 intercept(ctx: RequestContext): Promiseboolean; getName(): string; }链路执行器维护两个数组requestInterceptors和responseInterceptors。它按顺序依次await每个拦截器的intercept方法一旦返回false或抛异常就停止跳转到响应链对应的异常分支。class InterceptorChain { private requestChain: Interceptor[] []; private successChain: Interceptor[] []; private errorChain: Interceptor[] []; async executeRequest(ctx: RequestContext): PromiseResponseContext { for (const interceptor of this.requestChain) { const shouldContinue await interceptor.intercept(ctx); if (!shouldContinue) { return this.executeErrorChain(ctx, new InterruptError(interceptor.getName())); } } return this.executeHttpRequest(ctx); } }4.2 请求发射器与超时控制请求发射器是请求链的终点节点。它接收Context发起真实请求。这里我用了一个超时封装器基于Promise.race实现。function fireRequest(ctx: RequestContext): PromiseResponseContext { const timeout ctx.extraMap.get(timeout) ?? 10000; const controller new AbortController(); return new Promise((resolve, reject) { const timer setTimeout(() { controller.abort(); reject(new TimeoutError(ctx.traceId, timeout)); }, timeout); fetch(ctx.requestConfig.url, { method: ctx.requestConfig.method, body: ctx.requestConfig.data, headers: ctx.requestConfig.headers, signal: controller.signal, }) .then(async (res) { clearTimeout(timer); const body await res.json(); resolve({ status: res.status, headers: res.headers, data: body, ctx, }); }) .catch((err) { clearTimeout(timer); reject(normalizeNetworkError(err)); }); }); }4.3 重试机制的实现细节重试裁决器的核心逻辑我之前写了很长的一版后面简化成几个判断条件class RetryDecider { private maxRetryCount 2; async intercept(ctx: RequestContext): Promiseboolean { // 先在错误分类器之后取到 errorInfo const err ctx.errorInfo; const method ctx.requestConfig.method?.toUpperCase(); const retryable err.recoverable [GET, HEAD].includes(method); const hasIdempotent Boolean(ctx.requestConfig.headers.get(idempotent-key)); const reachedLimit ctx.retryCount this.maxRetryCount; if (retryable !reachedLimit (hasIdempotent || method GET)) { ctx.retryCount 1; // 重新走请求链 // 这里注意不能直接重新执行fireRequest要重新执行整个请求链 ctx.resetForRetry(); await executeRequest(ctx); return false; // 不再走下游响应链 } return true; } }重试时的重置动作很关键。resetForRetry会清除响应数据、恢复请求体到初始状态但不清空traceId和请求标识保证同一次业务请求的链路追踪ID一致。它还会把token重新刷新因为有可能第一次请求时token刚好过期了。4.4 缓存写入器碰到的坑缓存写入器在响应链里看起来简单但实际实现有个大坑缓存写入必须在数据转换之后否则你缓存下来的是未经转换的原始数据下一次命中缓存直接返回到业务层时就少了转换步骤。我第一次就写反了结果缓存命中的接口日期格式全是错的。解决办法是缓存写入器拿到的数据必须是经过转换器处理的最终数据并且在写入时同时保存数据版本号。业务层读取缓存时还要校验版本号是否匹配当前接口的转换规则版本如果缓存数据版本低直接丢弃重新请求。5. 我自己踩过的几个深坑5.1 签到一次接口请求三次这是排序问题导致的。我早期把重试逻辑放在状态码分流器之前结果一个响应超时的请求在重试时又执行了一次请求链。而请求链里有防重复提交器防重复提交器一看这个请求指纹在窗口内存在就中断了然后中断又触发了错误链错误链又走重试。这就是个死循环实际上发了三个请求才最终失败。后来我把重试放在错误分类之后并且给重试加上一次最大次数限制同时让防重复提交器在“重试中”的请求上放行一次才彻底解决。5.2 签名顺序的隐性依赖我们团队有一次在做字段加密时把加密器放在签名器前结果服务端验签失败率飙升。原因是服务端验签时用的是加密后的字段值而客户端签名时用的是加密前的明文。协议上两边不一致排查了半天才发现是顺序问题。这种问题在链路长的时候特别容易发生因为它不会直接报错而是表现为接口偶发失败。我现在有个习惯给每一条拦截器写清楚它依赖前序哪个节点的产物以及它自己会生成什么产物。整个链路配置就是一个声明式数组谁依赖谁一眼就能看出来新成员接手也不会猜。5.3 请求上下文被意外篡改因为所有拦截器都操作同一个Context对象如果某个拦截器直接修改了requestConfig.headers后续拦截器会感知到。这本来是设计好的但有人为了方便把业务状态存到了Context里导致同一个请求在不同拦截器里看到了不同的业务状态特别难查。我的规矩是Context.extraMap只能存不可变对象所有共享数据必须放在Context的固定字段里自定义字段一概不允许。代码评审时这条是红线。5.4 长尾请求的链路日志爆炸20条链每条链都打日志的话一次请求能打出几十行日志量大了之后日志系统先扛不住了。我们后来调整了日志等级策略正常成功请求只在链路最外层打一条汇总日志包含traceId、总耗时、各节点耗时明细只有异常请求才在每一层都打详细日志。这样日志量直接降了一个数量级排查问题时通过traceId又能拉全链路追踪信息。6. 性能调优与链路耗时观测6.1 异步拦截器的串行代价拦截器链最直接的性能隐患是每一条都是await串行执行的。20条链即使每条只消耗1毫秒最终影响也有20毫秒。对于接口动辄几百毫秒的场景20毫秒不算大但如果你在拦截器里做了同步加解密计算或者更糟——做了阻塞式IO操作那问题就大了。我踩过的一个坑是把日志上报的同步实现放在了埋点器里结果所有接口的响应时间平均多了30毫秒。后来把所有埋点、日志上报全部改成异步队列不阻塞主流程性能立刻恢复正常。6.2 用tracing收集每段耗时我在Context里内置了一个timing数组每个拦截器执行前记录一个时间戳执行后记录一个时间戳最后汇总输出。说白了就是给每条链打点。// context 里维护 timing async function runInterceptor(interceptor: Interceptor, ctx: RequestContext) { const start performance.now(); const result await interceptor.intercept(ctx); const end performance.now(); ctx.timings.push({ name: interceptor.getName(), durationMs: Number((end - start).toFixed(2)), }); return result; }这个耗时数据经过埋点器上报到监控平台后你可以直接看到token注入耗时异常、签名器耗时上涨、加密器计算时间过长这类具体问题。有一次签名器耗时从1毫秒涨到8毫秒排查发现是某次更新误把同步签名的库版本换成了异步版本链路因为await等待额外开销这种问题没有打点根本看不出。6.3 那些链可以并行执行不是所有拦截器都必须串行。在请求链里面请求标识生成器、超时控制器、序列化器这三者没有互相依赖可以并行。但为了链路可观测性和调试方便我最终仍然选择串行只是把这三个做了强化保证单个拦截器耗时在微秒级不让并行优化增加复杂度。响应链里有一个地方值得做并行成功埋点器和缓存写入器没有依赖关系但二者都是异步非阻塞的放在同一个位置也不会真串行阻塞太久。所以我没有做真正的并行化只用异步队列降低了阻塞经验是“优先减少单个拦截器的耗时而不是做并行。”7. 日志规范与排查手册7.1 统一日志格式链路日志必须有统一的字段模板不能各写各的。我定的模板包含traceId、userId、url、method、status、businessCode、retryCount、costMs、timings、errorType、errorMessage、interceptorName。日志尽量单行输出方便日志平台按traceId聚合。7.2 典型问题的排查路径日常排查最多的就是三类问题。第一类某个接口超时了。先看traceId再查看timing明细如果发现超时拦截器之前某个链耗时异常直接定位到那个拦截器。如果timing里没有异常说明请求根本没到业务服务端可能是网络层问题再看TCP连接耗时。第二类请求返回401。先看认证状态检查器是否把请求匿名放行了再看token注入器拿到的是不是过期token。一般来说token刷新机制如果出了问题重试比手动登录更有效因为重试会重新走一遍请求链再刷新token。第三类签名验签失败。第一步看序列化器是否把参数顺序整理一致第二步看加密器是否在签名器后面第三步看请求体在签名之后是否被后面的拦截器改过。把这三步走完90%的验签问题都能解决。7.3 每个拦截器状态可视化我做过一个内部小工具页面可以展示某个traceId从请求链到响应链经过的每一个拦截器节点、每个节点的耗时和返回状态。这个页面成了团队排查线上问题最常用的入口。后来我意识到拦截器链的价值一半在“拦截”本身另一半在“可观测性”。没有观测能力的长链对于维护者来说就是一个黑盒谁敢在凌晨三点维护这种系统。8. 从20条链回到实际业务的思考8.1 什么样的项目需要长链如果你做的只是一个内部管理系统接口调用量小业务逻辑简单那几条链就够用了甚至不用自研直接用HTTP客户端自带的拦截器能力就行。如果你做的是对外的开放平台接口、高并发交易场景、多端共用接口或者有严格的安全合规要求那确实值得把拦截器链做长做细。这个判断标准我在几次项目复盘后总结成一条当你的接口层出现“三处以上重复代码”并且“每次新增横切需求都要改一堆文件”的时候就是引入拦截器链的最佳时机。相反如果项目只有十来个接口为了用链而造链反而增加维护成本。8.2 拦截器链与AOP的关系拦截器链本质上是一种面向切面编程的实践。它和装饰器模式、中间件模式、管道模式都是近亲。理解这一点后你会发现它不仅能处理HTTP请求还能用于事件消息处理、数据库访问层、甚至前端路由切换时的权限控制。我在一个消息队列消费端也用了类似的链式设计把消息解码、幂等校验、消费限流、死信处理串起来效果很好。8.3 后续扩展的方向再深一步可以做动态链路编排也就是根据请求类型、用户等级、灰度标记动态决定执行哪几条链。比如VIP用户走一条更短的链内部测试请求走一条额外打印调试信息的链。这种能力在服务网格里叫故障注入在我们这里其实就是给拦截器链加一个条件判断器。我个人后来在项目里尝试过为每条请求设置一个chainSelector字段由它决定要运行哪几条拦截器。底层还是一个拦截器容器只是执行前过滤了一次。这个扩展让链路设计从一个固定数组变成了一个可编程规则灵活性高了很多。9. 最后的几条实操建议9.1 新加拦截器的准入标准每加一条新的拦截器之前我会要求回答三个问题这条逻辑是不是横跨多个业务场景它是不是可以在请求层统一处理而不需要知道业务细节如果把它放在业务代码里会不会导致多个业务模块重复实现三个问题都是肯定答案才允许加进链路。9.2 链路的版本化维护链路配置建议做一次版本管理。不是代码层面而是配置层面的版本比如拦截器集合从V1改到V2时要能回溯差异知道每次改链路影响了什么。我们内部是把链路配置定义成JSON配置文件存进仓库走代码评审。线上动态改链路这种事听着方便但出了事故很难回滚我个人不推荐。9.3 先小步跑通再逐步加长最后一条建议是不要一开始就设计20条链。我当初也是从3条加起跑了两个月稳定了再加签名、加密、幂等、重试。每加一条链都要配合打点和日志观察一段时间线上表现。链路越长调度复杂度越高出问题的时候要排查的节点也越多。宁可每一步走得稳一点也不要追求一步到位。关于拦截器链的话题我能分享的思路大概就是这些了。说到底请求响应拦截器链的本质不是堆砌拦截器的数量而是把系统里横切的关注点用结构化的方式管理起来。20条链听起来很多但只要职责清晰、顺序合理、上下文干净、可观测性到位它反而比一套散落在代码各处的逻辑更好维护。我也会继续在实践中迭代这条链的设计有新的体会再写出来。 
长河君 · 2026/10/20 11:42:29 · 阅读 1.2k 请求响应拦截器链设计：20级链条的实战经验与避坑指南
你有没有遇到过这种场景一个接口请求发出去要带token、要加签名、要打日志、要处理错误码、要考虑超时重试还得在页面跳转时带上来源参数。如果你在每个调用点都手动写一遍代码能臭到让人怀疑人生。我之前在某项目里就是活生生的例子——同一个请求函数里塞了七八层逻辑后来加了新需求想改超时策略愣是改了三天才把所有调用点找齐。后来我才彻底想明白这种事情就得用请求响应拦截器链来统一收口把横切逻辑从业务代码里剥出去让请求层变成一个可插拔、可组合、可调试的管道。这篇文章我从头到尾讲讲我设计和维护一条20级拦截器链条的完整思路包括链条怎么分、顺序怎么排、上下文怎么传、异常怎么兜底、性能怎么测以及我踩过的一堆坑。不管你是用框架自带的拦截器机制还是打算自研一套HTTP层中间件这里面大部分思路都能直接用。1. 拦截器链到底是什么以及它解决的三个核心问题1.1 一句话解释拦截器链拦截器链不是一个具体的库而是一种把“请求前处理”和“响应后处理”串成一条流水线的架构模式。你可以想象快递分拣线包裹请求进入传送带经过扫码鉴权、称重日志、贴单签名、安检校验等多个工位每个工位只做一件事做完传给下一个工位。响应回来之后反向再走一条质检通道。在这条链上每一个节点就是一个拦截器它负责接收上游传来的请求配置做自己的事情然后决定继续往下传还是直接短路返回。1.2 它解决的核心问题第一个问题是重复代码。没有拦截器的时候每个业务请求都要自己拼header、自己判断网络错误、自己弹toast。有了拦截器链这些横切逻辑收敛到一层业务代码里干干净净。第二个问题是顺序控制。真实项目中token刷新必须在签名之前日志埋点必须在鉴权之后重试逻辑必须在错误处理之前。拦截器链把顺序显式化每个环节的先后关系一目了然而不是散落在各种工具函数里靠命名约定维持。第三个问题是链路追踪能力。一条可编排的链意味着你可以知道请求在哪个环节耗时最长、在哪个环节被拦截了、为什么被拦截。排查问题的时候你能按图索骥而不是打开一堆日志靠猜。1.3 20条链是不是真的越多越好这里要说明一点。我当年设计的时候一开始只规划了7个拦截器后面业务扩张、安全需求增加慢慢加到了20条。很多人听到“20”会觉得夸张但我实际体会是只要每一条拦截器的职责足够单一链条长并不可怕可怕的是职责混杂、顺序混乱、上下文共享一团糟。真正合理的状态是每条链的命名就是它的职责你在链路配置里一眼就能看出来整个请求生命周期经历了什么。我做的那条链最终按功能分成四组前置基础组请求标识、超时控制、安全认证组token注入、签名、加密、语义处理组参数规范化、幂等键、防重复提交、响应后处理组状态码分流、错误映射、重试、埋点、兜底文案。每条链一个文件一个类一个职责。2. 拦截器链的总体设计与顺序决策2.1 分层拆解请求链与响应链怎么分我习惯把链路拆成请求链和响应链两条但它们在上下文上共享同一个对象。请求链按顺序执行一旦有拦截器抛出异常或主动中断后续请求链不再执行直接进入响应链的错误处理分支。响应链也不是只有成功路径。我把它分成成功处理链和异常处理链异常处理链会先经过错误归类器把网络异常、超时异常、业务码异常、序列化异常分别映射到不同类型的错误对象之后再走重试判断、用户提示、日志上报这些动作。这里有一个容易犯的错误把重试逻辑放在成功处理链里。我在项目里见过有人这么搞结果接口返回业务错误码时也触发了重试导致下单接口重复提交。重试逻辑只应该放在明确的异常分支里而且必须配合幂等键使用。2.2 顺序怎么定三个原则顺序设计我总结出三个原则。第一原则无依赖的靠前有依赖的靠后。比如请求标识生成不依赖任何其他信息就放在第一位。token注入依赖认证状态管理器所以放在登录态检查之后。第二原则凡是可能修改请求体的操作尽量靠前但要在签名之前完成。因为签名是对请求体做哈希的如果你在签名之后又改了请求体签名就失效了这个坑我们踩过不止一次。第三原则异常处理放在最外层重试放在异常处理之前。也就是说请求链执行完进入响应环节之后顺序是状态码判断 - 错误分类 - 重试判断 - 用户提示 - 全局日志。如果重试放在错误分类前面你就没法区分哪些错误值得重试比如参数校验错误也去重试那就是浪费资源。2.3 上下文传递用Context对象解决参数共享20条链之间怎么共享数据答案是不能用全局变量必须用请求级上下文对象。我定义了一个Context结构包含requestConfig、responseData、errorInfo、retryCount、startTime、duration、traceId、extraMap。每个拦截器只操作Context不直接修改原始请求对象。这样做的好处是你可以在不影响全局配置的前提下临时改动某次请求的行为。比如某个导出接口因为数据量大全局超时是10秒但这个请求需要60秒你就可以在这个请求初始化时往Context的extraMap里塞一个timeout字段超时拦截器会优先读取这个字段覆盖全局配置。这就是链路设计里“局部覆盖全局”的典型手法。3. 20条拦截器的具体职责拆解3.1 请求链的10个节点逐个说明我先说请求链这部分一共10个拦截器按执行顺序排列。第一个是请求标识生成器。它给每次请求生成全局唯一的traceId并写入header。这个traceId会透传到服务端服务端日志也打这个ID排查问题时可以一链到底。我们当时是基于UUID加上时间戳随机数生成避免并发冲突。第二个是超时控制器。它会读取Context里的自定义超时时间没有就用全局默认。这个拦截器实际做的事情是初始化一个超时信号在后续真正发请求时通过Promise.race来实现超时中断。第三个是请求序列化器。统一处理GET参数的序列化风格、POST的body编码格式。为啥要单独一条链因为后端接口风格不统一有的要form-data有的要JSON有的要query参数拼数组。序列化器根据每个接口声明的contentType来做转换。第四个是认证状态检查器。它检查当前请求是否需要登录态。白名单接口直接放行需要鉴权的接口如果本地没有token就走匿名异常通道不发请求直接返回401错误。第五个是token注入器。它从认证管理器拿accessToken放进Authorization头。这里有个细节token刷新逻辑不在这里因为刷新动作可能会失败失败之后需要重新走一遍请求链放这里是循环依赖。第六个是签名器。负责按照约定规则拼接请求参数生成签名串然后加进header。这个环节要求前面的序列化器已经把参数整理成最终形态。签名算法是公司内部约定的不做赘述但思路就是参数排序加盐加时间戳做哈希。第七个是请求加密器。针对敏感字段做加密比如身份证号、手机号。它只对配置了加密的接口生效。加密器在签名之后的原因是服务端校验签名时用的是密文字段如果先签名再加密服务端拿到的是加密后的原文签名就对不上。所以顺序不能随意换。第八个是幂等键生成器。对写操作接口生成一个基于用户ID加时间戳加随机数的幂等键存放在header里。这个是给后面重试用的关键凭据。第九个是防重复提交器。它维护一个滑动窗口记录最近N秒内的请求指纹。请求指纹是把URL、参数、幂等键做个哈希。如果窗口内命中相同的哈希直接终止链路并提示“操作太频繁”。第十个是最终请求发射器。其实它不算真正的拦截器而是一个终结节点它拿到经过前面所有拦截器加工后的Context执行真正的HTTP发送动作并把Promise传递给响应链。3.2 响应链的10个节点逐个说明响应链同样有10个节点其中7个是成功处理3个是异常处理但异常处理里有嵌套分支。我按优先级来排。响应链第一个是状态码分流器。它先看HTTP状态码200系列走成功链其余走异常链。但这个分流不是一下到底的它会把异常响应体缓存下来供后续错误映射使用。第二个是业务码解码器。进入成功链后并不是所有200都是真的成功业务码才代表语义成功。比如HTTP 200但body里code是5000这种属于业务逻辑异常需要把它转入特殊异常通道。第三个是数据解包器。如果接口做了统一包装比如data、message、traceId这种结构解包器在这里把外层剥掉只把业务数据传给下游。第四个是响应解密器。对应请求链的加密器如果某个接口的响应是密文这里做解密。解密失败会走异常通道并且不会触达业务层。第五个是数据转换器。统一处理字段命名转换比如下划线转驼峰、日期字符串转Date对象、分转元。这个环节放在解密之后确保业务层拿到的数据已经是可直接使用的形态。第六个是成功埋点器。记录接口耗时、状态、数据量异步上报给监控系统。埋点逻辑不能阻塞主流程我们用的是异步队列失败也不影响业务。第七个是缓存写入器。针对GET类型并且声明了可缓存的接口把响应数据写入本地缓存。写缓存也是异步的但回填的逻辑有一点复杂后面说坑。然后是异常链。异常链第一个是网络错误分类器。把断网、DNS解析失败、连接超时、服务端5xx、4xx等不同的错误类型归为不同的错误类。这个分类决定了后续是否值得重试。第二个是重试裁决器。它根据当前错误类型、请求方法、重试次数上限、幂等键是否存在综合判断要不要重试。重试不是无限重试我们会从Context读取retryCount超过上限就放弃。重试时会把当前Context的retryCount加一然后重新执行整条请求链而不是只重发HTTP请求这样签名、token都会重新生成保证一致性。第三个是用户提示映射器。把错误码映射成用户可以理解的中文提示比如“网络不给力请稍后再试”。这里有一个原则技术错误信息不能直接弹给用户必须经过映射。第四个兜底日志器。所有走到这里的请求统一错误日志包含请求链各节点耗时、哪一步中断、错误堆栈。这个日志是事后排查最重要的数据来源。4. 完整代码结构与核心实现要点4.1 拦截器接口与链路执行器先看拦截器的统一接口。我用的是TypeScript但去掉类型声明也一样。每个拦截器只需要实现两个方法intercept和getName。getName用来做链路标识排查问题时你能精确知道是哪一环出了问题。interface Interceptor { // 每个拦截器返回布尔值true表示继续false表示中断 // 也可以通过抛出异常中断 intercept(ctx: RequestContext): Promiseboolean; getName(): string; }链路执行器维护两个数组requestInterceptors和responseInterceptors。它按顺序依次await每个拦截器的intercept方法一旦返回false或抛异常就停止跳转到响应链对应的异常分支。class InterceptorChain { private requestChain: Interceptor[] []; private successChain: Interceptor[] []; private errorChain: Interceptor[] []; async executeRequest(ctx: RequestContext): PromiseResponseContext { for (const interceptor of this.requestChain) { const shouldContinue await interceptor.intercept(ctx); if (!shouldContinue) { return this.executeErrorChain(ctx, new InterruptError(interceptor.getName())); } } return this.executeHttpRequest(ctx); } }4.2 请求发射器与超时控制请求发射器是请求链的终点节点。它接收Context发起真实请求。这里我用了一个超时封装器基于Promise.race实现。function fireRequest(ctx: RequestContext): PromiseResponseContext { const timeout ctx.extraMap.get(timeout) ?? 10000; const controller new AbortController(); return new Promise((resolve, reject) { const timer setTimeout(() { controller.abort(); reject(new TimeoutError(ctx.traceId, timeout)); }, timeout); fetch(ctx.requestConfig.url, { method: ctx.requestConfig.method, body: ctx.requestConfig.data, headers: ctx.requestConfig.headers, signal: controller.signal, }) .then(async (res) { clearTimeout(timer); const body await res.json(); resolve({ status: res.status, headers: res.headers, data: body, ctx, }); }) .catch((err) { clearTimeout(timer); reject(normalizeNetworkError(err)); }); }); }4.3 重试机制的实现细节重试裁决器的核心逻辑我之前写了很长的一版后面简化成几个判断条件class RetryDecider { private maxRetryCount 2; async intercept(ctx: RequestContext): Promiseboolean { // 先在错误分类器之后取到 errorInfo const err ctx.errorInfo; const method ctx.requestConfig.method?.toUpperCase(); const retryable err.recoverable [GET, HEAD].includes(method); const hasIdempotent Boolean(ctx.requestConfig.headers.get(idempotent-key)); const reachedLimit ctx.retryCount this.maxRetryCount; if (retryable !reachedLimit (hasIdempotent || method GET)) { ctx.retryCount 1; // 重新走请求链 // 这里注意不能直接重新执行fireRequest要重新执行整个请求链 ctx.resetForRetry(); await executeRequest(ctx); return false; // 不再走下游响应链 } return true; } }重试时的重置动作很关键。resetForRetry会清除响应数据、恢复请求体到初始状态但不清空traceId和请求标识保证同一次业务请求的链路追踪ID一致。它还会把token重新刷新因为有可能第一次请求时token刚好过期了。4.4 缓存写入器碰到的坑缓存写入器在响应链里看起来简单但实际实现有个大坑缓存写入必须在数据转换之后否则你缓存下来的是未经转换的原始数据下一次命中缓存直接返回到业务层时就少了转换步骤。我第一次就写反了结果缓存命中的接口日期格式全是错的。解决办法是缓存写入器拿到的数据必须是经过转换器处理的最终数据并且在写入时同时保存数据版本号。业务层读取缓存时还要校验版本号是否匹配当前接口的转换规则版本如果缓存数据版本低直接丢弃重新请求。5. 我自己踩过的几个深坑5.1 签到一次接口请求三次这是排序问题导致的。我早期把重试逻辑放在状态码分流器之前结果一个响应超时的请求在重试时又执行了一次请求链。而请求链里有防重复提交器防重复提交器一看这个请求指纹在窗口内存在就中断了然后中断又触发了错误链错误链又走重试。这就是个死循环实际上发了三个请求才最终失败。后来我把重试放在错误分类之后并且给重试加上一次最大次数限制同时让防重复提交器在“重试中”的请求上放行一次才彻底解决。5.2 签名顺序的隐性依赖我们团队有一次在做字段加密时把加密器放在签名器前结果服务端验签失败率飙升。原因是服务端验签时用的是加密后的字段值而客户端签名时用的是加密前的明文。协议上两边不一致排查了半天才发现是顺序问题。这种问题在链路长的时候特别容易发生因为它不会直接报错而是表现为接口偶发失败。我现在有个习惯给每一条拦截器写清楚它依赖前序哪个节点的产物以及它自己会生成什么产物。整个链路配置就是一个声明式数组谁依赖谁一眼就能看出来新成员接手也不会猜。5.3 请求上下文被意外篡改因为所有拦截器都操作同一个Context对象如果某个拦截器直接修改了requestConfig.headers后续拦截器会感知到。这本来是设计好的但有人为了方便把业务状态存到了Context里导致同一个请求在不同拦截器里看到了不同的业务状态特别难查。我的规矩是Context.extraMap只能存不可变对象所有共享数据必须放在Context的固定字段里自定义字段一概不允许。代码评审时这条是红线。5.4 长尾请求的链路日志爆炸20条链每条链都打日志的话一次请求能打出几十行日志量大了之后日志系统先扛不住了。我们后来调整了日志等级策略正常成功请求只在链路最外层打一条汇总日志包含traceId、总耗时、各节点耗时明细只有异常请求才在每一层都打详细日志。这样日志量直接降了一个数量级排查问题时通过traceId又能拉全链路追踪信息。6. 性能调优与链路耗时观测6.1 异步拦截器的串行代价拦截器链最直接的性能隐患是每一条都是await串行执行的。20条链即使每条只消耗1毫秒最终影响也有20毫秒。对于接口动辄几百毫秒的场景20毫秒不算大但如果你在拦截器里做了同步加解密计算或者更糟——做了阻塞式IO操作那问题就大了。我踩过的一个坑是把日志上报的同步实现放在了埋点器里结果所有接口的响应时间平均多了30毫秒。后来把所有埋点、日志上报全部改成异步队列不阻塞主流程性能立刻恢复正常。6.2 用tracing收集每段耗时我在Context里内置了一个timing数组每个拦截器执行前记录一个时间戳执行后记录一个时间戳最后汇总输出。说白了就是给每条链打点。// context 里维护 timing async function runInterceptor(interceptor: Interceptor, ctx: RequestContext) { const start performance.now(); const result await interceptor.intercept(ctx); const end performance.now(); ctx.timings.push({ name: interceptor.getName(), durationMs: Number((end - start).toFixed(2)), }); return result; }这个耗时数据经过埋点器上报到监控平台后你可以直接看到token注入耗时异常、签名器耗时上涨、加密器计算时间过长这类具体问题。有一次签名器耗时从1毫秒涨到8毫秒排查发现是某次更新误把同步签名的库版本换成了异步版本链路因为await等待额外开销这种问题没有打点根本看不出。6.3 那些链可以并行执行不是所有拦截器都必须串行。在请求链里面请求标识生成器、超时控制器、序列化器这三者没有互相依赖可以并行。但为了链路可观测性和调试方便我最终仍然选择串行只是把这三个做了强化保证单个拦截器耗时在微秒级不让并行优化增加复杂度。响应链里有一个地方值得做并行成功埋点器和缓存写入器没有依赖关系但二者都是异步非阻塞的放在同一个位置也不会真串行阻塞太久。所以我没有做真正的并行化只用异步队列降低了阻塞经验是“优先减少单个拦截器的耗时而不是做并行。”7. 日志规范与排查手册7.1 统一日志格式链路日志必须有统一的字段模板不能各写各的。我定的模板包含traceId、userId、url、method、status、businessCode、retryCount、costMs、timings、errorType、errorMessage、interceptorName。日志尽量单行输出方便日志平台按traceId聚合。7.2 典型问题的排查路径日常排查最多的就是三类问题。第一类某个接口超时了。先看traceId再查看timing明细如果发现超时拦截器之前某个链耗时异常直接定位到那个拦截器。如果timing里没有异常说明请求根本没到业务服务端可能是网络层问题再看TCP连接耗时。第二类请求返回401。先看认证状态检查器是否把请求匿名放行了再看token注入器拿到的是不是过期token。一般来说token刷新机制如果出了问题重试比手动登录更有效因为重试会重新走一遍请求链再刷新token。第三类签名验签失败。第一步看序列化器是否把参数顺序整理一致第二步看加密器是否在签名器后面第三步看请求体在签名之后是否被后面的拦截器改过。把这三步走完90%的验签问题都能解决。7.3 每个拦截器状态可视化我做过一个内部小工具页面可以展示某个traceId从请求链到响应链经过的每一个拦截器节点、每个节点的耗时和返回状态。这个页面成了团队排查线上问题最常用的入口。后来我意识到拦截器链的价值一半在“拦截”本身另一半在“可观测性”。没有观测能力的长链对于维护者来说就是一个黑盒谁敢在凌晨三点维护这种系统。8. 从20条链回到实际业务的思考8.1 什么样的项目需要长链如果你做的只是一个内部管理系统接口调用量小业务逻辑简单那几条链就够用了甚至不用自研直接用HTTP客户端自带的拦截器能力就行。如果你做的是对外的开放平台接口、高并发交易场景、多端共用接口或者有严格的安全合规要求那确实值得把拦截器链做长做细。这个判断标准我在几次项目复盘后总结成一条当你的接口层出现“三处以上重复代码”并且“每次新增横切需求都要改一堆文件”的时候就是引入拦截器链的最佳时机。相反如果项目只有十来个接口为了用链而造链反而增加维护成本。8.2 拦截器链与AOP的关系拦截器链本质上是一种面向切面编程的实践。它和装饰器模式、中间件模式、管道模式都是近亲。理解这一点后你会发现它不仅能处理HTTP请求还能用于事件消息处理、数据库访问层、甚至前端路由切换时的权限控制。我在一个消息队列消费端也用了类似的链式设计把消息解码、幂等校验、消费限流、死信处理串起来效果很好。8.3 后续扩展的方向再深一步可以做动态链路编排也就是根据请求类型、用户等级、灰度标记动态决定执行哪几条链。比如VIP用户走一条更短的链内部测试请求走一条额外打印调试信息的链。这种能力在服务网格里叫故障注入在我们这里其实就是给拦截器链加一个条件判断器。我个人后来在项目里尝试过为每条请求设置一个chainSelector字段由它决定要运行哪几条拦截器。底层还是一个拦截器容器只是执行前过滤了一次。这个扩展让链路设计从一个固定数组变成了一个可编程规则灵活性高了很多。9. 最后的几条实操建议9.1 新加拦截器的准入标准每加一条新的拦截器之前我会要求回答三个问题这条逻辑是不是横跨多个业务场景它是不是可以在请求层统一处理而不需要知道业务细节如果把它放在业务代码里会不会导致多个业务模块重复实现三个问题都是肯定答案才允许加进链路。9.2 链路的版本化维护链路配置建议做一次版本管理。不是代码层面而是配置层面的版本比如拦截器集合从V1改到V2时要能回溯差异知道每次改链路影响了什么。我们内部是把链路配置定义成JSON配置文件存进仓库走代码评审。线上动态改链路这种事听着方便但出了事故很难回滚我个人不推荐。9.3 先小步跑通再逐步加长最后一条建议是不要一开始就设计20条链。我当初也是从3条加起跑了两个月稳定了再加签名、加密、幂等、重试。每加一条链都要配合打点和日志观察一段时间线上表现。链路越长调度复杂度越高出问题的时候要排查的节点也越多。宁可每一步走得稳一点也不要追求一步到位。关于拦截器链的话题我能分享的思路大概就是这些了。说到底请求响应拦截器链的本质不是堆砌拦截器的数量而是把系统里横切的关注点用结构化的方式管理起来。20条链听起来很多但只要职责清晰、顺序合理、上下文干净、可观测性到位它反而比一套散落在代码各处的逻辑更好维护。我也会继续在实践中迭代这条链的设计有新的体会再写出来。