如何设置 proxy_cache_methods 以实现特定 POST 请求的边缘缓存加速？

本文共计859个文字，预计阅读时间需要4分钟。

在默认情况下，Nginx 和大多数边缘节点（如阿里云 ESA）不支持缓存 POST 请求。这是因为 POST 请求通常具有副作用，例如提交表单、创建资源等。然而，现实中很多 POST 请求是查询类操作（如 GraphQL 查询、搜索 API、带有 JSON body 的条件筛选等），这类请求非常适合缓存。关键在于显式启用缓存并精确控制。

明确启用 POST 缓存的必要配置

仅靠 proxy_cache_methods GET HEAD POST; 不够，必须同步满足以下三点：

• 开启缓存区：在 location 或 server 块中声明 proxy_cache my_cache;（对应 http 块中已定义的 proxy_cache_path）
• 允许 POST 方法：设置 proxy_cache_methods GET HEAD POST;（PUT/DELETE 极少用，暂不建议）
• 设计唯一缓存键：必须包含请求体内容，否则所有 POST 都会命中同一缓存项。推荐写法：
  proxy_cache_key "$scheme$request_method$host$request_uri$request_body";
  ⚠️ 注意：$request_body 在 Nginx 中需配合 proxy_buffering on; 和足够大的 client_max_body_size 才能稳定获取；若 body 过大或含二进制内容，可改用哈希：
  proxy_cache_key "$scheme$request_method$host$request_uri$arg_q$arg_f";（提取关键查询参数）

按业务语义分层设定缓存策略

不能对所有 POST “一刀切”缓存。应结合响应含义分级处理：

• 幂等查询类 POST（如搜索、过滤、聚合）：
  设置短 TTL（如 proxy_cache_valid 200 302 5s;），搭配 proxy_cache_lock on; 防穿透，再启用 proxy_cache_use_stale updating;，确保高并发下旧缓存仍可服务
• 配置/字典类只读 POST（如根据 ID 批量查地区码）：
  可设长 TTL（proxy_cache_valid 200 10m;），并加 proxy_ignore_headers Cache-Control; 强制覆盖后端返回的 no-cache
• 真正有副作用的 POST（如下单、发消息）：
  用 proxy_no_cache $request_method; 或更细粒度地匹配路径（proxy_no_cache $uri ~ ^/api/v1/order/submit$;）彻底禁用缓存

安全绕过与强制刷新机制

即使启用了 POST 缓存，也要保留人工干预能力：

• 用 proxy_cache_bypass $http_x_refresh $arg_refresh; 实现“带头或带参即绕过”——调试时加 X-Refresh: 1 即可直连后端取最新结果
• 用 proxy_no_cache $http_cache_control; 尊重客户端主动发起的 no-cache 请求（如浏览器开发者工具勾选 Disable cache 时发出的请求）
• 避免用 IP 或 Cookie 做 bypass 条件，易引发缓存污染和一致性问题

验证是否生效的关键检查点

上线后务必确认三点：

• 响应头中出现 X-Proxy-Cache: HIT 或 MISS（需在 Nginx 中添加 add_header X-Proxy-Cache $upstream_cache_status;）
• 相同 POST body 发起两次请求，第二次响应时间显著下降（如从 300ms → 5ms），且无后端日志新增
• 修改 body 内容（如改搜索关键词），命中不同缓存项，响应内容随之变化