错误类型

request-guard 在不同治理场景下抛出不同的错误。推荐统一用 error.name 字符串判别，这是三个能力唯一一致的识别方式。

错误一览

错误名（error.name）	所属能力	触发时机
RequestGuardBlockedError	duplicate	block 策略命中重复请求
RequestGuardCancelledError	duplicate	reuse 等待方被 clearState() 主动取消
RequestGuardCacheEvictedError	duplicate	容量满拒绝新 key，或后台清理滞留 reuse 记录时通知等待方结束
RequestGuardRetryCancelledError	retry	waiting 状态被 clearState() 取消
RequestGuardCircuitBreakerError	circuitBreaker	熔断器打开时请求被拒绝

短路错误不经过响应拦截器

重要

duplicate block、cache evicted、circuitBreaker 熔断打开三种"请求未发出"的短路错误，不会进入 axios.interceptors.response.use 的错误处理，因为请求根本没发出去。

统一处理短路错误的两个正确出口：

1. notify 出口（推荐做 toast）
2. 请求级 .catch（用 error.name 判别）

详见 防重复请求 - 短路错误。

错误判别示例

try {
  await axios.post('/api/order', data);
} catch (error) {
  switch (error.name) {
    case 'RequestGuardBlockedError':
      Toast.show('请勿重复提交');
      break;
    case 'RequestGuardCircuitBreakerError':
      Toast.show('服务暂时不可用，请稍后重试');
      console.log(error.circuitKey, error.state, error.failCount);
      break;
    default:
      // 其他错误正常处理
      throw error;
  }
}

CircuitBreakerError 的类名陷阱

类名与 error.name 不同名

熔断错误导出的类叫 CircuitBreakerError，但实例的 error.name 是 'RequestGuardCircuitBreakerError'：

import { CircuitBreakerError } from '@hydd/request-guard';

error instanceof CircuitBreakerError              // ✅ true
error.name === 'RequestGuardCircuitBreakerError'  // ✅ true（带前缀）
error.name === 'CircuitBreakerError'              // ❌ false —— 不要用类名当 name 判断

duplicate 和 retry 的错误只通过 error.name 暴露、并未导出错误类，所以统一用 error.name 判别最稳妥。