API Proxy Tool 功能使用指南
更新时间：2026-07-14；使用模型：Codex（GPT-5）；用户：Jsmond2016
API Proxy Tool 用于管理浏览器中的 API Mock 规则。扩展通过 Manifest V3 declarativeNetRequest 将匹配的页面请求重定向到 Mock 地址，并提供 Apifox 同步、迭代文档、存档恢复和权限点复制等配套能力。
界面入口
浏览器弹窗
点击扩展图标后，弹窗显示当前模块数、已开启接口数和全局 Mock 状态。
- 使用“全局 Mock 开关”快速启用或停用全部代理规则。
- 点击“打开配置页”进入完整配置页面。
- 从弹窗打开配置页时，页面会保留来源标签页信息，可使用左上角返回按钮回到原页面。
配置页面
配置页从上到下分为：全局操作栏、模块标签页、迭代信息栏、接口操作栏和接口表格。
| 区域 | 主要功能 |
|---|---|
| 全局操作栏 | 全局开关、Apifox 配置、存档、迭代信息、全局权限点、全部重置 |
| 模块标签页 | “全部接口”聚合视图、模块切换、新建、重命名和删除 |
| 迭代信息栏 | 展示 tag 及关联文档，复制迭代信息或 CR 信息 |
| 接口操作栏 | 添加接口、复制模块权限点、批量删除、重置当前模块 |
| 接口表格 | 搜索、排序、开关、测试、编辑、复制、迁移和删除 |
第一次配置 Mock
1. 创建或选择模块
首次运行会创建默认模块。点击模块标签栏的 + 可直接新建模块；新模块创建后自动切换为当前模块。
- 点击模块名称右侧的编辑图标可修改名称。
- 模块名称用于区分业务分组；需要复制权限点时，名称必须是
a.b.c形式的英文分组名。 - 至少保留一个业务模块，最后一个模块不能删除。
- “全部接口”是聚合视图，不是可删除的业务模块。
2. 添加接口
在当前模块点击“添加”，填写接口信息：
| 字段 | 必填 | 说明 |
|---|---|---|
| 接口地址 | 是 | 页面原始请求地址，支持相对路径和完整 URL |
| 接口名称 | 是 | 表格中的显示名称 |
| 重定向 URL | 是 | 实际请求的 Mock 地址 |
| 权限点 | 否 | 用于生成 CMS 权限数据的 authPointKey |
| 页面路由 | 否 | 关联页面地址，可从表格直接跳转 |
| 请求方式 | 是 | GET、POST、PUT、DELETE 或 PATCH |
| 匹配方式 | 是 | 包含、精确匹配或正则表达式 |
已配置 Apifox 时，输入接口地址并离开输入框，扩展会优先按规范化后的精确路径匹配 Swagger 数据，自动补充名称、请求方式、Mock 地址、Apifox 链接、权限点和标签。
匹配方式
- “包含”适合稳定且唯一的路径片段。
- “精确匹配”适合明确的完整 URL。
- “正则表达式”适合路径参数或多种地址模式，使用前应先缩小匹配范围。
3. 开启代理
接口只有同时满足以下条件才会生效：
- 接口行的 Mock 开关已开启。
- 页面顶部或 Popup 中的全局 Mock 开关已开启。
修改开关后扩展会保存配置、重建声明式规则，并同步更新扩展图标状态。
模块与接口管理
全部接口视图
“全部接口”集中展示所有模块中的接口，适合全局搜索、状态排序、添加接口和跨模块批量删除。切换到具体模块后，可使用模块权限点复制和模块重置。
搜索与定位
页面顶部的全局搜索支持接口名称、原始 URL、Mock 地址和模块名称。选择结果后会切换到对应模块、滚动到目标接口并高亮显示。
“全部接口”视图还提供列表内搜索，可按接口名称、原始 URL 和 Mock 地址过滤当前表格。点击开关列表头的排序图标可按启用状态排序。
单条操作
| 操作 | 行为 |
|---|---|
| 测试 | 请求 Mock 地址并展示响应状态和响应体 |
| 编辑 | 修改当前接口配置 |
| 复制 | 在当前模块新增一条名称带“副本”的接口 |
| 迁移 | 将接口移动到另一个模块 |
| 删除 | 删除当前接口 |
| 复制地址 | 复制接口地址或 Mock 地址 |
| 跳转 | 已配置 Apifox 链接或页面路由时打开对应页面 |
单接口调试
- 点击请求方式标签三次，可关闭其他接口，只保留当前接口的 Mock 开关。
- 点击测试按钮时，如果全局开关关闭，可选择“仅调试单个接口”或“开启全局开关”。
- 当前接口开关关闭或没有 Mock 地址时，测试会提示先完成配置。
批量删除与重置
- 勾选多条接口后点击“批量删除”；在“全部接口”视图中可跨模块删除。
- “重置模块”只清空当前模块接口，不影响其他模块。
- “一键重置”重置全部 Mock 配置，属于不可逆操作，执行前应确认不再需要当前数据。
Apifox 同步
前置准备
当前界面使用 Apifox 在线导出能力，需要准备：
- Apifox 项目数字 ID。
- 个人访问令牌 Access Token，用于导出 OpenAPI 数据。
- 云端 Mock 令牌，用于访问生成的 Mock 地址。
- 用于筛选接口的一个或多个 tag。
凭据安全
令牌只应填写在扩展配置界面，不要写入 README、截图、Issue、提交记录或团队公共文档。
首次同步
- 点击顶部“设置 Apifox 配置”。
- 填写项目编号、授权令牌和 Mock 令牌。
- 验证通过后选择需要同步的 tag。
- 检查自动生成的 Mock 地址前缀和接口数量摘要。
- 如果 tag 与已有模块冲突，选择合并或覆盖策略。
- 点击“确定同步”。
扩展会按 Apifox tag 转换模块和接口。首次配置只允许在当前仅有默认示例模块时继续；已有其他 Mock 数据时，界面会提示先备份并重置，再执行首次同步。
刷新接口
已有 Apifox 配置后，再次点击“设置 Apifox 配置”可选择：
- “刷新接口”：配置不变，只拉取最新接口并展示变化摘要。
- “修改配置”：更改项目、令牌、Mock 前缀或 tag。
刷新只替换由 Apifox 同步维护的接口。手工添加接口和外部 Quick Mock 模块会保留；历史配置在刷新时兼容迁移。
标签历史与缓存
- 最近使用的 tag 组合会出现在快捷选择区，可复用或删除。
- Swagger 原始数据在当前运行周期内复用，减少添加表单和同步操作的重复请求。
- 解析后的接口映射会写入 IndexedDB，默认有效期 24 小时，供跨扩展 Quick Mock 使用。
迭代信息
完成 Apifox tag 同步后，点击“设置迭代信息”，可为 tag 维护：
- 需求文档
- 技术文档
- 原型文档
- 测试用例
- 排期文档
模块信息栏会展示当前接口涉及的 tag 和文档入口。可直接复制迭代信息，也可选择上线时间后复制 CR 信息。
存档与恢复
创建存档
- 先完成 Apifox 配置并选择迭代 tag。
- 点击“存档”，选择用于标识本次快照的 tag。
- 核对模块数、接口数和迭代文档预览。
- 确认保存。
存档保存在浏览器 IndexedDB，内容是当前面板完整快照，包括全部模块、接口、快速联调配置、Apifox 配置和对应迭代文档。tag 用于标识迭代，不限制保存范围。
查看和恢复
在“存档”下拉菜单中选择“查看存档”，可查看详情、复制文档、恢复或删除记录。恢复会覆盖当前模块、接口、Apifox 和快速联调配置，但保留当前全局 Mock 开关状态。
恢复前确认
恢复存档会覆盖当前面板配置。需要保留当前状态时，请先创建新的存档。
权限点复制
当前模块
进入具体模块，点击“复制权限点”：
- 默认复制当前模块全部接口。
- 勾选接口后，可从下拉菜单选择“复制勾选权限点”。
全部模块
点击顶部“复制全局权限点”可汇总所有模块接口。复制前会校验每个模块名称是否符合 a.b.c 英文格式；弹窗中还需填写 CMS 父级菜单名称。
跨扩展批量 Quick Mock
其他扩展可通过 chrome.runtime.sendMessage 发送 BATCH_QUICK_MOCK 请求。API Proxy Tool 会对 URL 去重，优先复用本地接口，再使用 Apifox 缓存或在线数据补全，并创建 quick.mock.external 模块。
处理完成后配置页会自动打开并展示结果摘要。外部模块标记为 external，不会被后续 Apifox tag 刷新覆盖。
外部扩展范围
当前 manifest.json 的 externally_connectable.ids 和后台校验均允许任意扩展 ID。正式分发到受控环境前，应由维护者将允许范围收敛为明确的扩展 ID 白名单。
接入协议、响应结构和联调步骤见跨插件批量 Quick Mock 联调。
常见问题
页面请求没有被代理
依次检查接口开关、全局开关、请求方式、匹配方式、原始地址和 Mock 地址。正则规则还需要确认表达式能匹配浏览器实际请求 URL。
Apifox 无法加载
确认项目编号为数字 ID，Access Token 有导出权限，Mock 令牌有效，并检查浏览器网络是否能访问 Apifox 在线接口。
同步后看不到接口
先清除“全部接口”视图中的列表搜索，再确认所选 tag 下确实存在接口。同步界面中的接口数量摘要可用于判断 tag 过滤结果。
权限点无法复制
将模块名称修改为 a.b.c 格式，并确认接口已填写权限点字段。复制弹窗还需要输入 CMS 父级菜单名称。
存档恢复后当前配置消失
这是恢复操作的预期行为：存档会覆盖当前面板数据。恢复前应先为当前状态创建快照。
数据与安全
- 配置保存在浏览器本地存储，存档和 Parsed API 缓存保存在 IndexedDB。
- 扩展需要访问 HTTP/HTTPS 页面并使用声明式网络规则才能完成请求重定向。
- 不要在生产 Mock 数据、公开文档或提交记录中放置真实令牌、Cookie、用户数据或其他敏感信息。
- 隐私说明见隐私声明。