ApiCatcher 使用手册

ApiCatcher 是一款为开发者、测试工程师以及网络排障人员打造的专业级 iOS 网络调试工具。它通过在本地建立虚拟网关，帮助您便捷地捕获、查看、分析并调试您自己开发的应用的 HTTP/HTTPS 以及 WebSocket 流量。

本手册将详细介绍如何配置和使用各个功能模块，以助力您的日常开发调试、Mock 测试、接口自动化分析及性能排障工作。

目录

1. 基础准备：证书配置与调试授权
2. 流量过滤：精准定位调试目标
3. 接口模拟与修改：重写规则 (Rewrite)
4. 高级自定义处理：JavaScript 脚本 (Script)
5. 自动化测试：组合重放 (Combo Replay)
6. 后台监控：定时任务 (Scheduled Tasks)
7. 质量与性能排查：API 扫描 (API Scan)
8. 实用工具：加解密与桌面端同步

1. 基础准备：证书配置与调试授权

1.1 安装并信任 CA 证书（调试 HTTPS 必备）

现代应用的数据交互普遍基于 HTTPS 协议加密。在开发和调试自有应用时，为了能够正常查看 API 的明文请求与响应数据，您需要配置并信任调试证书以允许解密。

ApiCatcher 提供了两种证书配置方式：

1. 使用系统默认生成的 CA 证书（推荐绝大多数场景）：跟随下方的引导，安装由 ApiCatcher 自动为您生成的专属 CA 证书。
2. 导入您自己的证书（企业证书）：如果您需要使用企业自签发证书，可直接跳过此部分，阅读 1.2 企业证书导入 章节。

使用系统默认 CA 证书的操作步骤：

1. 在 App 内点击“安装证书”，系统会跳转浏览器下载配置描述文件。
2. 进入系统 「设置」 -> 「通用」 -> 「VPN与设备管理」，安装刚下载的 ApiCatcher 描述文件。
3. 关键步骤：进入 「设置」 -> 「通用」 -> 「关于本机」 -> 「证书信任设置」，找到 ApiCatcher CA 开头的证书，打开开关启用完全信任。

💡 常见排障指南：

• 调试时抓到“连接超时”或者状态码异常：通常是因为第3步没有“完全信任”证书。
• 删除了 App 重新安装：旧的调试证书已经失效，必须去系统设置中删除旧的描述文件，重新走一遍上述流程。

1.2 企业证书导入（企业内网调试场景）

在企业内部开发测试时，部分内部应用可能会配置特定的证书信任策略（仅信任企业内部 CA）。

• 用途：导入企业提供的 .pem 或 .p12 证书，并与内部测试域名（如 *.corp.internal）绑定，用于在本地调试时完成合法的 TLS 握手。
• 注意：必须在停止抓包的状态下导入或修改配置，完成后重新启动方可生效。

1.3 使用自签证书

对于个人开发者，如果没有企业证书，也不想使用 ApiCatcher 提供的证书，您可以借助 ApiCatcher 的企业证书功能导入自己的证书。 详情请参考文档：使用自签证书

2. 流量过滤：精准定位调试目标

在开发过程中，为了排除系统底层及其他后台 App 的流量干扰，建议配置过滤规则，使视线聚焦于当前正在调试的项目。

• 黑名单：出现在黑名单中的域名不会被记录。如果白名单为空，默认记录除黑名单外的所有请求。
• 白名单：只要白名单中包含规则，系统就仅记录白名单匹配的请求，其余流量均不进入调试通道。
• 配置技巧：支持 * 通配符。例如填写 *.example-api.com 可以匹配该主域名下的所有测试环境子域名。

💡 常见排障指南：

• 无法看到目标应用的请求：请检查是否启用了白名单但漏填了目标域名，或者目标域名误加入了黑名单。
• 语法注意：请使用基础星号匹配（如 *.api.com），无需编写复杂的正则表达式。

3. 接口模拟与修改：重写规则 (Rewrite)

在前后端并行开发时，后端接口往往尚未就绪，或者需要测试某些异常状态码。通过重写规则，您可以优雅地进行接口 Mock 与边界测试。

3.1 作用域配置 (Scope)

在添加重写规则时，您需要指定该规则生效的范围，以避免误伤其他无关请求。系统提供了极其简便的配置方式，您无需编写复杂的匹配条件：

