Python on YuChen

如何使用 PyAutoGUI（一）：安裝與滑鼠控制

Thu, 30 Apr 2026 00:00:00 +0800

內容大綱

PyAutoGUI 基本介紹
安裝 PyAutoGUI
螢幕座標系統
安全機制：Fail-Safe
取得螢幕資訊
滑鼠點擊
滑鼠移動
滾輪操作
- 垂直滾動
- 水平滾動

1. PyAutoGUI 基本介紹

PyAutoGUI 是一個跨平台的 Python GUI 自動化套件，可以程式化地控制滑鼠與鍵盤，適用於 Windows、macOS 和 Linux。常見應用場景包括：

重複性操作自動化：自動填表、批次處理檔案。
GUI 測試：模擬使用者操作，進行介面測試。
螢幕截圖與圖像辨識：截圖並尋找特定圖案位置，再進行點擊。

⚠️ 注意事項
PyAutoGUI 會直接控制系統的滑鼠與鍵盤，執行時請先確認不會誤操作重要視窗，建議先在測試環境中嘗試。

2. 安裝 PyAutoGUI

在終端機輸入以下指令：

pip install pyautogui

若有多個版本的 python 可以指定特定版本：

py -3.8 -m pip install pyautogui

macOS：

python3 -m pip install pyautogui

Linux：
還需要安裝額外依賴套件。

sudo apt-get install python3-tk python3-dev scrot
python3 -m pip install pyautogui

安裝完成後，驗證是否成功：

import pyautogui
print(pyautogui.size()) # 印出螢幕解析度，例如 Size(width=1920, height=1080)

3. 螢幕座標系統

在開始自動化之前，我們必須先了解電腦螢幕的座標系統（Coordinate System）：

原點 (0, 0)：位於螢幕的 左上角 (Top-Left)。
X 軸：水平方向，由左向右遞增。
Y 軸：垂直方向，由上向下遞增。

如果你想更直觀地了解座標位置，可以使用下方我開發的小工具。移動滑鼠即可即時顯示座標，點擊畫面則可以釘選座標點。

互動小工具：螢幕座標地圖 建議點擊右上角的「全螢幕」按鈕或將瀏覽器視窗最大化，以獲得最準確的座標參考。
程式碼已開源於：screen-coordinate-map

4. 安全機制：Fail-Safe

PyAutoGUI 內建一個防呆安全機制：當滑鼠快速移動到螢幕左上角（座標 0, 0）時，會自動丟出 FailSafeException 並中止程式。

這個機制可以讓你在程式失控時，快速移動滑鼠到左上角以強制停止。

import pyautogui

# 安全機制，正式使用時請保持啟用（預設為 True）
pyautogui.FAILSAFE = True

# 若確定不需要此機制（不建議）可關閉
pyautogui.FAILSAFE = False

此外，還有一個全域延遲設定，讓每個操作之間自動暫停，避免操作太快：

# 每次 PyAutoGUI 函式呼叫後，暫停 0.5 秒（預設為 0.1）
pyautogui.PAUSE = 0.5

5. 取得螢幕資訊

import pyautogui

# 取得螢幕解析度
width, height = pyautogui.size()
print(f"螢幕寬度：{width}，高度：{height}")

# 取得滑鼠目前位置
x, y = pyautogui.position()
print(f"目前滑鼠座標：({x}, {y})")

💡 小技巧：執行以下程式碼，可以即時追蹤滑鼠座標，按 Ctrl+C 停止：

import pyautogui, time
try:
 while True:
 x, y = pyautogui.position()
 print(f"\r目前座標：({x:4}, {y:4})", end="", flush=True)
 time.sleep(0.1)
except KeyboardInterrupt: # 按下 Ctrl+C 會中斷程式
 print("\n已停止追蹤")

6. 滑鼠點擊

點擊 `click()`：

import pyautogui

pyautogui.click() # 在目前位置點擊左鍵

pyautogui.click(500, 300) # 點擊指定座標

pyautogui.click(500, 300, button='right') # 指定按鍵 'left'、'right'、'middle'

pyautogui.click(500, 300, clicks=2) # 連續點擊
pyautogui.click(500, 300, clicks=2, interval=0.25) # 設定兩次點擊之間的間隔（秒）
pyautogui.click(button='right', clicks=3, interval=0.25) # 指定按鍵並連續點擊

雙擊 `doubleClick()`：

# 在指定位置雙擊
pyautogui.doubleClick(500, 300)

註解
也有 tripleClick() 函數，用以點擊三次螢幕。

右鍵點擊 `rightClick()`：

pyautogui.rightClick(500, 300)

中鍵點擊 `middleClick()`：

pyautogui.middleClick(500, 300)

分開按下與放開 `mouseDown()` / `mouseUp()`：

# 按下與放開皆預設為左鍵
pyautogui.mouseDown() # 按下左鍵（不放開）
pyautogui.mouseUp() # 放開左鍵

# 按下右鍵（不放開）
pyautogui.mouseDown(500, 300, button='right')

# 放開右鍵
pyautogui.mouseUp(500, 300, button='right')

7. 滑鼠移動

移動到絕對座標 `moveTo(x, y, duration=num_seconds)`：

import pyautogui

# 移動到螢幕座標 (500, 300)
pyautogui.moveTo(500, 300)

# 移動到 (500, 300)，花費 1 秒（加入緩動效果）
pyautogui.moveTo(500, 300, duration=1)

# 使用緩動函式（easing），讓動作更自然
pyautogui.moveTo(500, 300, duration=1, tween=pyautogui.easeInOutQuad)

移動到相對座標 `moveRel(xOffset, yOffset, duration=num_seconds)`：

# 從目前位置，向右移動 100px、向下移動 50px
pyautogui.moveRel(100, 50)

# moveRel 與 move 完全相同
pyautogui.move(100, 50, duration=0.5)

拖曳到絕對座標 `dragTo(x, y, duration=num_seconds)`：

import pyautogui

# 從目前位置拖曳到 (700, 400)，花費 0.5 秒
pyautogui.dragTo(700, 400, duration=0.5)

# 指定使用左鍵拖曳
pyautogui.dragTo(700, 400, duration=0.5, button='left')

拖曳到相對座標 `dragRel(xOffset, yOffset, duration=num_seconds)`：

# 從目前位置向右拖曳 200px、向下 100px
pyautogui.dragRel(200, 100, duration=0.5)

# drag 與 dragRel 完全相同
pyautogui.drag(200, 100, duration=0.5)

實用範例：拖曳視窗

import pyautogui
import time

# 點擊視窗標題列(假設(400, 30)有視窗標題)
pyautogui.click(400, 30)
time.sleep(0.2)

# 拖曳視窗到新位置
pyautogui.dragTo(800, 200, duration=1, button='left')

常用 tween 緩動函式：

函式	效果	範例指令
`pyautogui.linear`	等速移動（預設）	`pyautogui.moveTo(x, y, tween=pyautogui.linear)`
`pyautogui.easeInQuad`	由慢到快	`pyautogui.moveTo(x, y, tween=pyautogui.easeInQuad)`
`pyautogui.easeOutQuad`	由快到慢	`pyautogui.moveTo(x, y, tween=pyautogui.easeOutQuad)`
`pyautogui.easeInOutQuad`	先慢後快再慢	`pyautogui.moveTo(x, y, tween=pyautogui.easeInOutQuad)`
`pyautogui.easeInBounce`	到達目標後反彈	`pyautogui.moveTo(x, y, tween=pyautogui.easeInBounce)`

8. 滾輪操作

垂直滾動 `scroll()`

import pyautogui

# 向上滾動 3 格（正值向上，負值向下）
pyautogui.scroll(3)

# 在指定座標向下滾動 5 格
pyautogui.scroll(-5, x=500, y=400)

水平滾動 `hscroll()`

# 向右水平滾動 3 格
pyautogui.hscroll(3)

# 向左水平滾動 3 格
pyautogui.hscroll(-3)

練習題

📝 練習題 1：滑鼠畫正方形

題目：使用 moveTo() 讓滑鼠依序移動到四個角落，畫出一個邊長 200px 的正方形路徑（從座標 (200, 200) 出發）。

答案：

import pyautogui
import time

pyautogui.PAUSE = 0.5

pyautogui.moveTo(200, 200, duration=0.5)
pyautogui.moveTo(400, 200, duration=0.5)
pyautogui.moveTo(400, 400, duration=0.5)
pyautogui.moveTo(200, 400, duration=0.5)
pyautogui.moveTo(200, 200, duration=0.5)

print("正方形路徑完成！")

📝 練習題 2：自動右鍵選單

題目：在桌面空白處模擬右鍵點擊，然後按下 Escape 關閉選單（需搭配第二篇的鍵盤操作）。

答案：

import pyautogui
import time

time.sleep(2) # 給自己時間切換到桌面

