防抖与节流

1. 学习目标

本节采用 Bloom 分类法对学习目标进行层级化建模，确保读者能够由浅入深、由具体到抽象地掌握防抖（Debounce）与节流（Throttle）的全部要义。

1.1 记忆层（Remember）

• 准确回忆防抖与节流的定义：防抖是”等待空闲”策略（Only the last call survives），节流是”固定速率”策略（At most one call per interval）。
• 列出 JavaScript 中实现两者的三种基础原语：setTimeout / clearTimeout、Date.now() 时间戳、requestAnimationFrame（rAF）。
• 复述”前缘触发（Leading Edge）“与”后缘触发（Trailing Edge）“的语义区别：前者在事件流起始立即触发，后者在事件流结束后补触发。

1.2 理解层（Understand）

• 解释防抖与节流在速率限制（Rate Limiting）理论中的对应关系：节流等价于漏桶算法（Leaky Bucket），防抖等价于”空闲检测器”（Idle Detector）。
• 阐释 this 绑定在防抖/节流函数中的传递机制：为何必须使用 fn.apply(this, args) 而非直接 fn(args)。
• 说明 requestAnimationFrame 节流为何仅适用于视觉更新场景，以及在不可见标签页（Hidden Tab）下 rAF 会被浏览器自动暂停的特性。

1.3 应用层（Apply）

• 在生产项目中使用防抖实现搜索自动补全、表单自动保存、窗口尺寸重算等典型场景。
• 通过节流实现滚动监听、拖拽轨迹绘制、按钮防连点、鼠标移动追踪等高频事件处理。
• 组合使用 Lodash 的 _.debounce / _.throttle 与 React useMemo / Vue ref 实现框架级速率限制。

1.4 分析层（Analyze）

• 对比”时间戳节流”、“定时器节流”、“时间戳+定时器混合节流”三种实现各自的首次触发行为、末次触发行为与边界条件。
• 拆解 Lodash _.debounce 源码：invokeFunc / leadingEdge / trailingEdge / remainingTime 四个核心方法的协作关系。
• 分析 RxJS 的 debounceTime / throttleTime 操作符与手写实现的差异：前者基于 Observable 调度器，后者基于宿主事件循环。

1.5 评价层（Evaluate）

• 评估在同一业务场景下，“防抖方案”与”节流方案”在响应延迟、最终一致性、用户体验三维度上的得分。
• 对给定的三套搜索补全实现（无速率限制、防抖 300ms、节流 300ms）评判其在弱网与强网环境下的服务端压力与用户感知。
• 评审主流 UI 库（Ant Design、Element Plus、Material-UI）的速率限制默认配置，给出可量化的改进建议。

1.6 创造层（Create）

• 设计并实现一个面向团队的通用速率限制工具库，支持防抖、节流、rAF 节流、指数退避（Exponential Backoff）四种策略的统一 API。
• 构建一套基于 Web Worker 的后台节流系统，将高频事件的计算密集型处理移出主线程。
• 撰写一份团队级《前端事件处理工程规范》文档，包含防抖/节流使用准则、性能预算、Code Review 检查项、CI 静态分析脚本。

2. 历史动机与演化

2.1 速率限制的思想起源（1960-1980）

速率限制（Rate Limiting）的概念最早源于 1960 年代的操作系统调度理论。1966 年，MIT 的 Multics 操作系统首次引入”CPU 时间片”机制，将处理器时间按固定配额分配给各进程，这是现代”节流”思想的鼻祖。1969 年，Leonard Kleinrock 在 ARPANET 的流量控制设计中提出”令牌桶”（Token Bucket）与”漏桶”（Leaky Bucket）两种经典算法，奠定了网络拥塞控制的理论基础。

漏桶算法的核心思想可形式化描述：设输入事件流为 $\lambda(t)$，桶容量为 $C$，泄漏速率为 $r$，则在时刻 $t$ 的输出速率为：

JavaScript 的节流正是漏桶算法在事件层的应用：不管输入事件多么密集，输出执行速率恒定为 $1/T$（$T$ 为节流间隔）。

2.2 GUI 事件系统的演化（1973-1995）

1973 年，Xerox PARC 的 Smalltalk-80 引入了 Model-View-Controller（MVC）模式，首次将用户事件作为一等对象处理。1984 年，Apple Macintosh 的 Toolbox 事件管理器引入”事件队列”（Event Queue）概念，操作系统将硬件中断（键盘、鼠标）转换为软件事件入队，应用程序通过 GetNextEvent 轮询处理。

这一设计面临的核心问题是事件洪泛（Event Flooding）：当用户快速移动鼠标时，系统每秒可产生 60-120 个鼠标移动事件，若每个事件都触发完整重绘，会导致 CPU 过载。Mac Toolbox 的解决方案是”事件合并”（Event Coalescing）：将多个 mouseMoved 事件合并为一个，仅保留最新位置。这正是防抖思想的雏形。

1989 年，NeXTSTEP 引入了”延迟执行”（Delayed Perform）机制：

// NeXTSTEP / macOS 的 NSObject 延迟执行
[NSObject cancelPreviousPerformRequestsWithTarget:self
                                         selector:@selector(handleInput:)
                                           object:nil];
[self performSelector:@selector(handleInput:)
           withObject:input
           afterDelay:0.3];

这段代码的语义是：先取消之前的延迟执行请求，再注册一个新的延迟执行请求，延迟 0.3 秒后执行。这正是现代 JavaScript 防抖的完整语义。

2.3 浏览器事件与早期实践（1995-2009）

1995 年，Netscape Navigator 引入 setTimeout API，最初用于动画与延迟加载。setTimeout 的语义是：将回调放入宏任务队列（Macrotask Queue），在指定延迟后由事件循环（Event Loop）调度执行。

2000 年代初期，随着 Web 2.0 与 AJAX 的兴起，开发者开始大量使用 onresize、onscroll、onmousemove 等高频事件。2006 年，Yahoo! 的 Julien Lecomte 在《Building High Performance Web Applications》中首次系统化地提出”使用 setTimeout 限制事件处理频率”的模式：

// 2006 年的早期节流实现
var resizeTimer = null;
window.onresize = function () {
  if (resizeTimer) clearTimeout(resizeTimer);
  resizeTimer = setTimeout(function () {
    recalculateLayout();
  }, 100);
};

这段代码是防抖的雏形，但当时并未明确区分”防抖”与”节流”两种模式。

2.4 jQuery 时代与命名确立（2009-2015）

2009 年，John Resig 在 jQuery 1.3 中引入了 $.throttle 与 $.debounce 的概念讨论（虽未直接进入核心库）。2010 年，Ben Alman 在其开源项目 jQuery throttle / debounce 中首次明确区分两者：

• throttle：保证函数在指定间隔内最多执行一次（保速）。
• debounce：保证函数在停止触发一段时间后才执行（保空闲）。

Ben Alman 的命名被社区广泛接受，成为现代 JavaScript 的事实标准术语。其实现的核心代码片段：

