问题从一张不该出现的图片开始

一套文搜图示例最初只有一个输入框：用户输入词语，列表展示匹配图片。为了让来回搜索快一点，我们顺手加了缓存。问题很快出现，同一个人将“雪山 湖泊”改成“雪山湖泊”，结果有时不变；切换语言后仍看见中文词条的旧结果；翻到第二页又遇到第一页的图片。请求接口本身没有明显报错，真正需要检查的不是图片相似度，而是缓存键怎样表达一次查询的完整语义。

我把 Demo 叫作 PhotoCacheScope。输入图片 ID 是 fixtures 内的构造数据；ArkUI Search 负责展示查询词交互，Node.js 专门处理缓存键、TTL 和命中分类。这样把 UI、检索引擎与缓存逻辑分开，能在缺少设备、模型和网络时先把业务层契约说清楚。

最容易写错的是“去掉所有空格”

一些代码会把用户输入先执行 trim，再把全部空格删除，以为这是提升命中率。对于“雪山 湖泊”和“雪山湖泊”，这种做法确实得到相同 key，却不能保证两个词的检索意图一定相同。更危险的是把所有标点也去掉，不同短语可能合并成同一个缓存位置，后续即使网络返回正确内容，也被旧条目盖过去。我选择保守规范化：Unicode NFKC、首尾空白清理、连续空白折成一个空格；保留有意义的内部间隔与标点。是否将语义同义词合并，应由独立的语义改写版本控制，而非简单字符串清理。

一次查询不能只用 query 作为 key。模型版本变化会改变排序，界面语言变化可能影响召回，页码不同意味着结果窗口不同。我的键由 query、locale、model、page 四项构成，按照固定顺序序列化成 JSON 数组字符串。这样不仅清晰，还能避免手工字符串拼接时分隔符出现在用户输入里造成二义性。把字符串长度前缀化也可以达到同样目的，这里优先选择容易阅读和单元测试的表示法。

function normalizeQuery(value) {
  if (typeof value !== 'string') throw new Error('query must be string');
  const text = value.normalize('NFKC').trim().replace(/\s+/gu, ' ');
  if (!text) throw new Error('empty query');
  return text;
}
function scopeKey(q) {
  if (!Number.isSafeInteger(q.page) || q.page < 1) throw new Error('page');
  return JSON.stringify([normalizeQuery(q.query), q.locale, q.model, q.page]);
}

locale 和 model 都应来自经过校验的配置，不要直接信任任意拼写。真实应用可能还必须包含登录用户、资源访问权限、过滤标签、裁切模型版本、排序方式甚至实验分桶。一旦这些维度会改变最终结果，就应该进入作用域键；否则缓存命中率看起来提高，正确性反而下降。尤其文搜图常有隐私照片，跨账号或跨图库误命中不仅是 UI 小毛病，还可能成为数据隔离风险。

让时间成为输入，缓存实验才能重复

缓存过期最方便的写法是 Date.now()，但它让单元测试依赖运行时间。测试时偶然快慢几毫秒，就会得到 HIT 或 EXPIRED 的不同结果。本次把 at 写到构造请求里，TTL 固定为五千个逻辑毫秒。条目保存 expiresAt，再遇到同一作用域的请求时比较 at。小于截止时间为 HIT；到达或超过截止时间视为 EXPIRED 并更新内容；此前从未出现的键是 MISS。

const cache = new Map();
function readOrFill(req, responseIds, ttlMs) {
  const key = scopeKey(req);
  const saved = cache.get(key);
  if (saved && req.at < saved.expiresAt) return { status: 'HIT', ids: saved.ids };
  const status = saved ? 'EXPIRED' : 'MISS';
  cache.set(key, { ids: [...responseIds], expiresAt: req.at + ttlMs });
  return { status, ids: responseIds };
}

不能把“过期”和“未命中”都直接记成 MISS，因为两种情况的排查路径不同。未命中意味着作用域发生变化或条目未建立；过期则说明原本有条目但生命周期结束。报告应该展示命中键的字段、截至时间和来源，方便诊断。还要注意缓存中的值是结果 ID 快照，不能保存指向 UI 可变数组的原始引用；否则列表原地排序后会无意修改缓存对象，重放时又出现漂移。

七次查询验证七个不同条件

这轮构造了七次查询。Q1 输入“雪山 湖泊”、中文、模型 v2、第一页、时刻一千，建立初始缓存。Q2 去掉内部空格，仍视为另一个查询，产生独立 MISS。Q3 输入两个空格，与 Q1 在规范化后得到同一个 key，且未过期，因此命中 Q1 的 PH-51、PH-52；即使 Q3 的构造候选列表写了 PH-999，也不允许覆盖命中结果。Q4 仅改变模型版本为 v3，必须重新取数。

