跳到主內容

【Shell】【Tool】call_api

call_api() {
  curl -fsS \
    --connect-timeout 2 \
    --max-time 5 \
    --retry 2 --retry-delay 1 \
    -w " [HTTP_CODE=%{http_code}]\n" \
    "$URL"
}

好的 👍 我來逐一說明 call_api() 這段裡面每個 curl 參數的作用，並且說明為什麼要加：

call_api() {
  curl -fsS \
    --connect-timeout 2 \
    --max-time 5 \
    --retry 2 --retry-delay 1 \
    -w " [HTTP_CODE=%{http_code}]\n" \
    "$URL"
}

 參數逐一解析

  1. -f / --fail

    • 作用：當 HTTP 狀態碼是 4xx / 5xx 時，不會把 HTML 錯誤頁輸出到 stdout，而是直接返回非零 exit code。

    • 好處：可以在 script 判斷「這次呼叫失敗」，而不是誤以為拿到一大串錯誤 HTML 也算成功。

  1. -s / --silent

    • 作用：靜默模式，不顯示下載進度條與錯誤訊息（錯誤還是會 exit code ≠ 0）。

    • 好處：避免 cron job 或 log 裡塞滿進度百分比。

  1. -S / --show-error

    • 作用：在 -s 靜默模式下，仍然把錯誤訊息（例如 DNS 解析失敗、timeout）顯示出來。

    • 好處：結合 -s 使用，可以安靜但又不失錯誤訊息。

  1. --connect-timeout 2

    • 作用：設定 TCP 連線的最大等待時間（單位：秒）。

    • 例子：如果 API 服務根本沒在聽 port 8082，curl 會在 2 秒 內放棄。

  1. --max-time 5

    • 作用：整個 request（連線、傳輸、讀取）的最長時間，超過就中斷。

    • 好處：避免 API 掛住時，curl 一直卡在那裡。

  1. --retry 2

    • 作用：遇到「暫時性錯誤」（像 DNS 解析失敗、timeout、connection reset by peer），會自動重試最多 2 次。

    • 預設只會 retry network-level 的錯誤，不會 retry 4xx/5xx。

  1. --retry-delay 1

    • 作用：每次 retry 前延遲 1 秒。

    • 預設會 delay 1 秒，但這裡寫死確保一致。

  1. -w " [HTTP_CODE=%{http_code}]\n"

    • 作用：在 response 輸出結尾，附加 HTTP 狀態碼。

    • 例子：成功時會多一行 [HTTP_CODE=200]

    • 好處：log 裡可以直接看出 API 狀態。

  1. "$URL"

    • 作用：實際要請求的 URL。

    • 這裡設成變數，方便修改。

 總結

這樣組合的意圖就是：

  • -fsS → 安靜，但保留錯誤訊息，不要 HTML 錯誤頁

  • --connect-timeout / --max-time → 控制時間上限，避免卡死

  • --retry / --retry-delay → 短暫網路錯誤自動補救

  • -w %{http_code} → log 裡清楚顯示 HTTP 狀態碼

 

回到頂端