如果你在日常业务里已经写过debounce或throttle封装大概对下面这种场景不陌生输入框触发搜索、按钮防重复提交、滚动列表做懒加载。以前这套方案只需要控制“函数调不调用”就够了回调函数里怎么处理、什么时候出结果都是函数自己的事。但今天不一样了。接口请求全部是异步的调用方需要await拿到结果做一个 Promise 版本的防抖节流库就成了一个非常实际的需求。这篇文章想讨论的不是“如何写一个 debounce”而是“当防抖节流遇上异步和 TypeScript会暴露出什么问题以及怎么从设计上去解决它”。1. 为什么防抖节流在异步场景下会“失灵”先回忆一下最传统的防抖实现。它的逻辑很简单每次触发时清理上一次的定时器然后重新开启一个新的定时器等用户停止操作后再执行回调。节流则相反它保证一个时间窗口内最多执行一次比如滚动事件里每 200ms 执行一次。在传统的同步回调模型里这套机制没什么问题。事件来了函数在合适的时机被调用返回值也没有人等待。但一旦把函数体改为异步函数问题就暴露了// 传统防抖包装的异步函数 const debouncedSearch debounce(async (keyword: string) { return await searchApi(keyword); }, 300); async function onInput(value: string) { // 这里拿到的到底是什么 const result await debouncedSearch(value); }上面的debouncedSearch在 debounce 内部被调用时函数确实返回了一个 Promise但调用方拿到的是void或者 undefined因为没有人在防抖层去接收并缓存这个 Promise。于是你在业务代码里 await 一个 undefined得到的自然是 undefined。更麻烦的是如果用户连续输入前几次调用被防抖合并丢弃那前几次调用方的 Promise 就永远没有结果了。调用方会一直处于等待状态这在页面里表现为 loading 转不停或者在 Node 端表现为一个永远不会结束的异步任务。还有一个隐藏问题如果最后一次请求失败失败的错误应该由谁捕获在传统防抖封装里被丢弃的调用根本不知道自己已经被“换掉”了错误归属非常混乱。因此我决定实现一个 Promise-aware 的 debounce 和 throttle 库专门解决这些异步场景下返回值、错误传播和调用方感知的问题。2. 核心思路把 Promise 当作一等公民纳入调度传统防抖节流库的调度单位是“函数调用”而 Promise-aware 库的调度单位是“Promise 的 resolve 和 reject”。第一次设计这个库时我陷入过一个误区把 Promise 当作函数的返回值来处理。后来发现这样设计仍然绕不开“被合并的调用拿不到结果”的问题。真正正确的做法应该是每一次调用都创建一个新的 Promise并把这个 Promise 的 resolve/reject 交给调度器管理。这样一来无论调度器最后选择执行还是丢弃这次函数调用调用方手里的 Promise 都会被妥善处理如果执行调用方最终拿到真实结果。如果被合并调用方共享最后一次执行的结果。如果取消调用方的 Promise 会被 reject。再看throttle的部分它和 debounce 的区别是固定时间窗口内最多执行一次但 Promise 的生命周期管理是完全一致的。每次触发都返回一个 Promise这个 Promise 要么被当前窗口的 leading 执行兑现要么被 trailing 执行兑现要么被取消。这里可以类比一个场景你在火车站排队窗口并不关心你手里的票是哪一趟车它只关心你这一队人在窗口处理完后如何被告知结果。防抖是把松散的人群合并成一批节流是控制每一批人的放行节奏但每一批人最终都要能收到“处理完成”的通知。3. 一个 Promise-aware debounce 的核心实现先写一个最小可用版本不引入复杂配置方便看清核心机制。// 文件路径src/promiseDebounce.ts export type AnyFn (...args: any[]) Promiseany; export function promiseDebounceT extends AnyFn( fn: T, waitMs: number ): { (...args: ParametersT): PromiseAwaitedReturnTypeT; cancel: (reason?: unknown) void; } { let timer: ReturnTypetypeof setTimeout | null null; const pending: Array{ resolve: (value: AwaitedReturnTypeT) void; reject: (reason?: unknown) void; args: ParametersT; } []; const execute async (args: ParametersT): Promisevoid { const currentPending pending.splice(0, pending.length); try { const result await fn(...args); currentPending.forEach((item) item.resolve(result)); } catch (error) { currentPending.forEach((item) item.reject(error)); } }; const debounced (...args: ParametersT): PromiseAwaitedReturnTypeT { return new PromiseAwaitedReturnTypeT((resolve, reject) { pending.push({ resolve, reject, args }); if (timer) { clearTimeout(timer); } timer setTimeout(() { timer null; // 取最后一次调用的参数 const lastArgs pending[pending.length - 1]?.args ?? args; void execute(lastArgs); }, waitMs); }); }; debounced.cancel (reason?: unknown) { if (timer) { clearTimeout(timer); timer null; } const currentPending pending.splice(0, pending.length); currentPending.forEach((item) item.reject(reason ?? new Error(debounced call canceled))); }; return debounced; }这里的核心在于pending数组。每一次调用 debounced 函数都会向pending推入一个带有 resolve、reject 和 args 的对象。定时器到期后取最后一次调用的参数执行然后用同一个结果去 resolve 所有等待中的 Promise。这样设计带来的效果是无论用户在这 300ms 内触发了多少次调用返回的每一个 Promise 最终都能拿到结果不会有任何一个await悬挂。一个容易被忽视的细节是execute函数中的pending.splice(0, pending.length)。这一步非常关键它把当前等待中的 Promise 列表取出来并清空原数组。如果在await fn(...args)期间又有新的调用进来这些新调用会进入下一次调度不会被错误地分发给当前正在执行的 Promise。4. 加上 leading、trailing 和 maxWait 配置在实际业务里我们往往需要 debounce 的完整配置。只做 trailing 模式的防抖某些场景下会带来明显延迟。比如“用户点击发送验证码”这种场景我们希望点击后立即执行一次而不是等 300ms 后才执行。所以我为 promiseDebounce 增加了三个配置项// 文件路径src/promiseDebounce.ts export interface PromiseDebounceOptions { leading?: boolean; trailing?: boolean; maxWait?: number; } export function promiseDebounceT extends AnyFn( fn: T, waitMs: number, options: PromiseDebounceOptions {} ): { (...args: ParametersT): PromiseAwaitedReturnTypeT; cancel: (reason?: unknown) void; } { const { leading false, trailing true, maxWait } options; let timer: ReturnTypetypeof setTimeout | null null; let maxTimer: ReturnTypetypeof setTimeout | null null; let lastCallTime 0; const pending: Array{ resolve: (value: AwaitedReturnTypeT) void; reject: (reason?: unknown) void; args: ParametersT; } []; const execute async (args: ParametersT): Promisevoid { const currentPending pending.splice(0, pending.length); try { const result await fn(...args); currentPending.forEach((item) item.resolve(result)); } catch (error) { currentPending.forEach((item) item.reject(error)); } finally { lastCallTime Date.now(); if (maxTimer) { clearTimeout(maxTimer); maxTimer null; } } }; const runTimer (...args: ParametersT): void { lastCallTime Date.now(); if (timer) { clearTimeout(timer); } timer setTimeout(() { timer null; if (!trailing) return; const lastArgs pending[pending.length - 1]?.args ?? args; void execute(lastArgs); }, waitMs); }; const debounced (...args: ParametersT): PromiseAwaitedReturnTypeT { return new PromiseAwaitedReturnTypeT((resolve, reject) { pending.push({ resolve, reject, args }); const isFirstCall lastCallTime 0 || Date.now() - lastCallTime waitMs; if (leading isFirstCall) { const firstPending pending.splice(0, pending.length); try { fn(...args).then( (result) firstPending.forEach((item) item.resolve(result)), (error) firstPending.forEach((item) item.reject(error)) ); lastCallTime Date.now(); } catch (error) { firstPending.forEach((item) item.reject(error)); } } else { runTimer(...args); } if (maxWait) { if (!maxTimer) { maxTimer setTimeout(() { if (timer) { clearTimeout(timer); timer null; } const lastArgs pending[pending.length - 1]?.args ?? args; void execute(lastArgs); }, maxWait); } } }); }; debounced.cancel (reason?: unknown) { if (timer) { clearTimeout(timer); timer null; } if (maxTimer) { clearTimeout(maxTimer); maxTimer null; } const currentPending pending.splice(0, pending.length); currentPending.forEach((item) item.reject(reason ?? new Error(debounced call canceled))); }; return debounced; }这里需要注意leading和trailing的语义。leading: true时第一次调用立即执行并清空pending数组中的全部 Promise让它们共享第一次执行的结果。trailing则负责最后一次调用。maxWait是为了防止用户持续不断地触发导致 trailing 永远执行不了它设定了一个上限时间保证至少在这个时间间隔内执行一次。5. Promise-aware throttle 的实现throttle 的核心思想是“时间窗口不变但每个窗口内最多执行一次”。与 debounce 不同throttle 需要记录上一次执行的时间并且要考虑 leading 调用和 trailing 调用的协同。// 文件路径src/promiseThrottle.ts export interface PromiseThrottleOptions { leading?: boolean; trailing?: boolean; } export function promiseThrottleT extends AnyFn( fn: T, limitMs: number, options: PromiseThrottleOptions {} ): { (...args: ParametersT): PromiseAwaitedReturnTypeT; cancel: (reason?: unknown) void; } { const { leading true, trailing true } options; let lastRunTime 0; let timer: ReturnTypetypeof setTimeout | null null; let trailingArgs: ParametersT | null null; const pending: Array{ resolve: (value: AwaitedReturnTypeT) void; reject: (reason?: unknown) void; args: ParametersT; } []; const execute async (args: ParametersT): Promisevoid { lastRunTime Date.now(); trailingArgs null; const currentPending pending.splice(0, pending.length); try { const result await fn(...args); currentPending.forEach((item) item.resolve(result)); } catch (error) { currentPending.forEach((item) item.reject(error)); } }; const throttled (...args: ParametersT): PromiseAwaitedReturnTypeT { return new PromiseAwaitedReturnTypeT((resolve, reject) { pending.push({ resolve, reject, args }); const now Date.now(); const remaining limitMs - (now - lastRunTime); if (remaining 0) { if (timer) { clearTimeout(timer); timer null; } void execute(leading ? pending[pending.length - 1]?.args ?? args : args); } else if (trailing) { trailingArgs args; if (!timer) { timer setTimeout(() { timer null; if (trailingArgs) { void execute(trailingArgs); } }, remaining); } } }); }; throttled.cancel (reason?: unknown) { if (timer) { clearTimeout(timer); timer null; } trailingArgs null; const currentPending pending.splice(0, pending.length); currentPending.forEach((item) item.reject(reason ?? new Error(throttled call canceled))); }; return throttled; }throttle 的实现里有一个容易踩坑的地方pending数组中的调用并不一定都在当前窗口内执行。比如在remaining大于 0 的时候调用会被trailingArgs记下来但同一时间窗口内可能有多个调用它们都会进入pending。当 trailing 定时器执行时execute会清空整个pending数组让所有等待的调用共享最后一次 trailing 调用的结果。这个方式并非完美它牺牲了一些“每次调用都拿到自己参数的结果”的精确性换来了更好的内存和时序一致性。从库设计角度看这是合理的权衡因为 throttle 语义本身就不保证每个调用都执行Promise 只是确保等待者不会永远挂起。6. 与 lodash debounce 的对比如果你熟悉 lodash可能已经发现我这种设计思路和 lodash 有一个重要差异。lodash 的 debounce 也有返回值但它的返回值设计有一个著名的限制只有leading边沿调用能拿到真正的返回值后续被合并的调用拿到的都是 undefined。看这段在 lodash 风格下的代码const debounced _.debounce(async () { return result; }, 300); const result await debounced(); console.log(result); // undefined这个结果对很多同学来说是反直觉的。明明 debounce 内部函数返回了 Promise为什么外部拿不到因为 lodash 的设计目标是“控制调用节奏”不是“Promise 结果的统一分发”。它在内部维护的是函数自身的执行状态不是你传给调用方的 Promise。在我设计的 Promise-aware 版本里每次调用都会立刻获得一个 Promise之后无论这个调用被合并到哪一次真正执行调用方都能得到结果。这是两者最大的差异对比维度lodash debouncePromise-aware debounce调度单位函数执行Promise 的 resolve/reject返回值语义只有 leading 边沿能拿到结果每次调用都能拿到结果被合并的调用返回 undefined共享最后一次执行结果取消行为取消后调用方感知不到所有等待中的 Promise 被 rejectTypeScript 类型需要手动维护类型自动推导返回值类型7. 一个完整可运行的示例下面写一个完整的示例演示 Promise-aware debounce 和 throttle 在 TypeScript 项目中的实际表现。// 文件路径src/example.ts import { promiseDebounce } from ./promiseDebounce; import { promiseThrottle } from ./promiseThrottle; interface SearchResult { keyword: string; data: string[]; } // 模拟异步搜索接口 async function searchApi(keyword: string): PromiseSearchResult { await new Promise((resolve) setTimeout(resolve, 200)); return { keyword, data: [${keyword}-result-1, ${keyword}-result-2], }; } // 防抖搜索 const debouncedSearch promiseDebounce(searchApi, 300); // 节流同步上报 const throttledReport promiseThrottle( async (event: string) { await new Promise((resolve) setTimeout(resolve, 100)); return report: ${event}; }, 1000 ); async function simulateInput() { const results: ArrayPromiseSearchResult []; results.push(debouncedSearch(typescript)); results.push(debouncedSearch(promise)); results.push(debouncedSearch(debounce)); // 只有最后一次调用真正执行但三个 Promise 都能拿到结果 const [r1, r2, r3] await Promise.all(results); console.log(r1:, r1.keyword); console.log(r2:, r2.keyword); console.log(r3:, r3.keyword); } async function simulateScroll() { const p1 throttledReport(scroll-1); const p2 throttledReport(scroll-2); const p3 throttledReport(scroll-3); const [r1, r2, r3] await Promise.allSettled([p1, p2, p3]); console.log(throttle results:, r1.status, r2.status, r3.status); } simulateInput(); setTimeout(simulateScroll, 500);运行这段代码时如果一切正常输出的结果是r1、r2、r3的 keyword 都是debounce。因为它们被合并到了最后一次真正执行的调用中共享了同一次searchApi(debounce)的结果。这种共享结果的语义在真实业务里有时会让人困惑。你可能会问如果用户输入了 typescript、promise、debounce 三个关键词最终拿到了三个相同的 debounce 结果这是否合理从防抖语义来说这是合理的因为前两次输入并未真正触发请求。但这也提醒我们如果每个输入都必须有独立的搜索结果就不应该用 debounce而应该用带竞态控制的独立请求。8. 使用场景与最佳实践Promise-aware 防抖节流适合哪些场景这里做一个清晰的分类。防抖适合“用户停止操作后才执行”的场景关键词联想搜索、表单输入校验、窗口 resize 后重新计算布局、多按钮的防重复提交。在这些场景里Promise 的存在让调用方可以直接拿到最终的异步结果而不必在回调里改状态。节流适合“固定频率持续执行”的场景滚动加载更多、鼠标移动轨迹上报、视频播放进度上报、WebSocket 消息批量合并发送。throttle 能保证在高频事件流中请求不会过载同时保持一定的实时性。需要特别提醒一类反模式不要在防抖函数内部再手动写 setTimeout 去等 Promise 完成。既然库已经处理了 Promise 的分发业务方只需要专注于函数本身的逻辑。另一个常见问题是取消。在 React 组件中组件卸载时如果有等待中的防抖请求最好主动 cancel避免出现对已卸载组件的状态更新。下面是一个简单的封装示例// 文件路径src/useDebouncedSearch.ts import { useEffect, useRef, useCallback } from react; import { promiseDebounce } from ./promiseDebounce; export function useDebouncedSearch(apiFn: (keyword: string) Promisestring[], waitMs 300) { const debouncedRef useRef(promiseDebounce(apiFn, waitMs)); useEffect(() { const current debouncedRef.current; return () { current.cancel(component unmounted); }; }, []); return useCallback((keyword: string) debouncedRef.current(keyword), []); }这里有一个值得注意的细节promiseDebounce返回的函数上还挂了一个cancel方法因此你可以像上面的代码一样在组件卸载时安全地取消所有等待中的 Promise。9. TypeScript 类型设计背后的考量这个库的类型设计并不复杂但是有两个点值得展开。第一点是ParametersT推导。promiseDebounce接收的泛型T extends AnyFn在返回类型中使用了ParametersT这样调用方传入的参数类型会被完整保留不会丢失函数签名。这一点非常实用你可以把一个类型良好的 apiFn 直接传给 promiseDebounce而不需要额外写类型断言。第二点是返回值的Awaited展开。在 TypeScript 4.5 之后AwaitedT可以递归地展开嵌套 Promise。如果 apiFn 返回PromisePromisestringAwaitedReturnTypeT仍然能正确得到string。在工具库设计中建议统一使用Awaited来避免多层 Promise 造成的类型混乱。下面是这个库最终对外输出的核心类型摘要方便你在自己的项目里复制使用// 文件路径src/types.ts export type AnyPromiseFn (...args: any[]) Promiseany; export interface CancelableAsyncFnT extends AnyPromiseFn { (...args: ParametersT): PromiseAwaitedReturnTypeT; cancel: (reason?: unknown) void; } export interface PromiseDebounceOptions { leading?: boolean; trailing?: boolean; maxWait?: number; } export interface PromiseThrottleOptions { leading?: boolean; trailing?: boolean; }如果你把strict: true打开这个库在编译期就能帮你识破很多问题。比如参数类型写错、返回值没有 await 等都不会走到运行时才暴露。10. 常见问题与排查思路在实践过程中大家可能会遇到下面这些问题整理成表格方便对照排查。问题现象可能原因排查思路解决方案拿到的结果是 undefined还在用普通 debounce 包装异步函数检查返回类型是否 Promise改用 Promise-aware 版本页面一直 loading被合并的调用永远得不到 resolve确认调用次数与等待窗口检查执行分支是否正确清空 pendingcancel 后仍然有请求发出cancel 之前函数已经执行了判断执行与取消的时序在业务层追加令牌或 abort 控制多个调用互相覆盖结果同一个函数被多处调用查看是否共享了同一个包装实例为不同业务模块创建独立实例trailing 模式下迟迟不执行高频触发导致 timer 不断重置检查 waitMs 与触发间隔配置 maxWait 保证最大等待Rule of thumb: 内部有 async 但外部拿不到 Promisedebounce 包装层没有优先分发 Promise查看函数返回类型改用 Promise-aware 封装另一个需要特别强调的坑是unhandled rejection。如果你调用了cancel所有等待中的 Promise 都会被 reject。如果调用方没有对这些 Promise 做.catch()或try/catch处理Node.js 会报unhandled rejection。良好的习惯是所有对外返回的 Promise 都要有对应的 catch 消费方至少在组件或调度入口统一捕获。11. 工程化落地建议如果你的项目需要一个 Promise-aware 防抖节流库直接拿上面的代码精简一下就能用。但在工程化落地时有几点建议值得参考。第一保留 cancel 的独立通道。cancel是 Promise-aware 方案区别于普通方案的关键能力不要为了精简 API 而省略它。第二参数过期保护。防抖合并调用时如果调用方各自传入了不同参数最终执行的是最后一次的参数。如果业务希望每次调用只用“自己的参数”就不能用防抖而应该用排队或独立请求。建议在文档里明确这一语义。第三优先使用共享 Promise而不是每次执行都创建新 Promise 并丢弃旧 Promise。共享 Promise 的好处是内存占用小且所有等待者能自然分组。第四性能测试。在高频场景比如每秒 1000 次触发下要注意pending数组的清理频率。当前实现中的splice(0, pending.length)是 O(n)但 n 是当前窗口内的调用数通常很小可以接受。第五单元测试要覆盖时序。建议用 fake timers 来测试每一类配置尤其是leading、trailing、maxWait的组合避免在真实业务里因为时间误差导致行为异常。12. 总结与后续方向Promise-aware 的防抖节流本质上解决的是异步调度中“调用方是否能拿到确定结果”的问题。它并没有改变防抖节流的时间控制逻辑而是把 Promise 的生命周期纳入了调度模型让每一次调用都能得到一次返回无论这次调用是执行、合并还是取消。这个方向还可以继续扩展下去比如结合 AbortSignal 做取消信号的标准化传参或者做成一个可插拔的中间件让 debounce、throttle、retry 组合在一起用。如果你正在做一个需要高频异步调用控制的前端项目推荐把 Promise-aware 作为基础工具库沉淀下来长期收益非常可观。