在搜索框里输入“浏览器”,看到的却是上一轮“浏览”的结果,这类问题常被归咎于网络慢。网络慢只是放大器:真正的缺口,是页面没有规定哪一次输入还拥有修改结果区的资格。把防抖从一百毫秒调到三百毫秒,通常只是让错误更难复现;接上取消请求,也不能代替这条规则。
下面做一个不依赖框架的搜索建议组件。后端使用 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 离开、方向键选择及触屏点选;再用项目支持的浏览器与读屏组合检查名称、展开状态和候选宣读。尤其要确认失焦后列表不会被响应重新打开,且没有候选时活动后代属性已经移除。
扩容之前,先量清楚用户真正等在哪
一百八十毫秒防抖不是通用最优值。它直接增加最后一次输入到开始请求之间的等待,却可能减少输入中途的查询。对于已经很快的本地目录,这段延迟反而成为体验主体;对于昂贵的远程搜索,它可能值得保留。应该分别记录防抖等待、网络与服务耗时、数据处理和渲染时间,不把总延迟全算在数据库头上。本文没有负载测试,也不给出虚构的吞吐量结论。
服务端固定扫描四条数据,数量增长后,单纯增加候选上限不能解决扫描成本。需要先明确前缀、包含、拼音、分词或容错搜索的产品语义,再选择索引。建议接口的结果顺序也要稳定:同分候选增加固定标识作为排序尾项,可以减少相同输入多次返回时的跳动。若不同用户可见范围不同,缓存键至少要体现授权范围和查询归一化规则;本例直接禁用缓存,牺牲一些复用,换取更容易理解的实验行为。
前端取消还不是服务端限流。大量客户端照样可以绕过输入框直接请求接口,甚至每次都发一个新词。真实服务应有请求大小限制、查询超时、并发上限和明确的过载响应,还应避免把完整搜索词长期写入访问日志,特别是查询可能包含个人资料时。本文的监听地址仅为本机,不能把演示服务器换成公网监听后就当作部署完成。
最后,别让候选接口承担最终业务确认。建议列表是某一时刻的读取结果,用户选中之后,权限、条目状态和可用性都可能变化。真正执行打开、关联或提交操作的接口仍要重新验证候选标识。搜索框的责任是让当前输入得到对应的建议,并让用户可靠地表达选择;它没有能力替后端永久担保这个选择有效。
评论
暂无评论。