// Ben Alman 的 jQuery throttle/debounce (2010)
function throttle(delay, no_trailing, callback, debounce_mode) {
  var timeout_id, last_exec = 0;
  return function () {
    var that = this, args = arguments, elapsed = +new Date() - last_exec;
    function exec() {
      last_exec = +new Date();
      callback.apply(that, args);
    }
    function clear() {
      timeout_id = undefined;
    }
    if (debounce_mode && !timeout_id) exec();
    if (timeout_id) clearTimeout(timeout_id);
    if (debounce_mode === undefined && elapsed > delay) {
      exec();
    } else if (no_trailing !== true) {
      timeout_id = setTimeout(debounce_mode ? clear : exec,
                              debounce_mode === undefined ? delay - elapsed : delay);
    }
  };
}

2.5 Underscore / Lodash 的标准化（2012-2018）

2012 年，Jeremy Ashkenas 在 Underscore.js 1.4 中引入 _.debounce 与 _.throttle，API 简洁：

_.debounce(func, wait, [immediate])
_.throttle(func, wait, [options])

2013 年，John-David Dalton 创建 Lodash，对 Underscore 的实现进行了全面重写。Lodash 的 _.debounce 与 _.throttle 共享同一套底层调度逻辑，支持以下高级特性：

• leading: true/false：是否在事件流起始立即触发。
• trailing: true/false：是否在事件流结束后补触发。
• maxWait：最大等待时间，防止防抖函数被无限拖延。
• cancel() / flush() / pending()：取消、立即执行、查询待执行状态。

Lodash 的实现成为现代 JavaScript 防抖/节流的事实标准，被广泛引用与移植。

2.6 现代框架集成（2018-2026）

随着 React、Vue、Angular 等现代框架的兴起，防抖与节流逐渐以 Hook / Composition API 的形式集成：

RxJS 的 debounceTime 与 throttleTime 基于 Observable 调度器，语义略有不同：

• debounceTime(n)：发射后等待 n ms，期间若有新值则重新计时，仅发射最后一个值。
• throttleTime(n, { leading: true, trailing: true })：发射后立即触发首次，n ms 内忽略后续，n ms 后发射最后一个值。

2.7 浏览器原生 API 的演化（2015-2026）

随着浏览器能力的扩展，部分场景出现了原生替代方案：

尽管如此，防抖与节流仍是不可替代的基础工具：IntersectionObserver 仅适用于交叉区域检测，ResizeObserver 仅适用于尺寸变化，而防抖/节流是通用的速率限制原语，适用于任意事件流。

3. 形式化定义

3.1 事件流的数学建模

设事件流为一个时间序列 $E = \{e_1, e_2, \ldots, e_n\}$，其中 $e_i = (t_i, \text{payload}_i)$，$t_i$ 为事件发生时间戳，$\text{payload}_i$ 为事件负载。事件流满足单调性：$t_1 \leq t_2 \leq \ldots \leq t_n$。

定义事件处理函数 $f: \text{Payload} \to \text{Output}$，速率限制函数 $R: (E, T) \to E'$ 将原始事件流 $E$ 映射为实际执行流 $E'$，其中 $T$ 为配置参数（如等待时间、间隔）。

3.2 防抖的形式化定义

定义 1（防抖，Debounce）：给定事件流 $E = \{e_1, \ldots, e_n\}$ 与等待时间 $W$，防抖后的执行流 $E'_D$ 定义为：

即：仅当某个事件后 $W$ 时间内无新事件时，该事件才会被触发执行。最后一个事件总是在事件流停止后 $W$ 时间被触发（若配置 trailing）。

防抖的执行时序可形式化为：

3.3 节流的形式化定义

定义 2（节流，Throttle）：给定事件流 $E = \{e_1, \ldots, e_n\}$ 与间隔时间 $T$，节流后的执行流 $E'_T$ 定义为：

即：在任意长度为 $T$ 的时间窗口内，最多有一个事件被执行。

节流的执行时序可形式化为：

3.4 前缘与后缘的语义

定义 3（前缘触发，Leading Edge）：事件流起始的第一次事件立即执行，无需等待。

定义 4（后缘触发，Trailing Edge）：事件流结束后，最后一次事件在 $T$ 时间后被补触发。

四种组合的执行模式：

3.5 maxWait 的形式化定义

定义 5（最大等待时间，maxWait）：防抖函数在连续触发下，最多延迟 maxWait 时间后必须执行一次。

即：若防抖被持续触发超过 $M$ 时间，则强制执行一次。maxWait 将防抖退化为”防抖 + 节流”的混合体：在事件流持续期间以 $M$ 为间隔节流，在事件流停止后以 $W$ 为延迟防抖。

3.6 复杂度分析

设事件流长度为 $n$，时间窗口为 $T$：

• 防抖的执行次数：最坏 $O(n)$（每个事件后都超过 $W$），最好 $O(1)$（仅最后一次）。
• 节流的执行次数：$O(nT_{\text{total}} / T)$，其中 $T_{\text{total}}$ 为事件流总时长。
• 防抖的内存开销：$O(1)$（仅一个 setTimeout 句柄与参数引用）。
• 节流的内存开销：$O(1)$（一个时间戳与一个 setTimeout 句柄）。
• 防抖的时间开销：每次触发 $O(1)$（clearTimeout + setTimeout 均为 $O(1)$）。
• 节流的时间开销：每次触发 $O(1)$（时间戳比较 + 条件 setTimeout）。

4. 理论推导与证明

4.1 引理：防抖的终止性

引理：若事件流 $E$ 在某时刻 $t_{\text{end}}$ 后不再产生新事件，则防抖函数必在 $t_{\text{end}} + W$ 时刻执行最后一次事件。

证明：

设防抖函数的调度逻辑为：每次新事件到来时，取消之前的 setTimeout，注册新的 setTimeout(callback, W)。

考虑事件流 $E = \{e_1, \ldots, e_n\}$，最后一个事件为 $e_n$，时刻为 $t_n$。

在 $t_n$ 时刻，防抖函数取消之前的 setTimeout，注册新的 setTimeout(callback, W)，其触发时刻为 $t_n + W$。

由于 $t_n$ 后无新事件，该 setTimeout 不会被取消，故在 $t_n + W$ 时刻必然触发。

证毕。

工程意义：防抖保证最终一致性——只要事件流停止，最后一次事件必然被执行。这对搜索补全、表单自动保存等场景至关重要。

4.2 定理：节流的速率上界

定理：对任意事件流 $E$ 与间隔 $T$，节流后的执行速率上界为 $1/T$ 次/秒。

证明：

设节流后的执行流为 $E'_T = \{e'_1, e'_2, \ldots\}$，按时间排序。

由节流的定义，对任意 $i < j$，有 $t'_j - t'_i \geq T$（若 $j = i + 1$）。

故在任意长度为 $\Delta t$ 的时间窗口内，执行次数最多为：

当 $\Delta t \to \infty$ 时，速率趋近于 $1/T$ 次/秒。

证毕。

工程意义：节流提供硬性速率保证，适用于与服务端有 QPS 限制的场景（如 API 调用频率限制）。

4.3 命题：防抖与节流的等价条件

命题：当 maxWait = W 时，防抖退化为节流。

证明：

设防抖配置为 (W, maxWait=W)。

