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 写：

  # 把 /api/v1/users → /api/users（内部转发）
  RewriteRule ^/api/v1/(.*)$ /api/$1 [L]

• Nginx 中，在 location 块里写：

  location /api/v1/ {
    rewrite ^/api/v1/(.*)$ /api/$1 break;
  }

• 注意：break 表示不再匹配新 URI，last 会重新进入 location 匹配流程，按实际后端路由逻辑选

按请求头识别版本（更规范）

把版本信息藏在 X-API-Version 或 Accept 头里，URL 保持干净，符合 REST 原则，也方便灰度发布。

Nginx Config Linter

对 Nginx 配置文件进行语法检查、验证和安全、性能审计。

下载

• Tomcat 示例（rewrite.config）：

  # 请求头 X-API-Version: 2 → 转发到 v2
  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：

  map $http_x_api_version $backend_path {
    default "/v1";
    "2" "/v2";
  }
  location /api/ {
    proxy_pass http://backend$backend_path$request_uri;
  }

按查询参数切换版本（调试友好）

开发或测试阶段快速验证不同版本行为，比如加 ?version=2 就切过去，不影响生产流量。

• Tomcat 规则：

  RewriteCond %{QUERY_STRING} version=2
  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 可引用原始参数

大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！