# 在桌面中央右鍵點擊
screen_w, screen_h = pyautogui.size()
pyautogui.rightClick(screen_w // 2, screen_h // 2)
time.sleep(0.5)

# 按 Escape 關閉選單
pyautogui.press('escape')

📝 練習題 3：計算並移動到螢幕中心

題目：用程式取得螢幕解析度後，計算出螢幕中心點，並將滑鼠移動過去。

答案：

import pyautogui

width, height = pyautogui.size()
center_x = width // 2
center_y = height // 2

print(f"螢幕中心：({center_x}, {center_y})")
pyautogui.moveTo(center_x, center_y, duration=1)

參考資料

學 FastAPI 前你需要知道的事：HTTP 與 API 基礎

Mon, 27 Apr 2026 10:32:00 +0800

1. 什麼是 API？

API（Application Programming Interface，應用程式介面） 是不同軟體之間溝通的「橋樑」。

用生活中的例子來說明：

想像去餐廳吃飯。
你（使用者）不需要知道廚房裡怎麼煮菜，只需要看著菜單（API 文件），跟服務員（API）說「我要一份炒飯」（發送請求），廚房處理好後，服務員再把菜端出來（回傳結果）。

在軟體世界裡：

你的程式 = 客戶端（Client）
菜單 = API 定義的格式與規則
廚房 = 伺服器（Server）

Web API 就是透過網路（HTTP）來溝通的 API，是現在最主流的形式。手機 App 打開時載入的資料、天氣網站顯示的即時溫度，背後都是透過 Web API 取得的。

2. HTTP 協定：請求與回應

HTTP（HyperText Transfer Protocol，超文本傳輸協定） 是網際網路資料傳輸的「語言規則」，規定了客戶端與伺服器之間「怎麼說話」。

HTTP 的溝通模式只有一種：「一問一答」。

客戶端（你的程式） ──── 請求（Request） ────▶ 伺服器
客戶端（你的程式） ◀─── 回應（Response） ───── 伺服器

一個 HTTP 請求包含什麼？

組成部分	說明	範例
URL	要存取的資源地址	`https://api.example.com/users/1`
Method	要做什麼操作	`GET`（取得）、`POST`（新增）
Headers	附加的元資訊（誰在發？帶什麼格式？）	`Content-Type: application/json`
Body	夾帶的資料內容（非所有請求都有）	`{"name": "小明", "age": 25}`

一個 HTTP 回應包含什麼？

組成部分	說明	範例
Status Code	請求的處理結果（成功？失敗？）	`200`、`404`、`500`
Headers	回應的元資訊	`Content-Type: application/json`
Body	回傳的資料內容	`{"id": 1, "name": "小明"}`

3. HTTP 方法（Method）

HTTP 方法定義了「要對資源執行什麼動作」。這對應到資料庫操作中常見的 CRUD（建立、讀取、更新、刪除）：

HTTP 方法	對應 CRUD	語意	範例
`GET`	Read（讀取）	取得資源，不改變任何東西	`GET /users` — 取得所有使用者
`POST`	Create（建立）	建立一筆新資源	`POST /users` — 新增一個使用者
`PUT`	Update（完整更新）	用新資料完整替換一筆資源	`PUT /users/1` — 完整更新 id=1 的使用者
`PATCH`	Update（部分更新）	只更新資源中的特定欄位	`PATCH /users/1` — 只改某個欄位
`DELETE`	Delete（刪除）	刪除一筆資源	`DELETE /users/1` — 刪除 id=1 的使用者

💡 記憶小技巧：
GET = 取得（不帶 Body）
POST = 送出（帶 Body，放新資料）
PUT = 放置（完整取代）
PATCH = 修補（部分修改）
DELETE = 刪除

4. HTTP 狀態碼

狀態碼是一個三位數的數字，告訴客戶端「這次請求的結果如何」。

分類規則（第一個數字決定大類）

類別	範圍	意義
1xx	100–199	資訊性，請求接收中
2xx	200–299	成功
3xx	300–399	重新導向
4xx	400–499	客戶端的錯誤
5xx	500–599	伺服器端的錯誤

FastAPI 開發最常見的狀態碼

狀態碼	名稱	使用時機
`200 OK`	成功	最常見，GET 成功回傳資料
`201 Created`	已建立	POST 成功新增一筆資料
`204 No Content`	無內容	成功但不回傳任何資料（常用於 DELETE）
`400 Bad Request`	錯誤請求	客戶端傳來的資料格式有問題
`401 Unauthorized`	未授權	沒有提供身份驗證（如 Token）
`403 Forbidden`	禁止存取	有驗證但沒有權限
`404 Not Found`	找不到	要存取的資源不存在
`422 Unprocessable Entity`	無法處理	資料格式正確但內容驗證失敗（FastAPI 常用）
`500 Internal Server Error`	伺服器錯誤	伺服器端程式碼出錯

5. 什麼是 JSON？

JSON（JavaScript Object Notation） 是目前 Web API 最主流的資料交換格式，用來在客戶端與伺服器之間傳遞資料。

JSON 的語法規則

{
 "id": 1,
 "name": "王小明",
 "isStudent": true,
 "score": 95.5,
 "hobbies": ["閱讀", "寫程式"],
 "address": {
 "city": "台北市",
 "district": "信義區"
 },
 "nickname": null
}

JSON 規則	說明
用 `{ }` 包住物件	一組 Key-Value 的集合
用 `[ ]` 包住陣列	多筆資料的列表
Key 必須用雙引號 `"`	`"name"` ✅，`name` ❌
Value 的類型	字串、數字、布林（`true`/`false`）、陣列、物件、`null`

JSON 與 Python dict 的對照

# Python dict
data = {
 "id": 1,
 "name": "王小明",
 "is_student": True, # Python 用 True（大寫）
 "hobbies": ["閱讀", "寫程式"],
 "nickname": None # Python 用 None
}

{
 "id": 1,
 "name": "王小明",
 "is_student": true,
 "hobbies": ["閱讀", "寫程式"],
 "nickname": null
}

FastAPI 會自動把 Python dict 轉換成 JSON 格式回傳，完全不需要手動處理。

6. 從瀏覽器到 API：完整流程回顧

以開啟「天氣 App」為例，理解一次完整的 API 呼叫：

1. 使用者打開 App
↓
2. App 發送 HTTP 請求
GET https://api.weather.com/current?city=Taipei
Headers: { "Authorization": "Bearer my-token" }
↓
3. 伺服器接收請求、查詢資料庫
↓
4. 伺服器回傳 HTTP 回應
Status: 200 OK
Body: { "city": "台北", "temperature": 28, "humidity": 75 }
↓
5. App 解析 JSON，顯示在畫面上

7. FastAPI 的分工：框架 vs 伺服器

在開始使用 FastAPI 之前，要先理解它和 Uvicorn 的分工：

使用者的瀏覽器 / App
↓ HTTP 請求
┌─────────────┐
│ Uvicorn │ ← 負責接收網路連線、處理 HTTP 協定
└──────┬──────┘
↓ 轉交給
┌─────────────┐
│ FastAPI │ ← 負責路由分配、資料驗證、執行你的程式邏輯
└──────┬──────┘
↓ 執行
┌─────────────┐
│ 你的程式碼 │ ← def read_item(), def create_user() ...
└─────────────┘

FastAPI：決定「收到這個 URL 要做什麼事」——這是你寫的邏輯
Uvicorn：負責在網路上監聽、收發 HTTP 封包——這是底層基礎設施

練習題

📝 練習題 1：HTTP 方法配對

題目：請說明以下 API 端點應該使用哪個 HTTP 方法？

取得 id=5 的商品資訊
新增一筆訂單
刪除 id=3 的留言
更新使用者的電子郵件（只改一個欄位）
完整替換一篇文章的所有內容

答案：

GET /products/5
POST /orders
DELETE /comments/3
PATCH /users/{id}
PUT /articles/{id}

📝 練習題 2：狀態碼判讀

題目：以下情境應該回傳哪個 HTTP 狀態碼？

使用者輸入了帳號密碼，但帳號不存在
成功建立了一筆新資料
伺服器程式碼發生了 Python 例外（Exception）
請求需要登入，但沒有提供 Token
請求格式正確，但 email 欄位不符合 email 格式

答案：

404 Not Found（找不到此帳號）
201 Created
500 Internal Server Error
401 Unauthorized
422 Unprocessable Entity（FastAPI 的資料驗證失敗）

📝 練習題 3：JSON 轉 Python dict

題目：將以下 JSON 轉換為 Python dict：

{
 "username": "alice",
 "age": 30,
 "is_active": true,
 "tags": ["admin", "user"],
 "bio": null
}

答案：

data = {
 "username": "alice",
 "age": 30,
 "is_active": True, # JSON true → Python True
 "tags": ["admin", "user"],
 "bio": None # JSON null → Python None
}

注意：true → True，false → False，null → None

---

參考資料

如何使用 FastAPI

Sun, 26 Apr 2026 22:15:56 +0800

內容大綱

FastAPI 基本介紹
安裝 FastAPI 與 Uvicorn
建立第一個 FastAPI 應用程式
啟動伺服器與測試
自動產生 API 文件

1. FastAPI 基本介紹

FastAPI 是一個現代、快速（高效能）的 Web 框架，用於建構 API，基於標準 Python 類型提示。它的主要特色包括：

高效能：可與 NodeJS 和 Go 相提並論的極高網頁效能。
易於使用：自動產生互動式的 API 文件 (Swagger UI)。
減少錯誤：透過資料驗證機制，減少人為錯誤。

2. 安裝 FastAPI 與 Uvicorn

在開始之前，請確保環境中已安裝 Python。我們需要安裝 FastAPI 框架本身，以及一個 ASGI 伺服器 (如 Uvicorn) 來運行它。

💡 補充說明：什麼是 Uvicorn？
FastAPI 是一個「網頁框架」，負責處理程式邏輯與路由；但它本身並沒有內建處理網路連線的伺服器功能。因此，我們需要搭配 Uvicorn 這個超高效能的 ASGI 伺服器。它就像是一座橋樑，負責在網路上接收使用者的 HTTP 請求，轉交給 FastAPI 處理後，再把結果傳回給瀏覽器。

請在終端機輸入以下指令：

pip install fastapi
pip install "uvicorn[standard]"

3. 建立第一個 FastAPI 應用程式

建立一個名為 main.py 的檔案，並輸入以下程式碼：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
 return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
 return {"item_id": item_id, "q": q}

這段程式碼定義了兩個端點 (Endpoints)：

根目錄 /：回傳一個簡單的 JSON { "Hello": "World" }。
/items/{item_id}：展示了如何接收路徑參數 (item_id) 以及查詢參數 (q)。

4. 啟動伺服器與測試

在終端機中，確保處於 main.py 所在的目錄，執行以下指令來啟動伺服器：

uvicorn main:app --reload

main：指的是 main.py 檔案。
app：是 main.py 中 app = FastAPI() 建立的實例。
--reload：當程式碼變動時會自動重新載入，非常適合在開發過程中使用。

啟動後，可以在瀏覽器中造訪：http://127.0.0.1:8000 將會看到：{"Hello": "World"}

5. 自動產生 API 文件

FastAPI 最大的亮點之一就是會自動產生文件。在伺服器運行時，可以造訪：

1. Swagger UI (互動式文件)

造訪：http://127.0.0.1:8000/docs

如何閱讀與使用 Swagger UI？
打開網頁後，會看到剛剛寫好的 / 與 /items/{item_id} 兩個端點 (Endpoints)：

展開端點：點擊想測試的端點（例如 /items/{item_id}），它會往下展開顯示詳細資訊。
開始測試：點擊右上角的 「Try it out」 按鈕。
輸入參數：這時參數欄位會變成可輸入狀態。可以在 item_id 填入數字（例如 5），在 q 填入字串（例如 somequery）。
執行請求：點擊下方的 「Execute」 藍色按鈕。
查看結果：往下捲動到 「Responses」 區塊，就可以看到伺服器回傳的真實 JSON 資料與 HTTP 狀態碼（例如 200 表示成功）。

2. ReDoc (靜態文件)

造訪：http://127.0.0.1:8000/redoc

這是另一種風格的 API 文件。它的排版更適合當作純閱讀的參考手冊，不包含互動測試的功能。

這樣就成功建立並運行了一個 FastAPI 應用程式！

練習題

📝 練習題 1：新增一個路由

題目：在 main.py 中新增一個 GET /hello/{name} 的端點，讓它回傳 {"message": "Hello, {name}!"}。

例如：呼叫 GET /hello/Alice 應該回傳 {"message": "Hello, Alice!"}

答案：

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello/{name}")
def say_hello(name: str):
 return {"message": f"Hello, {name}!"}

📝 練習題 2：Swagger UI 操作

題目：啟動伺服器後，請用 Swagger UI 測試以下兩個端點，並記錄回傳的結果：

GET / — 預期回傳什麼？
GET /items/42?q=fastapi — 預期回傳什麼？

答案：

GET / 回傳：{"Hello": "World"}
GET /items/42?q=fastapi 回傳：{"item_id": 42, "q": "fastapi"}

操作步驟：開啟 http://127.0.0.1:8000/docs → 點擊端點 → Try it out → 輸入參數 → Execute → 查看 Responses

📝 練習題 3：傳入錯誤型別會怎樣？

題目：在 Swagger UI 中呼叫 GET /items/{item_id}，但把 item_id 填入字串 "abc" 而不是整數，觀察 FastAPI 回傳什麼？

答案：

FastAPI 會自動回傳 422 Unprocessable Entity，並在 body 中說明哪個欄位驗證失敗：

{
 "detail": [
 {
 "type": "int_parsing",
 "loc": ["path", "item_id"],
 "msg": "Input should be a valid integer, unable to parse string as an integer",
 "input": "abc"
 }
 ]
}

這就是 FastAPI 自動驗證型別的威力——完全不需要自己寫驗證邏輯！

參考資料

FastAPI 官方教學 - 使用者指南

如何使用 venv 建立 Python 虛擬環境

Sat, 25 Apr 2026 03:29:13 +0800

內容大綱

什麼是虛擬環境？為何需要它？
建立虛擬環境
進階參數指令 (Options)
啟動與退出虛擬環境
套件的安裝、匯出與批次移除
常見問題與注意事項

1. 什麼是虛擬環境？為何需要它？

在開發 Python 專案時，經常需要使用 pip 安裝各種第三方套件。如果不使用虛擬環境，所有套件都會被安裝到系統全域環境中。這樣會產生幾個嚴重問題：

版本衝突：專案 A 需要 Django 3.0，但專案 B 卻依賴 Django 4.0，兩者無法共存於同一個環境。
環境污染：全域環境累積過多不需要的套件，難以管理。

venv 是 Python 3.3 之後內建的虛擬環境管理工具，它能為每個專案建立一個獨立的資料夾。在這個資料夾中，擁有獨立的 Python 執行檔與獨立的套件庫，從而完美隔離各個專案。

2. 建立虛擬環境

建立虛擬環境主要有兩種指定路徑的方式。

方式一：在目前目錄下建立（相對路徑） 請先開啟終端機，並使用 cd 指令切換到專案資料夾，接著輸入以下指令：

# Windows / macOS / Linux 通用指令
python -m venv venv

python -m venv：呼叫 Python 內建的 venv 模組。
最後的 venv：這是即將產生的虛擬環境資料夾名稱。一般約定成俗會將其命名為 venv 或 .venv。執行後，目前的專案目錄下就會多出這個資料夾。

方式二：在指定位置建立（絕對路徑） 如果不想將虛擬環境放在專案資料夾內，或者想統一集中管理所有虛擬環境，可以直接指定一個完整的路徑：

python -m venv /path/to/new/virtual/environment

兩個指令的差別：

python -m venv venv：利用相對路徑，將虛擬環境建立在「目前終端機所在的資料夾」底下。適合讓每個專案擁有專屬、跟隨專案代碼的環境，這也是最常見的做法。
python -m venv /path/to/...：利用絕對路徑（或明確指定的路徑），無論目前終端機在哪個目錄，都會將虛擬環境強制建立在指定的特定位置上。適合習慣把所有虛擬環境統一存放在同一個集中目錄（例如 ~/.virtualenvs/）的開發情境。

不管使用哪種方式，執行後該資料夾裡面都會包含獨立的 Python 執行檔與套件庫結構。

3. 進階參數指令 (Options)

在建立虛擬環境時，可以在終端機加上特定的參數來客製化環境設定（可透過 python -m venv -h 查詢完整列表），以下介紹幾個常用的進階參數：

--system-site-packages：預設情況下，虛擬環境是完全隔離的。加上此參數後，虛擬環境將「可以存取」系統全域 (System-wide) 所安裝的套件。
--clear：如果指定的資料夾已經存在，加上此參數會在建立前「先清空」該資料夾裡的所有內容，相當於重新建立一個乾淨的環境。
--without-pip：建立環境時預設會自動安裝 pip。若加上此參數則會跳過安裝。
--prompt <PROMPT>：自訂啟動虛擬環境後，終端機前面顯示的「提示字元前綴」（預設為資料夾的名稱）。
--upgrade-deps：建立環境的同時，將環境內的基礎套件（如 pip 和 setuptools）直接升級到 PyPI 上的最新版本。
--without-scm-ignore-files：建立環境時，不自動生成原始碼控制的忽略檔（新版 Python 預設會自動產生 .gitignore）。

4. 啟動與退出虛擬環境

建立好之後，需要「啟動 (Activate)」它，讓系統知道接下來的操作都要在這個隔離環境內進行。

啟動虛擬環境 (Windows Command Prompt)：

venv\Scripts\activate.bat

啟動虛擬環境 (Windows PowerShell)：

venv\Scripts\Activate.ps1

啟動虛擬環境 (macOS / Linux)：

source venv/bin/activate

啟動成功後，終端機的提示字元前方通常會出現 (venv)，代表目前已經身處於虛擬環境中。

退出虛擬環境： 當開發結束，想要回到系統全域環境時，只需執行：

deactivate

5. 套件的安裝、匯出與批次移除

在虛擬環境啟動的狀態下，使用 pip install 安裝的任何套件，都會被存放在這個虛擬環境中，完全不會影響到系統。

安裝套件：

pip install requests

匯出套件清單： 為了讓專案能夠在其他電腦上重現相同的環境，會將目前安裝的所有套件名稱與版本匯出成一份清單。

pip freeze > requirements.txt

從清單還原環境： 當其他人拿到專案時，只要先建立並啟動自己的虛擬環境，就可以透過這份清單一次安裝所有必需的套件。

pip install -r requirements.txt

強制清空環境的所有套件： 如果環境遭到污染（裝了太多不相關的套件），或者想將目前環境打掉重練，可以利用 pip freeze 配合 pip uninstall 來一鍵批次卸載所有第三方套件。

首先，將目前所有安裝的套件清單匯出到一個暫存檔：

pip freeze > uninstall.txt

接著，讓 pip 讀取這個清單，並強制 (-y) 刪除裡面的所有套件：

pip uninstall -r uninstall.txt -y

(備註：pip freeze 預設不會把基礎套件 pip、setuptools、wheel 列入清單，因此不用擔心會刪除到這三個核心套件。)

刪除完成後，再把暫存檔清掉即可：

# Windows 命令提示字元 (cmd):
del uninstall.txt

# Windows PowerShell:
Remove-Item uninstall.txt

# macOS / Linux:
rm uninstall.txt

6. 常見問題與注意事項

不要將 venv 資料夾加入版本控制：虛擬環境資料夾體積龐大且包含系統特定的編譯檔案。請務必在 .gitignore 檔案中加入 venv/，避免將它推送到 GitHub。
PowerShell 執行原則錯誤：在 Windows PowerShell 啟動時如果遇到「執行原則不允許」的紅色錯誤，請以系統管理員身分開啟 PowerShell 並執行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 即可解決。

參考資料

Python 官方文件：venv — 建立虛擬環境

如何使用 PyAutoGUI（二）：鍵盤控制

Fri, 01 May 2026 19:20:00 +0800

內容大綱

文字輸入
單鍵操作
常用 Key 名稱對照表
訊息彈出視窗
- alert()
- confirm()
- prompt()
- password()
實用範例：自動開啟記事本並輸入文字

1. 文字輸入

`typewrite()` / `write()`

兩者完全相同，用於模擬逐鍵輸入文字：

import pyautogui

# 在目前焦點位置輸入文字
pyautogui.typewrite('Hello, World!')

# 設定每個字元之間的間隔（秒），模擬真實打字速度
pyautogui.typewrite('Hello!', interval=0.1)

# write() 與 typewrite() 完全相同
pyautogui.write('Python automation', interval=0.05)

⚠️ 注意：中文輸入限制
typewrite() 只支援 ASCII 字元，無法直接輸入中文。若要輸入中文，需改用剪貼簿方式：
import pyautogui
import pyperclip # pip install pyperclip

# 將中文複製到剪貼簿，再貼上
pyperclip.copy('你好，世界！')
pyautogui.hotkey('ctrl', 'v') # 稍後會介紹 hotkey 函數

2. 單鍵操作：

按下並放開單一按鍵 `press()`：

import pyautogui

# 按下 Enter 鍵
pyautogui.press('enter')

# 按下 Tab 鍵
pyautogui.press('tab')

# 按下方向鍵（上下左右）
pyautogui.press('up')
pyautogui.press('down')
pyautogui.press('left')
pyautogui.press('right')

# 連續按多次（按 3 次空白鍵）
pyautogui.press('space', presses=3)

# 設定每次按鍵之間的間隔
pyautogui.press('tab', presses=5, interval=0.2)

# 也可以傳入 list，依序按下多個鍵
pyautogui.press(['up', 'up', 'down', 'down', 'left', 'right'])

按住不放與放開按鍵 `keyDown()` / `keyUp()`：

import pyautogui

# 按住 Shift 鍵不放
pyautogui.keyDown('shift')

# 輸入文字（若無鎖定`CAPSLOCK`，此時會全部變大寫）
pyautogui.typewrite('hello') # 實際輸入 HELLO

# 放開 Shift 鍵
pyautogui.keyUp('shift')

實際應用：按住 Shift 並點擊以選取文字

import pyautogui
# 先點擊起始位置
pyautogui.click(200, 300)
# 按住 Shift
pyautogui.keyDown('shift')
# 點擊結束位置（選取這段範圍的文字）
pyautogui.click(600, 300)
# 放開 Shift
pyautogui.keyUp('shift')

上下文管理器 `hold()`：

import pyautogui

# 該shift鍵將在上下文區塊期間保持按住狀態。
with pyautogui.hold('shift'):
 pyautogui.press(['left', 'left', 'left'])

組合鍵與熱鍵 `hotkey()`：

import pyautogui

pyautogui.hotkey('ctrl', 'c') # Ctrl + C（複製）
pyautogui.hotkey('ctrl', 'v') # Ctrl + V（貼上）

# Alt + F4（關閉視窗，Windows）
pyautogui.hotkey('alt', 'f4')
# Ctrl + Alt + Delete（Windows）
pyautogui.hotkey('ctrl', 'alt', 'delete')
# macOS 截圖：Cmd + Shift + 4
pyautogui.hotkey('command', 'shift', '4')
# Ctrl + Shift + T（重開分頁，瀏覽器）
pyautogui.hotkey('ctrl', 'shift', 't')

3. 常用 Key 名稱對照表

以下是 press()、keyDown()、keyUp()、hotkey() 可接受的常用鍵名：

類別	Key 名稱
修飾鍵	`shift`、`ctrl`、`alt`、`command`（macOS）、`win`（Windows）
功能鍵	`f1` ~ `f12`
方向鍵	`up`、`down`、`left`、`right`
特殊鍵	`enter`、`esc`、`tab`、`backspace`、`delete`、`space`、`capslock`
Page 鍵	`pageup`、`pagedown`、`home`、`end`
數字鍵盤	`num0` ~ `num9`、`numlock`、`add`、`subtract`、`multiply`、`divide`
媒體鍵	`volumemute`、`volumedown`、`volumeup`、`playpause`
符號鍵	`!`、`@`、`#`、`$`、`%`、`^`、`&`、`*`、`(`、`)`
字母/數字	`a`～`z`、`0`～`9`

查看所有支援的鍵名：

import pyautogui
print(pyautogui.KEYBOARD_KEYS)

你也可以使用下方的互動式工具，快速搜尋按鍵名稱與對應的變數寫法：

互動小工具：鍵盤按鍵對照查詢 支援分類篩選與關鍵字搜尋，點擊按鍵卡片可產生範例程式碼。
程式碼已開源於：pynput-key-reference

4. 訊息彈出視窗

PyAutoGUI 提供了簡易的 GUI 彈出視窗函式，可在自動化流程中提示使用者或取得確認。

顯示訊息 `alert()`：

import pyautogui

# 顯示提示訊息
pyautogui.alert('操作完成！')

# 自訂標題
pyautogui.alert(text='備份成功。', title='通知', button='確定')

確認視窗 `confirm()`：

result = pyautogui.confirm('確定要刪除嗎？', title='確認', buttons=['確定', '取消'])
print(result) # 使用者點了哪個按鈕的文字

文字輸入視窗 `prompt()`：

name = pyautogui.prompt('請輸入你的名字：', title='輸入', default='')
if name:
 print(f'你好，{name}！')

密碼輸入視窗 `password()`（遮蔽顯示）：

pwd = pyautogui.password('請輸入密碼：', title='登入', default='', mask='*')
print(f'輸入的密碼：{pwd}')

5. 實用範例：自動開啟記事本並輸入文字

以下範例示範如何在 Windows 上自動開啟記事本，並輸入一段文字再儲存：

import pyautogui
import subprocess
import time

# 開啟記事本
subprocess.Popen(['notepad.exe'])
time.sleep(1.5) # 等待視窗開啟

pyautogui.press('shift') # 切換鍵盤成英文

# 輸入文字
pyautogui.typewrite('Hello from PyAutoGUI!', interval=0.05)
pyautogui.press('enter')
pyautogui.typewrite('This is automated typing.', interval=0.05)

# 儲存（Ctrl + S）
pyautogui.hotkey('ctrl', 's')
time.sleep(1)

# 在另存新檔視窗中輸入檔名
pyautogui.typewrite('auto_test.txt', interval=0.05)
pyautogui.press('enter')

print("完成！已儲存為 auto_test.txt")

練習題

📝 練習題 1：自動全選並複製

題目：在任意文字編輯器中，用 PyAutoGUI 執行「全選→複製→游標移至末尾→貼上」的操作序列。

答案：

import pyautogui
import time

time.sleep(2) # 手動切換到目標視窗

pyautogui.hotkey('ctrl', 'a') # 全選
time.sleep(0.3)
pyautogui.hotkey('ctrl', 'c') # 複製
time.sleep(0.3)
pyautogui.press('end') # 移至末尾
pyautogui.press('enter') # 換行
pyautogui.hotkey('ctrl', 'v') # 貼上

📝 練習題 2：詢問使用者再執行

題目：用 confirm() 彈出確認視窗，若使用者點「確定」，才執行自動輸入文字的動作；若點「取消」，則印出「已取消」。

答案：

import pyautogui
import time

result = pyautogui.confirm('是否要開始自動輸入？', title='確認', buttons=['確定', '取消'])

if result == '確定':
 time.sleep(2) # 切換到目標視窗
 pyautogui.typewrite('自動輸入的文字！', interval=0.1)
else:
 print('已取消')

📝 練習題 3：模擬 Vim 儲存並離開

題目：假設 Vim 已開啟並在 Normal mode，用 PyAutoGUI 模擬輸入 :wq 後按 Enter 來儲存並離開。

答案：

import pyautogui
import time

time.sleep(2) # 切換到 Vim 視窗

# 確保在 Normal mode
pyautogui.press('esc')
time.sleep(0.2)

# 輸入 :wq 指令
pyautogui.typewrite(':wq', interval=0.1)
pyautogui.press('enter')

參考資料

如何使用 PyAutoGUI（三）：螢幕截圖與圖像辨識

Sat, 02 May 2026 21:40:44 +0800

內容大綱

截取螢幕畫面
- 全螢幕截圖
- 區域截圖
圖像辨識：在螢幕上尋找圖片
像素顏色偵測
- 取得指定座標的像素顏色
- 判斷像素顏色是否符合
實戰範例：自動點擊指定按鈕
實戰範例：等待圖案出現再執行
常見問題與除錯技巧

1. 截取螢幕畫面

全螢幕截圖 `screenshot()`：

在 1920 x 1080 的螢幕上，screenshot()大約需要 100 毫秒。

import pyautogui

# 截取全螢幕，回傳 PIL Image 物件
img = pyautogui.screenshot()

# 顯示圖片（需安裝 Pillow）
img.show()

# 直接儲存為檔案
pyautogui.screenshot('screenshot.png')

# 截圖並儲存
img = pyautogui.screenshot('my_screen.png')
print(f"截圖尺寸：{img.size}") # (寬, 高)

區域截圖 `screenshot(region=(...)))`：

region 參數格式為 (left, top, width, height)，分別表示要截圖區域的左側、頂部、寬度和高度。

import pyautogui

# 截取左上角 400x300 的區域
img = pyautogui.screenshot(region=(0, 0, 400, 300))

# 截取螢幕中央的 200x200 區域
screen_w, screen_h = pyautogui.size()
cx = screen_w // 2 - 100
cy = screen_h // 2 - 100
img = pyautogui.screenshot(region=(cx, cy, 200, 200))
img.save('center_crop.png')

💡 補充說明：PIL Image 物件
screenshot() 回傳的是 Pillow 的 Image 物件，可以進一步進行旋轉、裁切、濾鏡等影像處理，也可以轉成 NumPy 陣列配合 OpenCV 使用：
import numpy as np
import cv2

img = pyautogui.screenshot()
frame = np.array(img)
frame = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
cv2.imwrite('screen_cv2.png', frame)

2. 圖像辨識：在螢幕上尋找圖片

PyAutoGUI 可以在當前螢幕畫面中搜尋指定圖片，回傳其位置。

前置條件：需先準備好要搜尋的圖片（.png 格式最佳），可用截圖工具截取目標按鈕或圖案。

⚠️ 注意：新舊版本差異
在新版 PyAutoGUI 中，若找不到圖片會拋出 pyautogui.ImageNotFoundException；如果是舊版，則會回傳 None，可以使用 if location: 來判斷。
建議統一使用 try...except 來確保程式不會崩潰。

尋找圖片位置 `locateOnScreen()`：

import pyautogui

try:
 # 在螢幕上尋找 button.png，找到則回傳 Box(left, top, width, height)
 location = pyautogui.locateOnScreen('button.png')
 print(f"找到圖片：{location}")
 # location.left, location.top, location.width, location.height
except pyautogui.ImageNotFoundException:
 print("找不到圖片")

取得圖片中心座標 `locateCenterOnScreen()`：

import pyautogui

try:
 # 找到圖片並直接回傳中心點座標 (x, y)
 center = pyautogui.locateCenterOnScreen('button.png')
 x, y = center
 print(f"圖片中心：({x}, {y})")
 pyautogui.click(x, y)
except pyautogui.ImageNotFoundException:
 print("找不到圖片")

調整信心值（confidence）

當截圖與螢幕畫面因縮放或顯示設定略有差異時，可調整 confidence 參數（需安裝 opencv-python）：

pip install opencv-python

import pyautogui

# confidence 介於 0~1，預設為 1.0（完全相符）
# 降低至 0.8 可接受 80% 的相似度
try:
 location = pyautogui.locateOnScreen('button.png', confidence=0.8)
 print(f"找到圖片：{location}")
except pyautogui.ImageNotFoundException:
 print("找不到圖片")

尋找所有符合位置 `locateAllOnScreen()`：

import pyautogui

try:
 # 回傳所有符合位置的 generator
 all_locations = list(pyautogui.locateAllOnScreen('icon.png'))
 print(f"共找到 {len(all_locations)} 個符合位置")
 for loc in all_locations:
 print(loc)
except pyautogui.ImageNotFoundException:
 print("找不到任何符合的圖片")

在圖片中搜尋 `locate()`（非螢幕）：

from PIL import Image
import pyautogui

# 在一張截圖檔案中搜尋另一張圖片
haystack = Image.open('fullscreen.png')
needle = Image.open('button.png')

try:
 location = pyautogui.locate(needle, haystack, confidence=0.9)
 print(location)
except pyautogui.ImageNotFoundException:
 print("在圖片中找不到目標圖案")

3. 像素顏色偵測

取得指定座標的像素顏色 `pixel()`：

import pyautogui

# 取得座標 (100, 200) 的 RGB 顏色值
r, g, b = pyautogui.pixel(100, 200)
print(f"顏色：RGB({r}, {g}, {b})")

判斷像素顏色是否符合 `pixelMatchesColor()`：

import pyautogui

# 判斷 (100, 200) 是否為紅色 (255, 0, 0)
is_red = pyautogui.pixelMatchesColor(100, 200, (255, 0, 0))
print(f"是紅色嗎？{is_red}")

# 允許一定的顏色誤差（tolerance 預設為 0）
is_approx_red = pyautogui.pixelMatchesColor(100, 200, (255, 0, 0), tolerance=30)
print(f"接近紅色嗎？{is_approx_red}")

實用應用：偵測載入完成

import pyautogui
import time

# 等待某個座標的顏色變成綠色（表示載入完成）
print("等待載入完成...")
while True:
 r, g, b = pyautogui.pixel(500, 300)
 if g > 200 and r < 100 and b < 100: # 接近綠色
 print("載入完成！")
 break
 time.sleep(0.5)

4. 實戰範例：自動點擊指定按鈕

以下範例示範如何找到螢幕上的「送出」按鈕圖片並自動點擊：

import pyautogui
import time

def click_button(image_path, confidence=0.9, timeout=10):
 """
 在螢幕上搜尋圖片並點擊，若超過 timeout 秒仍找不到則拋出例外。
 """
 start_time = time.time()

 while True:
 try:
 location = pyautogui.locateCenterOnScreen(image_path, confidence=confidence)
 if location:
 pyautogui.click(location)
 print(f"成功點擊：{image_path}")
 return True
 except pyautogui.ImageNotFoundException:
 pass

 if time.time() - start_time > timeout:
 raise TimeoutError(f"超過 {timeout} 秒仍找不到：{image_path}")

 time.sleep(0.5)

# 使用範例
try:
 click_button('submit_button.png', confidence=0.85, timeout=15)
except TimeoutError as e:
 print(f"錯誤：{e}")

5. 實戰範例：等待圖案出現再執行

import pyautogui
import time

def wait_for_image(image_path, confidence=0.85, check_interval=1.0):
 """
 持續等待直到螢幕出現指定圖片，回傳中心座標。
 """
 print(f"等待出現：{image_path}")

 while True:
 try:
 center = pyautogui.locateCenterOnScreen(image_path, confidence=confidence)
 if center:
 print(f"已找到，座標：{center}")
 return center
 except pyautogui.ImageNotFoundException:
 pass

 time.sleep(check_interval)


# 完整自動化流程範例
import pyautogui, time

time.sleep(3) # 等待目標程式啟動

# 等待「登入」按鈕出現
login_btn = wait_for_image('login_button.png')
pyautogui.click(login_btn)
time.sleep(0.5)

# 輸入帳號密碼
pyautogui.typewrite('user@example.com', interval=0.05)
pyautogui.press('tab')
pyautogui.typewrite('mypassword', interval=0.05)

# 等待「送出」按鈕出現並點擊
submit_btn = wait_for_image('submit_button.png')
pyautogui.click(submit_btn)

# 等待「歡迎」畫面出現，確認登入成功
wait_for_image('welcome_screen.png')
print("登入成功！")

6. 常見問題與除錯技巧

問題 1：`locateOnScreen()` 找不到圖片

可能原因與解決方式：

原因	解決方式
螢幕縮放不同（HiDPI / Retina）	降低 `confidence` 值，例如 `0.8`
圖片有些微色差	加入 `grayscale=True` 進行灰階比對
圖片不在當前可視範圍	確認視窗是否最小化或被遮擋
圖片解析度不符	重新截取在目標機器上的按鈕圖片

# 灰階比對，對顏色差異更有容忍度
location = pyautogui.locateOnScreen('button.png', grayscale=True, confidence=0.8)

問題 2：macOS 截圖需要授權

在 macOS 上，需至「系統設定 → 隱私權與安全性 → 螢幕錄製」，將執行 Python 的終端機加入允許清單。

問題 3：速度太快造成錯誤

import pyautogui

# 增加全域延遲
pyautogui.PAUSE = 0.3

# 或在關鍵步驟加入 time.sleep()
import time
time.sleep(0.5)

取得當前像素顏色的小工具

import pyautogui, time

print("移動滑鼠到目標位置，3 秒後擷取顏色")
time.sleep(3)
x, y = pyautogui.position()
r, g, b = pyautogui.pixel(x, y)
print(f"座標 ({x}, {y}) 的顏色：RGB({r}, {g}, {b})")

練習題

📝 練習題 1：截取並儲存指定區域

題目：截取螢幕右下角 300x200 的區域，儲存為 corner.png。

答案：

import pyautogui

w, h = pyautogui.size()
region = (w - 300, h - 200, 300, 200)
pyautogui.screenshot('corner.png', region=region)
print("已儲存右下角截圖：corner.png")

📝 練習題 2：確認按鈕存在才點擊

題目：嘗試在螢幕上尋找 ok_button.png，若找到則點擊，否則印出「找不到按鈕」。

答案：

import pyautogui

try:
 center = pyautogui.locateCenterOnScreen('ok_button.png', confidence=0.85)
 if center:
 pyautogui.click(center)
 print("已點擊 OK 按鈕")
except pyautogui.ImageNotFoundException:
 print("找不到按鈕")

📝 練習題 3：像素顏色監控

題目：每秒偵測座標 (960, 540) 的像素顏色，若 R 值超過 200 則印出警告訊息並停止，最多監控 30 秒。

答案：

import pyautogui
import time

print("開始監控像素顏色...")
for i in range(30):
 r, g, b = pyautogui.pixel(960, 540)
 print(f"第 {i+1} 秒：RGB({r}, {g}, {b})")
 if r > 200:
 print("⚠️ 警告：R 值超過 200！")
 break
 time.sleep(1)
else:
 print("監控結束，未觸發警告")

參考資料

FastAPI 路徑參數

Mon, 27 Apr 2026 14:00:00 +0800

在第一篇教學中，我們建立了一個簡單的 / 根目錄端點。但真實世界的 API 通常需要根據不同的請求回傳不同的資料，例如：取得「特定 ID」的使用者資料。

這時候，我們就需要用到路徑參數（Path Parameters）。

內容大綱

前置知識：什麼是「動態 URL」？
什麼是路徑參數？
宣告路徑參數
加上型別提示：自動型別轉換
自動資料驗證（422 錯誤）
路徑順序的重要性
使用 Enum 限制合法選項
包含路徑分隔符的路徑參數

1. 前置知識：什麼是「動態 URL」？

靜態 URL 是固定的網址，例如 /users/list，每次造訪都會看到一樣的東西。

而動態 URL 則允許網址的某個部分變成「變數」。例如購物網站的商品網址可能是 /products/1、/products/2，其中 1 和 2 就是動態改變的部分。後端程式會讀取這個數字，然後從資料庫撈出對應的商品資料。

2. 什麼是路徑參數？

在 URL 中，那個會動態改變的部分，我們就稱為路徑參數。

在 FastAPI 裡，我們可以使用類似 Python f-string 的語法，用大括號 {} 將 URL 中的某個部分包起來，宣告它是一個變數。

3. 宣告路徑參數

讓我們在 main.py 中新增一個端點，用來取得特定使用者的資料：

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def read_user(user_id):
 return {"user_id": user_id}

在這個例子中：

/users/{user_id} 告訴 FastAPI：「/users/ 後面的那一截字串，請當作變數 user_id」。
路由函式 def read_user(user_id): 必須接收同名的參數 user_id。

如果你在瀏覽器輸入 http://127.0.0.1:8000/users/alice，就會看到回傳：

{"user_id": "alice"}

⚠️ 注意：不要宣告重複的路徑

如果你寫了兩個一模一樣的路由，例如：
@app.get("/test")
def test_1():
 return {"Test": "1!"}

@app.get("/test")
def test_2():
 return {"Test": "2!"}
FastAPI 的比對規則是 「從上往下掃描，先搶先贏」。當有人造訪 /test 時，任務會立刻交給第一個 test_1 處理並結束。下面的 test_2 函式會變成永遠等不到客人的「幽靈程式碼」。此外，這還會導致自動產生的 API 文件（Swagger UI）發生覆蓋錯亂。

4. 加上型別提示：自動型別轉換

在上面的例子中，user_id 預設會被當作字串（string）。但如果使用者的 ID 在資料庫中是整數（Integer）怎麼辦？

在 FastAPI 中，只需要使用 Python 標準的型別提示（Type Hints），FastAPI 就會自動幫忙做轉換。

@app.get("/items/{item_id}")
def read_item(item_id: int):
 return {"item_id": item_id, "type": type(item_id).__name__}

當你造訪 http://127.0.0.1:8000/items/5，FastAPI 發現你宣告了 item_id: int，就會自動把網址中的字串 "5" 轉換成整數 5 傳進函式中。

5. 自動資料驗證（422 錯誤）

延續上面的例子，如果有人亂輸入網址，造訪了 http://127.0.0.1:8000/items/foo，會發生什麼？字串 "foo" 沒辦法變成整數啊。

程式不會崩潰，FastAPI 會直接攔截這個錯誤，並回傳清楚的 HTTP 錯誤狀態碼 422 Unprocessable Entity（無法處理的實體），並附帶錯誤說明：

{
 "detail": [
 {
 "type": "int_parsing",
 "loc": [
 "path",
 "item_id"
 ],
 "msg": "Input should be a valid integer, unable to parse string as an integer",
 "input": "foo"
 }
 ]
}

錯誤訊息明確指出：在路徑（path）中的 item_id 發生了轉換整數失敗的錯誤。這省去了我們自己寫 if not item_id.isdigit(): ... 等檢查邏輯。

6. 路徑順序的重要性

在設計 API 時，有時候會同時有「固定路徑」和「動態路徑」。

例如，我們有一個取得所有使用者的端點 /users/all，也有一個取得特定使用者的端點 /users/{user_id}。

在 FastAPI 中，路由的宣告順序非常重要。程式碼是從上往下執行的，FastAPI 會比對第一個符合條件的路徑。

錯誤的寫法：

@app.get("/users/{user_id}")
def read_user(user_id: str):
 return {"user_id": user_id}

@app.get("/users/all")
def read_all_users():
 return ["Alice", "Bob"]

如果這樣寫，當你造訪 /users/all 時，FastAPI 會先看到 @app.get("/users/{user_id}")，然後把 "all" 當作是變數 user_id 的值傳進去，這是錯誤的。

正確的寫法（固定路徑在前）：

@app.get("/users/all")
def read_all_users():
 return ["Alice", "Bob"]

@app.get("/users/{user_id}")
def read_user(user_id: str):
 return {"user_id": user_id}

把固定的路由寫在前面，就能確保它會被正確攔截。

7. 使用 `Enum` 限制合法選項

有時候，路徑參數不能隨便亂填，只能是幾個特定的選項。這時候可以使用 Python 內建的 Enum。

假設我們有一個機器學習模型 API，只接受 alexnet、resnet、lenet 三種模型名稱：

from enum import Enum
from fastapi import FastAPI

class ModelName(str, Enum):
 alexnet = "alexnet"
 resnet = "resnet"
 lenet = "lenet"

app = FastAPI()

@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
 if model_name == ModelName.alexnet:
 return {"model_name": model_name, "message": "Deep Learning FTW!"}
 if model_name.value == "lenet":
 return {"model_name": model_name, "message": "LeCNN all the masses"}
 return {"model_name": model_name, "message": "Have some residuals"}

這個寫法有三個好處：

編輯器支援：打字時會有自動補全（Auto-completion）。
自動驗證：如果使用者輸入 http://127.0.0.1:8000/models/yolov4，FastAPI 會直接回傳 422 錯誤，並告訴使用者有哪些合法的選項。

{
 "detail": [
 {
 "type": "enum",
 "loc": [
 "path",
 "model_name"
 ],
 "msg": "Input should be 'alexnet', 'resnet' or 'lenet'",
 "input": "yolov4",
 "ctx": {
 "expected": "'alexnet', 'resnet' or 'lenet'"
 }
 }
 ]
}

API 文件：Swagger UI 會自動把這個欄位變成一個下拉式選單，讓測試更方便！

8. 包含路徑分隔符的路徑參數

最後一個比較特殊的情境是：如果路徑參數本身就是一個檔案路徑（包含 /）怎麼辦？

例如 URL 長這樣：/files/home/johndoe/myfile.txt。我們希望 /files/ 後面的所有東西 home/johndoe/myfile.txt 都被當成一個變數。

FastAPI 支援 Starlette 的特殊路徑語法：:path。

@app.get("/files/{file_path:path}")
def read_file(file_path: str):
 return {"file_path": file_path}

只要加上 :path，FastAPI 就不會因為遇到 / 就把字串切斷，而是會把它一字不漏地全部抓下來。

測試範例： 如果在瀏覽器輸入 http://127.0.0.1:8000/files/home/myfile.txt，將會收到完整的路徑字串：

{"file_path": "home/myfile.txt"}

練習題

📝 練習題 1：撰寫產品分類 API

題目：撰寫一個 API 端點 GET /categories/{category_name}。這個端點應該接收字串型別的 category_name，並回傳 JSON 格式的分類名稱。

答案：

from fastapi import FastAPI

app = FastAPI()

@app.get("/categories/{category_name}")
def get_category(category_name: str):
 return {"category": category_name}

📝 練習題 2：修復順序錯誤

題目：以下的程式碼有個問題。如果造訪 /posts/latest 會發生什麼事？請將程式碼修改成正確的順序。

from fastapi import FastAPI

app = FastAPI()

@app.get("/posts/{post_id}")
def get_post(post_id: int):
 return {"post_id": post_id}

@app.get("/posts/latest")
def get_latest_post():
 return {"post": "This is the latest post!"}

答案：

如果照著原本的寫法，造訪 /posts/latest 時，FastAPI 會以為 "latest" 是 post_id。由於 post_id 規定要是整數（int），所以會丟出 422 Validation Error 錯誤。

正確寫法（把固定路徑移到上面）：

from fastapi import FastAPI

app = FastAPI()

@app.get("/posts/latest")
def get_latest_post():
 return {"post": "This is the latest post!"}

@app.get("/posts/{post_id}")
def get_post(post_id: int):
 return {"post_id": post_id}

📝 練習題 3：使用 Enum 限制顏色

題目：建立一個 GET /items/color/{color_name} 的端點。請使用 Enum 限制 color_name 只能是 red、green 或 blue 其中一種。如果輸入合法，回傳對應的顏色名稱。

答案：

from enum import Enum
from fastapi import FastAPI

app = FastAPI()

class ColorName(str, Enum):
 red = "red"
 green = "green"
 blue = "blue"

@app.get("/items/color/{color_name}")
def get_color(color_name: ColorName):
 return {"selected_color": color_name}

參考資料

FastAPI 官方教學 - 路徑參數

FastAPI 查詢參數

Mon, 27 Apr 2026 18:55:00 +0800

在上一篇，我們學習了如何使用「路徑參數」來建立動態的 URL，例如透過 /users/alice 來取得特定使用者的資料。然而，如果我們想要在一個網頁中加入**「搜尋關鍵字」、「分頁（第幾頁）」或是「篩選條件（價格由高到低）」**，把這些條件全部塞進斜線 / 裡面會變得非常難以管理。

這時候，需要用到另一種常見的傳值方式：查詢參數（Query Parameters）。

內容大綱

什麼是查詢參數？
宣告查詢參數
設定預設值（選填參數）
必填的查詢參數
使用 Optional 表示可選欄位
布林值 (bool) 的自動轉換
同時使用路徑參數與查詢參數

1. 什麼是查詢參數？

大家一定有用過 Google 搜尋。當你在 Google 搜尋「FastAPI」時，你會發現網址列變成這樣： https://www.google.com/search?q=FastAPI

在這裡，? 後面的字串就是查詢參數。它的語法規則非常簡單：

以問號 ? 作為開頭。
格式是 鍵=值（Key=Value），例如 q=FastAPI。
如果有多個參數，就用 & 符號串接起來，例如 ?q=FastAPI&page=2。

2. 宣告查詢參數

在 FastAPI 中，要宣告查詢參數非常簡單。只要在路由函式中加入的參數名稱，沒有出現在路徑 @app.get(...) 的 {} 裡面，FastAPI 就會自動把它當作查詢參數！

以下是簡單的分頁 API 範例：

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def read_items(skip: int = 0, limit: int = 10):
 return {"skip": skip, "limit": limit}

在這個例子中：

路徑是 /items/，裡面沒有任何 {}。
函式 read_items 卻接收了 skip 和 limit 兩個參數。
因此，FastAPI 會自動認定 skip 和 limit 是從網址 ? 後面傳進來的查詢參數。

3. 設定預設值（選填參數）

上面的範例中，我們給了參數預設值：skip: int = 0 和 limit: int = 10。這代表這兩個參數是選填的（Optional）。

測試看看：

如果你直接造訪 http://127.0.0.1:8000/items/：由於你沒有在網址提供參數，FastAPI 會使用你設定的預設值，回傳：
```
{"skip": 0, "limit": 10}
```
如果你造訪 http://127.0.0.1:8000/items/?skip=20： FastAPI 會讀取網址的 skip，而 limit 依然使用預設值：
```
{"skip": 20, "limit": 10}
```
如果你造訪 http://127.0.0.1:8000/items/?skip=20&limit=5： FastAPI 會同時讀取網址的 skip 和 limit：
```
{"skip": 20, "limit": 5}
```

4. 必填的查詢參數

如果我們希望某個查詢參數是**必填（Required）**的，該怎麼做？很簡單，不要給它預設值就好了！

假設我們正在寫一個搜尋 API，使用者一定要提供搜尋的關鍵字 q：

@app.get("/search")
def search_items(q: str):
 return {"search_keyword": q}

因為 q 沒有等號 = 賦予預設值，它就變成了必填參數。

測試看看： 如果你沒有提供 q，直接造訪 http://127.0.0.1:8000/search，FastAPI 會非常貼心地自動擋下來，並回傳 422 錯誤，告訴客戶端少傳了資料：

{
 "detail": [
 {
 "type": "missing",
 "loc": ["query", "q"],
 "msg": "Field required",
 "input": null
 }
 ]
}

必須輸入 http://127.0.0.1:8000/search?q=apple 才能成功取得結果。

5. 使用 Optional 表示可選欄位

有時候，我們希望一個參數是選填的，但在使用者沒有提供時，我們希望它的值是 None（空值），而不是某個具體的數字或字串。

這時候建議搭配 Python typing 模組中的 Optional 來寫，這可以讓編輯器的提示更準確，程式碼也更有可讀性：

from typing import Optional

@app.get("/products")
def get_products(category: Optional[str] = None):
 if category:
 return {"message": f"顯示 {category} 類別的產品"}
 return {"message": "顯示所有產品"}

這裡的 Optional[str] = None 告訴了任何人（包含編輯器與 FastAPI）：「這個參數是字串，但它是可選的，如果不填，預設就是 None」。

測試看看：

如果造訪 http://127.0.0.1:8000/products（不提供參數）：
```
{"message": "顯示所有產品"}
```
如果造訪 http://127.0.0.1:8000/products?category=3C（提供參數）：
```
{"message": "顯示 3C 類別的產品"}
```

6. 布林值 (bool) 的自動轉換

FastAPI 的資料轉換機制非常聰明，尤其是對於布林值（Boolean）。

如果宣告了一個布林型別的查詢參數：

@app.get("/users/active")
def get_active_users(short_format: bool = False):
 if short_format:
 return {"users": ["Alice", "Bob"]}
 return {"users": [{"name": "Alice", "age": 25}, {"name": "Bob", "age": 30}]}

當你要在網址中把 short_format 設為 True 時，你不用只打 true。FastAPI 會自動識別以下所有字眼，並把它們轉換成 Python 的 True：

?short_format=true
?short_format=True
?short_format=1
?short_format=on
?short_format=yes

相反地，false、0、off、no 都會被轉換為 Python 的 False。這對前端工程師來說是一個極度友善的設計！

測試看看：

造訪 http://127.0.0.1:8000/users/active?short_format=1
```
{
"users": ["Alice", "Bob"]
}
```

造訪 http://127.0.0.1:8000/users/active?short_format=0

{
"users": [
 {"name": "Alice","age": 25},
 {"name": "Bob","age": 30}
]
}

7. 同時使用路徑參數與查詢參數

在實務上，最常把「路徑參數」和「查詢參數」混在一起使用。例如：若想查看「特定使用者（路徑）」底下的「某些物品，並進行分頁（查詢）」。

不用擔心順序問題，FastAPI 會根據變數名稱自動幫你分類：

@app.get("/users/{user_id}/items")
def get_user_items(user_id: int, short: bool = False, skip: int = 0):
 item_data = {"user_id": user_id, "items": ["筆電", "滑鼠"]}

 if short:
 return {"user_id": user_id, "status": "ok"}

 return item_data

在這個例子中：

user_id 因為出現在 @app.get 的 {} 中，所以它是路徑參數。
short 和 skip 沒有出現在路徑中，所以它們是查詢參數。

如果造訪：http://127.0.0.1:8000/users/5/items?short=yes&skip=1 FastAPI 就能將 user_id 解析為 5，short 解析為 True，skip 解析為 1。

練習題

📝 練習題 1：建立排序 API

題目：撰寫一個 API 端點 GET /books。該端點需要接收一個查詢參數 sort_by。如果使用者沒有提供，預設應該是 "id"。如果使用者提供，就回傳使用者輸入的排序方式。

答案：

from fastapi import FastAPI

app = FastAPI()

@app.get("/books")
def get_books(sort_by: str = "id"):
 return {"sort_by": sort_by}

📝 練習題 2：必填與選填混搭

題目：撰寫一個 API 端點 GET /search/videos。該端點需要一個必填的查詢參數 keyword（字串），以及一個選填的參數 max_results（整數，預設為 50）。

答案：

from fastapi import FastAPI

app = FastAPI()

@app.get("/search/videos")
def search_videos(keyword: str, max_results: int = 50):
 return {"keyword": keyword, "max_results": max_results}

📝 練習題 3：如何判斷參數類型？

題目：觀察以下的程式碼，請問 model_id 和 version 分別是什麼類型的參數？

@app.get("/models/{model_id}")
def check_model(model_id: int, version: float):
 pass

答案：

model_id 是路徑參數，因為它被宣告在 @app.get 的路徑字串 {} 中。
version 是查詢參數，因為它沒有出現在路徑字串中，而且它是必填的（沒有預設值）。造訪時的網址會像這樣：/models/10?version=1.5。

參考資料

FastAPI 官方教學 - 查詢參數

FastAPI Request Body

Mon, 27 Apr 2026 23:21:00 +0800

在前幾篇文章中，我們學會了如何透過「網址（URL）」把資料傳給伺服器，例如：路徑參數 /users/123 或是查詢參數 ?skip=10。但如果要傳送大量資料（例如：一整篇部落格文章的內容）或是機密資料（例如：登入的帳號密碼），把它們全部塞進網址裡就不太適合了。這時候需要使用 Request Body（請求本文）。

內容大綱

前置知識：HTTP 方法與 Pydantic
什麼是 Request Body？
建立第一個 Pydantic 模型
在路由函式中宣告 Body 參數
選填欄位與預設值設定
在函式內部使用模型資料
三合一：模型 + 路徑參數 + 查詢參數
Pydantic 的自動驗證機制

1. 前置知識：HTTP 方法與 Pydantic

在開始實作之前，需要先了解三個重要觀念：

為什麼要用 POST？
GET 請求是用來「取得」資料，傳統上不會夾帶 Body。如果要傳送資料給伺服器來「新增」或「修改」東西，通常會使用 POST、PUT 或 PATCH 這些 HTTP 方法。
什麼是 Pydantic？
FastAPI 的強大，有一半歸功於 Pydantic。Pydantic 是一個 Python 的資料驗證庫，它的核心概念是：如果資料驗證通過了，拿到的一定是預期的型別；如果驗證失敗，它會直接拋出清楚的錯誤，不會讓錯誤的資料跑進系統。
什麼是 class 繼承？
在 Python 裡，class（類別）用來定義一個物件的藍圖。當我們寫 class Item(BaseModel): 時，代表 Item 這個模型「繼承」了 Pydantic 提供的 BaseModel，這讓 Item 瞬間擁有了自動轉換 JSON、檢查型別的超能力！

2. 什麼是 Request Body？

Request Body（請求本文）是指客戶端（如瀏覽器、手機 App）在發送 HTTP 請求時，夾帶在請求底層的資料，最常見的格式就是 JSON。

例如，當想在購物車裡新增一個商品時，客戶端會送出這樣一段 JSON：

{
 "name": "滑鼠",
 "price": 999.0,
 "is_offer": true
}

3. 建立第一個 Pydantic 模型

在 FastAPI 中，要接收並處理上面的 JSON 資料，第一步就是利用 Pydantic 的 BaseModel 來宣告資料結構。

我們可以在檔案的最上方，把需要的工具匯入進來，然後定義一個 Item 模型：

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
 name: str
 price: float
 is_offer: bool = None

這裡的寫法與標準的 Python 變數宣告一模一樣：

name 必須是字串 (str)。
price 必須是浮點數 (float)。
is_offer 是一個布林值 (bool)，並且有一個預設值 None（代表如果前端沒傳這個欄位也沒關係）。

4. 在路由函式中宣告 Body 參數

有了模型之後，只要把它當作參數，加進路由函式裡就可以了！

請注意，這次要用的是 @app.post，因為是要「新增」資料：

app = FastAPI()

@app.post("/items/")
def create_item(item: Item):
 return item

當 FastAPI 看到 item: Item 時：

它知道 Item 是一個繼承自 BaseModel 的類別。
根據「路徑 vs 查詢」的規則，item 既不在路徑 {} 裡，也不是簡單的型別（如 int 或 str），所以 FastAPI 會自動把它判定為 Request Body。

測試看看： 啟動伺服器後，到 Swagger UI (http://127.0.0.1:8000/docs) 找到 POST /items/，點擊「Try it out」，你會發現 FastAPI 已經幫你準備好了一個可以填寫的 JSON 框，輸入資料後送出，就會原封不動地回傳你填入的資料。

5. 選填欄位與預設值設定

和查詢參數一樣，可以使用 Python 的 Optional 來讓模型的欄位意圖更清晰：

from typing import Optional
from pydantic import BaseModel

class Item(BaseModel):
 name: str
 description: Optional[str] = None
 price: float
 tax: Optional[float] = None

在這個模型中，name 和 price 是必填的。而 description 和 tax 是選填的。

6. 在函式內部使用模型資料

當 FastAPI 把 JSON 自動轉換為 Pydantic 模型（例如上方的 item 變數）後，在函式內部就可以直接用「點 (.)」來存取屬性，而且還有編輯器的自動補全功能！

@app.post("/items/")
def create_item(item: Item):
 # 可以直接用 item.price，不需要像字典一樣寫成 item["price"]
 total_price = item.price
 if item.tax:
 total_price += item.tax

 return {"item_name": item.name, "total_price": total_price}

這在開發時非常舒服，因為再也不用擔心把欄位名稱打錯，編輯器都會幫忙檢查。

7. 三合一：模型 + 路徑參數 + 查詢參數

FastAPI 最厲害的地方在於，可以毫無負擔地把三種參數全部混在一起用，而且依然能清晰地分類。

@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item, q: Optional[str] = None):
 result = {"item_id": item_id, "item": item}
 if q:
 result.update({"q": q})
 return result

在這個端點中：

item_id：有出現在路徑 /items/{item_id} 裡，所以是路徑參數。
q：沒有出現在路徑裡，且型別是簡單的字串，所以是查詢參數。
item：型別是 Pydantic 的 Item 模型，所以是 Request Body。ㄋ

8. Pydantic 的自動驗證機制

如果客戶端傳來了錯誤型別的資料怎麼辦？例如，price 應該要是數字，前端卻傳了一個字串：

{
 "name": "滑鼠",
 "price": "三百塊"
}

不用擔心程式崩潰，因為有 Pydantic 把關，FastAPI 會直接攔截下來，並回傳 422 錯誤告訴使用者：

{
 "detail": [
 {
 "type": "float_parsing",
 "loc": ["body", "price"],
 "msg": "Input should be a valid number, unable to parse string as a number",
 "input": "三百塊"
 }
 ]
}

注意看這裡的 loc，它會明確指出錯誤發生在 "body"（Request Body）裡的 "price" 欄位，這大大節省除錯的時間。

練習題

📝 練習題 1：建立使用者模型

題目：請利用 Pydantic 建立一個名為 User 的模型。這個模型需要有以下三個欄位：

username：字串（必填）
email：字串（必填）
age：整數（選填，預設為 18）

答案：

from typing import Optional
from pydantic import BaseModel

class User(BaseModel):
 username: str
 email: str
 age: Optional[int] = 18

📝 練習題 2：宣告 POST 路由

題目：接續上一題，請撰寫一個 API 端點 POST /users/，並使用剛才建立的 User 模型作為 Request Body。在函式內部，請回傳一個包含 message 和使用者名稱的 JSON，例如：{"message": "成功建立使用者：Alice"}。

答案：

from fastapi import FastAPI

app = FastAPI()

@app.post("/users/")
def create_user(user: User):
 return {"message": f"成功建立使用者：{user.username}"}

📝 練習題 3：參數分類大哉問

題目：觀察以下的程式碼，請問 user_id、token 和 profile 分別屬於哪一種參數（路徑、查詢、還是 Body）？

@app.patch("/profile/{user_id}")
def update_profile(user_id: int, profile: User, token: str):
 pass

答案：

user_id 是路徑參數（因為出現在路徑的 {} 中）。
profile 是 Request Body（因為型別為 Pydantic 模型 User）。
token 是查詢參數（沒有在路徑中，且是基本字串型別）。網址會長得像 /profile/5?token=abc。

參考資料

FastAPI 官方教學 - 請求本文

FastAPI Body 進階：多個模型、巢狀結構與欄位驗證

Tue, 28 Apr 2026 00:00:00 +0800

上一篇介紹了如何使用 Pydantic 建立基本的 Request Body 模型。然而，真實世界的 API 往往會面臨更複雜的需求：如果想在同一個請求中同時接收「商品資料」和「使用者資料」該怎麼辦？如果模型裡面還包含著另一個模型（巢狀結構）呢？

這篇將解鎖 FastAPI 與 Pydantic 的進階用法，讓 API 驗證變得更靈活。

內容大綱

同時接收多個 Body 參數
使用 Body() 明確宣告單一值
使用 Field() 為欄位加上驗證
List 與 Set：處理陣列資料
巢狀模型：模型中的模型

1. 同時接收多個 Body 參數

如果想在同一個路由中接收兩種不同的資料結構，例如：建立一筆訂單時，同時需要 Item 商品資訊與 User 買家資訊，直接把它們都宣告為參數即可，FastAPI 會自動將它們視為 Request Body。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
 name: str
 price: float

class User(BaseModel):
 username: str
 full_name: str

@app.put("/orders/{order_id}")
def update_order(order_id: int, item: Item, user: User):
 return {"order_id": order_id, "item": item, "user": user}

當 FastAPI 看到兩個繼承自 BaseModel 的參數時，它會預期客戶端傳來的 JSON 長這樣：

{
 "item": {
 "name": "機械鍵盤",
 "price": 3000.0
 },
 "user": {
 "username": "alice123",
 "full_name": "Alice Wang"
 }
}

它會自動使用參數名稱（item 和 user）作為 JSON 最外層的 Key，並把資料完美解析出來。

2. 使用 Body() 明確宣告單一值

有時候，除了完整的 Pydantic 模型之外，可能還想額外接收一個簡單的單一值，例如一個整數 importance。如果直接寫 importance: int，FastAPI 會把它當作查詢參數，因為它是基本型別。

如果堅持要把這個簡單的值也放進 JSON Body 裡面，可以使用 FastAPI 提供的 Body()：

from fastapi import Body, FastAPI

@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item, importance: int = Body(...)):
 return {"item_id": item_id, "item": item, "importance": importance}

