如何在Apache APISIX中实现并配置网关层熔断功能？

APISIX 内置了api-breaker插件实现网关层熔断能力，不需要侵入业务代码，直接配置规则即可生效，核心逻辑是实时统计上游服务的异常请求占比、连续异常次数，达到预设阈值时自动切断故障上游的流量转发，直接给客户端返回预设响应，避免级联故障拖垮整个链路。

核心规则逻辑 #

熔断状态共3种，自动流转：

• 关闭状态：正常转发所有请求到上游，同时统计异常请求指标
• 打开状态：不转发任何请求到对应上游，直接返回预设的熔断响应
• 半开状态：熔断时长到期后自动进入，仅放行少量试探请求到上游，根据试探结果决定是回到关闭状态还是重新进入打开状态

配置前置准备 #

先提前确定好规则的核心参数，避免配置反复调整：

• 判定为上游异常的HTTP状态码列表，通常包含500、502、503、504、408这类服务端错误、超时错误码
• 熔断触发阈值：支持两种判定维度，可同时配置，满足任意一个即触发：连续异常次数、统计窗口内异常请求占比
• 熔断持续时长：触发熔断后保持打开状态的时间，到期后自动进入半开试探
• 半开恢复规则：连续多少个试探请求正常，就判定上游恢复，关闭熔断
• 熔断触发后的返回内容：包含返回状态码、响应体、自定义响应头等

配置操作示例 #

以下是路由维度绑定熔断规则的示例，通过APISIX Admin API提交即可生效：

curl http://127.0.0.1:9180/apisix/admin/routes/1001 \
-H 'X-API-KEY: 替换为你实际的Admin API密钥' \
-X PUT -d '
{
  "uri": "/order/api/*",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "192.168.1.20:8080": 1
    }
  },
  "plugins": {
    "api-breaker": {
      "break_response_code": 503,
      "break_response_body": "{\"code\":503,\"msg\":\"服务暂时不可用，请1分钟后重试\"}",
      "break_response_headers": {
        "Content-Type": "application/json"
      },
      "unhealthy": {
        "http_statuses": [500, 502, 503, 504, 408],
        "failures": 5,
        "failure_percentage": 30
      },
      "healthy": {
        "http_statuses": [200],
        "successes": 2
      },
      "break_time": 30,
      "max_breaker_sec": 300
    }
  }
}'

核心参数说明：

• break_response_code：熔断触发后返回给客户端的HTTP状态码
• break_response_body：熔断触发后的响应内容，支持普通文本、JSON格式
• break_response_headers：熔断响应的自定义头，比如上面示例里配置了JSON格式的Content-Type
• unhealthy.http_statuses：纳入异常统计的状态码列表
• unhealthy.failures：连续出现多少次异常请求就触发熔断
• unhealthy.failure_percentage：统计周期内异常请求占比达到多少百分比触发熔断
• healthy.http_statuses：半开状态下判定为请求正常的状态码
• healthy.successes：半开状态下连续出现多少次正常请求，就判定上游恢复，关闭熔断
• break_time：熔断打开状态的持续时长，单位秒，到期后自动进入半开状态
• max_breaker_sec：单次熔断的最长持续时间，避免上游长期故障时频繁发起无效试探

生效范围调整 #

• 若需要某一组业务接口都复用同一套熔断规则，不需要给每个路由单独配置，直接把api-breaker插件绑定到对应的Service资源即可
• 若需要网关转发的所有请求都启用全局默认熔断规则，直接把插件配置到Global Rule资源上即可

注意事项 #

• 熔断维度是上游节点级别：多个上游节点做负载均衡时，单个节点触发熔断不会影响其他正常节点的流量转发
• 半开状态下最多只会放行healthy.successes配置数量的试探请求，不会放大量流量冲击尚未完全恢复的上游
• 不要把4xx类的客户端错误码纳入异常统计：这类错误是客户端请求参数、权限等问题导致，不是上游服务故障，会导致熔断误触发

内容的提问来源于stack exchange，提问作者feihan