错误分类：GovernanceBackendError 不在 GatewayUnavailableError 之下，且公开错误面没有文档 #7

New Issue

2026-08-05T00:21:05+08:00

iomgaa commented

2026-08-05 00:21:05 +08:00

调用方（CHSAnalyzer3）要按异常类型把外呼失败分成几类处置，其中一类是「整个用途暂时
不可用 → 延期重投、不消耗业务失败预算」。自然的写法是 except GatewayUnavailableError,
因为它的 docstring 就写着「业务侧 catch 本类做延期重投(CHS arq 模式)」。

按 1.0.1 的源码核了一遍，有两件事想提。

一、`GovernanceBackendError` 语义上属于 scope 级不可用，类型上却不在 `GatewayUnavailableError` 之下

它的含义是限流/熔断的状态后端自己坏了，而降级方向是 fail-closed——这时候一个请求都发不
出去，正是「整个 scope 暂时不可用」。但它是 PolyGatewayError 的直接子类。

它确实会到达调用方：记账那条路被 _record_quietly 降级成 warning
（middleware/retry.py:404），但闸门那条路（try_enter / try_acquire，
middleware/breaker.py:23、backends/redis/limiter.py:250）没有这层包裹，会一路抛出去。

于是只写 except GatewayUnavailableError 的调用方会把它落进兜底那一类。对我们这边的
后果很具体：Redis 抖一下，积压的任务一批批消耗失败预算，够到上限就进死信——而那是个
运维重启一下就好的故障。

看得出为什么它现在不是子类：GatewayUnavailableError.__init__ 强制要求 scope、
reason、retry_after_s 三项，而 reason 必须取自 SCOPE_REASONS,
后端故障不属于其中任何一个，retry_after_s 也没有一个算得出来的值。
所以这不是写错了，是那个构造契约容不下这一种。

两个方向，倾向哪个由你们定：

A：给 SCOPE_REASONS 加一个 governance_backend_down，让 GovernanceBackendError
继承 GatewayUnavailableError，retry_after_s 取 0——docstring 里已经写了
「0 = 可立即重试」，语义上是通的。好处是调用方一条 except 就覆盖完整。
B（更轻）：类型树不动，只在文档里写明这一条也该按「延期重投」处置。

二、看不出哪些异常会到达调用方，哪些是库内吸收的

这一条其实比上一条更值得改，因为它已经让我们写错过一次东西。

TransientError 和 SourceDeadError 的 docstring 描述的是治理行为
（「退避后可重试、可换源、计熔断」「不重试，立即换源，该源 force_open」），读起来像是
调用方要处理的东西。实际上 middleware/retry.py:364 那一行
except (SourceDeadError, TransientError) 把它们接住了、return _Failed(...),
重试预算耗尽时统一包成 AllSourcesExhausted——它们根本到不了调用方。

我们第一遍只看类型树和 docstring，据此在自己的设计文档里写了一整段「漏接
SourceDeadError 会让一次凭据过期烧掉业务失败预算」，是核到 retry.py 才发现不成立、
整段删掉的。

建议在 errors.py 的模块 docstring 或 README 里加一张两列的表，明确区分：

会到达调用方	库内吸收
`GatewayUnavailableError`（含 `AllSourcesExhausted`、`CircuitOpenError`）	`TransientError`
`RequestRejectedError`	`SourceDeadError`
`ResultInvalidError`
`GovernanceBackendError`（仅闸门路径）

这样调用方不必读 middleware/retry.py 才知道自己该 catch 什么。

环境：polygateway 1.0.1（conda 环境 chs，Python 3.13）。
上面每一处行号都是照 src/polygateway/ 当前代码数的。

调用方（CHSAnalyzer3）要按异常类型把外呼失败分成几类处置，其中一类是「整个用途暂时不可用 → 延期重投、**不消耗**业务失败预算」。自然的写法是 `except GatewayUnavailableError`, 因为它的 docstring 就写着「业务侧 catch 本类做延期重投(CHS arq 模式)」。按 1.0.1 的源码核了一遍，有两件事想提。 ## 一、`GovernanceBackendError` 语义上属于 scope 级不可用，类型上却不在 `GatewayUnavailableError` 之下它的含义是限流/熔断的状态后端自己坏了，而降级方向是 fail-closed——这时候一个请求都发不出去，正是「整个 scope 暂时不可用」。但它是 `PolyGatewayError` 的直接子类。它确实会到达调用方：记账那条路被 `_record_quietly` 降级成 warning （`middleware/retry.py:404`），但闸门那条路（`try_enter` / `try_acquire`， `middleware/breaker.py:23`、`backends/redis/limiter.py:250`）没有这层包裹，会一路抛出去。于是只写 `except GatewayUnavailableError` 的调用方会把它落进兜底那一类。对我们这边的后果很具体：Redis 抖一下，积压的任务一批批消耗失败预算，够到上限就进死信——而那是个运维重启一下就好的故障。 **看得出为什么它现在不是子类**：`GatewayUnavailableError.__init__` 强制要求 `scope`、 `reason`、`retry_after_s` 三项，而 `reason` 必须取自 `SCOPE_REASONS`, 后端故障不属于其中任何一个，`retry_after_s` 也没有一个算得出来的值。所以这不是写错了，是那个构造契约容不下这一种。两个方向，倾向哪个由你们定： - **A**：给 `SCOPE_REASONS` 加一个 `governance_backend_down`，让 `GovernanceBackendError` 继承 `GatewayUnavailableError`，`retry_after_s` 取 0——docstring 里已经写了「0 = 可立即重试」，语义上是通的。好处是调用方一条 `except` 就覆盖完整。 - **B**（更轻）：类型树不动，只在文档里写明这一条也该按「延期重投」处置。 ## 二、看不出哪些异常会到达调用方，哪些是库内吸收的这一条其实比上一条更值得改，因为它已经让我们写错过一次东西。 `TransientError` 和 `SourceDeadError` 的 docstring 描述的是**治理行为** （「退避后可重试、可换源、计熔断」「不重试，立即换源，该源 force_open」），读起来像是调用方要处理的东西。实际上 `middleware/retry.py:364` 那一行 `except (SourceDeadError, TransientError)` 把它们接住了、`return _Failed(...)`, 重试预算耗尽时统一包成 `AllSourcesExhausted`——**它们根本到不了调用方**。我们第一遍只看类型树和 docstring，据此在自己的设计文档里写了一整段「漏接 `SourceDeadError` 会让一次凭据过期烧掉业务失败预算」，是核到 `retry.py` 才发现不成立、整段删掉的。建议在 `errors.py` 的模块 docstring 或 README 里加一张两列的表，明确区分： | 会到达调用方 | 库内吸收 | |---|---| | `GatewayUnavailableError`（含 `AllSourcesExhausted`、`CircuitOpenError`） | `TransientError` | | `RequestRejectedError` | `SourceDeadError` | | `ResultInvalidError` | | | `GovernanceBackendError`（仅闸门路径） | | 这样调用方不必读 `middleware/retry.py` 才知道自己该 catch 什么。 --- 环境：polygateway 1.0.1（conda 环境 `chs`，Python 3.13）。上面每一处行号都是照 `src/polygateway/` 当前代码数的。