Body(...) 中的 ... 在 FastAPI 裡代表必填的意思。

此時，FastAPI 預期的 JSON 結構會變成：

{
 "item": {
 "name": "機械鍵盤",
 "price": 3000.0
 },
 "importance": 5
}

3. 使用 Field() 為欄位加上驗證

如果想要對 Pydantic 模型裡面的某個欄位做更嚴格的限制（例如：價格必須大於 0、名字長度最多 50 字元），需要使用 Pydantic 的 Field()。

from pydantic import BaseModel, Field

class Item(BaseModel):
 name: str = Field(..., max_length=50, description="商品的名稱")
 description: str | None = Field(default=None, title="商品詳細描述")
 price: float = Field(..., gt=0, description="價格必須大於 0")

這裡的參數解釋如下：

...：代表必填。
max_length=50：字串長度不能超過 50。
default=None：代表預設值為 None（可選填）。
gt=0：Greater Than，數值必須大於 0。
description / title：這兩個參數不會影響驗證，但會顯示在 Swagger UI 文件上，幫助前端工程師理解欄位意義。

4. List 與 Set：處理陣列資料

如果某個欄位會包含多個值（例如：商品的標籤清單），在 Python 中可以使用 list 或 set 型別。

class Item(BaseModel):
 name: str
 tags: list[str] = []
 unique_tags: set[str] = set()

