HTTP 缓存头

对于 REST 查询请求，客户端可以通过 Cache-Control 请求头来影响数据墙DBW 的缓存行为。这允许调用方在特定场景下强制绕过缓存获取最新数据，或阻止某些响应进入缓存。

NOTE

如果运行时配置中全局缓存已关闭（runtime.cache.enabled: false），Cache-Control 请求头被完全忽略，所有查询正常访问数据库。

支持的指令

数据墙DBW 仅处理 Cache-Control 请求头中的以下指令：

指令	行为
no-cache	绕过 L1 和 L2 缓存，强制从数据库查询最新数据，并将结果更新到缓存中
no-store	如果缓存中已有有效条目则返回缓存值；如果缓存未命中则查询数据库，但不会将结果写入 L1 或 L2

NOTE

数据墙DBW 不会在响应中主动设置 Cache-Control 响应头。缓存控制仅通过请求头单向驱动。指令匹配不区分大小写（NO-CACHE 和 no-cache 效果相同）。不处理其他标准 Cache-Control 指令如 max-age、max-stale、public、private。

no-cache：强制刷新

no-cache 的语义是"服务端应该在使用缓存前先验证"。在数据墙DBW 的实现中，它的效果是完全绕过缓存，强制从数据库读取，并将新结果写入缓存。

请求

GET /api/Books
Cache-Control: no-cache
Accept: application/json

行为流程

请求带 no-cache → 跳过 L1 → 跳过 L2 → 查询数据库 → 结果写入 L2 → 结果写入 L1 → 返回

使用场景

场景	说明
数据刚被外部系统修改	数据墙DBW 之外的进程直接修改了数据库，缓存中的数据已过时
调试排查	确认数据是否是缓存问题，强制看数据库真实值
实时性要求高的个别请求	绝大部分请求走缓存，关键请求绕过

使用 no-cache 后，缓存被更新为最新数据，后续不带该头的请求会命中更新后的缓存。

no-store：不写入缓存

no-store 的效果是不改变缓存状态。数据墙DBW 在收到 no-store 时：

• 如果缓存中已有有效条目，正常返回缓存值。
• 如果缓存未命中，则查询数据库并返回结果，但不会将结果写入 L1 或 L2。

请求

GET /api/Books
Cache-Control: no-store
Accept: application/json

行为流程

请求带 no-store → 检查 L1 → 检查 L2
  ├── 任一命中 → 返回缓存值（不更新缓存）
  └── 全部未命中 → 查询数据库 → 返回（不写入 L1 和 L2）

使用场景

场景	说明
不频繁的一次性查询	不希望这种临时查询占用缓存空间，驱逐热数据
敏感数据请求	不希望查询结果留在可能被其他请求读取的缓存中
全量导出	一次性的 $first=-1 全量数据拉取不应污染缓存

no-cache 与 no-store 对比

维度	no-cache	no-store
是否走缓存读	否，强制数据库	可能走（如果已有缓存）
是否写缓存	是，用新结果更新	否，不写入
缓存后续影响	后续请求受益于新缓存	对缓存无影响
典型用途	强制刷新	避免污染缓存

组合使用

可以同时发送两个指令：

GET /api/Books
Cache-Control: no-cache, no-store

效果：强制数据库查询，且不将结果写入缓存。适合在排查问题时使用，既保证拿到最新数据，又不影响生产缓存。

限制

限制	说明
仅 REST	GraphQL 请求不支持 Cache-Control 头控制缓存
仅查询	仅影响 GET 请求，对其他 HTTP 方法无缓存行为
仅控制读取路径	写操作（POST/PUT/PATCH/DELETE）的缓存失效行为不受影响
无响应头	引擎不在响应中设置任何 Cache-Control 相关响应头

下一步

• 一级缓存 — 完整的缓存配置说明。
• 二级缓存 — Redis 分布式缓存配置。