FastAPI on YuChen

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

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

內容大綱

什麼是 API？
HTTP 協定：請求與回應
HTTP 方法（Method）
HTTP 狀態碼
什麼是 JSON？
從瀏覽器到 API：完整流程回顧
FastAPI 的分工：框架 vs 伺服器

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

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 官方教學 - 使用者指南

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 錯誤。

FastAPI on YuChen

學 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 (靜態文件)

練習題

參考資料

FastAPI 路徑參數

內容大綱

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

2. 什麼是路徑參數？

3. 宣告路徑參數

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

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

6. 路徑順序的重要性

7. 使用 Enum 限制合法選項

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

練習題

參考資料

FastAPI 查詢參數

內容大綱

1. 什麼是查詢參數？

2. 宣告查詢參數

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

4. 必填的查詢參數

5. 使用 Optional 表示可選欄位

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

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

練習題

參考資料

FastAPI Request Body

內容大綱

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

2. 什麼是 Request Body？

3. 建立第一個 Pydantic 模型

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

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

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

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

8. Pydantic 的自動驗證機制

練習題

參考資料

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

內容大綱

1. 同時接收多個 Body 參數

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

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

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

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

練習題

參考資料

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

內容大綱

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

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

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

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

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

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