• 在事件流持续期间，每次触发都重置 setTimeout(W)，但同时检查距上次执行是否超过 maxWait = W。
• 若超过，则立即执行。这等价于”每 $W$ 时间至少执行一次”，即节流。

形式化：设 $t_{\text{last}}$ 为上次执行时刻，当前事件时刻 $t_i$：

• 若 $t_i - t_{\text{last}} \geq W$（即超过 maxWait），立即执行，更新 $t_{\text{last}} = t_i$。
• 否则，调度 setTimeout(W)，等待事件流停止。

这正是节流的”前缘触发”模式。

证毕。

4.4 推论：rAF 节流的帧率保证

推论：基于 requestAnimationFrame 的节流，在浏览器可见时保证执行速率等于显示器刷新率（通常 60fps，即 16.67ms 一次）。

证明：

requestAnimationFrame 的规范（HTML Living Standard §8.5）规定：浏览器在每次渲染前调用所有注册的 rAF 回调，渲染频率与显示器刷新率一致。

设显示器刷新率为 $R$ fps，则 rAF 回调的调用间隔为 $1000/R$ ms。

rAF 节流的实现：每次事件触发时，若未注册 rAF，则注册一个；rAF 回调执行后清空标记。

故在事件流持续期间，rAF 节流的执行频率等于 $R$ fps。

但当标签页不可见时，浏览器会暂停 rAF 调用，此时执行频率降为 0。

证毕。

工程意义：rAF 节流是视觉更新的最优选择，天然对齐显示器刷新率，避免无效渲染。但不可用于后台任务或服务端场景（Node.js 无 rAF）。

4.5 定理：防抖的内存安全性

定理：正确实现的防抖函数不会造成内存泄漏，即使事件持续触发。

证明：

防抖函数的闭包捕获以下变量：

1. timer：setTimeout 的句柄（数值或对象）。
2. fn：被防抖的原始函数。
3. args：最后一次调用的参数（若实现为保存 args）。
4. this：调用上下文。

每次新事件触发时：

1. clearTimeout(timer)：取消之前的 setTimeout，使旧的回调不再被调度。
2. timer = setTimeout(...)：注册新的 setTimeout，返回新句柄。

旧回调被取消后，其闭包引用的 args 与 this 不再被事件循环持有，可被 GC 回收（若无其他引用）。

故防抖函数的内存占用恒定为 $O(1)$，不随事件数量增长。

证毕。

反例：若实现错误（如未 clearTimeout 导致多个 setTimeout 同时存在），则会累积内存占用，每个未触发的回调都持有 args 引用。

4.6 定理：节流的最终一致性

定理：配置 trailing: true 的节流函数，在事件流停止后必然执行最后一次事件。

证明：

设节流函数的调度逻辑为：

1. 若距上次执行超过 $T$，立即执行，更新 lastExec。
2. 否则，调度 setTimeout(callback, T - (now - lastExec))，保存最新 args。

考虑事件流 $E = \{e_1, \ldots, e_n\}$，最后一个事件 $e_n$ 在时刻 $t_n$。

在 $t_n$ 时刻，距上次执行 $t_n - \text{lastExec} < T$（否则立即执行）。

调度 setTimeout(callback, T - (t_n - lastExec))，触发时刻为 $\text{lastExec} + T$。

由于 $t_n$ 后无新事件，该 setTimeout 不会被取消，故在 $\text{lastExec} + T$ 时刻必然触发，执行最后一次保存的 args。

证毕。

工程意义：trailing: true 保证节流不丢失末次事件，对拖拽、滚动等需要最终状态更新的场景至关重要。

5. 代码示例

5.1 基础防抖实现

// 文件名: debounce-basic.js
// 运行方式: node debounce-basic.js

/**
 * 基础防抖函数
 * @param {Function} fn - 需要防抖的函数
 * @param {number} delay - 等待时间（毫秒）
 * @returns {Function} 防抖后的函数
 */
function debounce(fn, delay) {
  let timer = null;

  return function (...args) {
    // 每次触发都取消之前的定时器，重新计时
    if (timer) clearTimeout(timer);

    timer = setTimeout(() => {
      fn.apply(this, args);
      timer = null;
    }, delay);
  };
}

// 测试：模拟搜索输入
const mockSearch = debounce((query) => {
  console.log(`[${new Date().toISOString()}] 搜索: ${query}`);
}, 300);

// 模拟用户快速输入
console.log('开始模拟输入...');
mockSearch('a');
mockSearch('ab');
mockSearch('abc');
mockSearch('abcd');
mockSearch('abcde');

// 300ms 后才会输出: 搜索: abcde
// 因为前 4 次都被第 5 次取消

5.2 支持立即触发的防抖

// 文件名: debounce-immediate.js
// 运行方式: node debounce-immediate.js

/**
 * 支持立即触发的防抖
 * @param {Function} fn - 原始函数
 * @param {number} delay - 等待时间
 * @param {boolean} immediate - 是否立即触发首次
 */
function debounce(fn, delay, immediate = false) {
  let timer = null;

  return function (...args) {
    if (timer) clearTimeout(timer);

    // 立即触发模式：首次（timer 为 null 时）立即执行
    if (immediate && !timer) {
      fn.apply(this, args);
    }

    timer = setTimeout(() => {
      if (!immediate) {
        fn.apply(this, args);
      }
      timer = null;
    }, delay);
  };
}

// 测试：立即触发模式
const immediateSearch = debounce(
  (q) => console.log(`立即搜索: ${q}`),
  500,
  true
);

immediateSearch('a');  // 立即输出: 立即搜索: a
immediateSearch('ab'); // 被防抖，不输出
immediateSearch('abc'); // 被防抖，不输出
// 500ms 后 timer 重置，下次调用又会立即触发

// 测试：延迟触发模式（默认）
const delayedSearch = debounce(
  (q) => console.log(`延迟搜索: ${q}`),
  500,
  false
);

delayedSearch('x');  // 不输出
delayedSearch('xy'); // 不输出
delayedSearch('xyz'); // 不输出
// 500ms 后输出: 延迟搜索: xyz

5.3 支持取消与立即执行的完整防抖

// 文件名: debounce-full.js
// 运行方式: node debounce-full.js

/**
 * 完整版防抖：支持取消、立即执行、pending 状态查询
 */
function debounce(fn, delay, { leading = false, trailing = true } = {}) {
  let timer = null;
  let lastArgs = null;
  let lastThis = null;

  function invoke() {
    if (lastArgs !== null) {
      fn.apply(lastThis, lastArgs);
      lastArgs = null;
      lastThis = null;
    }
  }

  function cancel() {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
    lastArgs = null;
    lastThis = null;
  }

  function flush() {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
    invoke();
  }

  function pending() {
    return timer !== null;
  }

  const debounced = function (...args) {
    lastArgs = args;
    lastThis = this;

    // 首次触发且 leading 启用时立即执行
    if (!timer && leading) {
      invoke();
    }

    if (timer) clearTimeout(timer);

    timer = setTimeout(() => {
      timer = null;
      if (trailing && lastArgs !== null) {
        invoke();
      }
    }, delay);
  };

  debounced.cancel = cancel;
  debounced.flush = flush;
  debounced.pending = pending;

  return debounced;
}

