API缓存键名设计需精准表达共享范围，避免污染：必须包含$request_method、$host、$uri$is_args$args；按需增强登录态、CORS、设备类型字段；主动过滤UTM等干扰参数；务必验证key生成是否符合预期。
API 接口缓存的键名（proxy_cache_key）不是越长越安全，而是要精准表达“哪些请求该共享一份缓存”。设计不当会直接导致缓存污染——比如用户 A 看到用户 B 的数据、移动端返回 PC 版本、带身份信息的响应被公开缓存。
必须包含的基础维度
默认的 $scheme$proxy_host$request_uri 太粗略，生产环境至少补全以下三项：
-
区分请求方法：加上
$request_method，避免 HEAD 请求命中并覆盖 GET 缓存； -
统一主机标识：用
$host替代$proxy_host，防止子域名（如 api.example.com 和 www.example.com）误共享缓存； -
保留路径与参数语义：用
$uri$is_args$args替代$request_uri，避免重写后 URI 变形影响一致性。
按业务需求选择性增强
是否加入额外字段，取决于接口是否对这些因素敏感：
-
登录态或角色差异：需区分用户时，添加
md5($cookie_user_id)或md5($http_x_user_role)，避免明文 cookie 泄露； -
跨域请求（CORS）：若接口支持多 Origin 调用，必须含
$http_origin，并配add_header Vary "Origin"，否则 A 站的Access-Control-Allow-Origin: a.com可能返回给 B 站； -
设备类型适配：优先用
$http_x_requested_with（值为XMLHttpRequest或空）判断是否为 Ajax 请求，比解析$http_user_agent更轻量稳定。
主动过滤干扰参数
UTM、时间戳、随机数等不影响内容的查询参数，会导致缓存键爆炸式增长。不能直接拼 $args，应预处理：
- 在
http块中用map清洗参数串，例如剔除utm_*、ts=、random=； - 定义清洗后变量
$clean_args，再用于 key：proxy_cache_key "$scheme$host$uri$is_args$clean_args";； - 若后端对参数顺序不敏感（如
?a=1&b=2≡?b=2&a=1），Nginx 不原生支持排序，建议仅对明确需参数区分的路径启用缓存（如限定location ~ \.json$）。
验证键是否按预期生成
配置写完不等于生效，必须验证实际生成的 key：
- 添加日志格式：
log_format cache '$cache_key - $upstream_cache_status';，并在access_log中启用； - 用
curl -I观察X-Cache-Status和Age字段变化； - 临时设 key 为固定字符串（如
"debug_key"），看多个不同请求是否全部命中HIT，可快速确认配置是否加载成功。
