# 【Shell】【Tool】call_api

```shell
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** 參數的作用，並且說明為什麼要加：

```bash
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 也算成功。

---

2. **`-s` / `--silent`**
    
    
    - 作用：靜默模式，不顯示下載進度條與錯誤訊息（錯誤還是會 exit code ≠ 0）。
    - 好處：避免 cron job 或 log 裡塞滿進度百分比。

---

3. **`-S` / `--show-error`**
    
    
    - 作用：在 `-s` 靜默模式下，仍然把錯誤訊息（例如 DNS 解析失敗、timeout）顯示出來。
    - 好處：結合 `-s` 使用，可以安靜但又不失錯誤訊息。

---

4. **`--connect-timeout 2`**
    
    
    - 作用：設定 TCP 連線的最大等待時間（單位：秒）。
    - 例子：如果 API 服務根本沒在聽 port 8082，curl 會在 **2 秒** 內放棄。

---

5. **`--max-time 5`**
    
    
    - 作用：整個 request（連線、傳輸、讀取）的最長時間，超過就中斷。
    - 好處：避免 API 掛住時，curl 一直卡在那裡。

---

6. **`--retry 2`**
    
    
    - 作用：遇到「暫時性錯誤」（像 DNS 解析失敗、timeout、connection reset by peer），會自動重試最多 2 次。
    - 預設只會 retry network-level 的錯誤，不會 retry 4xx/5xx。

---

7. **`--retry-delay 1`**
    
    
    - 作用：每次 retry 前延遲 **1 秒**。
    - 預設會 delay 1 秒，但這裡寫死確保一致。

---

8. **`-w " [HTTP_CODE=%{http_code}]\n"`**
    
    
    - 作用：在 response 輸出結尾，附加 HTTP 狀態碼。
    - 例子：成功時會多一行 ` [HTTP_CODE=200]`
    - 好處：log 裡可以直接看出 API 狀態。

---

9. **`"$URL"`**
    
    
    - 作用：實際要請求的 URL。
    - 這裡設成變數，方便修改。

---

###  總結

這樣組合的意圖就是：

- `-fsS` → 安靜，但保留錯誤訊息，不要 HTML 錯誤頁
- `--connect-timeout` / `--max-time` → 控制時間上限，避免卡死
- `--retry` / `--retry-delay` → 短暫網路錯誤自動補救
- `-w %{http_code}` → log 裡清楚顯示 HTTP 狀態碼

---