Spring Boot 微服务 HTTP 调用故障分级500、超时与降级微服务 HTTP 调用失败至少包含三类语义对方返回业务错误、对方返回 5xx以及根本没有建立或完成连接。它们都叫“调用失败”恢复策略却完全不同。如果客户端把所有异常统一吞掉并返回空对象业务会继续使用不完整数据如果一律重试又可能放大拥塞或重复写入。企业级调用需要先分类再决定超时、重试、降级和告警。MetaLite 将调用协议收敛到统一客户端和响应模型中让错误分类不散落在业务服务。本文先建立故障决策表再结合客户端源码说明 500、连接超时和业务失败怎样进入不同分支。一、先区分“收到错误响应”和“没有响应”调用链可以分成两个阶段建立连接并发送请求 → 获得 HTTP 响应 → 检查状态码 → 读取响应体HTTP 500 发生在已经获得响应之后。客户端至少知道目标地址可达服务端或中间代理返回了状态行HTTP 状态码是什么请求已经进入远端链路的某个阶段。连接超时等异常发生在无法获得可用响应的路径。客户端可能只知道DNS、网络、连接池或 Socket 操作失败没有可以交给业务层解析的 HTTP 响应远端是否执行过业务未必能够确定。这两类信息会直接影响降级决策。二、非 2xxfallback 收到原始 RespApache HttpClient 执行完成后MetaLite 首先检查状态码if(statusCode200statusCode226){originalResp.setData(responseBody);}else{originalRespResp.error(ErrorCode.API_CODE_NOT_2XX,statusLine.toString());}如果状态码不是 2xx并且调用方配置了 fallback调用方式是fallback.apply(null,originalResp);此时exception nulloriginalResp ! null原始响应中包含统一后的非 2xx 错误信息。调用方可以根据响应选择策略.fallback((exception,originalResp)-{if(originalResp!null){returnreadFromLocalSnapshot();}returnResp.error(服务暂时不可用);})如果没有配置 fallback非 2xx 当前不会抛出传输异常而是直接返回API_CODE_NOT_2XX对应的失败 Resp。三、传输异常fallback 收到 Exception如果closeableHttpClient.execute()或后续读取过程抛出异常会进入另一条重载方法。框架先尝试把连接、读取或连接池等待相关异常转换成更明确的TimeoutException然后调用fallback.apply(exception,null);此时exception ! nulloriginalResp null。调用方可以按异常类型决定是否降级.fallback((exception,originalResp)-{if(exceptioninstanceofTimeoutException){returnloadFromCache();}thrownewServiceException(依赖服务调用失败);})如果没有配置 fallback传输异常会被包装成运行时异常继续抛出而不是返回普通失败 Resp。这和非 2xx 路径形成了一个清晰差异失败类型fallback 参数未配置 fallbackHTTP 非 2xx(null, originalResp)返回失败 Resp传输或读取异常(exception, null)抛出运行时异常四、为什么不能只看 HTTP 500“HTTP 500”只是服务端错误的一种表现。实际链路中还可能出现502代理无法从上游获得正常响应503服务暂时不可用404端点不存在或版本不匹配401/403内部接口身份或权限异常429远端限流。当前客户端将所有非 2xx 统一为API_CODE_NOT_2XX同时保留状态行字符串。它没有为每个 HTTP 状态建立独立错误码。因此fallback 如果需要对 404、429、500 采用不同策略还需要从原始响应信息中进一步识别或让客户端模型以后显式保存数值状态码。文章不能把当前能力扩大为“已提供完整 HTTP 状态分类”。五、超时也不是一个超时HTTP 调用至少包含三类等待从连接池获取连接与目标地址建立连接连接建立后等待响应数据。它们分别指向不同问题连接池等待超时可能是本实例并发和连接配置问题建连超时通常与网络、目标实例或路由有关读取超时说明连接建立后远端迟迟没有完成响应。MetaLite 会尝试把底层异常转换成携带对应配置的超时异常让 fallback 和日志拥有比普通IOException更清楚的上下文。但“读取超时”不能证明远端业务没有执行。对于写操作客户端超时后盲目重试可能造成重复提交因此 fallback 更适合返回可识别失败或查询结果状态而不是默认重放请求。六、fallback 返回什么取决于业务语义一个合理 fallback 可能返回本地或远程缓存中的旧数据配置中心保存的最近快照空列表但附带明确降级消息默认配置原始失败要求上层终止事务业务可识别的“处理中”由后续查询确认。以下写法则需要谨慎.fallback((ex,resp)-Resp.ok(newUserDto()))把所有失败都伪装成成功对象会让上层无法区分真实数据和占位数据也可能把错误写入后续流程。降级结果必须符合当前接口的业务契约而不是只保证代码不抛异常。七、HttpCallContext 为排查保留了哪些信息每次调用都会创建HttpCallContext用于保存callMethodName request resp fallbackResp errorMessage timeCost非 2xx 路径会记录原始 Respfallback 执行后记录 fallbackResp没有 fallback 的传输异常记录 errorMessage 后继续抛出。这样排查时能够区分远端返回了什么fallback 最终返回了什么是哪个调用方法和请求触发总耗时是多少。日志是否开启由 HttpClient 配置控制因此不能把它描述成任何环境下都会强制输出完整调用信息。八、fallback 不是熔断器当前 fallback 是一次请求上的函数回调。它没有维护滑动失败率连续失败阈值open、half-open、closed 状态探测恢复请求并发隔离舱。因此它解决的是“这一次失败如何返回”不是“连续失败后是否停止调用远端”。把 fallback 称为降级函数是准确的把它宣传成完整熔断能力则会误导架构选型。如果系统需要依赖级熔断还应引入明确的状态机、指标窗口与恢复策略。九、设计失败接口时信息比默认值更重要两类 fallback 参数背后的原则是不要在进入业务降级之前丢掉失败信息。收到了响应就保留原始响应没有响应就保留异常fallback 产生新结果也同时记录原结果与降级结果没有配置降级时传输异常继续传播。容错设计不是让每次调用都返回成功而是让上层基于足够信息作出正确选择。框架简介MetaLite 是面向企业生产环境的新一代 Java 微服务技术底座。系列文章重点分享代码背后的设计思路、技术取舍与工程实践。源码基线JDK 21、Spring Boot 3.2.9、Spring Cloud 2023.0.1、Spring Cloud Alibaba 2023.0.1.3具体组件版本以项目backend-bom为准。作者简介15 年 Spring 体系企业级开发经验专注于 Java 微服务架构、工程治理与生产实践。持续更新MetaLite 系列内容将持续更新围绕核心设计、源码链路、技术取舍与生产实践展开。欢迎关注作者及时获取后续内容。在线演示演示地址: https://admin.metalite.top/演示账号: guess演示密码: admin2026