• 选择域名/主机 (Host)：您可以从下拉列表中快速选择已抓取过的目标 Host，或者手动输入。支持通配符（例如 *.example.com）。
• 选择 API (Path)：在选定了 Host 后，您可以从列表中直接选择具体的 API（会自动带入 Method 和 Path），或者手动输入特定路径（支持 * 通配符匹配路径，如 /api/v1/*）。

💡 效率提示：如果您从列表选择了已有 API，系统会自动为您预填充（Prefill）后续的 Mock 响应模板或 Headers，大幅节省您的配置时间！

3.2 调试动作 (Rewrite Action)

• 重定向 (Redirect)：将请求路由至其他地址（例如将生产环境流量重定向至 Localhost 或预发环境）。
• Mock 响应：不发起实际网络请求，直接返回您预设的测试数据（JSON/XML）。支持配置状态码（如模拟 404, 500 等异常）、响应头和响应体。
• 丢弃 (Drop)：
  • 丢弃请求：模拟请求无法发出（如断网场景）。
  • 丢弃响应：模拟服务器无响应超时。
• 延迟 (Delay)：人工注入网络延迟，用于测试 App 在弱网环境下的 Loading 交互表现。
• 修改请求/响应 (Modify)：
  • 编辑 Header：用于在请求头中注入测试 Token，或修改 User-Agent。
  • 替换 Body：完整替换请求体或响应体内容。
  • 正则查找并替换 Body：对 JSON 进行精细化字段替换。例如，使用正则将 "status": "pending" 替换为 "status": "success" 以测试后续逻辑。

💡 常见排障指南：

• 规则未生效：存在其他优先级更高（最近添加）的规则覆盖了当前规则。
• 正则替换失败：JSON 数据经常包含缩进和空格，若正则未考虑空白字符（如使用 \s*），可能导致匹配失败。建议使用内置的“测试”面板验证表达式。

4. 高级自定义处理：JavaScript 脚本 (Script)

针对需要动态计算的复杂 Mock 场景（如时间戳签名计算、动态数据拼装），脚本引擎提供了最高级别的可编程调试能力。

4.1 核心功能面板与辅助工具

除了手动编写，ApiCatcher 提供了强大的周边工具辅助您完成脚本创作与验证：

• AI 自动生成脚本：无需手写一行代码。您只需输入自然语言指令（例如：“帮我把响应体里 price 字段的值改为 9.9，并加上 discount_tag: true”），内置的 AI 助手即可直接帮您生成并填入标准的 JS 代码。
• 本地测试环境 (Test Script)：在正式保存生效前，可以直接点击测试。您可以自行从历史记录中选择一条实际抓取过的请求给脚本，系统会直观展示修改前后的数据比对结果和报错日志，确保您的语法无误。
• 远程脚本托管 (Remote Script)：支持直接填写一个公网的 http:// 或 https:// 脚本 URL。ApiCatcher 会在本地加载执行该云端脚本，这对于在团队内部统一下发并维护公共 Mock 规则非常有帮助！

4.2 脚本核心函数

如何编写脚本请阅读文档：APICatcher 脚本功能使用指南

您只需实现预定义的生命周期函数：

// 处理发出的请求
function interceptRequest(request) {
    // request.method, request.url, request.headers, request.body, request.queryParams
    if (request.path === '/api/v1/test') {
        request.headers['X-Debug-Token'] = 'test_token';
    }
    // 返回动作：passthrough(放行), modify(修改), mock(模拟数据), drop(丢弃)
    return { action: 'modify', request: request };
}

// 处理收到的响应
function interceptResponse(request, response) {
    // response.statusCode, response.headers, response.body
    if (response.body) {
        var data = safeJsonParse(response.body); // 内置安全解析函数
        if (data) {
            data.mock_field = true;
            response.body = JSON.stringify(data);
            return { action: 'modify', response: response };
        }
    }
    return { action: 'passthrough' };
}

4.2 内置高级 API

• localStore：用于跨请求的状态维护。例如在登录接口保存授权态，在后续接口自动注入。
  • localStore.write('session_id', 'abc')
  • var t = localStore.read('session_id')
• httpClient：支持在脚本执行期间发出额外的网络请求（用于同步外部状态或获取动态配置）。
  • var res = httpClient.get('https://api.ipify.org')

💡 常见排障指南：

• 语法或运行时错误：使用内置的“测试脚本”按钮验证逻辑。可以使用 console.log("...") 并在“日志(Logs)”页面查看输出。
• 生命周期冲突：若某请求已被优先级更高的“重写规则”执行了 Mock 或 Drop，则不会再进入该请求的后续脚本执行流程。

5. 自动化测试：组合重放 (Combo Replay)

单接口测试无法满足完整的业务流验证（如：登录 -> 获取授权 -> 查询信息 -> 提交表单）。组合重放支持对多个关联接口进行可视化编排与自动化回归。

5.1 配置步骤

1. 添加节点：将历史记录中的业务流请求依次添加到画布中。
2. 建立依赖：建立节点间的有向边，确保请求严格按照依赖顺序依次执行。
3. 参数映射（依赖注入）：配置数据流向。将上游接口响应中的特定字段，动态注入至下游请求中。

5.2 参数映射配置详解

• 提取来源：可从上游的 响应体(responseBody) 或 响应头(responseHeader) 中提取。
  • 提取路径：若为 JSON 响应体，直接使用 JSON Path（例如 data.session.token）。
• 注入目标：可注入下游的 请求头(requestHeader)、URL参数(queryParam) 或是 请求体(requestBody)。
• 可选前缀 (Optional Prefix)：用于特定规范的自动补全。如提取的值是 abc，但规范要求在头部带 Bearer abc，只需在此项填入 Bearer 即可自动拼接。

💡 常见排障指南：

• 参数未成功提取：使用画布中节点自带的“样本响应体”树状结构进行点击选择，避免手写路径造成的格式层级错误。

6. 后台执行：定时任务 (Scheduled Tasks)

借助基于 VPN 进程的后台常驻能力，您可以使用“定时任务”定期执行特定的请求或组合重放规则。 典型应用场景：在开发或测试电商“秒杀抢购”活动时，由于秒杀时间窗口极其短暂，人工拼手速点击测试往往会错过抢购瞬间。此时，您可以配置一个定时任务，在秒杀开始前让接口高频自动请求提交订单，帮助您充分验证秒杀链路的并发稳定性和业务逻辑。

6.1 调度配置 (Schedule Type)

• Cron 表达式：采用标准的 5 位 Cron 语法（如 */5 * * * * 表示每5分钟执行）。您可利用内置 AI 辅助生成。
• 自定义配置：支持精细设定起始时间、间隔时长及最大执行次数。

