重写规则与脚本

通过重写规则，您可以在本地对接口进行 Mock、重定向、延迟与报文修改。当规则无法覆盖动态计算场景时，可使用 JavaScript 脚本进行可编程拦截。

脚本编写细节请参阅脚本功能使用指南。

1. 作用域配置 (Scope)

作用域用于指定规则或脚本的作用范围，由 Host + Path 组成。Host 必填，Path 可选。

Host：将规则或脚本作用到整个 Host 的所有请求。支持模糊匹配：只填主域名（例如 example.com）时，所有子域名请求都会匹配。您可以从下拉列表中快速选择已抓取过的目标 Host，或者手动输入。
Path（可选）：填写后，规则/脚本只作用到指定 API。Path 只支持前缀匹配（请不要写 * 通配符）。例如填写 /api/v1 即可匹配 /api/v1/users、/api/v1/orders 等。选定 Host 后，您可以从列表中直接选择具体的 API（会自动带入 Method 和 Path），或者手动输入路径。

💡 效率提示：如果您从列表选择了已有 API，系统会自动带入 Method 与 Path；添加重写规则时还会预填充 Mock 响应模板或 Headers，大幅节省配置时间。

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

在前后端并行开发时，后端接口往往尚未就绪，或者需要测试某些异常状态码。通过重写规则，您可以优雅地进行接口 Mock 与边界测试。规则的生效范围请参阅 1. 作用域配置。

2.1 调试动作 (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*），可能导致匹配失败。建议使用内置的“测试”面板验证表达式。

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

针对需要动态计算的复杂 Mock 场景（如时间戳签名计算、动态数据拼装），脚本引擎提供了最高级别的可编程调试能力。脚本同样通过作用域决定对哪些请求生效，配置方式见 1. 作用域配置。

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

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

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

3.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' };
}

3.3 内置高级 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，则不会再进入该请求的后续脚本执行流程。