Vue 3 异步搜索实战:watch、请求取消与竞态控制

在 Vue 3 后台系统中,搜索框往往连接远程接口:用户输入关键词后,列表展示新结果;切换分类后,同一个请求还需要携带筛选条件。如果只是监听输入,然后直接 await fetch(),页面很容易出现一个隐蔽问题:用户搜索了 B,最终显示的却是更早的 A 结果。

这个问题不是 Vue 的响应式缺陷,而是异步请求的返回顺序无法保证。本文基于 Vue 3 Composition API,给出能够实际复用的搜索组件设计,覆盖 watch、防抖、AbortController、加载状态、失败重试和组件卸载。

一、先设计响应式数据流

假设一个客户列表支持关键词搜索与状态过滤。界面应当保存两类状态:用户正在编辑的条件 与服务端已经返回的查询结果。不要把服务端返回值直接当成查询条件,否则很容易出现循环触发。

vue 复制代码
<script setup lang="ts">
import { computed, ref } from 'vue';

type Customer = { id: string; name: string; status: 'active' | 'inactive' };

const keyword = ref('');
const status = ref<'all' | 'active' | 'inactive'>('all');
const rows = ref<Customer[]>([]);
const loading = ref(false);
const errorMessage = ref('');
const normalizedKeyword = computed(() => keyword.value.trim());
</script>

搜索框通过 v-model 修改输入值,watch 负责观察真正需要发起请求的条件。结果数据不参与请求条件计算,数据流方向始终是"条件变化 → 发起请求 → 结果更新"。

html 复制代码
<form class="customer-filters" role="search">
  <label for="customer-keyword">客户名称</label>
  <input id="customer-keyword" type="search" placeholder="输入名称关键词">
</form>
<a href="https://www.yxtiktok.com/blog/guides/">

二、为什么 watch 比 watchEffect 更适合远程搜索

watchEffect 会自动收集同步执行期间读取的响应式依赖,适合依赖明确且副作用简单的逻辑。但是远程搜索通常要求精确控制触发条件,比如只监听规范化关键词和状态,而不希望错误文案或结果列表变化导致请求重发。

ts 复制代码
watch([normalizedKeyword, status], ([query, currentStatus]) => {
  // 仅在搜索条件变化时执行
}, { immediate: true });

这里的 immediate: true 意味着组件加载后会立即请求一次初始列表;如果首屏数据已经通过 SSR 注入,则可以根据实际架构去掉首次请求,避免重复拉取。

在 Vue 3.5 及更新版本中,onWatcherCleanup() 提供了清理前一次侦听操作的能力。清理函数必须在异步回调的同步阶段注册,不能等 await 之后再注册。 这是避免竞态的关键。

三、构建可取消的搜索请求

先封装请求函数,组件不直接关心 URL 参数的字符串拼接方式。这样未来增加分页、排序条件时,只需要修改 API 层。

ts 复制代码
async function fetchCustomers(
  query: string,
  currentStatus: string,
  signal: AbortSignal
): Promise<Customer[]> {
  const url = new URL('/api/customers', window.location.origin);
  if (query) url.searchParams.set('q', query);
  if (currentStatus !== 'all') url.searchParams.set('status', currentStatus);

  const response = await fetch(url, { signal });
  if (!response.ok) throw new Error(`查询失败:HTTP ${response.status}`);
  const payload: unknown = await response.json();
  if (!Array.isArray(payload)) throw new Error('接口响应格式错误');
  return payload as Customer[];
}

生产环境需要对每条记录的字段进行运行时校验,上面只展示数组这一层的简化判断。TypeScript 的类型断言不会在运行时验证接口内容。

html 复制代码
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/778cdca125bc0c3254f054737c9d119ece75b7af" class="search-status" role="status" aria-live="polite">
  <span data-query-state>等待搜索条件</span>
</div>

四、在 watch 内正确清理旧任务

下面的实现同时处理防抖与请求取消。输入变化后,前一次定时器会被清除;如果请求已经发出,则通过 AbortController 中止读取。新旧请求即使异常交错,也能通过序号判断当前结果是否仍有效。

ts 复制代码
import { watch, onWatcherCleanup } from 'vue';

let requestVersion = 0;

watch([normalizedKeyword, status], ([query, currentStatus]) => {
  const version = ++requestVersion;
  const controller = new AbortController();
  let timer: ReturnType<typeof setTimeout> | undefined;

  onWatcherCleanup(() => {
    if (timer !== undefined) clearTimeout(timer);
    controller.abort();
  });

  loading.value = true;
  errorMessage.value = '';

  timer = setTimeout(async () => {
    try {
      const result = await fetchCustomers(query, currentStatus, controller.signal);
      if (version !== requestVersion) return;
      rows.value = result;
    } catch (error) {
      if (controller.signal.aborted || version !== requestVersion) return;
      errorMessage.value = error instanceof Error ? error.message : '查询失败';
    } finally {
      if (version === requestVersion) loading.value = false;
    }
  }, 250);
}, { immediate: true });

即使浏览器已发出网络请求,abort() 也不保证服务端停止执行,因此请求序号仍有价值:它负责保证旧响应绝不覆盖新界面状态。对普通只读搜索接口,这种组合具有清晰的职责边界。

五、正确组织加载态与空状态

搜索体验不只是"有数据就画表格"。至少应区分首次加载、重新查询、空结果和接口错误。重新查询时可以保留上一批结果,但必须明确标注其正在更新,避免用户将旧数据视为新条件的结果。

html 复制代码
<section class="result-panel" aria-labelledby="result-heading">
  <h2 id="result-heading">查询结果</h2>
  <p data-loading-note aria-live="polite">正在更新结果</p>
  <div data-results></div>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">