// 测试用例
const log = debounce(
  (msg) => console.log(`[${Date.now()}] ${msg}`),
  200,
  { leading: true, trailing: true }
);

log('first');  // 立即输出（leading）
log('second'); // 被防抖
log('third');  // 被防抖
// 200ms 后输出 third（trailing）

console.log('pending:', log.pending()); // true（200ms 内）
setTimeout(() => {
  console.log('pending after 250ms:', log.pending()); // false
}, 250);

5.4 时间戳节流（首次立即执行）

// 文件名: throttle-timestamp.js
// 运行方式: node throttle-timestamp.js

/**
 * 基于时间戳的节流
 * 特点：首次立即执行，末次不补执行
 */
function throttle(fn, interval) {
  let lastTime = 0;

  return function (...args) {
    const now = Date.now();

    if (now - lastTime >= interval) {
      fn.apply(this, args);
      lastTime = now;
    }
  };
}

// 测试
const throttledLog = throttle((msg) => {
  console.log(`[${Date.now()}] ${msg}`);
}, 100);

// 模拟高频调用
console.log('开始高频调用...');
for (let i = 0; i < 10; i++) {
  throttledLog(`call-${i}`);
}
// 仅 call-0 会执行（首次立即触发）
// 后续 9 次因间隔不足 100ms 被忽略

5.5 定时器节流（末次补执行）

// 文件名: throttle-timer.js
// 运行方式: node throttle-timer.js

/**
 * 基于定时器的节流
 * 特点：首次延迟执行，末次必执行
 */
function throttle(fn, interval) {
  let timer = null;
  let lastArgs = null;
  let lastThis = null;

  return function (...args) {
    lastArgs = args;
    lastThis = this;

    if (!timer) {
      timer = setTimeout(() => {
        fn.apply(lastThis, lastArgs);
        timer = null;
        lastArgs = null;
        lastThis = null;
      }, interval);
    }
  };
}

// 测试
const throttledLog = throttle((msg) => {
  console.log(`[${Date.now()}] ${msg}`);
}, 100);

// 模拟高频调用
for (let i = 0; i < 10; i++) {
  throttledLog(`call-${i}`);
}
// 100ms 后执行 call-9（最后一次保存的参数）

5.6 混合节流（首尾都执行）

// 文件名: throttle-hybrid.js
// 运行方式: node throttle-hybrid.js

/**
 * 时间戳 + 定时器混合节流
 * 特点：首次立即执行，末次补执行
 */
function throttle(fn, interval) {
  let lastTime = 0;
  let timer = null;

  return function (...args) {
    const now = Date.now();
    const remaining = interval - (now - lastTime);

    if (remaining <= 0) {
      // 已超过间隔，立即执行
      if (timer) {
        clearTimeout(timer);
        timer = null;
      }
      fn.apply(this, args);
      lastTime = now;
    } else if (!timer) {
      // 未超过间隔，调度末次补执行
      timer = setTimeout(() => {
        fn.apply(this, args);
        lastTime = Date.now();
        timer = null;
      }, remaining);
    }
  };
}

// 测试
const throttledLog = throttle((msg) => {
  console.log(`[${Date.now()}] ${msg}`);
}, 100);

// 模拟持续高频调用
let count = 0;
const intervalId = setInterval(() => {
  throttledLog(`call-${count++}`);
  if (count >= 20) clearInterval(intervalId);
}, 30);
// 每 100ms 执行一次，首次立即执行

5.7 requestAnimationFrame 节流

// 文件名: throttle-raf.js
// 运行方式: 在浏览器环境运行

/**
 * 基于 requestAnimationFrame 的节流
 * 适用场景：视觉更新（动画、滚动、拖拽）
 * 注意：Node.js 无 rAF，仅在浏览器可用
 */
function rafThrottle(fn) {
  let rafId = null;
  let lastArgs = null;
  let lastThis = null;

  return function (...args) {
    lastArgs = args;
    lastThis = this;

    if (rafId !== null) return;

    rafId = requestAnimationFrame(() => {
      fn.apply(lastThis, lastArgs);
      rafId = null;
      lastArgs = null;
      lastThis = null;
    });
  };
}

// 浏览器使用示例
const onMouseMove = rafThrottle((e) => {
  // 仅在每帧执行一次，对齐显示器刷新率
  updateCursorPosition(e.clientX, e.clientY);
});

document.addEventListener('mousemove', onMouseMove);

// 注意：rAF 在标签页不可见时会暂停
// 若需要后台执行，应使用 setTimeout 节流

5.8 搜索自动补全（防抖典型应用）

// 文件名: search-autocomplete.js
// 运行方式: 在浏览器环境运行

/**
 * 搜索输入防抖处理
 * 场景：用户输入时延迟请求后端，减少无效请求
 */

class SearchBox {
  constructor(inputElement, suggestionsElement) {
    this.input = inputElement;
    this.suggestions = suggestionsElement;
    this.controller = null; // AbortController 用于取消未完成请求

    // 防抖 300ms：用户停止输入 300ms 后才发请求
    this.debouncedSearch = this.debounce(this.search.bind(this), 300);

    this.input.addEventListener('input', (e) => {
      this.debouncedSearch(e.target.value);
    });
  }

  debounce(fn, delay) {
    let timer = null;
    return function (...args) {
      clearTimeout(timer);
      timer = setTimeout(() => fn.apply(this, args), delay);
    };
  }

  async search(query) {
    if (!query.trim()) {
      this.renderSuggestions([]);
      return;
    }

    // 取消上一次未完成的请求
    if (this.controller) {
      this.controller.abort();
    }
    this.controller = new AbortController();

    try {
      const response = await fetch(
        `/api/search?q=${encodeURIComponent(query)}`,
        { signal: this.controller.signal }
      );
      const data = await response.json();
      this.renderSuggestions(data);
    } catch (err) {
      if (err.name === 'AbortError') {
        console.log('请求已取消');
      } else {
        console.error('搜索失败:', err);
      }
    }
  }

  renderSuggestions(items) {
    this.suggestions.innerHTML = items
      .map((item) => `<li>${item}</li>`)
      .join('');
  }
}

// 使用
// const searchBox = new SearchBox(
//   document.getElementById('search-input'),
//   document.getElementById('suggestions')
// );

5.9 滚动加载（节流典型应用）

// 文件名: infinite-scroll.js
// 运行方式: 在浏览器环境运行

/**
 * 无限滚动节流处理
 * 场景：滚动时检测是否触底，加载更多内容
 */

class InfiniteScroll {
  constructor(container, loader) {
    this.container = container;
    this.loader = loader;
    this.loading = false;
    this.page = 1;

    // 节流 200ms：避免滚动事件密集触发
    this.throttledCheck = this.throttle(this.checkAndLoad.bind(this), 200);

    window.addEventListener('scroll', this.throttledCheck);
  }

  throttle(fn, interval) {
    let lastTime = 0;
    let timer = null;

    return function (...args) {
      const now = Date.now();
      const remaining = interval - (now - lastTime);

      if (remaining <= 0) {
        if (timer) {
          clearTimeout(timer);
          timer = null;
        }
        fn.apply(this, args);
        lastTime = now;
      } else if (!timer) {
        timer = setTimeout(() => {
          fn.apply(this, args);
          lastTime = Date.now();
          timer = null;
        }, remaining);
      }
    };
  }