list[str] 代表這個欄位必須是一個列表，且裡面的元素都要是字串。
set[str] 與 list 類似，但如果是 set，當前端傳來包含重複值的 JSON（例如 ["電子", "電子", "促銷"]）時，FastAPI 轉成 Python set 後會自動去重複，變成 {"電子", "促銷"}！

5. 巢狀模型：模型中的模型

Pydantic 最強大的地方在於它的高階組合能力，可以把一個模型當作另一個模型中的欄位型別，創造出「巢狀結構」。

例如，一個商品可能包含多個「圖片」：

from pydantic import BaseModel, HttpUrl

class Image(BaseModel):
 url: HttpUrl
 name: str

class Item(BaseModel):
 name: str
 price: float
 # 這個欄位是一個列表，且裡面的元素必須符合 Image 類
 images: list[Image] = []

HttpUrl 是 Pydantic 內建的特殊型別，它會自動驗證傳入的字串是否為合法的網址。

此時，FastAPI 預期的 JSON 就會是一個深層的巢狀結構：

{
 "name": "遊戲主機",
 "price": 15000.0,
 "images": [
 {
 "url": "https://example.com/console_front.png",
 "name": "正面照"
 },
 {
 "url": "https://example.com/console_back.png",
 "name": "背面照"
 }
 ]
}