如果业务要求严格不展示旧结果,可以在新请求启动时清空 rows。如果列表是信息密集型后台,保留旧结果并降低视觉强调通常更平滑。选择哪一种,不应由技术框架默认决定。

使用 Vue 模板表达状态比直接操作 DOM 更容易维护:

vue 复制代码
<template>
  <section>
    <div class="toolbar">
      <input v-model="keyword" type="search" aria-label="搜索客户" />
      <select v-model="status" aria-label="客户状态">
        <option value="all">全部状态</option>
        <option value="active">有效</option>
        <option value="inactive">停用</option>
      </select>
    </div>
    <p v-if="loading" role="status">正在查询...</p>
    <p v-else-if="errorMessage" role="alert">{{ errorMessage }}</p>
    <p v-else-if="rows.length === 0">暂无符合条件的记录</p>
    <ul v-else>
      <li v-for="row in rows" :key="row.id">{{ row.name }}</li>
    </ul>
  </section>
</template>

六、URL、分页和筛选条件必须保持一致

真实列表常常还需要页码、每页条数和排序字段。一个容易忽略的陷阱是:用户处于第 8 页,修改关键词后依然请求第 8 页,看起来像"搜索不到任何结果"。

可以通过单独的响应式变量维护页码,并在筛选条件变化时归零:

ts 复制代码
const page = ref(1);
watch([normalizedKeyword, status], () => { page.value = 1; });

如果同时监听 [normalizedKeyword, status, page] 发请求,这种重置可能带来短暂的两次触发。要减少额外调度,可以将条件更新统一到一个受控动作,或者直接用查询键进行去重。

html 复制代码
<div class="pagination-controls" aria-label="搜索结果分页">
  <button type="button" data-page="previous">上一页</button>
  <output data-current-page>第 1 页</output>
  <button type="button" data-page="next">下一页</button>
</div>
<a href="https://www.yxtiktok.com/blog/guides/">

当筛选参数需要可分享和刷新恢复时,可以交给 Vue Router 的查询参数管理,并在路由状态与本地状态之间明确唯一数据源,避免双向侦听造成导航循环。

七、抽成 composable 之前先确定接口契约

并不是把所有 watch 代码复制到 useSearch() 就叫复用。真正的复用需要明确输入参数、返回状态、取消策略和请求函数的责任边界。推荐先把请求函数作为参数注入,再由 composable 处理重复的状态转换。

ts 复制代码
export type SearchResult<T> = {
  items: T[];
  nextCursor?: string | null;
};

export type SearchFunction<T> = (
  keyword: string,
  signal: AbortSignal
) => Promise<SearchResult<T>>;

这样的接口既可以用于客户列表,也可以用于文章检索和任务筛选。需要注意,composable 本身不自动提供全局缓存。如果多个组件请求同一资源,仍可能重复访问接口;跨组件缓存可以考虑专门的数据查询库,而不是在每个 composable 中临时维护一个全局 Map。

html 复制代码
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/a724a4a6d324f9de9326e3e35dd6cf38b88078cd" class="saved-searches">
  <h3>常用筛选</h3>
  <button type="button" data-preset="active">仅看有效记录</button>
</div>

八、错误重试要重试当前条件

重试按钮不应捕获旧的关键词字符串,否则用户修改搜索条件后点击重试,可能再次发送过期查询。最简单的处理方式是维护一个独立 retryKey,让侦听器读取当前 normalizedKeyword 和 status 再次发起请求。

ts 复制代码
const retryKey = ref(0);
function retrySearch() { retryKey.value += 1; }

// 将 retryKey 追加到 watch 的依赖数组即可触发当前条件重新查询

不过,如果接口返回 401、403 等明确的权限异常,就不应该无条件重试;应引导用户重新认证或展示权限提示。

html 复制代码
<div class="search-error" role="alert">
  <p data-error-message>当前查询未完成</p>
  <button type="button" data-retry-search>重新查询</button>
</div>
<a href="https://www.yxtiktok.com/blog/guides/">

九、为什么不用纯防抖就结束?

防抖只减少请求次数,不保证正确的结果顺序。假设 A 请求已经发出,用户开始输入 B,250ms 的防抖并不能让 A 自动停止;如果 A 在 B 之后返回,仍然可能覆盖 B 的结果。AbortController 控制资源,版本号控制结果有效性,二者与防抖解决的是三个不同问题。

对于搜索结果较多的页面,渲染阶段还可能出现列表卡顿。这时应该使用分页或虚拟列表,而不是继续把防抖时长从 250ms 调到 1 秒。网络层和渲染层的瓶颈,需要分别测量。

html 复制代码
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/67e53da2b31518b072caaeb22445d63e195f1a5b" class="request-metrics">
  <span data-request-count>请求次数</span>
  <span data-last-duration>最近查询耗时</span>
</div>

开发阶段可以通过浏览器 Network 面板模拟慢速网络,连续输入两个关键词并控制响应顺序。验证重点是:页面最终内容必须对应最后一次查询条件,旧请求失败不应清空新请求的错误提示。

html 复制代码
<aside class="search-help" aria-label="搜索使用说明">
  <p>输入关键词后自动更新列表,可配合状态筛选缩小范围。</p>
</aside>
<a href="https://www.yxtiktok.com/blog/guides/">

十、总结

Vue 3 的响应式系统让搜索条件与页面展示容易组织,但真正稳定的异步搜索还需要处理网络竞态。推荐将 watch 用于明确依赖,利用同步注册的 onWatcherCleanup 清理定时器和请求,再用请求版本号保证过期结果不会覆盖新状态。对于复杂后台,进一步考虑缓存、分页、路由参数和统一错误模型,才能形成可长期维护的搜索模块。