Nginx API缓存可将800ms接口降至20–50ms，需筛选读多写少、无用户依赖、纯GET、后端耗时>200ms的接口；配置专用缓存区、清洗缓存键、强制有效期、忽略干扰头、启用stale托底与后台更新，并配套监控与主动清理机制。
直接在 Nginx 中为 API 接口配置精细化缓存，是提升聚合网关性能最见效的手段之一。它不改后端代码、不引入新组件，却能把 800ms 的接口压到 20–50ms 返回，同时大幅降低后端负载。
明确哪些 API 适合缓存
不是所有接口都该进缓存，否则可能返回错误数据或泄露敏感信息。重点选这四类：
- 读多写少、更新频率低：比如商品类目树（几小时一变）、城市天气预报（每小时更新）、系统公告页；
- 无用户身份依赖：响应内容不随 Cookie、Authorization token 或 session 变化；若必须区分登录态，需显式构造缓存键；
- 纯 GET 请求：不触发下单、扣库存、发消息等副作用操作；
- 后端耗时明显：单次响应超过 200ms，尤其含数据库 JOIN、远程调用或复杂计算的接口。
定义独立缓存区与安全缓存键
避免缓存污染和磁盘爆满，关键在于隔离与精准识别请求：
- 声明专用缓存区：
proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api_cache:100m max_size=5g inactive=10m use_temp_path=off;——use_temp_path=off能跳过临时文件拷贝，显著提速； - 设计健壮缓存键：
proxy_cache_key "$scheme$request_method$host$uri$is_args$args";默认已排除 body，但若 URL 含分页参数（如page=1）或时间戳（如t=1722266481），建议用map清洗参数，或改用更稳定的标识字段（如 ID）； - 若需按用户角色缓存，可加入
$http_x_user_role，但务必确认该 header 不含个人隐私信息。
强制有效期 + 忽略干扰响应头
别完全信任后端返回的 Cache-Control，它常被误设或缺失：
- 主动设定缓存时长：
proxy_cache_valid 200 302 5m; proxy_cache_valid 404 1m;—— 成功响应缓存 5 分钟，404 缓存 1 分钟防穿透； - 屏蔽后端干扰：
proxy_ignore_headers Cache-Control Expires Set-Cookie Vary;—— 尤其Set-Cookie必须忽略，否则可能缓存带用户态的响应； - 对部分接口可叠加
proxy_cache_bypass $arg.nocache;，方便调试时加?nocache=1强制绕过。
启用 stale 托底与后台刷新
真正的高可用不是“永不故障”，而是“故障时用户无感”：
- 开启 stale 响应：
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;—— 后端超时或返回 5xx 时，自动返回过期但可用的缓存； - 搭配后台更新：
proxy_cache_background_update on;—— Nginx 在返回 stale 数据的同时，异步拉取新响应并更新缓存； - 加状态头便于观测：
add_header X-Cache-Status $upstream_cache_status;—— 响应头中可见HIT、MISS、STALE，快速定位问题。
配套可观测与主动干预机制
缓存不能一配了之，上线后必须持续盯住实效性：
- 监控命中率：通过日志统计
$upstream_cache_status出现频次，或用 Prometheus 抓取 stub_status 指标； - 支持主动清除：配置
location ~ ^/purge(/.*)?$ { allow 127.0.0.1; deny all; proxy_cache_purge api_cache $scheme$request_method$host$1; }，运维可按路径清理； - 定期清理无效缓存：配合
inactive=10m参数，自动淘汰 10 分钟未被访问的条目，防止冷数据占满空间。
