应按调用阶段（请求构建、网络传输、响应解析）和可恢复性分类处理外部接口异常：请求构建错抛IllegalArgumentException，网络超时等可重试并熔断，响应解析错需按HTTP状态码语义处理。
处理外部接口调用时的异常，不能一概而用 try-catch(Exception e)，关键在于按**发生阶段**和**可恢复性**分类，再匹配语义明确的标准异常或自定义异常类型。分类不清，容易掩盖真实问题，也难以做针对性重试、降级或告警。
按调用阶段划分三类异常
Java调用外部API通常经历三个阶段：请求构建 → 网络传输 → 响应解析。每个阶段失败原因不同，应使用不同策略应对：
-
请求构建阶段异常：如 URL 编码错误、必填 Header 缺失、JSON 请求体格式非法（多逗号、引号未闭合）。这类属于开发阶段可发现的问题，建议抛出
IllegalArgumentException或自定义InvalidRequestException，不重试，需修复代码。 -
网络传输阶段异常：包括
ConnectTimeoutException、SocketTimeoutException、UnknownHostException、SSLHandshakeException。它们反映基础设施或环境问题，具备临时性，适合加入指数退避重试；若连续失败，应触发熔断并告警。 -
响应解析阶段异常：如 HTTP 状态码非 2xx（401/403/404/500）、
JsonParseException、ClassCastException、空指针（因字段缺失未判空）。其中业务状态码需根据语义处理（401 刷新 token，404 记录缺失，500 触发降级）；解析类异常建议包装为ApiResponseParseException并附带原始响应体，便于排查。
区分“客户端错”与“服务端错”
HTTP 状态码是重要信号，不应统一当作网络失败处理：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
-
4xx 类错误：代表客户端责任。例如 400（参数校验失败）对应
IllegalArgumentException；401/403 需单独捕获，走认证刷新流程；404 可记录日志后返回默认值或空结果，避免中断主流程。 - 5xx 类错误：代表服务端不可用或不稳定。除 503（Service Unavailable）可考虑重试外，其余如 500、502、504 建议立即降级（返回缓存、兜底数据），并上报监控系统。不要盲目重试，可能加剧对方压力。
避免泛化捕获，善用异常链与上下文
不要吞掉原始异常信息。推荐做法：
立即学习“Java免费学习笔记（深入）”；
- 在 catch 块中保留原始异常作为 cause，用
new BusinessException("调用支付接口失败", e)包装； - 记录关键上下文：请求 ID、URL、耗时、HTTP 状态码、响应体前 200 字符（脱敏后）；
- 对可预期的业务异常（如余额不足、库存超限），定义明确的业务异常类（如
InsufficientBalanceException），而非复用RuntimeException； - 拒绝在 finally 中 return 或 throw，防止覆盖 try/catch 中的异常传播路径。
重试与熔断需配合异常分类
不是所有异常都适合重试：
- 仅对网络层临时异常（超时、连接拒绝）和部分 5xx（如 503）启用重试；
- 4xx 错误、JSON 解析失败、参数非法等，重试无意义，应直接失败并告警；
- 熔断器（如 Sentinel 或 Resilience4j）应基于异常类型配置：将
ConnectTimeoutException和SocketTimeoutException设为触发熔断的“失败异常”，而把IllegalArgumentException排除在外。