Q5 将时钟推到七千，Q1 的原条目已超过截止时间六千，故结果是 EXPIRED，并写入 PH-57。Q6 保持原词和模型，但访问第二页，是新的作用域，不能复用第一页；Q7 切换到英文区域 en-US，仍然要独立 MISS。最终一条 HIT、五条 MISS、一条 EXPIRED。

我在输出里同时保留 request id、原始查询、归一化结果、语言、模型版本、页码和所返回的 ID。查看 Q3 就应看到 PH-51、PH-52，而不是 PH-999。只看 HIT 数量很容易漏掉值来源错误，因此回归断言还需要验证返回 ID。调试时可以故意删掉 key 中的 page，再跑 Q6；如果结果错误地变成 HIT，就证明本来分开的作用域发生了碰撞。这个反例比口头解释“页码要入 key”更有说服力。

Search 组件和缓存逻辑不应该绑死

界面使用 ArkUI Search 的输入、onChange 或 onSubmit 来更新查询文本，并在提交后交给独立的数据服务。Search 本身不会替我们处理 TTL、用户隔离和缓存一致性。为了避免边输入边发出十几次请求，实际工程还应增加防抖或明确“提交搜索”触发；输入预上屏与正式提交要分开，IME 组合输入阶段也不应视为完整检索词。

@Entry
@Component
struct SearchPreview {
  @State query: string = '雪山 湖泊'
  @State hint: string = '点击回放构造请求查看缓存结果'
  build() {
    Column({ space: 12 }) {
      Search({ value: this.query, placeholder: '输入图片描述' })
        .onChange((v: string) => { this.query = v })
      Button('重放缓存轨迹').onClick(() => {
        this.hint = 'CK-405：HIT 1 / MISS 5 / EXPIRED 1'
      })
      Text(this.hint)
    }.padding(20)
  }
}

实际产品应该通过明确的接口取得检索结果，不要在 ArkTS 运行时直接使用 Node 文件模块。这种拆分也便于开发者换掉示例输入数据而不触碰 UI。

验证流程、异常和缓存释放

进入目录依次执行 node --check tools/cache-check.mjs、node tools/cache-check.mjs，结果会写入 reports/cache.json。日志应包含 Q1 MISS、Q2 MISS、Q3 HIT、Q4 MISS、Q5 EXPIRED、Q6 MISS、Q7 MISS，汇总为 HIT=1、MISS=5、EXPIRED=1。改动数组中的任一缓存维度后，应该重新生成并比对快照报告；在 CI 中保留失败日志即可，不必上传用户真实搜索词。

对生产缓存还需增加最大条目数、LRU 或分代清理。本文的 Map 只在本次 Node 进程生命周期内存在，退出便释放内存；长驻服务必须定期删除过期项并设置上限，不能依靠读时发现过期来实现无限期运行。若远端数据源发生主动变更，单靠 TTL 无法立即失效，必须增加内容版本或主动失效通知。遇到网络错误，应该区分“允许短时展示已过期缓存”和“必须强制刷新”的业务策略，并在 UI 显示数据新鲜度，而不应静默当作最新结果展示。

对于缓存键，最值得审计的是权限作用域而不是大小写技巧。私有相册至少还要包含用户身份、授权范围和数据集版本；共享素材库也要考虑地域授权及审核状态。不要将原始敏感查询、访问令牌或者图片存储地址直接输出到常规 HiLog。示例的测试词和 PH 编号都是公开构造数据，日志才允许逐条打印。生产环境可在取得排查所需结构后对搜索词打摘要，同时确保摘要无法被轻易还原。

技术结论与官方资料

文搜图结果缓存的第一目标是不把别的作用域的答案错发给当前查询，其次才是提升速度。键要表达所有会影响结果的维度，时间要可测试，过期与未命中要分开，命中值的来源必须可追溯。后续要接入真正的语义检索，需要另行验证模型输入、相册授权、图像资源释放和服务错误处理。

官方资料： 华为 ArkUI 资源与组件文档入口；华为开发者文档中心；AtomicServiceSearch 参考（从 API 18 提供，用于元服务，本文普通 Search 不依赖该组件）。具体 Search 的 API、目标 SDK 和组件变更请以实际工程锁定的官方参考版本为准，缓存键与 TTL 则是本例 Node.js 业务规则。