配置Nginx缓存RESTful API需匹配资源语义、更新频率与安全性：优先缓存幂等GET请求，忽略无关查询参数，按状态码分层设置有效期，禁用敏感状态码缓存，并结合ETag/Last-Modified校验与主动失效机制。
配置 Nginx 缓存处理 RESTful API，关键不是简单开启缓存，而是让缓存行为与 API 的资源语义、更新频率和安全性匹配。RESTful 接口天然具备可缓存性（Cacheable）这一架构约束，但必须通过精准的缓存策略避免返回过期数据、泄露用户敏感信息或缓存错误状态码。
明确哪些 API 值得缓存
并非所有接口都适合缓存。优先缓存满足以下特征的 GET 请求：
-
幂等且无副作用：只读操作，如
GET /api/products/123、GET /api/articles?tag=tech - 内容更新频率低：商品详情、新闻列表、配置类数据（如地区字典），通常分钟级或小时级更新
- 高请求量 + 高计算成本：聚合报表、搜索结果页、带复杂 JOIN 的数据库查询结果
- 不含用户私有上下文：避免缓存依赖 Cookie、Authorization 或用户 ID 的响应；若需个性化，应剥离动态部分（如用 ESI 或前端异步加载头像/购物车）
设置合理的缓存存储与键规则
Nginx 默认按完整请求 URI + Host + 请求方法生成缓存键，这对 RESTful API 通常足够，但要注意两点：
-
忽略无关查询参数：例如
?utm_source=xxx或?t=1718234567这类追踪参数不应影响缓存命中。可在 location 块中用proxy_cache_key自定义键：
proxy_cache_key "$scheme$request_method$host$uri$is_args$arg_category$arg_sort";
- 分离缓存区域：为不同业务模块分配独立 keys_zone，便于单独清理或调优。例如：
proxy_cache_path /var/cache/nginx/api_products levels=1:2 keys_zone=products:10m max_size=500m; proxy_cache_path /var/cache/nginx/api_articles levels=1:2 keys_zone=articles:5m max_size=200m;
按 HTTP 状态码与资源特性设定有效期
不能对所有 200 响应一概缓存 10 分钟。应结合响应头中的 Cache-Control 和业务逻辑分层控制：
-
尊重后端明确指令：启用
proxy_cache_use_stale updating，并在后端响应中设置Cache-Control: public, max-age=3600，Nginx 会优先采用该值 -
兜底策略防失控：对未带 Cache-Control 的响应，用
proxy_cache_valid设定默认行为：
proxy_cache_valid 200 301 302 1h; # 成功响应缓存 1 小时 proxy_cache_valid 404 1m; # 404 缓存 1 分钟，避免反复穿透 proxy_cache_valid 500 502 503 504 30s; # 错误响应短暂缓存，缓解雪崩
- 禁止缓存敏感状态码：显式排除 401、403 等认证相关响应，防止错误授权被共享：
proxy_cache_valid 200 301 302 1h; # 不配置 401/403，即默认不缓存
启用缓存校验与失效机制
静态缓存时间不够灵活，需配合服务端的验证机制实现“准实时”更新：
-
支持条件请求：确保后端返回
ETag或Last-Modified，Nginx 会自动转发If-None-Match或If-Modified-Since到上游，并正确处理 304 响应 -
主动失效（Purge）需谨慎：Nginx 本身不提供标准 purge 接口，生产环境建议用
ngx_http_cache_purge_module扩展，或改用 Redis 等应用层缓存承担细粒度失效逻辑 - 缓存状态可观测：添加响应头辅助排查：
add_header X-Cache-Status $upstream_cache_status; add_header X-Cache-Age $upstream_http_cache_control;
常见值：HIT（命中）、MISS（未命中）、STALE（过期但仍在用）、UPDATING（后台更新中）。
