DevPeek
全部文章

接口调试新姿势

API 已迁新服务，前端还没发版？用「转发规则」联调

2026年7月26日

微服务拆分做到一半，是很多团队都会遇到的联调场景。

后端已经把订单服务迁到了 b.api.example.com，但线上 H5 还在请求 a.api.example.com。结果就是：用户接口正常、订单统计正常，唯独订单列表返回 501。

这种时候，问题并不是接口坏了，而是前端和后端还没有完成同一次发版。

等后端迁移完成、等前端发版，再重新联调——往往要排期。接口联调窗口里更现实的做法是：让浏览器继续请求旧 API，由 DevPeek 在代理层配置「转发规则」，把指定 path 指到新域名；若新服务暂时连不上，还可以用 Mock 先短路响应，把页面 UI 跑通。

本文用 devpeek.demo 里的 mock-map-route-demo 案例，演示一次完整的服务迁移联调：「转发规则」与 Mock 两条路怎么走，以及规则里 path 前缀、port 匹配与端口继承怎么写。

适用读者

前置：代理、证书与系统代理

本文 Demo 跑在本机浏览器，流量须先经过 DevPeek 代理，「转发规则」才会生效。

  1. 安装 DevPeek 并确认代理端口（默认见标题栏 / 设置）。
  2. 设为系统代理：菜单 代理 → 设为系统代理（本机浏览器抓包时用；抓手机则改 Wi‑Fi 代理，见 快速上手）。

设为系统代理

本机联调时在 DevPeek 菜单开启系统代理即可。

  1. 安装并信任根证书：DevPeek → 证书管理，按提示安装到「受信任的根证书颁发机构」。否则 HTTPS 只能看到 CONNECT 隧道，看不到明文请求与响应。完整步骤见 零基础上手 与 代理与 SSL 证书。
  2. （可选） 若抓 HTTPS 业务域名，把对应 Host 加入 SSL 解密范围（本 Demo 为 http://*.demo.test:3002，纯 HTTP，可跳过）。

完成标准： 打开任意网页，DevPeek 抓包列表里能看到对应 HTTP(S) 记录。

案例场景：三个域名，一套服务

Demo 在本地 :3002 起了一个 Express，用 Host 头区分「旧 API」「新 API」和「页面」——模拟典型的 API 域名迁移 中间态：

域名 角色
page.demo.test 打开 H5 页面
a.api.demo.test 前端硬编码的 API（旧）
b.api.demo.test 订单接口所在（新）

接口行为（简化）：

接口 a.api b.api
GET /api/user/profile ✅ 200 ✅ 200
GET /api/orders/stats ✅ 200 ✅ 200
GET /api/orders/list ❌ 501 ✅ 200

前端 script.js 里三个请求都写死为 http://a.api.demo.test:3002/...。未配「转发规则」时，页面底部订单区会显示 501 和提示文案——这就是服务拆分进行中的常态。

步骤一：跑起 Demo

git clone https://github.com/GYPengDev/devpeek.demo.git
cd devpeek.demo
pnpm install
pnpm --filter @devpeek/mock-map-route-demo dev

hosts（三域名都指本机）：

127.0.0.1  page.demo.test a.api.demo.test b.api.demo.test

浏览器打开 http://page.demo.test:3002/，点 🔄 重新检测。

此时不要开启任何「转发规则」——先确认基线：订单接口在旧域名上确实 501。

完成标准： 用户信息、订单统计加载成功；订单列表显示 a.api — 501 未实现；进度条停在步骤 1。

在 DevPeek 抓包列表里，此时 a.api.demo.test 的 /api/orders/list 仍返回 501：

未配置转发时的抓包列表

列表里 Host 仍是 a.api；订单接口 501。

未转发时的 501 响应体

响应体提示 a.api 未实现，需通过「转发规则」转到 b.api。

步骤二：「转发规则」— 只转发订单相关 path

入口：规则 → 「转发规则」（或抓包页左侧 转发 面板）。

「转发规则」入口

添加一行（制表符或空格分隔）：

a.api.demo.test:3002/api/orders    b.api.demo.test/api/orders

这条规则表示：

  • 匹配侧写了 :3002，只匹配 Host 为 a.api.demo.test:3002 的请求；不写 port 则匹配任意端口。
  • 目标侧没写 port，继承请求端口（这里是 3002），不必两边都写死 :3002。
  • 只匹配 /api/orders 及其子 path（如 /api/orders/list）；/api/user/profile 仍走 a.api。

「转发规则」中的端口继承

匹配侧写了 :3002，目标侧只写 host——上游端口继承自请求。

保存后，path 级规则在窗口里应类似：

path 级「转发规则」示例

