FastAPI 教程

FastAPI 框架，高性能，易于學習，高效編碼，生產可用

---

文檔： https://fastapi.tiangolo.com

源碼： https://github.com/tiangolo/fastapi

---

FastAPI 是一個用于構建 API 的現代、快速（高性能）的 web 框架，使用 Python 3.6+ 并基于標準的 Python 類型提示。

關鍵特性:

• 快速：可與 NodeJS 和 Go 比肩的極高性能（歸功于 Starlette 和 Pydantic）。最快的 Python web 框架之一。

• 高效編碼：提高功能開發速度約 200％ 至 300％。*

• 更少 bug：減少約 40％ 的人為（開發者）導致錯誤。*
• 智能：極佳的編輯器支持。處處皆可自動補全，減少調試時間。
• 簡單：設計的易于使用和學習，閱讀文檔的時間更短。
• 簡短：使代碼重復最小化。通過不同的參數聲明實現豐富功能。bug 更少。
• 健壯：生產可用級別的代碼。還有自動生成的交互式文檔。
• 標準化：基于（并完全兼容）API 的相關開放標準：OpenAPI (以前被稱為 Swagger) 和 JSON Schema。

* 根據對某個構建線上應用的內部開發團隊所進行的測試估算得出。

---

Typer，命令行中的 FastAPI

如果你正在開發一個在終端中運行的命令行應用而不是 web API，不妨試下 Typer。

Typer 是 FastAPI 的小同胞。它想要成為命令行中的 FastAPI。 

依賴

Python 3.6 及更高版本

FastAPI 站在以下巨人的肩膀之上：

• Starlette 負責 web 部分。
• Pydantic 負責數據部分。

安裝

在命令提示符（macOS或者Linux的終端）中使用pip安裝FastAPI：

pip install fastapi
████████████████████████████████████████ 100%

安裝完FastAPI后還需要一個 ASGI 服務器來運行相應的代碼，生產環境可以使用 Uvicorn 或者 Hypercorn。

安裝方法也是在命令提示符中使用pip進行安裝：

pip install uvicorn
████████████████████████████████████████ 100%

示例

創建

• 創建一個 main.py 文件并寫入以下內容:

from typing import Optional

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: Optional[str] = None):
    return {"item_id": item_id, "q": q}

或者使用 async def...

如果你的代碼里會出現 async / await，請使用 async def：

from typing import Optional

from fastapi import FastAPI

app = FastAPI()


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


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

如果你不知道是否會用到，可以查看文檔的 并發和異步/等待 章節中 關于 async 和 await 的部分。

運行

通過以下命令運行服務器：

uvicorn main:app --reload

uvicorn main:app --reload
    
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.

 注意：當8000端口被占用時，使用該指令會報錯：[WinError 10013] 以一種訪問權限不允許的方式做了一個訪問套接字的嘗試。這是由于8000端口被占用導致的，可以通過更改啟動的端口或者kill使用8000端口的應用來解決：

1. kill應用的方式:在Windows環境下使用netstat -aon|findstr "8000"查看占用8000端口的應用的PID，然后在任務管理器中找到對應應用結束。
2. 改變啟動端口方式（更通用）：在啟動命令后加--port來改變啟動端口,例如 uvicorn main:app --reload --port 18080

關于uvicorn main:app --reload --port 18080命令

uvicorn main:app命令含義如下:

• main：main.py文件（一個 Python "模塊"）。
• app：在 main.py 文件中通過 app = FastAPI() 創建的對象。
• --reload：讓服務器在更新代碼后重新啟動。僅在開發時使用該選項。
• --port:指定啟動的端口，該代碼中指定了18080端口。

檢查

使用瀏覽器訪問 http://127.0.0.1:8000/items/5?q=somequery。

你將會看到如下 JSON 響應：

{"item_id": 5, "q": "somequery"}

你已經創建了一個具有以下功能的 API：

• 通過 路徑 / 和 /items/{item_id} 接受 HTTP 請求。
• 以上 路徑 都接受 GET 操作（也被稱為 HTTP 方法）。
• /items/{item_id} 路徑 有一個 路徑參數 item_id 并且應該為 int 類型。
• /items/{item_id} 路徑 有一個可選的 str 類型的 查詢參數 q。

交互式 API 文檔

現在訪問 http://127.0.0.1:8000/docs。

你會看到自動生成的交互式 API 文檔（由 Swagger UI生成）：

可選的 API 文檔

訪問 http://127.0.0.1:8000/redoc。

你會看到另一個自動生成的文檔（由 ReDoc 生成）：

示例升級

現在修改 main.py 文件來從 PUT 請求中接收請求體。

我們借助 Pydantic 來使用標準的 Python 類型聲明請求體。

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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


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


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


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

服務器將會自動重載（因為在上面的步驟中你向 uvicorn 命令添加了 --reload 選項）。

交互式 API 文檔升級

訪問 http://127.0.0.1:8000/docs。

• 交互式 API 文檔將會自動更新，并加入新的請求體：

• 點擊「Try it out」按鈕，之后你可以填寫參數并直接調用 API：

• 然后點擊「Execute」按鈕，用戶界面將會和 API 進行通信，發送參數，獲取結果并在屏幕上展示：

可選文檔升級

訪問 http://127.0.0.1:8000/redoc。

• 可選文檔同樣會體現新加入的請求參數和請求體：

