rewrite 管理 API 版本的核心是将路径、请求头或查询参数中的版本信息映射到后端实际服务路径，实现零代码修改、无感知兼容与平滑升级；常用方式包括按路径前缀重写（如 /api/v1/ → /api/）、按请求头（如 X-API-Version）识别版本、按查询参数（如 ?version=2）切换版本，并需注意正则精确匹配、规则顺序及参数传递等关键细节。
用 rewrite 管理 API 版本，核心是把请求路径、请求头或查询参数中携带的版本信息，映射到后端实际的服务路径上，不改代码、不暴露变更、不中断调用。
按路径前缀重写（最常用）
适合统一规划 URL 结构的团队。比如所有 v1 接口走 /api/v1/xxx，v2 改为 /api/v2/xxx，但旧客户端仍调用 /api/v1/，需要兼容；或者想把 /api/v1/ 全部导向新服务的根路径。
- Tomcat 中，在
rewrite.config写：
RewriteRule ^/api/v1/(.*)$ /api/$1 [L]
- Nginx 中，在
location块里写：
rewrite ^/api/v1/(.*)$ /api/$1 break;
}
- 注意：
break表示不再匹配新 URI，last会重新进入 location 匹配流程，按实际后端路由逻辑选
按请求头识别版本（更规范）
把版本信息藏在 X-API-Version 或 Accept 头里，URL 保持干净，符合 REST 原则，也方便灰度发布。
- Tomcat 示例（
rewrite.config）：
RewriteCond %{HTTP:X-API-Version} ^2$
RewriteRule ^/api/users$ /api/v2/users [L]
# 其他情况默认走 v1
RewriteRule ^/api/users$ /api/v1/users [L]
- Nginx 中可用
map预定义变量，再配合rewrite或直接proxy_pass：
default "/v1";
"2" "/v2";
}
location /api/ {
proxy_pass http://backend$backend_path$request_uri;
}
按查询参数切换版本（调试友好）
开发或测试阶段快速验证不同版本行为，比如加 ?version=2 就切过去，不影响生产流量。
- Tomcat 规则：
RewriteRule ^/api/orders$ /api/v2/orders?%1 [L,R=307]
# 注意：R=307 保留原请求方法和 body，比 302 更稳妥
- Nginx 中建议用
if + rewrite，但要避免在location外使用if；更推荐用map提前提取参数值，再做路径拼接
避免常见陷阱
rewrite 不是万能胶，用错反而引入问题。
-
别对静态资源用 redirect：301/302 会让浏览器缓存重定向结果，导致新版 JS/CSS 加载失败；内部重写（
last或break）才是正解 -
正则末尾加
$防误匹配：比如^/api/v1/会误中/api/v10/，应写成^/api/v1/(.*)$ -
顺序很重要：规则从上到下执行，[L] 后停止；把更具体的规则放前面，泛匹配（如
^/api/.*$）放最后 -
注意 query string 传递：默认 rewrite 不带参数，需显式用
?或?%1拼接；Nginx 中$args可引用原始参数