只转发 /api/orders 及其子 path；/api/user/profile 仍走 a.api。

若整站 API 都已迁到新域名，可以用 host 级规则，a 下所有子路由原样转到 b：

a.api.demo.test:3002    b.api.demo.test

（目标侧同样可省略 port，继承请求端口。）

确认 系统代理已开启（上文），回到页面点 重新检测。

完成标准： 订单列表出现表格数据；页面状态显示转发已生效；终端日志类似：

→ [GET] Host: b.api.demo.test:3002  /api/orders/list

抓包详情 概览 里会出现 转发 URL，表示实际上游已打到 b.api，列表里仍保留浏览器原始 URL，便于对照契约。详见 「转发规则」文档。

转发生效后的抓包列表

同一条请求：列表仍显示 a.api，详情里可看实际上游。

请求详情中的转发 URL

概览中的「转发 URL」指向 b.api.demo.test:3002。

步骤三（可选）：Mock — 新服务还没起来时

若 b.api 暂时不可达，但你想先验订单列表 UI，可以对 GET .../api/orders/list 建一条 自动 Mock，直接返回 JSON（页面底部「Mock 备选方案」有示例数据）。

「转发规则」和 Mock 的区别

很多人第一次做微服务联调都会纠结：该用「转发规则」，还是直接 Mock？

「转发规则」 Mock
是否访问真实上游 ✅ 是 ❌ 否（短路）
典型用途 新服务已就绪，做 API 转发 服务迁移未完成，先验页面
匹配依据 host + path + port Mock 规则（URL、Method 等）

「转发规则」在代理层把请求真连到新服务，适合新域名已部署、只是前端还没发版。Mock 则短路上游，适合接口联调时新服务尚未就绪、只想先看 UI。

两者可组合：先配「转发规则」指到测试机，再对某 path Mock 错误码。配置入口见 Mock 规则。

「转发规则」语法

一条规则由 匹配地址（Pattern） 和 目标地址（Target） 两部分组成，写法为：

Pattern → Target

地址格式：

[http(s)://]host[:port][/pathPrefix]
维度 匹配侧（Pattern） 目标侧（Target）
port 写了则必须等于请求端口；不写则任意端口 写了则固定；不写则继承请求 Host 端口
path 写了则只匹配该前缀及子 path；不写则整站 host 可与 Pattern 不同，用于 path 重写
scheme 写了 http:// / https:// 则须一致 指本地 HTTP 时建议写 http://

优先级： 最长 path 前缀优先；同 path 时，带 port 的规则更具体。

path 重写示例（进阶）：若请求 path 与上游 path 结构不一致，可写：

a.example.com/route1/route2    b.example.com/route1

请求 /route1/route2/orders/list → 上游 /route1/orders/list（去掉匹配前缀，余下部分拼到目标前缀后）。

CONNECT 隧道仅应用无 path 的主机级规则；HTTP(S) 请求才走 path 级匹配。

和抓包、页面调试在同一条链

「转发规则」只修改代理层的目标地址，不会修改浏览器发起的请求 URL。抓包列表里仍显示客户端原始 Host 与 path。因此：

  • Mock 仍按抓包列表里的 URL 匹配；
  • 移动端网页调试 里点按钮触发的请求，同样经过转发；
  • 与 参数转换 组合：先转发到测试环境，再解密参数、改 Mock。

典型接口联调顺序：「转发规则」（指到正确服务）→ 参数转换（看明文）→ Mock（模拟异常）。

容易卡住的地方

订单仍 501

  • 「转发规则」是否保存且未注释（行首 #）？
  • 系统代理是否已开启？
  • path 是否写对：订单是 /api/orders/list，规则前缀至少要到 /api/orders。
  • 本地 dev 端口：匹配侧建议写 :3002，或确认请求 Host 与规则一致。

用户/统计也挂了

  • 若用了 host 级整站转发，确认 b.api 上 profile/stats 也可用；否则改用 path 级，只转发 /api/orders。
  • 检查 hosts 是否包含 a.api.demo.test。

概览没有「转发 URL」

  • 该请求未命中任何「转发规则」，或目标 host:port 与原始完全相同（视为未转发）。见 常见问题。

下一篇

《待整理：代理链上的断点、重发与协作》——继续补充联调技巧。

如果你也遇到过「后端已经迁服务、前端却还没发版」的联调问题，不妨 下载 DevPeek，按照本文的 Demo 跑一遍。从「转发规则」到 Mock 验页面，全程无需改一行前端代码。案例源码见 devpeek.demo / mock-map-route-demo，也欢迎到 GitHub Discussions 聊聊你的 API 域名迁移 方案。

相关文档

系列文章