Nginx URL重写管理API版本的核心目标是平滑过渡、不破坏旧调用、保障兼容性；通过路径重写、请求头路由、灰度分流及强制升级提醒等策略，实现v1请求自动转v2、透传版本标识、按需分流降级，并需规避循环重写、优先使用map替代if、保留query string、覆盖边界测试。
API 版本号升级时，Nginx URL 重写的核心目标是：**平滑过渡、不破坏旧调用、保障兼容性**。不需要客户端立刻改代码，就能让 v1 接口请求自动转给 v2 后端，或按需分流、降级、提示升级。
一、常见升级模式与对应 rewrite 策略
根据升级方式选择匹配的重写逻辑：
-
路径式版本升级（如
/api/v1/users→/api/v2/users）：适合后端服务已部署 v2，只需路由转发 -
无版本路径 + 后端适配（如
/api/users→ 后端自动识别版本头或参数）：重写重点在透传或注入版本标识 -
灰度切换：按请求头（
X-Api-Version）、IP 或参数决定走 v1 还是 v2 - 强制升级提醒：对明确访问 v1 的请求返回 410 或 301 跳转到文档页
二、典型 rewrite 配置示例
以下配置均放在 location /api/ 块内，确保前置匹配精准：
-
v1 路径自动映射到 v2 后端（内部重写，客户端无感）
location /api/v1/ {
rewrite ^/api/v1/(.*)$ /api/v2/$1 last;
} -
统一入口，通过请求头路由（需配合 proxy_pass）
if ($http_x_api_version = "v2") {
set $backend "http://backend-v2";
}
if ($http_x_api_version = "v1") {
set $backend "http://backend-v1";
}
proxy_pass $backend;
⚠ 注意：if 在 location 中慎用；更稳方案是用 map 指令预定义变量 -
永久重定向所有 v1 请求到新版文档（引导升级）
location /api/v1/ {
return 301 https://docs.example.com/api/v2;
} -
保留 v1 接口但加版本头透传（兼容老客户端，后端做兼容逻辑）
location /api/v1/ {
proxy_set_header X-Api-Compatibility "v1";
proxy_pass http://legacy-backend;
}
三、关键注意事项
-
避免循环重写：检查 rewrite 规则是否可能反复触发（例如
rewrite ^/api/(.*)$ /api/v2/$1 last;若没限定 v1 前缀，会把 v2 也再匹配） -
优先用
map替代if：对版本判断类逻辑，map $http_x_api_version $upstream更高效、更安全 -
query string 自动保留：rewrite 默认携带原始参数（
$args），无需额外拼接；若需修改参数，用set+rewrite ...?new=1&$args -
测试必须覆盖边界：如
/api/v1/、/api/v1/users/、/api/v1/users?id=1、带编码字符的路径等
四、推荐进阶做法
生产环境建议组合使用：
- 用
map定义版本路由策略（清晰、可维护） - 用
rewrite ... last做路径标准化（如统一补尾部斜杠、剥离多余前缀） - 用
return 410或return 301明确废弃接口（比 404 更友好） - 配合 access_log 记录 v1 请求量，作为下线依据
