JavaScript 重寫 API（v1）

需要帶有條件的 JSON 或文字轉換時，可使用 JavaScript 正文規則。本章介紹 MintFlow 2.0.0 的 $MF API，並以可匯入範例說明完整流程。若只轉換 JSON，jq 也是一種選擇。

正文重寫需要有效 MintFlow Pro 權限，包括符合資格且有效的試用。使用直接連線出口即可，不需要遠端 VPN 伺服器。請只檢查或修改你有權處理的流量。

1. 體驗官方 JavaScript 範例

官方範例分別提供 jq 與 JavaScript 套件。JavaScript 套件只比對 https://jsonplaceholder.typicode.com/posts/1（允許查詢參數），而非該服務的所有流量。

1. 開啟 HTTP → HTTP 重寫，點工具列匯入按鈕，再選從 URL…。使用 JavaScript 套件原始檔案，不要使用 GitHub 網頁位址。也可下載後透過**選取檔案…**匯入。
2. 匯入會將腳本儲存於本機，視需要將 jsonplaceholder.typicode.com 加入網域擷取，並建立停用的規則。檢查原始碼及比對式後再啟用。URL 匯入只取得一次，不是自動更新的訂閱。
3. 啟用 HTTP 處理，確認 TCP 連接埠 443 在範圍內。HTTPS 需要安裝並完全信任使用中設定檔的 CA，請見擷取設定指南。必要時，停用 HTTP/3可促使相容用戶端改用 TCP，但不會解密 QUIC。
4. 儲存設定檔並啟動或重新啟動 VPN，解決編譯錯誤或 Pro 限制。若要用即時擷取檢查結果，請先開始錄製。
5. 在 iPhone 或 iPad 開啟 https://jsonplaceholder.typicode.com/posts/1，重新載入以取得新回應，避免只檢視快取。比較下列欄位；實驗後停用示範規則並重新啟動 VPN。

套件使用 direction: "response"、bodyMode: "json"、apiVersion: 1 及 language: "javascript"。原始碼如下：

const body = $MF.resp.body;
body.title = "MintFlow JavaScript rewrote this JSON response";
body.mintflowDemo = {
  language: "JavaScript",
  method: $MF.req.method,
  working: true
};
$MF.done({ body });

JSON 模式已提供解析後的物件，不要再對正文呼叫 JSON.parse，也不要對替換值呼叫 JSON.stringify。預期回應包含：

{
  "title": "MintFlow JavaScript rewrote this JSON response",
  "mintflowDemo": {
    "language": "JavaScript",
    "method": "GET",
    "working": true
  }
}

以上僅呈現部分預期欄位；原有的 userId、id 與 body 保持不變。另一個 jq 範例使用 /todos/1，兩條規則不重疊。兩種匯入要求相同的擷取後綴，不會重複加入；均省略優先順序，因此新規則採用預設值 100。

範例已依套件格式與腳本契約檢查，不代表已成功完成真實通道測試；公共示範服務也可能變更。請在實體裝置驗證實際流量。

2. API 參考

每次呼叫由 MintFlow 提供一個凍結的 $MF 命名空間。

上下文欄位包括 url、direction（request 或 response）、method、contentType（字串或 null）、requestID（呼叫識別字串）、ruleName、status（回應狀態碼或 null）。識別值只用於診斷，請勿依賴其內部格式。

命名空間與要求/回應容器均凍結，但 JSON 模式的正文值本身可修改。修改該值或建立新值後，必須明確提交。對這些物件的 URL、狀態碼或標頭賦值，不是支援的重寫操作。v1 API 不提供標頭集合，也不提供另一方向的正文。

3. 完成與失敗行為

每條執行路徑都必須明確呼叫 $MF.done(...)、$MF.done() 或 $MF.fail(...)。只修改 JSON、傳回值或讓程式自然結束，都不會提交重寫。第一個完成訊號生效；請將完成呼叫放在對應分支末尾，不要在其後繼續修改物件。

