配置 api 版本缓存键的核心做法是将版本号作为变量嵌入 $request_uri 或自定义路径中,并通过 proxy_cache_key 指令将其组合进缓存标识。这样做的结果是不同版本的 api 请求会生成独立的缓存文件,避免旧版本响应被新版本覆盖。若请求中包含动态查询参数,建议结合 $query_string 或使用 $uri 配合版本号前缀来确保缓存隔离。

如何基于 URL 路径中的版本号设计缓存键
当 API 版本直接体现在 URL 路径中(如 /api/v1/...)时,最直接的方案是利用 Nginx 内置的 $uri 变量,因为它已经包含了路径信息但不包含查询字符串。通过设置 proxy_cache_key 为 $scheme$host$uri,Nginx 会自动根据路径中的版本号区分缓存。这种方法简单且高效,因为路径结构天然反映了资源版本。如果希望更明确地控制,也可以手动拼接 $uri 和 $args,但通常 $uri 已足够区分不同版本的路径。
server {
listen 80;
server_name api.example.com;
# 定义缓存路径
proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api_cache:10m max_size=1g inactive=60m;
location /api/ {
# 核心配置:使用 URI 作为缓存键的一部分
# $uri 自动包含 /api/v1/ 或 /api/v2/ 等版本路径
proxy_cache_key "$scheme$host$uri";
proxy_pass http://backend_servers;
proxy_cache api_cache;
# 可选:设置缓存过期时间
proxy_cache_valid 200 10m;
}
}上述配置中,$uri 变量在 Nginx 内部处理时会保留原始请求的路径部分。对于 /api/v1/users 和 /api/v2/users,生成的缓存键分别为 http://api.example.com/api/v1/users 和 http://api.example.com/api/v2/users,从而实现了版本间的缓存隔离。无需额外正则提取版本号,路径结构本身即提供了足够的区分度。
如何处理带查询参数的 API 版本缓存键
当 API 版本通过查询参数传递(如 ?version=v1)或需要同时考虑路径和参数时,必须将 $query_string 显式加入缓存键。否则,/api/data?version=v1 和 /api/data?version=v2 可能会命中同一个缓存条目,导致数据混乱。此时应将 $uri 与 $query_string 组合,形成完整的唯一标识。这种组合方式确保了即使路径相同,只要参数不同,就会生成不同的缓存键。
server {
listen 80;
server_name api.example.com;
proxy_cache_path /var/cache/nginx/api_query levels=1:2 keys_zone=api_query_cache:10m max_size=1g inactive=60m;
location /api/data {
# 核心配置:URI + 查询字符串作为缓存键
# 确保 ?version=v1 和 ?version=v2 产生不同缓存
proxy_cache_key "$scheme$host$uri?$query_string";
proxy_pass http://backend_servers;
proxy_cache api_query_cache;
proxy_cache_valid 200 5m;
}
}在此配置下,$query_string 变量包含了完整的查询字符串(不含 ?)。例如,请求 /api/data?version=v1&format=json 会生成缓存键 http://api.example.com/api/data?version=v1&format=json。这保证了每个独特的参数组合都有独立的缓存空间。需要注意的是,如果某些参数不影响内容(如追踪 ID),应在后端或前端过滤掉,或在 Nginx 中使用 map 指令清理后再生成缓存键,以避免缓存爆炸。
基于特定输入条件验证缓存键冲突
为了验证缓存键是否真正隔离了不同版本,我们可以构造一个具体的测试场景:同一路径但不同版本参数。假设后端服务返回的内容严格依赖于 version 参数,我们将发送两个请求:/api/data?version=v1 和 /api/data?version=v2。如果配置正确,这两个请求应分别生成两个独立的缓存文件。我们可以通过检查 Nginx 缓存目录下的文件数量或内容哈希来确认。若未正确配置 $query_string,则第二个请求可能命中第一个请求的缓存,导致返回错误版本的数据。此验证方法直接针对缓存键的设计有效性,确保版本隔离在实际运行中生效。


















