搜索建议串结果:Node.js 与浏览器时序实战

用原生浏览器模块与零依赖 Node.js 实现搜索建议,拆解防抖窗口、旧响应覆盖、输入法和键盘选择,附本地接口与时序测试及未验证边界。

在搜索框里输入“浏览器”,看到的却是上一轮“浏览”的结果,这类问题常被归咎于网络慢。网络慢只是放大器:真正的缺口,是页面没有规定哪一次输入还拥有修改结果区的资格。把防抖从一百毫秒调到三百毫秒,通常只是让错误更难复现;接上取消请求,也不能代替这条规则。

下面做一个不依赖框架的搜索建议组件。后端使用 Node.js,前端使用原生模块,目录里只有四个运行文件和一个测试文件。它不追求花哨的搜索算法,而是把三件容易互相干扰的事拆开:输入变化怎样使旧结果失效,网络请求怎样尽量少做无用功,以及用户怎样在候选列表中操作。研究和验证日期为 2026 年 11 月 14 日,实际执行环境是 Node.js v24.22.1;浏览器、中文输入法和读屏软件的组合测试尚未执行,后面会给出验收方法。

先明确结果属于谁,再讨论取消

设想一个具体时间线。用户先输入“浏览”,请求甲已经发出;再输入“浏览器”,请求乙还在等待防抖计时器。此时请求甲返回。如果版本号只在“真正发送请求”时递增,页面依然认为甲是最新请求,于是把旧结果画出来。等待乙发出并返回后,列表又跳一次。用户恰好在这段时间按下回车,选择的可能不是当前输入对应的候选。

因此,本文把版本号绑定到输入意图,而不是绑定到网络请求。每次输入变化,立即递增版本号、取消上一个控制器、清空候选与活动项,然后才决定是否等待一百八十毫秒发送请求。输入被清空、输入法开始组词、搜索框失焦、按下 Escape、选中候选,这些动作也都会让原有意图过期。即使其中某个动作根本不会发出新请求,旧请求仍然失去更新页面的资格。

防抖控制启动频率,取消帮助停止已经不需要的工作,版本检查控制最终呈现。三者服务于不同目标。为了验证最后一层保护真的存在,测试中的模拟网络会故意无视取消,照常把旧响应交回来。如果这种情况下仍能保住新结果,才说明正确性没有寄托在网络层的善意配合上。

MDN 的 AbortController 文档说明控制器可以取消请求及响应体消费。这里额外保留版本检查,是本文的实现选择:结果可能经过其他异步步骤,也可能来自没有响应取消信号的测试替身或封装层。取消不是让服务器撤销任何已完成工作的通用协议,更不能用它判断业务写入是否发生。本例只做只读建议查询,不把这套交互逻辑移植成付款取消机制。

把异步正确性放进一个独立模块

search.mjs 不知道输入框、方向键或数据库,它只接收查询词和版本令牌,把状态交给渲染函数。这样既能在浏览器中使用真实 fetch,也能在测试中精确控制响应先后。

export function createSearch(fetcher, render) {
  let revision = 0, controller;
  function invalidate() {
    revision += 1;
    controller?.abort();
    controller = undefined;
    render({ phase: 'idle', items: [] });
    return revision;
  }
  async function run(q, token) {
    if (token !== revision) return;
    const own = new AbortController();
    controller = own;
    render({ phase: 'loading', items: [] });
    try {
      const r = await fetcher('/api/suggest?q=' + encodeURIComponent(q),
        { signal: own.signal });
      if (!r.ok) throw new Error('HTTP ' + r.status);
      const data = await r.json();
      if (!Array.isArray(data.items) || data.items.length > 8 ||
          data.items.some(x => typeof x.id !== 'string' ||
            typeof x.label !== 'string' || x.label.length > 100)) {
        throw new Error('invalid response');
      }
      if (token === revision) render({ phase: 'ready', items: data.items });
    } catch (error) {
      if (token === revision && !own.signal.aborted)
        render({ phase: 'error', items: [] });
    } finally {
      if (token === revision) controller = undefined;
    }
  }
  return { invalidate, run };
}

这里最重要的检查发生在响应体解析之后。只在收到响应头时比较版本,随后等待 JSON 解析,仍然可能跨过一次新的输入变化。成功分支、失败分支都必须受同一个版本约束,否则旧请求的网络错误会把已经成功的新结果盖成“查找失败”。清理控制器也只允许当前版本执行,避免旧请求的 finally 抹掉新请求的控制器引用。

