捲曲到程式碼

什麼是 cURL？

cURL（Client URL）是一個用於通過 URL 傳輸數據的命令行工具。它支持 HTTP、HTTPS、FTP 以及許多其他協議。在大多數系統上它已預裝——你可以在 macOS、Linux 或 Windows（PowerShell）的任意終端中運行 curl。

cURL 是 API 文檔的通用語言。當 API 展示示例請求時，幾乎總是一條 cURL 命令。瀏覽器開發者工具允許你將任意網絡請求複製為 cURL。這使 cURL 成為分享和復現 HTTP 請求的通用格式，即使你在生產代碼中從不直接使用 cURL。

常用 cURL 選項

-X（或 --request）設定 HTTP 方法：-X POST、-X PUT、-X DELETE。未指定方法時預設為 GET。

-H（或 --header）添加請求頭：-H "Content-Type: application/json" -H "Authorization: Bearer token123"。

-d（或 --data）發送請求體並隱含 POST：-d '{"name":"test"}'。使用 --data-raw 發送字面數據，不會把 @ 解釋為檔案引用。

-F（或 --form）發送 multipart 表單數據：-F "file=@photo.jpg" -F "caption=My photo"。每個 -F 標誌添加一個表單字段。

-o（或 --output）將響應保存到檔案：-o response.json。-O 使用遠程檔案名。

-v（或 --verbose）顯示完整的請求和響應頭——對調試極有價值。

-s（或 --silent）隱藏進度條。-S（或 --show-error）即使在靜默模式下也顯示錯誤。可組合使用：-sS。

-L（或 --location）跟隨重定向。不加該選項時，cURL 返回 301/302 響應而不是跟隨重定向。

從瀏覽器複製 cURL 命令

所有現代瀏覽器都允許將網絡請求複製為 cURL 命令。在 Chrome、Firefox 或 Edge 中：打開開發者工具（F12），進入 Network 面板，發起要捕獲的請求，右鍵該請求，選擇「Copy as cURL」。

複製的命令包含 URL、方法、所有請求頭（包括 cookie 和認證令牌）以及請求體。這是在代碼中復現瀏覽器請求，或與同事分享以便調試的最快方式。

重要提示：複製的命令常常包含會話 cookie 和授權令牌。分享前請移除敏感請求頭。粘貼到文檔或聊天時，用「Bearer YOUR_TOKEN_HERE」等佔位符替換真實令牌。

用 cURL 進行 API 測試

cURL 是無需寫代碼即可測試 API 端點的最快方式。從 API 文檔中的示例 cURL 命令入手，修改參數後在終端運行。

對於 JSON API，請包含 Content-Type 請求頭：curl -X POST -H "Content-Type: application/json" -d '{"email":"test@example.com"}' https://api.example.com/users。

要同時查看響應頭和響應體，添加 -i。要查看完整的請求/響應交換，添加 -v。要格式化 JSON 輸出，通過 jq 管道：curl -s https://api.example.com/users | jq .

測試需要認證的 API 時，將令牌存入變量：TOKEN="your_token"，然後引用：curl -H "Authorization: Bearer $TOKEN" https://api.example.com/me。這樣可保持命令歷史乾淨，也便於切換令牌。

從 cURL 到生產代碼

在終端中可用的 cURL 命令是一份已驗證的請求規範——你知道端點、請求頭、方法和請求體都正確。接下來是將其轉換為所用語言的 HTTP 客户端。

Dokall 可將 cURL 轉換為 JavaScript（fetch 和 axios）、Python（requests 和 http.client）、Go（net/http）、PHP（cURL 擴展）、Rust（reqwest）等。生成的代碼會按各語言約定處理請求頭格式、請求體序列化和方法指定。

轉換後請審閲生成的代碼並按生產環境調整：添加錯誤處理、設定超時、用環境變量存放 API 密鑰（切勿硬編碼密鑰）、為瞬時失敗實現重試邏輯，並添加日誌。轉換後的代碼是起點——並非可直接上線的生產代碼。

對於常用的 API 調用，將轉換後的代碼封裝為帶類型參數和返回值的函數。這樣可形成清晰的 API 客户端，應用其他部分無需瞭解 HTTP 細節即可調用。