  checkAndLoad() {
    if (this.loading) return;

    const scrollTop = document.documentElement.scrollTop;
    const windowHeight = window.innerHeight;
    const documentHeight = document.documentElement.scrollHeight;

    // 距底部 100px 时触发加载
    if (scrollTop + windowHeight >= documentHeight - 100) {
      this.loadMore();
    }
  }

  async loadMore() {
    this.loading = true;
    this.loader.style.display = 'block';

    try {
      const response = await fetch(`/api/items?page=${this.page}`);
      const items = await response.json();

      if (items.length === 0) {
        // 无更多数据，移除监听
        window.removeEventListener('scroll', this.throttledCheck);
        return;
      }

      items.forEach((item) => {
        const el = document.createElement('div');
        el.className = 'item';
        el.textContent = item.text;
        this.container.appendChild(el);
      });

      this.page++;
    } catch (err) {
      console.error('加载失败:', err);
    } finally {
      this.loading = false;
      this.loader.style.display = 'none';
    }
  }

  destroy() {
    window.removeEventListener('scroll', this.throttledCheck);
  }
}

5.10 按钮防连点（节流应用）

// 文件名: prevent-double-click.js
// 运行方式: 在浏览器环境运行

/**
 * 按钮防连点
 * 场景：表单提交按钮，防止用户快速点击导致重复提交
 */

function preventDoubleClick(handler, cooldown = 2000) {
  let lastClick = 0;
  let pending = false;

  return async function (...args) {
    const now = Date.now();

    if (pending) {
      console.log('请求处理中，忽略点击');
      return;
    }

    if (now - lastClick < cooldown) {
      console.log(`冷却中，剩余 ${cooldown - (now - lastClick)}ms`);
      return;
    }

    lastClick = now;
    pending = true;

    try {
      await handler.apply(this, args);
    } finally {
      pending = false;
    }
  };
}

// 使用示例
const submitBtn = document.getElementById('submit-btn');
const submitForm = preventDoubleClick(async () => {
  const response = await fetch('/api/submit', {
    method: 'POST',
    body: new FormData(document.getElementById('form'))
  });
  const result = await response.json();
  console.log('提交结果:', result);
}, 2000);

submitBtn.addEventListener('click', submitForm);

5.11 Vue 3 Composition API 集成

// 文件名: use-debounce.js
// 运行方式: 在 Vue 3 项目中导入使用

import { ref, watch, onUnmounted } from 'vue';

/**
 * Vue 3 防抖 Hook
 * @param {Function} fn - 原始函数
 * @param {number} delay - 延迟时间
 * @returns {Object} { run, cancel, flush }
 */
export function useDebounceFn(fn, delay = 300) {
  let timer = null;

  const cancel = () => {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
  };

  const flush = () => {
    cancel();
    fn();
  };

  const run = (...args) => {
    cancel();
    timer = setTimeout(() => {
      fn(...args);
      timer = null;
    }, delay);
  };

  onUnmounted(cancel);

  return { run, cancel, flush };
}

/**
 * Vue 3 防抖响应式值
 * @param {import('vue').Ref} source - 源响应式值
 * @param {number} delay - 延迟时间
 * @returns {import('vue').Ref} 防抖后的响应式值
 */
export function useDebounce(source, delay = 300) {
  const debounced = ref(source.value);
  let timer = null;

  watch(source, (val) => {
    if (timer) clearTimeout(timer);
    timer = setTimeout(() => {
      debounced.value = val;
      timer = null;
    }, delay);
  });

  onUnmounted(() => {
    if (timer) clearTimeout(timer);
  });

  return debounced;
}

/**
 * Vue 3 节流 Hook
 */
export function useThrottleFn(fn, interval = 200) {
  let lastTime = 0;
  let timer = null;

  const run = (...args) => {
    const now = Date.now();
    const remaining = interval - (now - lastTime);

    if (remaining <= 0) {
      if (timer) {
        clearTimeout(timer);
        timer = null;
      }
      fn(...args);
      lastTime = now;
    } else if (!timer) {
      timer = setTimeout(() => {
        fn(...args);
        lastTime = Date.now();
        timer = null;
      }, remaining);
    }
  };

  const cancel = () => {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
    lastTime = 0;
  };

  onUnmounted(cancel);

  return { run, cancel };
}

5.12 React Hook 集成

// 文件名: use-debounce.js
// 运行方式: 在 React 项目中导入使用

import { useRef, useCallback, useEffect, useState } from 'react';

/**
 * React 防抖回调 Hook
 * @param {Function} fn - 原始函数
 * @param {number} delay - 延迟时间
 * @param {Array} deps - 依赖数组
 * @returns {Function} 防抖后的函数
 */
export function useDebouncedCallback(fn, delay, deps = []) {
  const fnRef = useRef(fn);
  const timerRef = useRef(null);

  // 更新最新的函数引用
  useEffect(() => {
    fnRef.current = fn;
  }, [fn]);

  // 组件卸载时清理定时器
  useEffect(() => {
    return () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
      }
    };
  }, []);

  const debounced = useCallback((...args) => {
    if (timerRef.current) {
      clearTimeout(timerRef.current);
    }
    timerRef.current = setTimeout(() => {
      fnRef.current(...args);
      timerRef.current = null;
    }, delay);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [delay, ...deps]);

  const cancel = useCallback(() => {
    if (timerRef.current) {
      clearTimeout(timerRef.current);
      timerRef.current = null;
    }
  }, []);

  const flush = useCallback((...args) => {
    cancel();
    fnRef.current(...args);
  }, [cancel]);

  return { debounced, cancel, flush };
}

/**
 * React 防抖值 Hook
 * @param {*} initialValue - 初始值
 * @param {number} delay - 延迟时间
 * @returns {Array} [value, setValue]
 */
export function useDebouncedValue(initialValue, delay = 300) {
  const [value, setValue] = useState(initialValue);
  const [debouncedValue, setDebouncedValue] = useState(initialValue);

  useEffect(() => {
    const timer = setTimeout(() => {
      setDebouncedValue(value);
    }, delay);

    return () => clearTimeout(timer);
  }, [value, delay]);

  return [debouncedValue, setValue];
}

/**
 * React 节流回调 Hook
 */
export function useThrottledCallback(fn, interval, deps = []) {
  const fnRef = useRef(fn);
  const lastTimeRef = useRef(0);
  const timerRef = useRef(null);

  useEffect(() => {
    fnRef.current = fn;
  }, [fn]);

  useEffect(() => {
    return () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
      }
    };
  }, []);

  const throttled = useCallback((...args) => {
    const now = Date.now();
    const remaining = interval - (now - lastTimeRef.current);

    if (remaining <= 0) {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
        timerRef.current = null;
      }
      fnRef.current(...args);
      lastTimeRef.current = now;
    } else if (!timerRef.current) {
      timerRef.current = setTimeout(() => {
        fnRef.current(...args);
        lastTimeRef.current = Date.now();
        timerRef.current = null;
      }, remaining);
    }
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [interval, ...deps]);

  return throttled;
}

