消息与日志系统

完整的观测体系，让每一次治理行为都可追踪、可分析、可上报。

消息提示系统（notify）

notify 是统一的消息出口，所有能力的用户提示都走这里：

const requestManager = setupRequestGuard(axios, {
  notify: (payload) => {
    // payload.message — 提示文案
    // payload.capability — 触发能力名：'duplicate' / 'circuitBreaker'
    // payload.strategy — duplicate 策略：'block' / 'reuse'（仅 duplicate 时存在）
    Toast.show(payload.message);
  },
  defaults: {
    duplicate: {
      showToast: true,       // 控制是否触发 notify
      message: '请勿重复提交' // 默认提示文案
    }
  }
});

触发时机

时机	说明
blocked	防重策略为 block 时，重复请求被拦截时触发
reuse-waiting	防重策略为 reuse 时，命中已有请求进入复用等待时触发
circuit-breaker-open	熔断器处于打开状态，请求被熔断拒绝时触发
retry	默认不触发 notify；准备重试与停止重试都可通过日志系统观测，停止后仍返回原始错误

notify payload 字段（duplicate 触发时）

字段	类型	描述
message	string	提示文案
strategy	string	触发策略（block / reuse）
capability	string	触发能力名（'duplicate'）
config	object	原始请求配置
requestKey	string	请求唯一标识
repeatCount	number	重复次数
pendingCount	number	当前待处理总数
method	string	请求方法
url	string	请求地址

notify payload 字段（circuitBreaker 触发时）

字段	类型	描述
message	string	提示文案
capability	string	触发能力名（'circuitBreaker'）
circuitKey	string	熔断单元标识
state	string	当前熔断状态
failCount	number	失败次数
openedAt	number	熔断开始时间戳

日志系统

使用内置控制台 Logger

import { ConsoleRequestGuardLogger, setupRequestGuard } from '@hydd/request-guard';

const requestManager = setupRequestGuard(axios, {
  logger: new ConsoleRequestGuardLogger({
    devOnly: true,    // 仅开发环境输出（production 自动静默）
    level: 'debug'    // 最低输出等级：debug / info / warn / error
  })
});

自定义 Logger（接入 ARMS / 远程监控）

必须继承 RequestGuardLogger 基类，重写 write(event) 方法：

import { RequestGuardLogger, setupRequestGuard } from '@hydd/request-guard';

class ARMSLogger extends RequestGuardLogger {
  write(event) {
    // event 结构：
    // {
    //   level: 'warn',                    — 日志等级
    //   event: 'duplicate.triggered',     — 事件名称
    //   message: '请勿重复提交（第2次）',   — 可读消息
    //   namespace: 'requestGuard',        — 命名空间
    //   timestamp: 1717315200000,         — 时间戳
    //   data: { ... }                     — 结构化诊断数据
    // }
    __bl?.api(event.event, event.data);
  }
}

setupRequestGuard(axios, {
  logger: new ARMSLogger({ devOnly: false, level: 'warn' })
});

Logger 配置项

配置项	类型	默认值	说明
devOnly	boolean	true	仅开发环境输出
enabled	boolean	undefined	显式开关（优先级高于 devOnly）
level	string	'debug'	最低输出等级（debug / info / warn / error）

TIP

如果把日志发往远端监控，建议对调用栈做脱敏处理，避免敏感信息外泄。