練習題

📝 練習題 1：建立包含清單的模型

題目：建立一個 Post（部落格文章）模型，包含以下欄位：

title：字串
content：字串
comments：字串的列表（預設為空列表）

答案：

from pydantic import BaseModel

class Post(BaseModel):
 title: str
 content: str
 comments: list[str] = []

📝 練習題 2：使用 Field() 加上限制

題目：請修改上一題的 Post 模型，要求 title 的長度不可超過 100 個字元，並加上描述 "文章的標題"。

答案：

from pydantic import BaseModel, Field

class Post(BaseModel):
 title: str = Field(..., max_length=100, description="文章的標題")
 content: str
 comments: list[str] = []

參考資料

FastAPI 參數驗證：Query() 與 Path() 的完整用法

Tue, 28 Apr 2026 10:46:00 +0800

在第 2 篇和第 3 篇中，我們學會了宣告路徑參數和查詢參數，FastAPI 已經幫我們做好了最基礎的「型別轉換」與「必填/選填」檢查。但如果需要更嚴格的限制呢？例如：

密碼長度至少要 8 個字元。
商品 ID 必須大於 0。
查詢參數的名稱在網址上是 item-query（帶有橫線，在 Python 中是不合法的變數名稱）。

這時候，就需要 FastAPI 內建的 Query() 與 Path() 兩大工具了。