5.13 指数退避防抖（用于错误重试）

// 文件名: exponential-backoff.js
// 运行方式: node exponential-backoff.js

/**
 * 指数退避重试
 * 场景：网络请求失败后，以指数增长间隔重试
 * @param {Function} fn - 返回 Promise 的函数
 * @param {Object} options - 配置
 * @param {number} options.maxRetries - 最大重试次数
 * @param {number} options.baseDelay - 基础延迟
 * @param {number} options.maxDelay - 最大延迟
 * @param {number} options.factor - 退避因子
 */
async function exponentialBackoff(fn, options = {}) {
  const {
    maxRetries = 5,
    baseDelay = 1000,
    maxDelay = 30000,
    factor = 2,
  } = options;

  let lastError;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn(attempt);
    } catch (err) {
      lastError = err;

      if (attempt === maxRetries) {
        console.error(`达到最大重试次数 ${maxRetries}，放弃`);
        throw err;
      }

      // 计算退避延迟：baseDelay * factor^attempt
      const delay = Math.min(baseDelay * Math.pow(factor, attempt), maxDelay);

      // 添加抖动（jitter），避免多个客户端同时重试
      const jitter = Math.random() * delay * 0.1;
      const finalDelay = delay + jitter;

      console.warn(
        `第 ${attempt + 1} 次失败，${finalDelay.toFixed(0)}ms 后重试:`,
        err.message
      );

      await new Promise((resolve) => setTimeout(resolve, finalDelay));
    }
  }

  throw lastError;
}

// 测试用例
async function mockRequest(attempt) {
  console.log(`第 ${attempt + 1} 次尝试请求...`);
  // 模拟前 3 次失败，第 4 次成功
  if (attempt < 3) {
    throw new Error(`模拟失败 (attempt ${attempt + 1})`);
  }
  return { success: true, attempt };
}

exponentialBackoff(mockRequest, {
  maxRetries: 5,
  baseDelay: 100,
  maxDelay: 5000,
  factor: 2,
})
  .then((result) => console.log('最终成功:', result))
  .catch((err) => console.error('最终失败:', err.message));

5.14 Lodash 风格的完整实现

// 文件名: lodash-style.js
// 运行方式: node lodash-style.js

/**
 * Lodash 风格的 debounce + throttle 统一实现
 * 支持 leading / trailing / maxWait 完整配置
 */
function debounce(fn, wait = 0, options = {}) {
  const { leading = false, trailing = true, maxWait } = options;
  let timer = null;
  let maxTimer = null;
  let lastArgs = null;
  let lastThis = null;
  let lastCallTime = 0;
  let lastInvokeTime = 0;

  function invokeFunc(time) {
    const args = lastArgs;
    const thisArg = lastThis;
    lastArgs = null;
    lastThis = null;
    lastInvokeTime = time;
    return fn.apply(thisArg, args);
  }

  function leadingEdge(time) {
    lastInvokeTime = time;
    timer = setTimeout(timerExpired, wait);
    if (leading) {
      return invokeFunc(time);
    }
    return lastArgs;
  }

  function remainingWait(time) {
    const timeSinceLastCall = time - lastCallTime;
    const timeSinceLastInvoke = time - lastInvokeTime;
    const timeWaiting = wait - timeSinceLastCall;
    return maxWait !== undefined
      ? Math.min(timeWaiting, maxWait - timeSinceLastInvoke)
      : timeWaiting;
  }

  function shouldInvoke(time) {
    const timeSinceLastCall = time - lastCallTime;
    const timeSinceLastInvoke = time - lastInvokeTime;
    return (
      lastCallTime === undefined ||
      timeSinceLastCall >= wait ||
      timeSinceLastCall < 0 ||
      (maxWait !== undefined && timeSinceLastInvoke >= maxWait)
    );
  }

  function timerExpired() {
    const time = Date.now();
    if (shouldInvoke(time)) {
      return trailingEdge(time);
    }
    timer = setTimeout(timerExpired, remainingWait(time));
  }

  function trailingEdge(time) {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
    if (trailing && lastArgs) {
      return invokeFunc(time);
    }
    lastArgs = null;
    lastThis = null;
    return lastArgs;
  }

  function cancel() {
    if (timer) clearTimeout(timer);
    if (maxTimer) clearTimeout(maxTimer);
    timer = null;
    maxTimer = null;
    lastArgs = null;
    lastThis = null;
    lastCallTime = 0;
    lastInvokeTime = 0;
  }

  function flush() {
    if (timer) {
      clearTimeout(timer);
      timer = null;
    }
    return lastArgs ? invokeFunc(Date.now()) : undefined;
  }

  function pending() {
    return timer !== null;
  }

  function debounced(...args) {
    const time = Date.now();
    const isInvoking = shouldInvoke(time);

    lastArgs = args;
    lastThis = this;
    lastCallTime = time;

    if (isInvoking) {
      if (!timer) {
        return leadingEdge(lastCallTime);
      }
      if (maxWait !== undefined) {
        timer = setTimeout(timerExpired, remainingWait(time));
        return invokeFunc(time);
      }
    }
    if (!timer) {
      timer = setTimeout(timerExpired, wait);
    }
    return lastArgs;
  }

  debounced.cancel = cancel;
  debounced.flush = flush;
  debounced.pending = pending;

  return debounced;
}

/**
 * throttle 等价于 debounce(fn, wait, { leading: true, trailing: true, maxWait: wait })
 */
function throttle(fn, wait = 0, options = {}) {
  return debounce(fn, wait, {
    leading: true,
    trailing: true,
    maxWait: wait,
    ...options,
  });
}

// 测试
const debounced = debounce(
  (msg) => console.log(`[${Date.now()}] debounced: ${msg}`),
  200,
  { leading: true, trailing: true }
);

debounced('a');
debounced('b');
debounced('c');
// 立即输出 a（leading）
// 200ms 后输出 c（trailing）

const throttled = throttle(
  (msg) => console.log(`[${Date.now()}] throttled: ${msg}`),
  200
);

throttled('x');
throttled('y');
throttled('z');
// 立即输出 x（leading）
// 200ms 后输出 z（trailing，因为 maxWait=200）

5.15 拖拽场景的完整实现

// 文件名: drag-demo.js
// 运行方式: 在浏览器环境运行

/**
 * 拖拽场景的速率限制处理
 * - mousedown 时立即响应
 * - mousemove 时使用 rAF 节流，保证流畅
 * - mouseup 时立即响应，并清理资源
 */
class Draggable {
  constructor(element) {
    this.element = element;
    this.isDragging = false;
    this.startX = 0;
    this.startY = 0;
    this.offsetX = 0;
    this.offsetY = 0;
    this.rafId = null;

    // 绑定方法
    this.handleMouseDown = this.handleMouseDown.bind(this);
    this.handleMouseMove = this.handleMouseMove.bind(this);
    this.handleMouseUp = this.handleMouseUp.bind(this);

    this.element.addEventListener('mousedown', this.handleMouseDown);
  }

  handleMouseDown(e) {
    this.isDragging = true;
    this.startX = e.clientX - this.offsetX;
    this.startY = e.clientY - this.offsetY;
    this.element.style.cursor = 'grabbing';

    document.addEventListener('mousemove', this.handleMouseMove);
    document.addEventListener('mouseup', this.handleMouseUp);
  }