總結

總的來說，你就像聲明函數的參數類型一樣只聲明了一次請求參數、請求體等的類型。

你使用了標準的現代 Python 類型來完成聲明。

你不需要去學習新的語法、了解特定庫的方法或類，等等。

只需要使用標準的 Python 3.6 及更高版本。

舉個例子，比如聲明 int 類型：

item_id: int

或者一個更復雜的 Item 模型：

item: Item

......在進行一次聲明之后，你將獲得：

編輯器支持，包括：

• 自動補全 
• 類型檢查

數據校驗：

• 在校驗失敗時自動生成清晰的錯誤信息。
• 對多層嵌套的 JSON 對象依然執行校驗

轉換 來自網絡請求的輸入數據為 Python 數據類型。包括以下數據：

• JSON
• 路徑參數
• 查詢參數
• Cookies
• 請求頭
• 表單文件

轉換輸出的數據：轉換 Python 數據類型為供網絡傳輸的 JSON 數據：

• 轉換 Python 基礎類型 （str、 int、 float、 bool、 list 等）
• datetime 對象
• UUID 對象
• 數據庫模型
• .....以及更多其他類型

自動生成的交互式 API 文檔，包括兩種可選的用戶界面：

• Swagger UI
• ReDoc

回到前面的代碼示例，FastAPI 將會：

• 校驗 GET 和 PUT 請求的路徑中是否含有 item_id。
• 校驗 GET 和 PUT 請求中的 item_id 是否為 int 類型。
  • 如果不是，客戶端將會收到清晰有用的錯誤信息。
• 檢查 GET 請求中是否有命名為 q 的可選查詢參數（比如 http://127.0.0.1:8000/items/foo?q=somequery）。
  • 因為 q 被聲明為 = None，所以它是可選的。
  • 如果沒有 None 它將會是必需的 (如 PUT 例子中的請求體)。
• 對于訪問 /items/{item_id} 的 PUT 請求，將請求體讀取為 JSON ，同時：
  • 檢查是否有必需屬性 name 并且值為 str 類型 。
  • 檢查是否有必需屬性 price 并且值為 float 類型。
  • 檢查是否有可選屬性 is_offer， 如果有的話值應該為 bool 類型。
  • 以上過程對于多層嵌套的 JSON 對象同樣也會執行
• 自動對 JSON 進行轉換或轉換成 JSON。
• 通過 OpenAPI 文檔來記錄所有內容，可被用于：
  • 交互式文檔系統
  • 許多編程語言的客戶端代碼自動生成系統
• 直接提供 2 種交互式文檔 web 界面。

雖然我們才剛剛開始，但其實你已經了解了這一切是如何工作的。

嘗試更改下面這行代碼：

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

......從：

        ... "item_name": item.name ...

......改為：

        ... "item_price": item.price ...

......注意觀察編輯器是如何自動補全屬性并且還知道它們的類型：

教程 - 用戶指南 中有包含更多特性的更完整示例。

劇透警告： 教程 - 用戶指南中的內容有：

• 對來自不同地方的參數進行聲明，如：請求頭、cookies、form 表單以及上傳的文件。
• 如何設置校驗約束如 maximum_length 或者 regex。
• 一個強大并易于使用的 依賴注入 系統。
• 安全性和身份驗證，包括通過 JWT 令牌和 HTTP 基本身份認證來支持 OAuth2。
• 更進階（但同樣簡單）的技巧來聲明 多層嵌套 JSON 模型 （借助 Pydantic）。
• 許多額外功能（歸功于 Starlette）比如：
  • WebSockets
  • GraphQL
  • 基于 requests 和 pytest 的極其簡單的測試
  • CORS
  • Cookie Sessions
  • ......以及更多

性能

獨立機構 TechEmpower 所作的基準測試結果顯示，基于 Uvicorn 運行的 FastAPI 程序是 最快的 Python web 框架之一，僅次于 Starlette 和 Uvicorn 本身（FastAPI 內部使用了它們）。(*)

想了解更多，請查閱 基準測試 章節。

可選依賴

用于 Pydantic：

• ujson - 更快的 JSON 「解析」。
• email_validator - 用于 email 校驗。

用于 Starlette：

• requests - 使用 TestClient 時安裝。
• aiofiles - 使用 FileResponse 或 StaticFiles 時安裝。
• jinja2 - 使用默認模板配置時安裝。
• python-multipart - 需要通過 request.form() 對表單進行「解析」時安裝。
• itsdangerous - 需要 SessionMiddleware 支持時安裝。
• pyyaml - 使用 Starlette 提供的 SchemaGenerator 時安裝（有 FastAPI 你可能并不需要它）。
• graphene - 需要 GraphQLApp 支持時安裝。
• ujson - 使用 UJSONResponse 時安裝。

用于 FastAPI / Starlette：

• uvicorn - 用于加載和運行你的應用程序的服務器。
• orjson - 使用 ORJSONResponse 時安裝。

你可以通過 pip install fastapi[all] 命令來安裝以上所有依賴。

許可協議

該項目遵循 MIT 許可協議。

領取免費資料

掃描下方二維碼或打開微信搜一搜“w3cschool編程獅”關注公眾號回復關鍵詞【Python123】或者【Python資料包】免費領取 Python 學習資料，包含軟件安裝包，電子書、思維導圖等