重寫規則與指令碼

透過重寫規則，您可以在本地對介面進行 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，則不會再進入該請求的後續指令碼執行流程。