返回数据也不直接交给界面。示例限制候选数量,检查标识和名称类型,对名称长度设置上限。服务端仍是可信度需要验证的边界:接口发生版本漂移、代理返回错误页面,或者服务端代码出错时,前端应该显示失败,而不是把异常对象当候选渲染。这个校验不是完整的协议库,但足以让演示的输入和输出约束一眼可见。

状态刻意分成 idle、loading、ready 和 error。没有匹配项属于成功完成后的空数组,网络失败属于 error;两者不能共享“没有结果”的文案。否则用户会把服务故障理解为资料不存在,也会让业务监控误把错误归到正常零结果率里。本例在新输入时清空旧列表,代价是列表可能短暂消失;好处是用户不会误选已经失效的候选。如果产品必须保留旧结果,应当把它明确标为旧状态并禁止选择,而不是悄悄保留可点击的旧条目。

后端接口先保持小而确定

server.mjs 提供同源静态文件和 /api/suggest。示例只有四条固定数据,使用包含匹配,目的是让读者不需要准备数据库就能复现时序问题。它不是可直接支撑大目录的搜索服务。

import { createServer } from 'node:http';
import { readFile } from 'node:fs/promises';
import { pathToFileURL } from 'node:url';
const catalog = [
  { id: '1', label: 'Node.js HTTP 服务' },
  { id: '2', label: 'Node.js 文件流' },
  { id: '3', label: '浏览器搜索交互' },
  { id: '4', label: '浏览器键盘操作' }
];
const assets = new Map([
  ['/', ['index.html', 'text/html; charset=utf-8']],
  ['/app.mjs', ['app.mjs', 'text/javascript; charset=utf-8']],
  ['/search.mjs', ['search.mjs', 'text/javascript; charset=utf-8']]
]);
export function makeServer() {
  return createServer(async (req, res) => {
    function send(status, body, type = 'application/json; charset=utf-8') {
      res.writeHead(status, { 'Content-Type': type,
        'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
      res.end(body);
    }
    try {
      if (req.method !== 'GET') {
        res.setHeader('Allow', 'GET');
        return send(405, JSON.stringify({ error: 'method' }));
      }
      const url = new URL(req.url, 'http://localhost');
      if (url.pathname === '/api/suggest') {
        const values = url.searchParams.getAll('q');
        const q = values[0]?.trim().normalize('NFC') ?? '';
        if (values.length !== 1 || [...q].length < 2 ||
            [...q].length > 64 || /[\p{Cc}\p{Cf}]/u.test(q))
          return send(400, JSON.stringify({ error: 'invalid query' }));
        const items = catalog.filter(x =>
          x.label.toLowerCase().includes(q.toLowerCase())).slice(0, 8);
        return send(200, JSON.stringify({ items }));
      }
      const asset = assets.get(url.pathname);
      if (!asset) return send(404, JSON.stringify({ error: 'not found' }));
      send(200, await readFile(new URL(asset[0], import.meta.url)), asset[1]);
    } catch {
      if (!res.headersSent) send(500, JSON.stringify({ error: 'internal' }));
      else res.destroy();
    }
  });
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
  makeServer().listen(3000, '127.0.0.1', () => console.log('http://127.0.0.1:3000'));

查询只接受一个 q 参数,去除两端空格后进行 NFC 规范化,并以 Unicode 码点计数限制在二到六十四之间。这是示例的协议选择,不等于用户感知的字符数;某些表情包含多个码点。这里拒绝控制字符和格式字符,也会拒绝部分语言或复杂表情中的合法序列,因此真实多语言产品要重新评估这项限制,不能把它宣传成普适的文本清洗规则。前端与后端都做长度判断,后端的判断才是协议底线。

重复参数被明确拒绝,是为了避免某一层取第一个 q、另一层取最后一个 q 的歧义。空查询不会退化成全量目录,合法但无匹配的查询返回空数组,非 GET 请求返回方法错误。静态文件通过固定映射提供,不把请求路径直接拼到文件系统路径中。读者可以将目录内容替换成自己的公开标题,但不应把私人通讯录直接塞进这个无认证接口。

这里没有数据库,也没有声称数据库查询会随着浏览器取消自动停止。接入真实存储时,应把租户与访问范围从服务端已验证的会话中取得,在查询阶段过滤,再限制候选条数。若先从全局索引取前八条、再在应用层过滤,既可能漏掉本应出现的候选,也容易在计数、排序或日志中泄露跨租户线索。名称检索若使用 SQL,查询词必须作为参数传入;若产品想把百分号和下划线当普通字符,LIKE 的通配符语义还需要单独处理,参数化本身并不解决匹配含义。

对应版本的 Node.js HTTP 文档提供底层服务器、请求和响应接口。本文使用这些接口搭建可观察的小实验,没有引入路由框架,也没有设置跨域许可。前后端通过同一个本地地址访问,先把跨源 Cookie 和代理配置排除出这次问题定位范围。

候选列表不能只让鼠标用户完成操作

index.html 只负责建立输入、列表和反馈区域之间的关系。本文选择手动选定候选:收到结果时不会自动把第一项当成已选择值,用户需要按方向键定位,再按回车确认,或者点击候选。

<!doctype html>
<html lang="zh-CN"><meta charset="utf-8"><title>搜索建议实验</title>
<body>
<label for="query">查找技术条目</label>
<input id="query" type="text" role="combobox" autocomplete="off"
  aria-autocomplete="list" aria-expanded="false" aria-controls="suggestions"
  aria-describedby="help">
<p id="help">输入至少两个字符,用上下方向键浏览,回车选定。</p>
<ul id="suggestions" role="listbox" aria-label="搜索建议" hidden></ul>
<p id="status" role="status"></p>
<p id="chosen"></p>
<script type="module" src="/app.mjs"></script>
</body></html>

app.mjs 连接输入事件、失效逻辑和 DOM。所有候选名称都写入 textContent,不把服务器文本解释成 HTML。用户选择时先保存候选对象,再使当前搜索失效,否则清空数组后就找不到刚刚选择的内容。

import { createSearch } from './search.mjs';
const input = document.querySelector('#query');
const list = document.querySelector('#suggestions');
const status = document.querySelector('#status');
const chosen = document.querySelector('#chosen');
let items = [], active = -1, timer, composing = false;
function render(state) {
  items = state.items; active = -1;
  input.removeAttribute('aria-activedescendant');
  list.replaceChildren();
  for (const [index, item] of items.entries()) {
    const li = document.createElement('li');
    li.id = 'suggestion-' + index; li.role = 'option';
    li.setAttribute('aria-selected', 'false');
    li.textContent = item.label;
    li.addEventListener('pointerdown', e => e.preventDefault());
    li.addEventListener('click', () => choose(index));
    list.append(li);
  }
  list.hidden = items.length === 0;
  input.setAttribute('aria-expanded', String(!list.hidden));
  status.textContent = state.phase === 'loading' ? '正在查找' :
    state.phase === 'error' ? '查找失败,请修改文字后重试' :
    state.phase === 'ready' ? (items.length ? `${items.length} 条建议` : '没有匹配项') : '';
}
const search = createSearch(fetch, render);
function stop() { clearTimeout(timer); return search.invalidate(); }
function schedule() {
  const token = stop(); chosen.textContent = '';
  const q = input.value.trim().normalize('NFC');
  if (composing || [...q].length < 2 || [...q].length > 64) return;
  timer = setTimeout(() => search.run(q, token), 180);
}
function choose(index) {
  const item = items[index];
  if (!item) return;
  stop(); input.value = item.label;
  chosen.textContent = `已选:${item.label},ID:${item.id}`;
}
input.addEventListener('input', schedule);
input.addEventListener('compositionstart', () => { composing = true; stop(); });
input.addEventListener('compositionend', () => { composing = false; schedule(); });
input.addEventListener('blur', stop);
input.addEventListener('keydown', event => {
  if (event.isComposing || composing) return;
  if (event.key === 'Escape') { event.preventDefault(); stop(); return; }
  if (event.key === 'Enter' && active >= 0) {
    event.preventDefault(); choose(active); return;
  }
  if (!items.length || !['ArrowDown', 'ArrowUp'].includes(event.key)) return;
  event.preventDefault();
  active = event.key === 'ArrowDown' ? (active + 1) % items.length :
    (active < 0 ? items.length - 1 : (active - 1 + items.length) % items.length);
  for (const [i, li] of [...list.children].entries()) {
    li.setAttribute('aria-selected', String(i === active));
    li.style.background = i === active ? '#dde8ff' : '';
  }
  input.setAttribute('aria-activedescendant', list.children[active].id);
  list.children[active].scrollIntoView({ block: 'nearest' });
});

WAI-ARIA 的 Combobox 模式是角色与键盘行为的参考。这个实现让焦点留在输入框,用活动后代属性指向当前候选,列表展开状态跟实际可见状态同步;上下键移动候选,回车选定,Escape 关闭。左右方向键、Home、End 及普通文字编辑键没有被接管,以免破坏输入框原有的编辑习惯。添加 role 并不会自动实现键盘逻辑,本文的事件处理仍需要实际设备验证。

还要注意失焦与点击的顺序。用户按下候选时,如果输入框先失焦,失焦处理会清空列表,后续点击可能找不到目标。示例在候选的 pointerdown 阶段阻止默认焦点迁移,再由 click 完成选择。这是一个简洁的演示取舍;触屏滚动、触控笔与不同浏览器的指针行为并未实测,生产组件不能仅凭桌面鼠标的成功就验收。若采用其他失焦延迟方案,要防止延迟期间旧响应重新打开列表。

中文输入不是一串可以立即拿去检索的普通按键。拼音组词过程中,回车可能用于确认输入法候选,不能被搜索框抢走。代码在组合开始时撤销旧搜索,组合期间不启动新查询,也不接管相关按键;组合结束后再按完整输入安排查询。MDN 的 compositionend 说明指出,这个事件也可能来自组合取消,因此仍读取当前输入框值,而不是假定事件一定表示新增了一个汉字。不同浏览器的组合事件与 input 事件先后需要实测;重复安排会被后一次版本和计时器覆盖,减少对固定事件顺序的依赖。

怎样运行,以及怎样故意制造失败

把上述四个文件放在同一目录,保存下面的测试为 test.mjs。不需要 package.json,也不需要安装第三方依赖。运行环境要提供原生 fetch、Unicode 属性正则和 ES 模块;本文只对前述 Node.js 版本做过实际执行,不把其他版本自动视为已验证。

node --version
node --check app.mjs
node --test test.mjs
node server.mjs
# 另开终端检查接口
curl 'http://127.0.0.1:3000/api/suggest?q=Node'

最后一条命令应返回两条 Node.js 候选。服务启动后,在浏览器打开终端打印的本地地址,输入“浏览器”,应看到两条候选;输入一个字符应清空建议;输入“找不到”应显示没有匹配项。页面中“已选”只用于演示选择结果,不会打开详情页,也不会提交搜索。如果要增加跳转,应该基于受信的路由和候选标识构造地址,不直接执行服务端返回的任意网址。

以下测试让旧请求在新请求之后成功,让旧请求在新请求成功后失败,还让旧响应体在输入失效后才解析完成。网络延迟并不靠定时等待模拟,而是由测试明确释放 Promise,避免偶发快慢掩盖问题。

import test from 'node:test';
import assert from 'node:assert/strict';
import { createSearch } from './search.mjs';
import { makeServer } from './server.mjs';
function deferred() { let resolve, reject; const promise = new Promise((a,b)=>{resolve=a;reject=b;}); return {promise,resolve,reject}; }
const response = label => ({ok:true,json:async()=>({items:[{id:label,label}]})});
function fixture() {
 const jobs=[], states=[];
 const search=createSearch((url,options)=>{const d=deferred();jobs.push({...d,url,options});return d.promise},s=>states.push(s));
 return {jobs,states,search};
}
test('late old success cannot overwrite new results',async()=>{
 const {jobs,states,search}=fixture();
 const old=search.run('old',search.invalidate());
 const fresh=search.run('new',search.invalidate());
 assert.equal(jobs[0].options.signal.aborted,true);
 jobs[1].resolve(response('new')); await fresh;
 jobs[0].resolve(response('old')); await old;
 assert.equal(states.at(-1).items[0].label,'new');
});
test('invalidate before debounce blocks old completion',async()=>{
 const {jobs,states,search}=fixture();const old=search.run('old',search.invalidate());
 search.invalidate();jobs[0].resolve(response('old'));await old;
 assert.equal(states.at(-1).phase,'idle');
});
test('stale timer cannot launch a request',async()=>{
 const {jobs,search}=fixture();const t=search.invalidate();search.invalidate();await search.run('old',t);assert.equal(jobs.length,0);
});
test('late old failure cannot replace new result',async()=>{
 const {jobs,states,search}=fixture();const a=search.run('old',search.invalidate());const b=search.run('new',search.invalidate());
 jobs[1].resolve(response('new'));await b;jobs[0].reject(new Error('offline'));await a;assert.equal(states.at(-1).items[0].label,'new');
});
test('current HTTP failure is error, not empty success',async()=>{
 const {jobs,states,search}=fixture();const p=search.run('xx',search.invalidate());jobs[0].resolve({ok:false,status:503});await p;assert.equal(states.at(-1).phase,'error');
});
test('malformed payload is rejected',async()=>{
 const {jobs,states,search}=fixture();const p=search.run('xx',search.invalidate());jobs[0].resolve({ok:true,json:async()=>({items:[{id:1,label:'x'}]})});await p;assert.equal(states.at(-1).phase,'error');
});
test('late response body cannot overwrite newer intent',async()=>{
 const {jobs,states,search}=fixture();const body=deferred();const p=search.run('xx',search.invalidate());
 jobs[0].resolve({ok:true,json:()=>body.promise});await Promise.resolve();search.invalidate();body.resolve({items:[{id:'x',label:'x'}]});await p;assert.equal(states.at(-1).phase,'idle');
});
test('HTTP routes and query contract',async t=>{
 const server=makeServer();await new Promise(r=>server.listen(0,'127.0.0.1',r));
 t.after(()=>new Promise(r=>{server.closeAllConnections();server.close(r)}));const base='http://127.0.0.1:'+server.address().port;
 for(const [name,path,expected] of [
 ['matching','/api/suggest?q=Node',200],['Chinese','/api/suggest?q='+encodeURIComponent('浏览器'),200],
 ['missing','/api/suggest',400],['short','/api/suggest?q=a',400],
 ['duplicate','/api/suggest?q=Node&q=xx',400],['long','/api/suggest?q='+ 'a'.repeat(65),400],
 ['control','/api/suggest?q=aa%00',400],['unknown','/private',404],['page','/',200]]) {
  await t.test(name,async()=>{const r=await fetch(base+path);assert.equal(r.status,expected);if(name==='matching'||name==='Chinese')assert.equal((await r.json()).items.length,2);});
 }
 await t.test('method',async()=>{const r=await fetch(base+'/api/suggest?q=Node',{method:'POST'});assert.equal(r.status,405);assert.equal(r.headers.get('allow'),'GET');});
 await t.test('empty is valid and uncached',async()=>{const r=await fetch(base+'/api/suggest?q=zzzz');assert.deepEqual(await r.json(),{items:[]});assert.equal(r.headers.get('cache-control'),'no-store');});
});

本次实际运行,测试器报告十九项通过、零失败,其中一项是包含子测试的 HTTP 总测试,实际覆盖十八个叶子场景;同时通过前端模块语法检查。接口检查覆盖英文和中文匹配、参数缺失、过短、过长、重复参数、控制字符、未知路径、首页、错误方法和合法空结果。异步测试覆盖旧成功、旧失败、等待期间失效、过期计时器、当前请求错误、非法数据结构及延迟解析。

这些结果只能证明对应模块在本地测试下的行为,不能证明完整组件已经无障碍合格。我没有执行真实浏览器的键盘、读屏、输入法、触屏或弱网测试,也没有连接数据库、生产反向代理和实际鉴权系统。上线前至少要做一次快速连续输入后立即清空、按 Escape 后等待慢响应、输入法回车确认、Tab 离开、方向键选择及触屏点选;再用项目支持的浏览器与读屏组合检查名称、展开状态和候选宣读。尤其要确认失焦后列表不会被响应重新打开,且没有候选时活动后代属性已经移除。

扩容之前,先量清楚用户真正等在哪

一百八十毫秒防抖不是通用最优值。它直接增加最后一次输入到开始请求之间的等待,却可能减少输入中途的查询。对于已经很快的本地目录,这段延迟反而成为体验主体;对于昂贵的远程搜索,它可能值得保留。应该分别记录防抖等待、网络与服务耗时、数据处理和渲染时间,不把总延迟全算在数据库头上。本文没有负载测试,也不给出虚构的吞吐量结论。

服务端固定扫描四条数据,数量增长后,单纯增加候选上限不能解决扫描成本。需要先明确前缀、包含、拼音、分词或容错搜索的产品语义,再选择索引。建议接口的结果顺序也要稳定:同分候选增加固定标识作为排序尾项,可以减少相同输入多次返回时的跳动。若不同用户可见范围不同,缓存键至少要体现授权范围和查询归一化规则;本例直接禁用缓存,牺牲一些复用,换取更容易理解的实验行为。

前端取消还不是服务端限流。大量客户端照样可以绕过输入框直接请求接口,甚至每次都发一个新词。真实服务应有请求大小限制、查询超时、并发上限和明确的过载响应,还应避免把完整搜索词长期写入访问日志,特别是查询可能包含个人资料时。本文的监听地址仅为本机,不能把演示服务器换成公网监听后就当作部署完成。

最后,别让候选接口承担最终业务确认。建议列表是某一时刻的读取结果,用户选中之后,权限、条目状态和可用性都可能变化。真正执行打开、关联或提交操作的接口仍要重新验证候选标识。搜索框的责任是让当前输入得到对应的建议,并让用户可靠地表达选择;它没有能力替后端永久担保这个选择有效。

相关文章

评论

登录后即可参与讨论

暂无评论。