  handleMouseMove(e) {
    // 保存最新位置，使用 rAF 节流
    this.lastX = e.clientX - this.startX;
    this.lastY = e.clientY - this.startY;

    if (this.rafId !== null) return;

    this.rafId = requestAnimationFrame(() => {
      this.offsetX = this.lastX;
      this.offsetY = this.lastY;
      this.element.style.transform = `translate(${this.offsetX}px, ${this.offsetY}px)`;
      this.rafId = null;
    });
  }

  handleMouseUp() {
    this.isDragging = false;
    this.element.style.cursor = 'grab';

    document.removeEventListener('mousemove', this.handleMouseMove);
    document.removeEventListener('mouseup', this.handleMouseUp);

    // 清理未执行的 rAF
    if (this.rafId !== null) {
      cancelAnimationFrame(this.rafId);
      this.rafId = null;
    }
  }

  destroy() {
    this.element.removeEventListener('mousedown', this.handleMouseDown);
    document.removeEventListener('mousemove', this.handleMouseMove);
    document.removeEventListener('mouseup', this.handleMouseUp);
    if (this.rafId !== null) {
      cancelAnimationFrame(this.rafId);
    }
  }
}

// 使用
// const draggable = new Draggable(document.getElementById('drag-box'));

6. 对比分析

6.1 防抖 vs 节流 vs rAF vs requestIdleCallback

6.2 各框架速率限制方案对比

6.3 速率限制算法对比

6.4 选择决策树

是否需要速率限制？
├── 否 → 直接处理事件
└── 是
    ├── 场景是视觉更新？（动画、滚动渲染）
    │   └── 使用 rAF 节流
    ├── 场景是搜索/保存？（等待用户停止操作）
    │   └── 使用防抖（debounce）
    ├── 场景是滚动/拖拽？（固定频率更新）
    │   └── 使用节流（throttle）
    ├── 场景是后台计算？（不影响主线程）
    │   └── 使用 requestIdleCallback
    └── 场景是失败重试？
        └── 使用指数退避

7. 常见陷阱与反模式

7.1 反模式：丢失 this 绑定

// 反模式：直接调用 fn，丢失 this
function badDebounce(fn, delay) {
  let timer;
  return function (...args) {
    clearTimeout(timer);
    timer = setTimeout(() => {
      fn(args); // 错误：未使用 apply，this 指向全局或 undefined
    }, delay);
  };
}

// 正确做法
function goodDebounce(fn, delay) {
  let timer;
  return function (...args) {
    clearTimeout(timer);
    timer = setTimeout(() => {
      fn.apply(this, args); // 正确：传递 this 与 args
    }, delay);
  };
}

// 验证
const obj = {
  name: 'Alice',
  greet: goodDebounce(function () {
    console.log(`Hello, ${this.name}`); // this 指向 obj
  }, 100),
};

obj.greet(); // 100ms 后输出: Hello, Alice

7.2 反模式：未清理定时器导致内存泄漏

// 反模式：组件销毁时未清理定时器
function useBadDebounce(fn, delay) {
  let timer;
  const debounced = (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), delay);
  };
  // 未在组件卸载时清理 timer，可能导致：
  // 1. 回调在组件销毁后仍执行，访问已销毁的状态
  // 2. 闭包引用组件数据，阻碍 GC
  return debounced;
}

// 正确做法：提供 cancel 并在卸载时调用
function useGoodDebounce(fn, delay) {
  let timer;
  const debounced = (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), delay);
  };
  debounced.cancel = () => {
    clearTimeout(timer);
    timer = null;
  };
  return debounced;
}

// React 中使用
function MyComponent() {
  const debouncedSearch = useGoodDebounce(search, 300);

  useEffect(() => {
    return () => debouncedSearch.cancel(); // 卸载时清理
  }, []);

  return <input onChange={(e) => debouncedSearch(e.target.value)} />;
}

7.3 反模式：事件监听器累积

// 反模式：每次渲染都添加新监听器，未移除旧的
function BadComponent() {
  const handleScroll = throttle(() => {
    console.log('scroll');
  }, 200);

  useEffect(() => {
    window.addEventListener('scroll', handleScroll);
    // 未 return cleanup，每次渲染都累积监听器
  });

  return <div>...</div>;
}

// 正确做法：在 useEffect 中添加与清理
function GoodComponent() {
  useEffect(() => {
    const handleScroll = throttle(() => {
      console.log('scroll');
    }, 200);
    window.addEventListener('scroll', handleScroll);
    return () => {
      window.removeEventListener('scroll', handleScroll);
      handleScroll.cancel(); // 清理定时器
    };
  }, []); // 空依赖，仅挂载时添加

  return <div>...</div>;
}

7.4 反模式：异步函数未取消导致竞态

// 反模式：防抖触发多个异步请求，结果乱序返回
const badSearch = debounce(async (query) => {
  const response = await fetch(`/api/search?q=${query}`);
  const data = await response.json();
  renderResults(data); // 可能后发先至，显示旧结果
}, 300);

// 正确做法：使用 AbortController 取消未完成请求
const goodSearch = debounce(async (query) => {
  if (goodSearch.controller) {
    goodSearch.controller.abort();
  }
  goodSearch.controller = new AbortController();
  try {
    const response = await fetch(`/api/search?q=${query}`, {
      signal: goodSearch.controller.signal,
    });
    const data = await response.json();
    renderResults(data);
  } catch (err) {
    if (err.name !== 'AbortError') {
      console.error(err);
    }
  }
}, 300);

7.5 反模式：节流配置不当导致末次丢失

// 反模式：拖拽场景使用纯时间戳节流，末次位置丢失
const badDrag = throttle((x, y) => {
  updatePosition(x, y);
}, 16);
// 纯时间戳节流不保证末次执行
// 拖拽结束时位置可能未更新到最新

// 正确做法：使用 leading + trailing 节流
const goodDrag = throttle(
  (x, y) => {
    updatePosition(x, y);
  },
  16,
  { leading: true, trailing: true } // 保证末次执行
);

7.6 反模式：在循环中创建防抖函数

// 反模式：每次循环都创建新的防抖函数，防抖失效
function badBatchProcess(items) {
  items.forEach((item) => {
    // 每次循环都创建新的 debounce，互不影响
    const debouncedSave = debounce(save, 300);
    debouncedSave(item);
  });
}

// 正确做法：在循环外创建一次防抖函数
function goodBatchProcess(items) {
  const debouncedSave = debounce((item) => save(item), 300);
  items.forEach((item) => debouncedSave(item));
  // 或更优：批量保存
  const batchSave = debounce(() => {
    saveAll(items);
  }, 300);
  batchSave();
}

7.7 反模式：混淆防抖与节流

// 反模式：滚动监听使用防抖，导致滚动过程中无反馈
window.addEventListener(
  'scroll',
  debounce(() => {
    updateProgressBar(); // 仅在滚动停止后更新，体验差
  }, 200)
);

