FastAPI教程 請求體

當你需要將數據從客戶端（例如瀏覽器）發(fā)送給 API 時，你將其作為「請求體」發(fā)送。

請求體是客戶端發(fā)送給 API 的數據。響應體是 API 發(fā)送給客戶端的數據。

你的 API 幾乎總是要發(fā)送響應體。但是客戶端并不總是需要發(fā)送請求體。

我們使用 Pydantic 模型來聲明請求體，并能夠獲得它們所具有的所有能力和優(yōu)點。

你不能使用 GET 操作（HTTP 方法）發(fā)送請求體。
要發(fā)送數據，你必須使用下列方法之一：POST（較常見）、PUT、DELETE 或 PATCH。

導入 Pydantic 的 BaseModel

首先，你需要從 pydantic 中導入 BaseModel：

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

創(chuàng)建數據模型

然后，將你的數據模型聲明為繼承自 BaseModel 的類。

使用標準的 Python 類型來聲明所有屬性：

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

和聲明查詢參數時一樣，當一個模型屬性具有默認值時，它不是必需的。否則它是一個必需屬性。將默認值設為 None 可使其成為可選屬性。

例如，上面的模型聲明了一個這樣的 JSON「object」（或 Python dict）：

{
    "name": "Foo",
    "description": "An optional description",
    "price": 45.2,
    "tax": 3.5
}

...由于 description 和 tax 是可選的（它們的默認值為 None），下面的 JSON「object」也將是有效的：

{
    "name": "Foo",
    "price": 45.2
}

聲明為參數

使用與聲明路徑和查詢參數的相同方式聲明請求體，即可將其添加到「路徑操作」中：

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    return item

...并且將它的類型聲明為你創(chuàng)建的 Item 模型。

結果

僅僅使用了 Python 類型聲明，FastAPI 將會：

• 將請求體作為 JSON 讀取。
• 轉換為相應的類型（在需要時）。
• 校驗數據。如果數據無效，將返回一條清晰易讀的錯誤信息，指出不正確數據的確切位置和內容。
• 將接收的數據賦值到參數 item 中。由于你已經在函數中將它聲明為 Item 類型，你還將獲得對于所有屬性及其類型的一切編輯器支持（代碼補全等）。
• 為你的模型生成 JSON 模式 定義，你還可以在其他任何對你的項目有意義的地方使用它們。
• 這些模式將成為生成的 OpenAPI 模式的一部分，并且被自動化文檔 UI 所使用。

自動化文檔

你所定義模型的 JSON 模式將成為生成的 OpenAPI 模式的一部分，并且在交互式 API 文檔中展示：

而且還將在每一個需要它們的路徑操作的 API 文檔中使用：

編輯器支持

在你的編輯器中，你會在函數內部的任意地方得到類型提示和代碼補全（如果你接收的是一個 dict 而不是 Pydantic 模型，則不會發(fā)生這種情況）：

你還會獲得對不正確的類型操作的錯誤檢查：

這并非偶然，整個框架都是圍繞該設計而構建。

并且在進行任何實現之前，已經在設計階段經過了全面測試，以確保它可以在所有的編輯器中生效。

Pydantic 本身甚至也進行了一些更改以支持此功能。

上面的截圖取自 Visual Studio Code。

但是在 PyCharm 和絕大多數其他 Python 編輯器中你也會獲得同樣的編輯器支持：

使用模型

在函數內部，你可以直接訪問模型對象的所有屬性：

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None


app = FastAPI()


@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

請求體 + 路徑參數

你可以同時聲明路徑參數和請求體。

FastAPI 將識別出與路徑參數匹配的函數參數應從路徑中獲取，而聲明為 Pydantic 模型的函數參數應從請求體中獲取。

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None


app = FastAPI()


@app.put("/items/{item_id}")
async def create_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

請求體 + 路徑參數 + 查詢參數

你還可以同時聲明請求體、路徑參數和查詢參數。

FastAPI 會識別它們中的每一個，并從正確的位置獲取數據。

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None


app = FastAPI()


@app.put("/items/{item_id}")
async def create_item(item_id: int, item: Item, q: Optional[str] = None):
    result = {"item_id": item_id, **item.dict()}
    if q:
        result.update({"q": q})
    return result

函數參數將依次按如下規(guī)則進行識別：

• 如果在路徑中也聲明了該參數，它將被用作路徑參數。
• 如果參數屬于單一類型（比如 int、float、str、bool 等）它將被解釋為查詢參數。
• 如果參數的類型被聲明為一個 Pydantic 模型，它將被解釋為請求體。

不使用 Pydantic

如果你不想使用 Pydantic 模型，你還可以使用 Body 參數。請參閱文檔 請求體 - 多個參數：請求體中的單一值。