RequestGuardController

setupRequestGuard 返回的 RequestGuardController 提供以下方法，用于运行时动态管理配置和状态。

方法列表

方法	参数	返回值	说明
configure(options)	RequestGuardOptions	this（链式调用）	更新全局配置（defaults / rules / notify / logger）
use(capabilityDescriptor)	capability descriptor	this	装配能力 descriptor；重复同名能力会幂等处理
setRules(rules)	GuardRuleInput[]	this	覆盖全局规则（替换全部）
addRule(rule)	GuardRuleInput	this	追加一条规则（不影响已有规则）
clearRules()	无	this	清空所有规则（不释放已在途的能力状态）
clearState()	无	this	清空所有能力状态（取消等待方、释放在途记录）
getStateSnapshot()	无	StateSnapshot	获取当前状态快照（各能力的活跃状态数量）
createLoadingKey(label?)	string	string	创建当前运行期内唯一的 loadingKey
isLoading(key)	string	boolean	查询某个 loadingKey 当前是否处于执行中
subscribeLoading(key, listener)	string, (loading) => void	() => void	订阅某个 loadingKey 的执行态变化
uninstall()	无	this	卸载守护，恢复 axios 原始行为（仅 Axios 模式）

createLoadingKey / isLoading / subscribeLoading 的完整语义、并发引用计数与框架示例，见 Loading 协作 API。

configure 的宽容输入

configure(null)、configure(undefined) 或其他非对象输入会按空配置处理并返回 controller 本身，便于链式调用和防御式集成。有效配置仍应传入对象，例如 { defaults, rules, notify, logger }。

熔断器手动控制（circuitBreaker）

requestManager.circuitBreaker 提供熔断器的手动控制 API：

方法	参数	返回值	说明
tryRecover(key)	string	boolean	尝试将指定 key 从 CIRCUIT_BREAKER 转为 HALF_OPEN（满足 recoverDelay 才会切换）
reset(key)	string	void	手动重置指定 key 到 NORMAL 状态
getState(key)	string	CircuitBreakerStateSnapshot | null	获取指定 key 的状态快照
getAllStates()	无	Record<string, CircuitBreakerStateSnapshot>	获取所有熔断单元的状态快照

CircuitBreakerStateSnapshot 包含 circuitKey、state（NORMAL / CIRCUIT_BREAKER / HALF_OPEN）、failureTimestamps、openedAt、halfOpenedAt、probePassCount、probeGeneration、failCount、window、recoverDelay、probeCount 等诊断字段。这些字段仅供观测，不属于稳定 API 契约。

// 获取某个接口的熔断状态
const state = requestManager.circuitBreaker.getState('POST:/api/payment/create');
// → { state: 'CIRCUIT_BREAKER', openedAt: 1717315200000, failCount: 5, ... }

// 手动重置到正常状态
requestManager.circuitBreaker.reset('POST:/api/payment/create');

更多熔断状态机说明见 熔断守护。

使用示例

const requestManager = setupRequestGuard(axios, {
  notify: (payload) => Toast.show(payload.message)
});

// ---- configure：运行时更新配置 ----
requestManager.configure({
  defaults: {
    duplicate: { strategy: 'reuse' }  // 修改全局默认策略
  },
  logger: null  // 关闭日志输出
});

// ---- setRules：覆盖全局规则 ----
requestManager.setRules([
  { method: 'post', duplicate: true },
  { url: /\/api\/query/, duplicate: { strategy: 'reuse' } }
]);

// ---- addRule：追加一条规则（不影响已有规则） ----
requestManager.addRule({
  url: /\/api\/payment/,
  duplicate: { strategy: 'ignore', message: '支付中，请勿重复点击' }
});

// ---- clearRules：清空全部规则 ----
requestManager.clearRules();

// ---- clearState：清空全部能力状态 ----
// 常用于路由切换、用户登出时，取消等待中的 reuse、释放在途记录
requestManager.clearState();

// ---- getStateSnapshot：查看当前状态 ----
const snapshot = requestManager.getStateSnapshot();
// 返回：{ total: 3, capabilities: { duplicate: { total: 2, policies: { ignore: 1, reuse: 1 } }, retry: { total: 1 } } }
console.log('当前活跃状态数:', snapshot.total);

clearRules vs clearState vs uninstall

• clearRules() 只切断后续请求的规则来源，不释放已在途的能力状态。
• clearState() 会真正清掉当前状态，并取消 reuse 等待方。
• 要恢复 axios 安装前状态请使用 uninstall()。