debounce 与 throttle：从实现原理到类型安全

在前端开发中，高频事件（如窗口 resize、输入框 input、滚动 scroll）若直接绑定昂贵操作（如 API 请求、DOM 重绘），将严重拖慢性能。
debounce（防抖）与 throttle（节流）是解决这一问题的经典控制策略。它们看似相似，实则语义不同，适用场景也截然相反。

深入其实现原理、行为差异与类型推导，是掌握函数式控制流的关键一步。

防抖（Debounce）：最后一次调用后延迟执行

核心语义

“在一系列连续调用中，只执行最后一次”。
常用于：搜索框输入、自动保存、表单验证——用户停止操作后再触发。

实现要点

依赖 clearTimeout + setTimeout 清除并重置计时器：

const debounce = <T extends (...args: any[]) => any>(
  fn: T,
  delay: number
): ((...args: Parameters<T>) => void) => {
  let timer: ReturnType<typeof setTimeout> | null = null

  return (...args: Parameters<T>) => {
    if (timer) clearTimeout(timer)
    timer = setTimeout(() => {
      fn(...args)
      timer = null
    }, delay)
  }
}

关键逻辑

• 每次调用时清除上一个定时器。
• 重新设置新定时器，延迟 delay 毫秒后执行。
• 只有最后一次调用能“存活”到定时器触发。

节流（Throttle）：固定时间间隔内最多执行一次

核心语义

“无论触发多频繁，只在固定时间间隔内执行一次”。
常用于：滚动加载、按钮点击、鼠标移动——限制执行频率。

实现方式一：时间戳比较（立即执行）

记录上次执行时间，判断是否超过间隔：

const throttleByTimestamp = <T extends (...args: any[]) => any>(
  fn: T,
  interval: number
): ((...args: Parameters<T>) => void) => {
  let lastTime = 0

  return (...args: Parameters<T>) => {
    const now = Date.now()
    if (now - lastTime >= interval) {
      fn(...args)
      lastTime = now
    }
  }
}

实现方式二：定时器锁（延迟执行）

使用定时器作为“锁”，防止重复执行：

const throttleByTimer = <T extends (...args: any[]) => any>(
  fn: T,
  interval: number
): ((...args: Parameters<T>) => void) => {
  let timer: ReturnType<typeof setTimeout> | null = null

  return (...args: Parameters<T>) => {
    if (!timer) {
      fn(...args)
      timer = setTimeout(() => {
        timer = null
      }, interval)
    }
  }
}

对比

方式	执行时机	特点
时间戳	达到间隔立即执行	首次立即执行，无延迟
定时器	间隔结束后执行	更平滑，但首次有延迟

leading 与 trailing：为何可选却可能互斥？

Lodash 的 debounce 支持配置 { leading, trailing }，但理解其行为至关重要。

选项含义

• leading: true：在第一次调用时立即执行。
• trailing: true：在最后一次调用后延迟执行（默认行为）。

四种组合

1. { leading: false, trailing: true }（默认）：延迟执行最后一次。
2. { leading: true, trailing: false }：立即执行第一次，后续不执行。
3. { leading: true, trailing: true }：第一次立即执行，最后一次延迟执行。
4. { leading: false, trailing: false }：什么都不执行（无意义）。

为何某些场景必须互斥？

场景一：按钮防重复点击

const submit = debounce(sendRequest, 1000, { leading: true, trailing: true })

用户快速点击两次：

• 第一次点击：leading 触发，请求发出。
• 第二次点击：重置定时器。
• 1秒后：trailing 再次触发，又发一次请求。

结果：用户点一次，提交两次 —— 灾难性错误。

解法：只能启用 leading 或 trailing，不可共存。

场景二：搜索框输入

const search = debounce(fetchResults, 300, { trailing: true })

用户输入 "hello"：

• 每敲一个字母都重置定时器。
• 停顿300ms后，只请求一次 /search?q=hello。

若启用 leading：

• 敲 'h' 时立即请求 /search?q=h。
• 后续输入被防抖，但用户已看到无关结果。

体验差：展示大量中间态结果。

权衡：用户体验 vs 资源节约

• leading 提供即时反馈，适合需要“立即响应”的 UI（如按钮）。
• trailing 节约资源，避免无效计算，适合异步请求。
• 二者共存可能导致逻辑冲突，需根据业务语义谨慎选择。

类型安全：推导参数与返回类型

debounce 返回一个新函数，必须保持原函数的类型签名。

核心工具类型

• Parameters<T>：提取函数 T 的参数类型，返回元组。
• ReturnType<T>：提取函数 T 的返回类型。

泛型实现

const debounce = <T extends (...args: any[]) => any>(
  fn: T,
  delay: number
): ((...args: Parameters<T>) => ReturnType<T> | undefined) => {
  let timer: ReturnType<typeof setTimeout> | null = null

  return (...args: Parameters<T>): ReturnType<T> | undefined => {
    let result: ReturnType<T> | undefined

    if (timer) clearTimeout(timer)
    timer = setTimeout(() => {
      result = fn(...args)
      timer = null
    }, delay)

    return result // 注意：异步执行，此处返回 undefined
  }
}

类型推导示例

const add = (a: number, b: number): number => a + b
const debouncedAdd = debounce(add, 300)

// 类型自动推导：
// debouncedAdd: (a: number, b: number) => number | undefined

IDE 能正确提示参数和返回类型，实现“零配置智能提示”。

注意：由于 fn 是异步执行，debouncedAdd 的同步返回值始终是 undefined。若需获取结果，原函数应返回 Promise，或使用回调。

实战：为 Vue3 组件添加防抖输入

在 Vue3 中，使用 debounce 优化搜索框性能。

组件代码

<script setup lang="ts">
import { ref } from 'vue'
import { debounce } from '@/utils/function'

const keyword = ref('')
const results = ref<string[]>([])

// 防抖搜索函数
const search = debounce(async (query: string) => {
  if (!query) {
    results.value = []
    return
  }
  const res = await fetch(`/api/search?q=${query}`)
  results.value = await res.json()
}, 300)

// 输入处理
const handleInput = (e: Event) => {
  const value = (e.target as HTMLInputElement).value
  keyword.value = value
  search(value) // 每次输入都调用，但只会执行最后一次
}
</script>

<template>
  <div>
    <input
      :value="keyword"
      @input="handleInput"
      placeholder="搜索..."
    />
    <ul>
      <li v-for="item in results" :key="item">{{ item }}</li>
    </ul>
  </div>
</template>

关键点

1. debounce 封装了异步搜索逻辑，避免频繁请求。
2. delay 设为 300ms，平衡响应速度与性能。
3. trailing: true（默认）确保只发起最终查询。
4. 组件无需管理定时器，逻辑清晰。

结语：控制流的本质是时间抽象

debounce 和 throttle 不仅是性能优化工具，更是对时间流的抽象。

• debounce 抽象了“等待稳定”的模式。
• throttle 抽象了“限频执行”的模式。

手写其实现，迫使我们直面：

• 定时器的生命周期管理。
• leading 与 trailing 的语义冲突。
• 类型系统如何精确描述高阶函数。

当你能为 Vue3 组件无缝集成防抖逻辑时，你不仅掌握了一个技巧，更掌握了一种控制程序节奏的能力——而这，正是高级前端工程师的核心竞争力。