今天的練習會延續 Week 1 的步調，把 Day 06 學到的錯誤處理，真正用在實際的 API 上。

為什麼選「笑話 API」當題材？

原因其實和選擇 Open-Meteo 天氣 API 相同。

• 不需要 API 金鑰

• 回傳的資料格式 JSON 結構簡單，容易解析

• 成果很快就看得到(一執行程式就會看到笑話)

這次目標不只是把笑話資料印出來看，而是做一個小工具，可以：

• 連續一直要笑話，使用體驗好，不容易當機

• 可以把笑話存到檔案裡備份

• 練習 命令列介面 (CLI) 的流程管理

• 檔案的增加式寫入

環境準備

建資料夾與檔案

mkdir day08
cd day08
ni .\day08\day08_joke_random.py

API 的資料格式說明

1. 免費公開的笑話 API 大多會回傳 JSON 格式的資料。

2. 常見的兩種笑話格式：

• 單欄位格式：只有一個欄位，例如：

{"joke": "這是一則笑話內容"}

• 雙欄位格式：有兩個欄位，分成「前半段 (setup)」和「後半段 (delivery)」，例如：

{"setup": "笑話的開頭", "delivery": "笑話的結尾"}

3. 處理策略（格式統一）：

• 如果是單欄位，直接用 joke["joke"]。

• 如果是雙欄位，合成字串呈現，格式是 f"{setup} — {delivery}"。

get_random_joke() 函式設計說明

函式介面

• 函式名稱：get_random_joke

• 參數：timeout=10（設定請求等待時間，秒為單位）

• 回傳值：可能會回傳一個「字典」(dict) 或「純文字」(str)

函式要做什麼？

1. 送出 GET 請求

• 用 requests.get() 叫笑話 API，請求資料。

2. 檢查回傳的狀態碼

• 如果不是成功狀態（200~299），就發生錯誤，要用 raise_for_status() 丟出錯誤。

3.解析回傳的 JSON

• 先檢查重要的欄位存不存在（例如笑話字串的欄位）。

• 用「格式統一」策略，把笑話變成同一種字串格式。

4. 回傳結果

• 回傳一個字典（包含笑話的ID、來源、及文字）

• 或者只回傳笑話文本字串。

例外情況要怎麼處理？

（延續 Day 06 錯誤處理概念）

• 連線失敗（例如網路問題、DNS 不通）

• 逾時錯誤（等太久無回應）

• 非成功回應碼（伺服器錯誤 5xx、找不到頁面 4xx）

• JSON 解析錯誤（資料格式不符預期）

如果遇到錯誤，顯示友善提示，例如：

• 「連線逾時（timeout=10秒），請稍後再試」

• 「伺服器忙碌（HTTP 5xx），請稍後重試」

• 「回傳格式有誤，暫時無法解析」

程式不會直接崩潰，可以繼續操作。

主程式：命令列選單流程

• 匯入與基礎設定
  
• API 來源清單 SOURCES
  
• 取笑話
  
• 選單、存檔
  
  
  

程式會一直循環顯示選項，讓我們做選擇。

[1] 再來一則笑話
[2] 儲存剛剛的笑話到 jokes.txt
[0] 結束程式

輸入後程式要做的事情：
按 1：
呼叫 get_random_joke() 函式，從 API 拿一則新笑話，並顯示在螢幕上。

自動把英文拆成「段落」→ 翻成中文 → 做簡單潤飾。

如果判定翻譯得很奇怪，就改成雙語顯示（中文 + 英文）。

按 2：
把剛剛取得的笑話「追加」寫入檔案 jokes.txt 裡（不會覆蓋舊檔案）。

格式：

YYYY-MM-DD HH:MM:SS - <笑話內容>

（像是 2025-09-19 14:30:00 - 這是一則好笑的笑話）

按 0：
正常結束程式。

執行結果：

雖然笑話一點也不好笑，但至少程式碼可以跑成功。

檔案讀寫與資料保存

怎麼把笑話存到檔案？

用 Python 的with open() 搭配「追加模式」，在 jokes.txt 這個檔案後面寫入新笑話，指令長這樣：

with open("jokes.txt", "a", encoding="utf-8") as f:
    f.write(text + "\n")  # 把笑話內容加上換行寫入檔案

• "a" 是「追加模式」，意思是新資料會加在檔案最後面，不會把原本檔案內容清掉。

• encoding="utf-8" 是設定檔案編碼，避免中文亂碼。

可能會遇到的問題？

• 路徑問題
  例如檔案所在資料夾不存在，或檔名錯誤。

• 權限問題
  例如沒有寫入該資料夾或檔案的權限，電腦不允許寫入。

怎麼回報友善提示給使用者？

當寫檔失敗時，用 try/except 把錯誤抓住，告訴使用者：

try:
    with open("jokes.txt", "a", encoding="utf-8") as f:
        f.write(text + "\n")
except Exception:
    print("無法寫入檔案，請確認檔案是否存在且有寫入權限")

今日總結

• 完成選單式笑話工具：多來源 API 隨機取笑話，循環操作（1取笑話／2追加存檔／0結束）。

• 強化穩定度與可讀性：requests 超時 ＋ 狀態碼檢查 ＋ 例外處理。