ApiCatcher
ApiCatcher
iOS HTTP(s)抓包與調試工具

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 防火牆已放通對應連接埠，並確保兩者處於同一區域網網段內。