// 正确做法：滚动使用节流，提供持续反馈
window.addEventListener(
  'scroll',
  throttle(() => {
    updateProgressBar(); // 每 200ms 更新一次，流畅
  }, 200)
);

7.8 反模式：rAF 节流用于非视觉场景

// 反模式：用 rAF 节流网络请求
const badApiCall = rafThrottle(() => {
  fetch('/api/track', { method: 'POST' });
});
// 问题：标签页隐藏时 rAF 暂停，数据丢失

// 正确做法：网络请求用 setTimeout 节流
const goodApiCall = throttle(() => {
  fetch('/api/track', { method: 'POST' });
}, 1000);

8. 工程最佳实践

8.1 TypeScript 类型定义

// debounce.types.ts

interface DebounceOptions {
  /** 是否在事件流起始立即触发，默认 false */
  leading?: boolean;
  /** 是否在事件流结束后补触发，默认 true */
  trailing?: boolean;
  /** 最大等待时间（防抖退化为节流），仅 debounce 有效 */
  maxWait?: number;
}

interface DebouncedFunction<T extends (...args: any[]) => any> {
  (...args: Parameters<T>): ReturnType<T> | undefined;
  /** 取消待执行的调用 */
  cancel(): void;
  /** 立即执行待调用的函数 */
  flush(): ReturnType<T> | undefined;
  /** 是否有待执行的调用 */
  pending(): boolean;
}

/**
 * 防抖函数
 * @param fn 原始函数
 * @param wait 等待时间（毫秒）
 * @param options 配置选项
 */
declare function debounce<T extends (...args: any[]) => any>(
  fn: T,
  wait?: number,
  options?: DebounceOptions
): DebouncedFunction<T>;

/**
 * 节流函数
 * @param fn 原始函数
 * @param wait 间隔时间（毫秒）
 * @param options 配置选项
 */
declare function throttle<T extends (...args: any[]) => any>(
  fn: T,
  wait?: number,
  options?: Omit<DebounceOptions, 'maxWait'>
): DebouncedFunction<T>;

8.2 ESLint 自定义规则

// eslint-no-raw-settimeout.js
// 自定义 ESLint 规则：禁止在高频事件中直接使用 setTimeout，必须包裹 debounce/throttle

module.exports = {
  meta: {
    type: 'suggestion',
    docs: {
      description: '高频事件必须使用防抖或节流',
      category: 'Best Practices',
      recommended: true,
    },
    messages: {
      requireDebounce: '{{event}} 事件处理器必须使用 debounce 或 throttle 包裹',
    },
  },

  create(context) {
    const highFreqEvents = ['scroll', 'resize', 'mousemove', 'input', 'wheel'];
    const wrappedFunctions = new Set();

    return {
      // 检测 debounce/throttle 包裹的函数声明
      CallExpression(node) {
        if (
          node.callee.type === 'Identifier' &&
          (node.callee.name === 'debounce' || node.callee.name === 'throttle')
        ) {
          if (node.arguments[0]?.type === 'Identifier') {
            wrappedFunctions.add(node.arguments[0].name);
          }
        }
      },

      // 检测 addEventListener 调用
      'CallExpression[callee.property.name="addEventListener"]'(node) {
        const eventName = node.arguments[0]?.value;
        const handler = node.arguments[1];

        if (!highFreqEvents.includes(eventName)) return;

        // 检查 handler 是否被 debounce/throttle 包裹
        if (handler.type === 'Identifier') {
          if (!wrappedFunctions.has(handler.name)) {
            context.report({
              node,
              messageId: 'requireDebounce',
              data: { event: eventName },
            });
          }
        } else if (handler.type === 'CallExpression') {
          if (
            handler.callee.type !== 'Identifier' ||
            (handler.callee.name !== 'debounce' &&
              handler.callee.name !== 'throttle')
          ) {
            context.report({
              node,
              messageId: 'requireDebounce',
              data: { event: eventName },
            });
          }
        } else if (handler.type === 'FunctionExpression' || handler.type === 'ArrowFunctionExpression') {
          context.report({
            node,
            messageId: 'requireDebounce',
            data: { event: eventName },
          });
        }
      },
    };
  },
};

8.3 单元测试模板

// debounce.test.js
const { test, expect, vi } = require('vitest'); // 或 jest
const { debounce, throttle } = require('./debounce');

// 使用假定时器，避免真实等待
vi.useFakeTimers();

describe('debounce', () => {
  test('应在等待时间后执行一次', () => {
    const fn = vi.fn();
    const debounced = debounce(fn, 300);

    debounced();
    expect(fn).not.toHaveBeenCalled();

    vi.advanceTimersByTime(300);
    expect(fn).toHaveBeenCalledTimes(1);
  });

  test('连续调用应只执行最后一次', () => {
    const fn = vi.fn();
    const debounced = debounce(fn, 300);

    debounced('a');
    debounced('b');
    debounced('c');

    vi.advanceTimersByTime(300);
    expect(fn).toHaveBeenCalledTimes(1);
    expect(fn).toHaveBeenCalledWith('c');
  });

  test('leading 选项应立即执行首次', () => {
    const fn = vi.fn();
    const debounced = debounce(fn, 300, { leading: true });

    debounced('a');
    expect(fn).toHaveBeenCalledTimes(1);
    expect(fn).toHaveBeenCalledWith('a');

    vi.advanceTimersByTime(300);
    expect(fn).toHaveBeenCalledTimes(1); // 不会再次执行（trailing 默认 false）
  });

  test('cancel 应取消待执行调用', () => {
    const fn = vi.fn();
    const debounced = debounce(fn, 300);

    debounced();
    debounced.cancel();

    vi.advanceTimersByTime(300);
    expect(fn).not.toHaveBeenCalled();
  });

  test('flush 应立即执行', () => {
    const fn = vi.fn();
    const debounced = debounce(fn, 300);

    debounced('test');
    debounced.flush();

    expect(fn).toHaveBeenCalledTimes(1);
    expect(fn).toHaveBeenCalledWith('test');

    vi.advanceTimersByTime(300);
    expect(fn).toHaveBeenCalledTimes(1); // 不会重复执行
  });

  test('pending 应正确反映状态', () => {
    const fn = vi.fn();
    const debounced = debounce(fn, 300);

    expect(debounced.pending()).toBe(false);
    debounced();
    expect(debounced.pending()).toBe(true);

    vi.advanceTimersByTime(300);
    expect(debounced.pending()).toBe(false);
  });
});

describe('throttle', () => {
  test('应在首次调用时立即执行（leading 默认 true）', () => {
    const fn = vi.fn();
    const throttled = throttle(fn, 300);

    throttled('a');
    expect(fn).toHaveBeenCalledTimes(1);
    expect(fn).toHaveBeenCalledWith('a');
  });

  test('间隔内再次调用应被节流', () => {
    const fn = vi.fn();
    const throttled = throttle(fn, 300);

    throttled('a'); // 立即执行
    throttled('b'); // 被节流
    throttled('c'); // 被节流

    expect(fn).toHaveBeenCalledTimes(1);

    vi.advanceTimersByTime(300);
    expect(fn).toHaveBeenCalledTimes(2); // trailing 执行 c
    expect(fn).toHaveBeenLastCalledWith('c');
  });
});