什么是 request-guard

@hydd/request-guard 是一个前端请求治理平台。它把散落在各处拦截器里的请求治理逻辑——防重在 A 拦截器、重试在 B 拦截器、熔断靠手动变量——统一收拢成一套可声明、可组合、可观测的治理管道，让你用几行代码给项目加上一整套系统级请求守护能力。

🤔 为什么存在

前端请求治理是个老问题，但现有方案都是碎片化的：

• 防重靠手写 inFlight 变量或拦截器里的 Set
• 重试靠 axios-retry 或在 catch 里手动递归
• 熔断几乎没有前端会做，出了问题只能让请求一直打爆服务端
• 日志/提示每个能力各搞一套，没有统一出口

这些方案有三个共同痛点：能力之间无法组合（防重 + 重试 + 熔断一起用就互相打架）、跨平台不通用（axios 的拦截器搬到 fetch/小程序就废了）、出了问题没法观测（拦截器静默吞错，线上故障只能盲猜）。

request-guard 的思路是：把请求治理抽成一层独立的运行层，不依附于任何请求库。治理能力（防重、重试、熔断）作为可插拔的能力接入，能力之间自由组合互不冲突，所有治理行为通过统一的日志和消息出口可观测。

日志和消息系统最重要的价值，是给平台级守护加上诊断治理能力，形成闭环——治理行为触发后，日志让你知道"为什么拦了、拦了什么"，消息让用户感知到"发生了什么"。没有这套观测体系，守护层就是个黑盒，线上出问题无法定位；有了它，每一次拦截、重试、熔断都可追踪、可上报、可分析。

🏆 核心优势

🌐 全平台可用

不依赖任何请求库。axios、fetch、wx.request、自定义 SDK 都能接——同一套治理配置在不同平台写法完全一致。

• Web 项目用 Axios 安装模式一键接入
• 小程序 / React Native / 自定义 SDK 用 Wrapper 模式包装请求函数
• 平台快捷入口（如 createWechatRequestGuard）进一步降低小程序接入成本
• 包体敏感项目从 @hydd/request-guard/core 按需引入能力，只打包真正用到的部分

详见 三大接入方式。

🧩 能力自由组合

防重、重试、熔断按需引入，同时生效互不冲突。你可以给同一个请求同时配 ignore 防重 + 重试 + 熔断，guard 会在请求生命周期里协调各能力，无需你处理它们之间的交互。

// 一个请求同时享有三种守护，互不打架
await axios.post('/api/payment/create', data, {
  requestGuard: {
    duplicate: { strategy: 'ignore', message: '支付处理中...' },
    retry: { attempts: 2, delay: 1000 },
    circuitBreaker: { failCount: 3 }
  }
});

详见 组合配置。

📐 声明式规则

用 rules 声明"哪些请求需要什么治理"，无需在每个请求处重复配置。规则支持 URL 正则、方法匹配、自定义函数，按声明顺序首个命中生效。

setupRequestGuard(axios, {
  rules: [
    { method: 'post', duplicate: true },                      // 所有 POST 自动防重
    { url: /\/api\/(list|search)/, duplicate: { strategy: 'reuse' } }, // 查询接口复用
    { url: /\/api\/payment/, circuitBreaker: { failCount: 3 } }        // 支付服务熔断
  ]
});

详见 规则系统。

📢 统一观测出口

一个 notify 出口接业务 Toast，一个 logger 出口接开发日志。所有能力的治理行为都走这两个出口，无需为每个能力单独对接。

不传 logger 时自动用内置开发日志，只需传 dev: true：

setupRequestGuard(axios, {
  dev: true,  // 开发环境输出诊断日志，生产自动静默
  notify: (payload) => Toast.show(payload.message)
});

需要接入自定义日志或远程上报时，可传自定义 logger，详见 消息与日志系统。

详见 消息与日志系统。

🛡️ 安全无感

守护层只做加法不做减法——内置三层降级保护，永远不会拦住该发的请求：

1. 全链路兜底——内部任何环节异常都被 catch，不向业务抛出
2. 异常自动放行——守护层出问题时请求直接正常发出，跟没装一样
3. 请求级开关——requestGuard: false 随时绕过守护层

详见 系统特性。

⚖️ 与手写拦截器的对比

	手写拦截器	request-guard
防重 + 重试 + 熔断一起用	各能力互相打架，需手动协调	自由组合，自动协调
跨平台	axios 拦截器搬到 fetch/小程序就废	同一套配置，全平台通用
新增能力	从头写拦截器，容易破坏现有逻辑	实现能力并注册，不动现有配置
出问题排查	拦截器静默吞错，盲猜	统一日志出口，可追踪可上报
业务侵入	每个请求手动加 flag/变量	声明式规则，业务代码零改动

🎯 何时用 / 何时不用

适合用：

• 有表单提交、下单、支付等需要防重的写操作
• 依赖第三方/上游服务，需要重试和熔断保护
• 多平台项目（Web + 小程序 + RN）想统一请求治理
• 想给现有项目加请求守护但不想改业务代码

可以不用：

• 纯静态页、无请求交互
• 只有一个请求且无需治理
• 已有成熟的请求治理体系且满足需求

🚀 选择你的学习路径

不同的人有不同的学习方式，你可以按自己的节奏选择入口：

你是	建议从这里开始
第一次接触，想赶紧跑起来	5 分钟接入 —— 一行代码，立刻看到防重生效
想先看能解决什么问题	常见业务场景 —— 8 个真实场景对号入座
想完整了解每个能力	能力详解 —— 防重、重试、熔断逐个讲透
项目不是 axios	三大接入方式 —— 对号入座选接入方式
从手写拦截器迁移	迁移指南 —— 一步步替换旧方案
遇到问题了	排错指南 —— 常见误区与诊断方法

也可以直接用左侧搜索找到你需要的内容。