---
name: external-dependency
when: '外部依赖, 第三方接口, 外部服务调用, HTTP客户端, Feign, RPC, 微服务调用, 超时, 重试, 降级'
scope:
  - backend
products:
  - '*'
id: ka-pattern-external-dependency
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 外部依赖
  - 第三方接口
  - 外部服务调用
  - HTTP客户端
  - Feign
  - RPC
  - 微服务调用
  - 超时
  - 重试
  - 降级
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 每个外部依赖调用必须定义超时时间，禁止无限等待
- 需要重试时必须同时定义幂等或去重策略，避免重复副作用
- 需要降级时必须定义：降级行为、用户提示、恢复条件
- 新增配置项必须文档化：默认值、环境差异、灰度方式、回滚策略
- 外部调用失败必须有区别于业务异常的错误码和用户提示
- 外部依赖必须设置合理的超时时间（连接超时 + 读超时），禁止无限等待
- 外部依赖调用必须有熔断保护，连续失败 N 次自动熔断
- 外部依赖必须有降级策略（返回缓存数据/默认值），不能因为依赖故障拖垮主流程
- 第三方库版本必须锁定（package-lock.json / Gradle version），禁止使用 latest 或范围版本
- 外部依赖的健康检查必须纳入监控，响应时间/成功率异常时触发告警

## 验收项
- [AC-01] 外部调用有超时配置
- [AC-02] 重试操作有幂等/去重策略
- [AC-03] 降级场景有用户提示和恢复条件
- [AC-04] 外部调用失败有独立错误码
- [AC-05] 外部调用有超时配置
- [AC-06] 有熔断和降级策略
- [AC-07] 依赖版本锁定
- [AC-08] 依赖健康检查有监控