內容大綱

前置知識：正規表達式 (Regex)
為什麼需要 Query() 和 Path()？
Query() 的字串與長度驗證
Query() 解決參數別名與文件說明
使用 Query() 接收多個相同名稱的值
Path() 的數值範圍驗證
將多個查詢參數整合成模型

1. 前置知識：正規表達式 (Regex)

正規表達式（Regular Expression，簡稱 Regex 或 RegExp） 是一種用來「匹配字串模式」的語法。
例如，如果要檢查一個字串是否完全由大寫和小寫的英文字母組成，可以使用正規表達式 ^[a-zA-Z]+$。
FastAPI 允許我們直接把這段模式丟給它，它會自動幫我們檢查前端傳來的字串是否符合規則。

2. 為什麼需要 Query() 和 Path()？

之前在處理 Request Body 時，我們學過可以用 Pydantic 的 Field() 來加上驗證，但查詢參數和路徑參數並不是 Pydantic 模型，它們只是函式的參數。
因此，FastAPI 提供了 Query() 和 Path()，讓你能為這些網址上的參數做到和 Field() 一模一樣的驗證與文件宣告效果！

3. Query() 的字串與長度驗證

假設有一個搜尋 API，希望使用者傳入的關鍵字 q 長度介於 3 到 50 個字元之間，並且只能包含英文字母：

