# FastAPI { #fastapi }
FastAPI 框架，高效能，易於學習，快速開發，適用於生產環境
---
**文件**： https://fastapi.tiangolo.com/zh-hant
**程式碼**： https://github.com/fastapi/fastapi
---
FastAPI 是一個現代、快速（高效能）的 Web 框架，用於以 Python 並基於標準的 Python 型別提示來構建 API。
主要特點包含：
* **快速**：非常高的效能，可與 **NodeJS** 和 **Go** 相當（歸功於 Starlette 和 Pydantic）。[最快的 Python 框架之一](#performance)。
* **極速開發**：開發功能的速度可提升約 200% 至 300%。*
* **更少的 Bug**：減少約 40% 的人為（開發者）錯誤。*
* **直覺**：具有出色的編輯器支援，處處都有 自動補全。更少的偵錯時間。
* **簡單**：設計上易於使用與學習。更少的讀文件時間。
* **簡潔**：最小化程式碼重複性。每個參數宣告可帶來多個功能。更少的錯誤。
* **穩健**：立即獲得可投入生產的程式碼，並自動生成互動式文件。
* **標準化**：基於（且完全相容於）API 的開放標準：OpenAPI（之前稱為 Swagger）和 JSON Schema。
* 基於內部開發團隊在建立生產應用程式時的測試預估。
## 贊助 { #sponsors }
### 基石贊助商 { #keystone-sponsor }
{% for sponsor in sponsors.keystone -%}
{% endfor -%}
### 金級與銀級贊助商 { #gold-and-silver-sponsors }
{% for sponsor in sponsors.gold -%}
{% endfor -%}
{%- for sponsor in sponsors.silver -%}
{% endfor %}
其他贊助商
## 評價 { #opinions }
"_[...] 近期大量使用 **FastAPI**。[...] 我實際上打算在我在**微軟**團隊的所有**機器學習**服務上使用它。其中一些正在整合到核心的 **Windows** 產品，以及一些 **Office** 產品。_"
Kabir Khan -
Microsoft (ref)Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala -
Uber (ref)Kevin Glisson, Marc Vilanova, Forest Monsen -
Netflix (ref)Deon Pillsbury -
Cisco (ref)
## **Typer**，命令列的 FastAPI { #typer-the-fastapi-of-clis }
如果你不是在做 Web API，而是要建立一個在終端機中使用的 CLI 應用程式，可以看看 **Typer**。
**Typer** 是 FastAPI 的小老弟。他立志成為命令列世界的 **FastAPI**。⌨️ 🚀
## 需求 { #requirements }
FastAPI 是站在以下巨人的肩膀上：
* Starlette 負責 Web 部分。
* Pydantic 負責資料部分。
## 安裝 { #installation }
建立並啟用一個虛擬環境，然後安裝 FastAPI：
```console
$ pip install "fastapi[standard]"
---> 100%
```
**注意**：請務必將 `"fastapi[standard]"` 用引號包起來，以確保在所有終端機中都能正常運作。
## 範例 { #example }
### 建立 { #create-it }
建立檔案 `main.py`，內容如下：
```Python
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 = None):
return {"item_id": item_id, "q": q}
```
或使用 async def...
如果你的程式碼使用 `async` / `await`，請使用 `async def`：
```Python hl_lines="7 12"
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: str | None = None):
return {"item_id": item_id, "q": q}
```
**注意**：
如果你不確定，請查看文件中 _"In a hurry?"_ 章節的 `async` 與 `await`。
### 運行 { #run-it }
使用以下指令運行伺服器：
```console
$ fastapi dev main.py
╭────────── FastAPI CLI - Development mode ───────────╮
│ │
│ Serving at: http://127.0.0.1:8000 │
│ │
│ API docs: http://127.0.0.1:8000/docs │
│ │
│ Running in development mode, for production use: │
│ │
│ fastapi run │
│ │
╰─────────────────────────────────────────────────────╯
INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp']
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [2248755] using WatchFiles
INFO: Started server process [2248757]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
關於指令 fastapi dev main.py...
指令 `fastapi dev` 會讀取你的 `main.py`，偵測其中的 **FastAPI** 應用，並使用 Uvicorn 啟動伺服器。
預設情況下，`fastapi dev` 會在本機開發時啟用自動重新載入。
可在 FastAPI CLI 文件中閱讀更多資訊。
### 檢查 { #check-it }
使用瀏覽器開啟 http://127.0.0.1:8000/items/5?q=somequery。
你將會看到以下 JSON 回應：
```JSON
{"item_id": 5, "q": "somequery"}
```
你已經建立了一個具有以下功能的 API：
* 透過路徑 `/` 和 `/items/{item_id}` 接受 HTTP 請求。
* 以上兩個路徑都接受 `GET` 操作（也被稱為 HTTP _方法_）。
* 路徑 `/items/{item_id}` 有一個 `int` 型別的路徑參數 `item_id`。
* 路徑 `/items/{item_id}` 有一個可選的 `str` 查詢參數 `q`。
### 互動式 API 文件 { #interactive-api-docs }
接著前往 http://127.0.0.1:8000/docs。
你會看到自動生成的互動式 API 文件（由 Swagger UI 提供）：
### 替代 API 文件 { #alternative-api-docs }
現在前往 http://127.0.0.1:8000/redoc。
你會看到另一種自動文件（由 ReDoc 提供）：
## 範例升級 { #example-upgrade }
現在修改 `main.py` 檔案，使其能從 `PUT` 請求接收 body。
多虧了 Pydantic，你可以用標準的 Python 型別來宣告 body。
```Python hl_lines="2 7-10 23-25"
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
price: float
is_offer: bool | None = None
@app.get("/")
def read_root():
return {"Hello": "World"}
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = 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}
```
`fastapi dev` 伺服器應會自動重新載入。
### 互動式 API 文件升級 { #interactive-api-docs-upgrade }
前往 http://127.0.0.1:8000/docs。
* 互動式 API 文件會自動更新，包含新的 body：
* 點擊「Try it out」按鈕，你可以填寫參數並直接與 API 互動：
* 然後點擊「Execute」按鈕，使用者介面會與你的 API 溝通、送出參數、取得結果並顯示在螢幕上：
### 替代 API 文件升級 { #alternative-api-docs-upgrade }
現在前往 http://127.0.0.1:8000/redoc。
* 替代文件也會反映新的查詢參數與 body：
### 總結 { #recap }
總結來說，你只需在函式參數中**一次**宣告參數、body 等的型別。
你使用的是現代標準的 Python 型別。
你不需要學新的語法、特定函式庫的方法或類別，等等。
就用標準的 **Python**。
例如，對於一個 `int`：
```Python
item_id: int
```
或是一個更複雜的 `Item` 模型：
```Python
item: Item
```
…透過一次宣告，你將獲得：
* 編輯器支援，包括：
* 自動補全。
* 型別檢查。
* 資料驗證：
* 當資料無效時，自動且清楚的錯誤。
* 即使是深度巢狀的 JSON 物件也能驗證。
* 輸入資料的 轉換：從網路讀入到 Python 資料與型別。包含：
* JSON。
* 路徑參數。
* 查詢參數。
* Cookies。
* 標頭。
* 表單。
* 檔案。
* 輸出資料的 轉換：從 Python 資料與型別轉換為網路資料（JSON）：
* 轉換 Python 型別（`str`、`int`、`float`、`bool`、`list` 等）。
* `datetime` 物件。
* `UUID` 物件。
* 資料庫模型。
* ...還有更多。
* 自動生成的互動式 API 文件，包含 2 種替代的使用者介面：
* 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` 時的 body）。
* 對於 `/items/{item_id}` 的 `PUT` 請求，以 JSON 讀取 body：
* 檢查是否有必填屬性 `name`，且為 `str`。
* 檢查是否有必填屬性 `price`，且為 `float`。
* 檢查是否有可選屬性 `is_offer`，若存在則應為 `bool`。
* 以上也適用於深度巢狀的 JSON 物件。
* 自動在 JSON 與 Python 之間轉換。
* 以 OpenAPI 記錄所有內容，可用於：
* 互動式文件系統。
* 為多種語言自動產生用戶端程式碼的系統。
* 直接提供兩種互動式文件網頁介面。
---
我們只觸及了表面，但你已經了解它的運作方式了。
試著把這一行：
```Python
return {"item_name": item.name, "item_id": item_id}
```
…從：
```Python
... "item_name": item.name ...
```
…改為：
```Python
... "item_price": item.price ...
```
…然後看看你的編輯器如何自動補全屬性並知道它們的型別：
若想看包含更多功能的完整範例，請參考 教學 - 使用者指南。
**劇透警告**：教學 - 使用者指南包含：
* 來自不同來源的**參數**宣告：例如 **headers**、**cookies**、**form fields** 和 **files**。
* 如何設定**驗證限制**，如 `maximum_length` 或 `regex`。
* 一個非常強大且易用的 **依賴注入** 系統。
* 安全與驗證，包含支援 **OAuth2** 搭配 **JWT tokens** 與 **HTTP Basic** 驗證。
* 宣告**深度巢狀 JSON 模型**的進階（但同樣簡單）技巧（感謝 Pydantic）。
* 與 Strawberry 及其他函式庫的 **GraphQL** 整合。
* 許多額外功能（感謝 Starlette），例如：
* **WebSockets**
* 基於 HTTPX 與 `pytest` 的極其簡單的測試
* **CORS**
* **Cookie Sessions**
* ...以及更多。
### 部署你的應用（可選） { #deploy-your-app-optional }
你也可以選擇將 FastAPI 應用部署到 FastAPI Cloud，如果你還沒加入，去登記等候名單吧。🚀
如果你已經有 **FastAPI Cloud** 帳號（我們已從等候名單邀請你 😉），你可以用一個指令部署你的應用。
部署前，先確認你已登入：
```console
$ fastapi login
You are logged in to FastAPI Cloud 🚀
```
接著部署你的應用：
```console
$ fastapi deploy
Deploying to FastAPI Cloud...
✅ Deployment successful!
🐔 Ready the chicken! Your app is ready at https://myapp.fastapicloud.dev
```
就這樣！現在你可以在該 URL 造訪你的應用。✨
#### 關於 FastAPI Cloud { #about-fastapi-cloud }
**FastAPI Cloud** 由 **FastAPI** 的同一位作者與團隊打造。
它讓你以最小的努力精簡地完成 API 的**建置**、**部署**與**存取**流程。
它把用 FastAPI 開發應用的**開發者體驗**帶到**部署**到雲端的流程中。🎉
FastAPI Cloud 是「FastAPI 與好朋友們」這些開源專案的主要贊助與資金來源。✨
#### 部署到其他雲端供應商 { #deploy-to-other-cloud-providers }
FastAPI 是開源且基於標準。你可以把 FastAPI 應用部署到任何你選擇的雲端供應商。
依照你雲端供應商的指南來部署 FastAPI 應用吧。🤓
## 效能 { #performance }
獨立的 TechEmpower 基準測試顯示，在 Uvicorn 下運行的 **FastAPI** 應用是最快的 Python 框架之一，僅次於 Starlette 與 Uvicorn 本身（FastAPI 內部使用它們）。(*)
想了解更多，請參閱測試結果。
## 依賴套件 { #dependencies }
FastAPI 依賴 Pydantic 與 Starlette。
### `standard` 依賴套件 { #standard-dependencies }
當你以 `pip install "fastapi[standard]"` 安裝 FastAPI 時，會包含 `standard` 這組可選依賴套件：
Pydantic 會使用：
* email-validator - 用於電子郵件驗證。
Starlette 會使用：
* httpx - 若要使用 `TestClient` 必須安裝。
* jinja2 - 若要使用預設的模板設定必須安裝。
* python-multipart - 若要支援表單 "解析"，搭配 `request.form()`。
FastAPI 會使用：
* uvicorn - 用於載入並服務你的應用的伺服器。這包含 `uvicorn[standard]`，其中含有一些高效能服務所需的依賴（例如 `uvloop`）。
* `fastapi-cli[standard]` - 提供 `fastapi` 指令。
* 其中包含 `fastapi-cloud-cli`，可讓你將 FastAPI 應用部署到 FastAPI Cloud。
### 不含 `standard` 依賴套件 { #without-standard-dependencies }
如果你不想包含 `standard` 可選依賴，可以改用 `pip install fastapi`（而不是 `pip install "fastapi[standard]"`）。
### 不含 `fastapi-cloud-cli` { #without-fastapi-cloud-cli }
如果你想安裝帶有 standard 依賴、但不包含 `fastapi-cloud-cli`，可以使用 `pip install "fastapi[standard-no-fastapi-cloud-cli]"`。
### 額外可選依賴套件 { #additional-optional-dependencies }
有些額外依賴你可能也會想安裝。
Pydantic 的額外可選依賴：
* pydantic-settings - 設定管理。
* pydantic-extra-types - 與 Pydantic 一起使用的額外型別。
FastAPI 的額外可選依賴：
* orjson - 若要使用 `ORJSONResponse` 必須安裝。
* ujson - 若要使用 `UJSONResponse` 必須安裝。
## 授權 { #license }
本專案以 MIT 授權條款釋出。