修改實際資料前，請檢查回應狀態與結構。下列範例適用於 JSON 模式的回應規則：

const body = $MF.resp.body;
if ($MF.resp.status !== 200 || body === null ||
    typeof body !== "object" || Array.isArray(body)) {
  $MF.log.debug("Unexpected response shape; leaving body unchanged");
  $MF.done();
} else {
  body.title = "MintFlow JavaScript rewrote this JSON response";
  $MF.done({ body });
}

規則失敗、輸出無效或逾時，都不會套用該規則的替換值，而是保留目前正文繼續處理。先前成功的規則可能已變更正文。缺少完成呼叫或逾時，也可能讓同一規則鏈後續的 JavaScript 規則被略過。請勿將腳本失敗當成安全或廣告封鎖機制；需要拒絕時，應使用相應路由或 URL 拒絕規則。

4. JSON 模式與文字模式

• JSON：正文是解析後的 JSON 相容值，不一定是物件，也可能是陣列、純量或 null。提交的資料必須相容於 JSON；循環參照、undefined、BigInt、函式、符號與非有限數字都不是有效輸出。
• 文字：正文與替換值都必須是字串，可直接使用文字操作。若在文字模式編輯 JSON，需要自行解析及序列化；通常直接選擇 JSON 模式較簡單。

下列範例用於比對範圍受限、設定為 bodyMode: "text" 的要求規則，替換一處文字：

const text = $MF.req.body;
$MF.done({ body: text.replace("demo=off", "demo=on") });

方向與正文模式在規則中設定，不是在腳本中設定。設定檔文字使用 direction、type:javascript、body-mode、api-version；MFHRB 使用 bodyMode、apiVersion。設定檔語法中的 JavaScript 規則預設採用文字模式，因此 JSONPlaceholder 範例應明確選擇 JSON。

5. 沙盒與限制

這是受限的正文轉換環境，不是 Node.js，也不是通用瀏覽器腳本 API。請勿依賴 Node 模組、網頁 DOM、跨呼叫的持久狀態或其他代理伺服器 App 的 API。網路存取遭封鎖，fetch、XMLHttpRequest、WebSocket 等功能已停用。轉換所需資訊應來自原始碼與目前呼叫。

• MFHRB 中的 JavaScript 原始碼最多 128 KiB；完整套件最多 1 MiB。
• 規則逾時為 50–2000 ms，預設 500 ms。MFHRB 使用 timeoutMS，設定檔文字使用 timeout-ms。共用規則鏈的截止時間可能使實際剩餘時間更短。
• 替換正文最多 1 MiB；JSON 另有深度與節點數量限制。請讓轉換保持精簡且有明確邊界。
• 每次呼叫最多記錄 32 筆日誌、16 KiB 編碼後日誌內容。不要記錄認證資訊或完整私密正文；日誌用於診斷，不是擷取匯出。

不會自動提供獨立的 body、context、MF 變數，也沒有 $request、$response、$done 別名。自行宣告 const body = $MF.resp.body 是合法的。

6. 審查、測試與分享

在 HTTP 實驗室使用具代表性的正文，以及正確的 URL、方法、方向、狀態碼與正文模式測試。加入非預期結構的案例，確認無關資料不變。匯入驗證的是語法，不是對所有回應的正確性。

若規則看似無效，請檢查 Pro 權限、啟用狀態、HTTP 範圍、目前 CA 信任、實際 URL 與方向、正文模式、明確完成呼叫，以及儲存後是否重新啟動 VPN。查看重寫診斷中的失敗、大小及時間限制。

透過 MFHRB 套件分享一條審查過的規則及完整原始碼。修訂時保持規則與腳本名稱不變；重複匯入會更新同一組所屬規則/腳本，並再次停用供審查。只有設定檔文字並不包含受管理腳本的原始碼。

設定檔參考 · HTTP 分析與 MFHRB

閱讀本頁 Markdown