• 目錄

理解「寫出能動的 API」和「寫出可靠的 API」的差異，在資料進入系統前先把關，並用測試確保邏輯正確。

Data Validation

為什麼需要驗證？

回想前一堂課寫的筆記 CRUD，我們從使用者的角度可以考慮以下情境：

• 使用者建立筆記時，title 傳了空字串 ""
• GET /notes/{id} 的 id 被傳入 "ㄅㄆㄇ"
• content 被傳入一段 10 萬字的文字

這樣的情況下我們的 API 會有什麼反應？如果沒有做驗證，可能會發生以下的問題：

• 把空字串存進資料庫，產生無意義的資料
• 因為型別錯誤而發生 500 Server Error
• 讓資料庫儲存不合理的大量資料

因此，驗證的目的是在資料進入系統之前先把關，把錯誤擋在門口。

<aside> <img src="/icons/chat_gray.svg" alt="/icons/chat_gray.svg" width="40px" />

為什麼不應該回傳 500 Server Error？

HTTP status code 是有意義的溝通語言，在上述情況中實際導致錯誤的是使用者輸入錯誤的資料，但回傳 500 會誤以為是伺服器自己出了問題，前端也很難根據 500 做出正確的錯誤處理。

</aside>

應該在哪裡驗證？

Frontend (React / Browser)
        ↓ HTTP Request
API (FastAPI Route)
        ↓
Pydantic（驗證資料）
        ↓
ORM（SQLAlchemy）
        ↓
Database（PostgreSQL）
        ↓
ORM
        ↓
Pydantic
        ↓ HTTP Response (JSON)
Frontend

FastAPI 搭配 Pydantic 讓我們可以在 Controller 層用宣告式的方式完成驗證，而不是等資料已經存進 Database 才進行驗證。

以筆記的 POST /notes 為例：