基礎概念

FastAPI 的主要特點

特點	說明
高效能	• 基於 Starlette 和 Uvicorn，性能與 Node.js 和 Go 相當 • 支持異步處理，適合高併發應用
自動資料驗證	• 利用 Python 類型提示（Type Hints）進行自動資料驗證 • 與 Pydantic 深度整合，提供強大的資料模型定義和驗證功能
自動文檔生成	• 自動生成 OpenAPI 文檔 • 內建 Swagger UI 和 ReDoc 介面
開發者友好	• 編輯器支持完善（自動補全、類型檢查） • 清晰的錯誤提示 • 簡潔直觀的 API 設計
標準兼容	• 完全兼容 OpenAPI 和 JSON Schema 標準 • 支持 OAuth2、JWT 等認證機制

OpenAPI 規範（前身為 Swagger）是一個用於描述 RESTful API 的標準化規範。它定義了一種與程式語言無關的標準格式，用於描述 API 的結構、行為和能力。

概念	說明
API 描述文檔	• 使用 JSON 或 YAML 格式定義 • 包含 API 的所有方面：端點、操作、參數、響應等
主要組成部分	• Info 對象：提供 API 的元數據，如標題、描述、版本等 • Paths 對象：定義 API 的端點和操作 • Components 對象：定義可重用的 Schema 組件 • Security 對象：定義安全機制
資料模型定義	• 使用 JSON Schema 定義請求和響應的資料結構 • 支持複雜的資料類型和驗證規則
文檔生成	• 可以從 OpenAPI Schema 自動生成交互式文檔 • 常用工具包括 Swagger UI、ReDoc 等

FastAPI 與 OpenAPI 之間存在密切的關係，這是 FastAPI 框架的核心優勢之一。

特點	說明
從代碼到文檔	• FastAPI 分析您的路由函數、參數類型和 Pydantic 模型 • 自動生成完整的 OpenAPI Schema • 無需手動編寫文檔或註釋
即時更新	• 當代碼變更時，文檔自動更新 • 確保文檔與實際 API 行為始終同步

驗證類型	說明
請求驗證	• 根據定義的參數類型和約束驗證傳入的請求 • 自動將 JSON 請求體轉換為 Python 對象 • 提供清晰的錯誤訊息
響應驗證	• 可以使用 `response_model` 參數驗證響應 • 確保返回的資料符合定義的模型

界面	特點
Swagger UI	• 默認在 `/docs` 路徑可用 • 提供交互式 API 測試功能 • 顯示詳細的參數和響應信息
ReDoc	• 默認在 `/redoc` 路徑可用 • 提供更適合閱讀的文檔格式 • 清晰展示 API 結構和模型定義

轉變	說明
API 優先設計	• 可以先定義模型和端點，再實現業務邏輯 • 促進更清晰的 API 設計
契約驅動開發	• API 定義作為前後端開發的契約 • 前端可以基於 OpenAPI 文檔開始開發，無需等待後端完成
減少文檔維護成本	• 不需要單獨維護 API 文檔 • 減少文檔與代碼不同步的風險

框架/標準	主要優勢
FastAPI	• 開發效率高：簡潔語法，減少樣板代碼 • 自動化程度高：資料驗證和文檔生成 • 高性能：基於 Starlette，支持異步處理
OpenAPI	• 標準化：廣泛接受的 API 描述標準 • 豐富工具生態：客戶端生成、測試工具等 • 提高可維護性：清晰文檔，促進團隊協作

場景	適用原因
微服務架構	• 清晰的 API 契約對微服務間的通信至關重要 • 自動文檔生成簡化服務集成
公開 API	• 提供給第三方使用的 API 需要清晰的文檔 • 標準化的描述促進 API 的採用
大型團隊協作	• 前後端分離開發模式 • 明確的 API 契約減少溝通成本
需要嚴格資料驗證的應用	• 金融、醫療等對資料準確性要求高的領域 • 自動驗證減少錯誤風險

通過 FastAPI 和 OpenAPI 的結合，開發者可以構建高效、可靠且文檔完善的 API。這種方式不僅提高了開發效率，還增強了 API 的可用性和可維護性，使其成為現代 API 開發的理想選擇。