from fastapi import FastAPI, Query
from typing import Optional

app = FastAPI()

@app.get("/search")
def search_items(
 q: Optional[str] = Query(None, min_length=3, max_length=50, pattern="^[a-zA-Z]+$")
):
 return {"results": [{"item_id": "Foo"}, {"item_id": "Bar"}], "q": q}

Query(None, ...) 的第一個參數 None 代表這是選填的預設值，如果這是一個必填參數，可以寫成 Query(...)。
pattern 會在幕後使用 Python 的 re 模組進行正規表達式比對，如果使用者傳了包含數字的 ?q=hello123，FastAPI 會直接回傳 422 錯誤。

4. Query() 解決參數別名與文件說明

有些時候，前端習慣用帶有橫線的參數名稱（如 item-query），但在 Python 中，變數名稱不能有橫線（- 會被當作減號）。這時可以使用 alias（別名）來解決這個衝突。

此外，也可以加上 title、description 甚至標記為 deprecated（已棄用）：

@app.get("/search")
def search_items(
 q: Optional[str] = Query(
 None,
 alias="item-query",
 title="搜尋關鍵字",
 description="輸入想尋找的商品名稱，必須是英文字母。",
 deprecated=True,
 )
):
 return {"results": ["Foo", "Bar"]}

在瀏覽器中，網址必須輸入 http://127.0.0.1:8000/search/?item-query=foo。
在 Python 程式碼中，我們依然使用合法的變數名稱 q 來接收它。
在 Swagger UI 中，這個欄位會顯示詳細的中文說明，並且被畫上一條刪除線，提示開發者這個參數未來可能會被移除（deprecated=True）。

