JSON接口缓存需基于路径、响应头等语义信号判断，而非格式识别；适合缓存的须满足只读、用户无关、内容稳定三条件，如配置类接口可设public max-age，带版本号查询可用immutable，含用户标识的则必须private no-store，并推荐用map动态设置Cache-Control。
JSON 接口缓存不能靠“格式识别”，而要靠“语义判断”——Nginx 本身不解析 JSON 内容，但能根据路径、响应头、请求方法、状态码等信号，精准决定是否缓存、缓多久、给谁用。
识别哪些 JSON 接口适合缓存
不是所有返回 JSON 的接口都该缓存。重点看三点：是否只读、是否用户无关、是否内容稳定。
- 公开配置类接口（如
/api/v1/dict/countries、/api/config）——内容更新少、无用户上下文，适合设为public, max-age=3600 - 带版本号或时间戳参数的只读查询（如
/api/search?q=nginx&v=2或/api/data?ts=20260601）——可缓存且易失效，建议用Cache-Control: public, immutable - 含用户标识、Session、Cookie 或权限校验的接口（如
/api/user/profile）——必须设为private, no-store或直接 bypass 缓存
用 map + add_header 动态设置 Cache-Control
避免硬编码 location 块，推荐用 map 指令按响应类型或路径前缀动态生成缓存策略，再统一注入响应头。
示例配置：
map $request_uri $json_cache_control {
~^/api/v1/dict/ "public, max-age=7200";
~^/api/v1/config/ "public, immutable";
~^/api/search "public, stale-while-revalidate=86400";
default "no-cache";
}
<p>server {
location /api/ {
proxy_pass <a href="https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e">https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e</a>;
add_header Cache-Control $json_cache_control;</p><h1>覆盖后端可能返回的旧头</h1><pre class='brush:php;toolbar:false;'> proxy_ignore_headers Cache-Control Expires;
}}
这样既保持配置集中，又便于后续按业务线灰度调整。
谨慎启用 POST 接口缓存
默认 Nginx 不缓存 POST 响应，但部分幂等只读场景（如 GraphQL 查询、复杂搜索表单提交）可安全开启。
- 在 location 中显式声明：
proxy_cache_methods GET HEAD POST;（必须包含 GET 和 HEAD） - 重写 cache key，避免不同请求体共用缓存：
proxy_cache_key "$scheme$proxy_host$request_uri$args$request_body"; - 确保
$request_body可用：需开启proxy_buffering on，且client_max_body_size合理（如 1M） - 更稳妥做法：让后端将请求参数哈希后写入
X-Req-Sign头，Nginx 用$http_x_req_sign构建 key
配合压缩与传输优化提升实际体验
缓存只是第一步，大体积 JSON 的传输效率同样关键。
- 启用 Gzip 压缩：
gzip_types application/json;，对典型 JSON 可减少 60%~80% 体积 - 调大 proxy 缓冲区，避免 JSON 响应体过大触发磁盘临时文件：
proxy_buffers 16 32k;、proxy_buffer_size 8k; - 若接口返回超大 JSON（>5MB），建议前端改用流式解析，并在 Nginx 关闭缓冲：
proxy_buffering off;，防止内存堆积
