FastAPI 基礎概念（Fundamentals）

建立第一個 FastAPI 應用（Hello World）

---

簡介

在現代的 Web 開發中，API（Application Programming Interface） 已成為前後端、微服務以及行動應用溝通的核心橋樑。FastAPI 以 高效能、易用性 與 自動產生文件 為賣點，讓開發者能在短時間內寫出符合 OpenAPI 標準的 RESTful 服務。即使是剛踏入 Python Web 開發的新人，也能在幾分鐘內完成「Hello World」的示範，進而體驗 FastAPI 帶來的開發快感。

本單元的目標是從零開始，一步步帶領讀者建立第一個 FastAPI 應用，了解核心概念、常見陷阱與最佳實踐，並探討實務上可以如何把這個簡單範例延伸到真實專案中。

---

核心概念

1. FastAPI 是什麼？

FastAPI 是一個基於 Starlette（非同步網路框架）與 Pydantic（資料驗證）構建的 Python 框架。它的核心特性包括：

• 自動產生 OpenAPI（Swagger）文件：只要寫好路由與型別註解，文件即時生成。
• 支援非同步（async）程式：可直接使用 async def，配合 await 呼叫 I/O 密集型任務，效能媲美 Node.js、Go。
• 型別安全：透過 Python 3.6+ 的型別提示（type hints），在開發階段即捕捉錯誤，提升程式碼可讀性與維護性。

2. 安裝與環境設定

在開始撰寫程式之前，先建立一個乾淨的 virtual environment（建議使用 venv 或 conda），再安裝 FastAPI 與 Uvicorn（ASGI 伺服器）：

# 建立虛擬環境（以 venv 為例）
python -m venv .venv
source .venv/bin/activate   # Windows 使用 .venv\Scripts\activate

# 安裝 FastAPI 與 Uvicorn
pip install fastapi uvicorn

Tip：若需要在開發階段即時重載（auto‑reload），可以安裝 uvicorn[standard]，或在執行指令加入 --reload 參數。

3. 建立第一個「Hello World」應用

以下是一個最小可執行的 FastAPI 程式，說明了 路由（Route）、回傳 JSON 與 啟動伺服器 的完整流程。

# hello.py
from fastapi import FastAPI

# 建立 FastAPI 實例
app = FastAPI()

# 設定根路由（GET /）
@app.get("/")
def read_root():
    """
    回傳一段簡單的文字，示範最基本的 GET 請求。
    """
    return {"message": "Hello, FastAPI!"}

啟動應用：

uvicorn hello:app --reload

• hello 為檔案名稱（不含 .py），app 為 FastAPI 實例的變數名。
• --reload 讓程式碼變動時自動重新載入，開發時非常便利。

開啟瀏覽器並前往 http://127.0.0.1:8000/，即可看到 JSON 回傳：

{
  "message": "Hello, FastAPI!"
}

4. 路由的多樣寫法

FastAPI 支援多種 HTTP 方法（GET、POST、PUT、DELETE…），以下示範 三種常見的路由寫法：

(1) Path Parameter（路徑參數）

@app.get("/items/{item_id}")
def read_item(item_id: int):
    """
    取得單一商品資訊，item_id 會自動轉型為 int。
    """
    return {"item_id": item_id, "detail": f"Item #{item_id} 的資訊"}

(2) Query Parameter（查詢參數）

@app.get("/search")
def search(q: str = None, limit: int = 10):
    """
    q 為搜尋關鍵字，limit 控制回傳筆數，皆為可選參數。
    """
    return {"query": q, "limit": limit}

(3) Request Body（請求本文）— 使用 Pydantic Model

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None   # 可為 None

@app.post("/items/")
def create_item(item: Item):
    """
    透過 POST 建立新商品，FastAPI 會自動把 JSON 轉成 Item 物件。
    """
    return {"message": "Item created", "item": item}

註解：以上三個範例展示了 型別提示（type hints）如何與 FastAPI 緊密結合，讓框架在執行時自動完成資料驗證與轉型。

5. 自動產生的 API 文件

啟動伺服器後，FastAPI 會在兩個預設路徑提供互動式文件：

• Swagger UI：http://127.0.0.1:8000/docs
• ReDoc：http://127.0.0.1:8000/redoc

只要在程式碼中寫好型別與 docstring，就能即時在 UI 中看到參數說明、範例回傳與測試介面，極大提升 API 開發與溝通效率。

---

常見陷阱與最佳實踐

陷阱	可能的結果	改善方式
忘記使用 async	同步函式在大量 I/O 時會阻塞，效能下降。	需要非同步 I/O（如資料庫、外部 API）時，將路由改為 async def，並使用支援 async 的套件。
過度使用全域變數	多執行緒/多工作者環境下會產生 race condition。	把需要共用的資源（DB 連線、設定）封裝成 依賴注入（Depends） 或使用 ContextVar。
未設定回傳模型	Swagger 文件缺乏結構，前端開發者不易了解回傳格式。	使用 response_model=YourModel 明確描述回傳資料結構，FastAPI 會自動產生文件與資料驗證。
直接拋出 Python 例外	客戶端會收到 500 錯誤，且資訊過於模糊。	使用 HTTPException(status_code=..., detail=...) 回傳符合 HTTP 規範的錯誤訊息。
忽略 CORS 設定	前端跨域請求會被瀏覽器阻擋。	加入 fastapi.middleware.cors.CORSMiddleware，設定允許的來源、方法與標頭。

最佳實踐清單

1. 型別安全：盡量為每個參數、回傳值加上型別註解與 Pydantic 模型。
2. 依賴注入：使用 Depends 管理資料庫、認證、設定等資源，保持程式碼單一職責。
3. 環境變數：將敏感資訊（DB 密碼、API 金鑰）放在 .env，配合 python-dotenv 讀取。
4. 測試：利用 TestClient 撰寫單元測試，確保路由行為符合預期。
5. 日誌：使用 logging 或 structlog 記錄請求與錯誤，方便排錯與監控。

---

實際應用場景

場景	為什麼選 FastAPI	如何從「Hello World」擴充
微服務	輕量、非同步、易於部署（Docker）	把每個功能拆成獨立的 router，使用 APIRouter 進行模組化。
資料科學模型服務	支援大型檔案上傳、非同步推論	在 POST /predict 中接受檔案，使用 async def 呼叫模型推論，回傳 JSON 結果。
行動 App 後端	自動產生 Swagger，前端可以直接對照文件開發	使用 JWT 認證（fastapi.security），在路由上加上 Depends(get_current_user)。
即時資料串流	結合 WebSocket（Starlette 原生支援）	在 FastAPI 中加入 @app.websocket("/ws")，實作雙向即時通訊。

---

總結

本篇文章從 安裝環境、撰寫第一個 Hello World、路由多樣寫法、自動產生文件，一路帶領讀者掌握 FastAPI 的核心概念。透過表格列出常見陷阱與最佳實踐，並提供多個實務應用場景，讓你在完成「Hello World」後，能快速將這個微型範例升級為可投入生產的 API 服務。

重點回顧

• FastAPI 以 型別提示 + Pydantic 為基礎，提供即時驗證與文件生成。
• 使用 async 可充分發揮非同步效能，避免 I/O 阻塞。
• 依賴注入、環境變數與日誌是打造可維護系統的必備工具。

只要掌握上述概念，你就能在 幾分鐘內 建立一個功能完整、文件自動化、效能優異的 API，為後續的微服務、機器學習部署或行動後端奠定堅實基礎。祝開發順利，玩得開心！ 🚀