5. 使用 Query() 接收多個相同名稱的值

如果前端想要一次搜尋多個關鍵字，網址可能會長這樣： http://127.0.0.1:8000/items/?q=foo&q=bar

為了讓 FastAPI 把這兩個 q 收集成一個 Python 列表（List），必須明確使用 Query() 來宣告：

@app.get("/items/multi")
def read_items_multi(q: list[str] = Query(default=["apple", "banana"])):
 return {"q_list": q}

如果不加上 Query()（例如唯獨宣告 q: str = None），當網址包含多個相同參數時，FastAPI 只會抓到最後一個值。

錯誤測試範例（只宣告 q: str）：發送請求：GET http://127.0.0.1:8000/items/multi?q=foo&q=bar

{
 "q": "bar"
}

注意：如果在參數寫了 q: list[str] 但卻沒有加上 = Query()，FastAPI 會把 q 當作是要從 JSON Request Body 接收的資料，並拋出錯誤。

加上了 Query() 後，回傳的才會是正確且完整的陣列：

正確測試範例（宣告 q: list[str] = Query(…)）：發送請求：GET http://127.0.0.1:8000/items/multi?q=foo&q=bar

{
 "q_list": [
 "foo",
 "bar"
 ]
}

6. Path() 的數值範圍驗證

Path() 的用法與 Query() 幾乎完全一樣，唯一的差別是：它專門用在路徑參數上。由於路徑參數通常是 ID（數字），最常使用它來做數值範圍的限制。

from fastapi import Path

@app.get("/users/{user_id}")
def get_user(
 user_id: int = Path(..., title="使用者 ID", ge=1, le=1000)
):
 return {"user_id": user_id}

數值驗證參數非常直觀：

ge：Greater than or Equal（大於等於 ≥）
gt：Greater Than（大於 >）
le：Less than or Equal（小於等於 ≤）
lt：Less Than（小於 <）

在這個例子中，如果輸入 /users/0 或 /users/1001，都會被 FastAPI 的驗證機制阻擋下來。

錯誤測試範例：發送請求：GET http://127.0.0.1:8000/users/-14

{
 "detail": [
 {
 "type": "greater_than_equal",
 "loc": [
 "path",
 "user_id"
 ],
 "msg": "Input should be greater than or equal to 1",
 "input": "-14",
 "ctx": {
 "ge": 1
 }
 }
 ]
}

7. 將多個查詢參數整合成模型

如果一個 API 有高達十幾個查詢參數（例如搜尋頁面有分類、價格上下限、排序方式、頁碼…），路由函式的參數列表會變得長得嚇人。

在較新的 FastAPI 版本中，可以把這些「查詢參數」也打包成一個 Pydantic 模型，只要在依賴注入時加上 Depends() 即可。（關於 Depends() 我們會在後面的章節詳細介紹，現在先記住這個好用的寫法）。

from fastapi import Depends
from pydantic import BaseModel, Field

class FilterParams(BaseModel):
 limit: int = Field(100, gt=0, le=100)
 offset: int = Field(0, ge=0)
 order_by: str = "created_at"

@app.get("/products/")
def read_products(filters: FilterParams = Depends()):
 return {"filters": filters}

現在，只要客戶端造訪 /products/?limit=50&offset=10&order_by=price，FastAPI 就會自動幫你把這些散落的查詢參數，組裝成一個漂亮的 FilterParams 物件。

練習題

📝 練習題 1：混合驗證

題目：撰寫一個 GET /books/{book_id} 的端點。

路徑參數 book_id 必須是整數，且大於等於 1。
查詢參數 author 是選填的字串，長度至少 2 個字元。

答案：

from typing import Optional
from fastapi import FastAPI, Path, Query

app = FastAPI()

@app.get("/books/{book_id}")
def get_book(
 book_id: int = Path(..., ge=1),
 author: Optional[str] = Query(None, min_length=2)
):
 return {"book_id": book_id, "author": author}

📝 練習題 2：陣列查詢參數

題目：撰寫一個 GET /tags/ 端點。它可以接收多個同名的查詢參數 tag（例如：?tag=python&tag=web）。請確保 tag 是必填的陣列。

答案：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/tags/")
def get_tags(
 tag: list[str] = Query(...)
):
 return {"tags": tag}

這裡的 Query(...) 中的 ... 代表這是必填的。如果不提供任何 ?tag=，將會拋出 422 錯誤。

Python on YuChen

如何使用 PyAutoGUI（一）：安裝與滑鼠控制

內容大綱

1. PyAutoGUI 基本介紹

2. 安裝 PyAutoGUI

3. 螢幕座標系統

4. 安全機制：Fail-Safe

5. 取得螢幕資訊

6. 滑鼠點擊

點擊 click()：

雙擊 doubleClick()：

右鍵點擊 rightClick()：

中鍵點擊 middleClick()：

分開按下與放開 mouseDown() / mouseUp()：

7. 滑鼠移動

移動到絕對座標 moveTo(x, y, duration=num_seconds)：

移動到相對座標 moveRel(xOffset, yOffset, duration=num_seconds)：

拖曳到絕對座標 dragTo(x, y, duration=num_seconds)：

拖曳到相對座標 dragRel(xOffset, yOffset, duration=num_seconds)：

8. 滾輪操作

垂直滾動 scroll()

水平滾動 hscroll()

練習題

參考資料

學 FastAPI 前你需要知道的事：HTTP 與 API 基礎

內容大綱

1. 什麼是 API？

2. HTTP 協定：請求與回應

一個 HTTP 請求包含什麼？

一個 HTTP 回應包含什麼？

3. HTTP 方法（Method）

4. HTTP 狀態碼

分類規則（第一個數字決定大類）

FastAPI 開發最常見的狀態碼

5. 什麼是 JSON？

JSON 的語法規則

JSON 與 Python dict 的對照

6. 從瀏覽器到 API：完整流程回顧

7. FastAPI 的分工：框架 vs 伺服器

練習題

參考資料

如何使用 FastAPI

內容大綱

1. FastAPI 基本介紹

2. 安裝 FastAPI 與 Uvicorn

3. 建立第一個 FastAPI 應用程式

4. 啟動伺服器與測試

5. 自動產生 API 文件

1. Swagger UI (互動式文件)

2. ReDoc (靜態文件)

練習題

參考資料

如何使用 venv 建立 Python 虛擬環境

內容大綱

1. 什麼是虛擬環境？為何需要它？

2. 建立虛擬環境

3. 進階參數指令 (Options)

4. 啟動與退出虛擬環境

5. 套件的安裝、匯出與批次移除

6. 常見問題與注意事項

參考資料

如何使用 PyAutoGUI（二）：鍵盤控制

內容大綱

1. 文字輸入

typewrite() / write()

2. 單鍵操作：

按下並放開單一按鍵 press()：

按住不放與放開按鍵 keyDown() / keyUp()：

上下文管理器 hold()：

組合鍵與熱鍵 hotkey()：

3. 常用 Key 名稱對照表

4. 訊息彈出視窗

顯示訊息 alert()：

確認視窗 confirm()：

文字輸入視窗 prompt()：

密碼輸入視窗 password()（遮蔽顯示）：

5. 實用範例：自動開啟記事本並輸入文字

練習題

參考資料

如何使用 PyAutoGUI（三）：螢幕截圖與圖像辨識

點擊 `click()`：

雙擊 `doubleClick()`：

右鍵點擊 `rightClick()`：

中鍵點擊 `middleClick()`：

分開按下與放開 `mouseDown()` / `mouseUp()`：

移動到絕對座標 `moveTo(x, y, duration=num_seconds)`：

移動到相對座標 `moveRel(xOffset, yOffset, duration=num_seconds)`：

拖曳到絕對座標 `dragTo(x, y, duration=num_seconds)`：

拖曳到相對座標 `dragRel(xOffset, yOffset, duration=num_seconds)`：

垂直滾動 `scroll()`

水平滾動 `hscroll()`

`typewrite()` / `write()`

按下並放開單一按鍵 `press()`：

按住不放與放開按鍵 `keyDown()` / `keyUp()`：

上下文管理器 `hold()`：

組合鍵與熱鍵 `hotkey()`：

顯示訊息 `alert()`：

確認視窗 `confirm()`：

文字輸入視窗 `prompt()`：

密碼輸入視窗 `password()`（遮蔽顯示）：

全螢幕截圖 `screenshot()`：

區域截圖 `screenshot(region=(...)))`：

尋找圖片位置 `locateOnScreen()`：

取得圖片中心座標 `locateCenterOnScreen()`：

尋找所有符合位置 `locateAllOnScreen()`：

在圖片中搜尋 `locate()`（非螢幕）：

取得指定座標的像素顏色 `pixel()`：

判斷像素顏色是否符合 `pixelMatchesColor()`：

問題 1：`locateOnScreen()` 找不到圖片

7. 使用 `Enum` 限制合法選項