接口缓存
接口缓存把查询接口的响应写入 Redis，在缓存有效期内直接返回结果，减少数据库和下游服务压力。缓存规则按环境创建，再关联到具体接口。
入口
安全管理 → 流控规则 → 接口缓存。
列表字段
| 列 | 说明 |
|---|---|
| 规则ID | 缓存规则编号 |
| 规则名称 | 便于识别的名称 |
| 缓存时长/s | 缓存有效期，单位秒 |
| 缓存Key规则 | URL、URL+Query、URL+Body、URL+自定义参数 |
| 最大结果值/kb | 单个响应允许写入缓存的大小上限 |
| 关联API | 已绑定该规则的接口数量 |
| 修改时间 | 最近更新时间 |
支持按规则名称和环境筛选。删除规则前需先解除接口关联，已关联接口的规则不可删除。
新建缓存规则
- 点击「新建」；
- 选择所属环境（创建后不可修改）；
- 填写规则名称；
- 填写缓存时长，单位秒；
- 填写最大缓存结果，单位 KB。超过该大小的响应不会写入缓存；
- 选择缓存 Key 规则；
- 保存后通过「关联」绑定接口。
缓存 Key 规则
| 值 | 规则 | Key 组成 | 适用场景 |
|---|---|---|---|
| 0 | URL | 方法 + 路径 | 所有调用方共享同一份结果 |
| 1 | URL+Query | 方法 + 路径 + 全部 Query 参数（排序后） | GET 查询参数决定结果 |
| 2 | URL+Body | 方法 + 路径 + 请求体 MD5 | POST 查询，body 决定结果 |
| 3 | URL+自定义参数 | 方法 + 路径 + 指定 Query 参数（排序后） | 只按关键参数区分缓存 |
选择「自定义参数」时，需要填写参与 Key 计算的 Query 参数名，多个参数用英文逗号分隔。若请求中缺少指定的全部参数，本次请求不进入缓存，直接转发。
实际 Key 还包含调用方维度
网关生成缓存 Key 时会在规则 Key 前拼接调用方作用域：已认证请求按应用 ID 隔离，未认证接口使用 anon。因此不同应用即使请求参数相同，也不会命中彼此的缓存，避免跨应用数据串读。
生效条件
缓存并非对所有接口生效，需要同时满足：
- 接口关联了缓存规则；
- 接口响应的内容类型为 JSON；
- 接口的 SQL 类型为 SELECT（查询类 SQL 接口）；
- 响应大小未超过「最大结果值」；
- 请求未被限流、熔断或 IP 规则拦截。
不满足条件时请求正常转发，只是不读缓存、不写缓存。MCP 调用和管理后台路由会跳过缓存。
执行流程
- 命中缓 存时返回 HTTP 200，并带上响应头
Api-Cache: true； - 缓存写入为异步 fire-and-forget，写入失败不影响本次响应；
- 缓存值只保存响应体，不保存响应头；命中后内容类型按 JSON 返回。
容量与安全边界
| 边界 | 默认值 | 说明 |
|---|---|---|
| 请求体参与 Key 的最大大小 | 100 KB | 超过后跳过缓存直接转发，避免大请求体占用内存；可通过 apigo.cache.max-body-size-bytes 调整 |
| 单个响应缓存上限 | 规则配置值，未配置时 1024 KB | 超过上限不写缓存 |
| 网关聚合硬顶 | 256 MB | 即使规则配置更大，也不会超过该硬顶 |
| 默认缓存时长 | 300 秒 | 规则未填写时使用 |
| 调用方隔离 | 按 appId / anon | 不同应用不共享缓存 |
设计逻辑
- 按环境隔离：规则与关联关系都带环境，开发、测试、生产的缓存互不影响；
- 只缓存查询：写入逻辑要求 SQL 类型为 SELECT，避免把写操作的结果缓存后在有效期内重复返回；
- 大小有界：聚合响应时边转发边累计，超过上限立即停止累计并只记录日志，防止大响应耗尽网关内存；
- 失败降级：Redis 不可用或写入失败时，请求走正常转发，不阻塞主链路；
- 不主动清理旧值：规则修改或删除后，已写入的缓存不会立即失效，需要等待 TTL 到期；如需立即生效，可在 Redis 中清理对应缓存键。
常见问题
| 现象 | 排查方向 |
|---|---|
响应没有 Api-Cache: true | 规则是否关联接口、响应是否 JSON、SQL 是否为 SELECT |
| 修改数据后仍返回旧结果 | 缓存尚未过期；缩短 TTL 或清理缓存 |
| 不同应用读到了相同结果 | 确认接口认证方式；未认证接口共用 anon 作用域 |
| 大响应始终不缓存 | 检查「最大结果值」与响应实际大小 |
| POST 接口不缓存 | 使用 URL+Body 或 URL+Query 规则，并确认请求体未超过 100 KB |