6.2 自动终止条件 (Auto Terminate)

设定终止条件避免异常情况下的无意义重试，或者在达成目标后自动退出：

• 匹配 JSON 字段：例如在“秒杀测试”场景中，监控返回结果的 code 字段。一旦 code 等于 200（表示抢购成功提交）或等于 400（表示库存已空活动结束），则触发终止。
• 正则表达式匹配：对响应体进行全文本匹配。只要匹配到类似 "msg": "抢购成功" 或 "error": "活动已结束" 的字符特征，任务便自动彻底停止。

💡 常见排障指南：

• 任务无法运行：iOS 系统存在严格的后台管控。当内存吃紧时，VPN 进程可能被系统回收，定时任务将一并暂停。
• 无历史记录显示：定时任务是由底层引擎直接发起的监控请求，不会被记录到主 App 的常规“历史记录”中。需在任务专属的“执行历史”面板中查看成功率、p95 等报表。
• 规则更新未生效：定时任务在创建时绑定的是规则快照。若更改了原“组合重放”规则，需重建定时任务。

7. 质量与性能排查：API 扫描 (API Scan)

基于本地捕获的流量记录，提供非侵入式的 API 质量、安全合规与性能体检。所有分析均在设备本地内存闭环完成。

7.1 内置扫描引擎

• 敏感信息自查：支持检测明文传输的手机号、身份证、邮箱及云服务凭据（如 AWS Key、OpenAI API Key），帮助前端及 API 设计者及早发现数据脱敏遗漏。
• 异常堆栈泄露：识别响应体中不慎返回的 Java、Python 或 SQL 报错调用栈。
• 高频调用分析：根据设定阈值（如平均请求间隔小于特定毫秒），排查是否存在由死循环或不当逻辑引发的冗余接口调用。
• 耗时评估：聚合计算各个接口的 p95、p99 延迟，协助定位后端性能瓶颈。

7.2 自定义质量检测 (Custom Scan)

您可以编写 JS 脚本执行业务定制的合规检查。

• 返回值规约：函数若认为该请求符合预期，返回 null；若检出不合规（如返回体过大、缺少安全头部），则返回精简描述（≤200字符），系统会自动纳入扫描报告。

💡 常见排障指南：

• 未分析出结果：确认“扫描范围 (Host/Session)”内是否确实包含有效的 JSON/API 流量记录，而非纯静态资源。为保障体验，单次扫描存在条数上限限制。

8. 实用工具：加解密与桌面端同步

8.1 开发者工具箱 (Decrypt/Encrypt)

应对报文加密传输的情况，内置了常用编解码工具：

• AES 解密：支持填入自定义密钥(Key)与初始向量(IV)快速解密测试 Payload。
• Base64 / URL Encode / MD5 / SHA256。
• 自定义处理：支持写入单次执行的 JS snippet 对选中文本进行数据转换。

8.2 桌面端实时推流 (Realtime Sync)

用途：若需在 PC 端以更大视野进行数据调试，可通过 WebSocket 协议将设备抓取的数据包无缝推送至 ApiCatcher Desktop 桌面端。 配置：

• 输入局域网内分配的 WebSocket 地址。
• 务必先行通过“测试连通性” 验证握手成功。
• 排障：确保移动端已获授“本地网络”权限，PC 防火墙已放通对应端口，并确保两者处于同一局域网网段内。