跳至內容

直接返回一個回應

當您建立一個 FastAPI 路徑操作 時，通常可以從中返回任何資料：一個 dict、一個 list、一個 Pydantic 模型、一個資料庫模型等等。

預設情況下，FastAPI 會使用在 JSON 相容編碼器 中說明的 jsonable_encoder 自動將返回的值轉換為 JSON。

然後，在幕後，它會將該 JSON 相容資料（例如 dict）放入 JSONResponse 中，該 JSONResponse 將用於將回應發送給客戶端。

但您可以直接從您的 路徑操作 返回一個 JSONResponse。

例如，返回自訂標頭或 Cookie 可能會很有用。

返回一個 Response

事實上，您可以返回任何 Response 或其任何子類別。

提示

JSONResponse 本身就是 Response 的一個子類別。

當您返回一個 Response 時，FastAPI 將直接傳遞它。

它不會使用 Pydantic 模型進行任何資料轉換，也不會將內容轉換為任何類型，等等。

這給您很大的彈性。您可以返回任何資料類型，覆蓋任何資料宣告或驗證，等等。

在 Response 中使用 jsonable_encoder

由於 FastAPI 不會對您返回的 Response 進行任何更改，因此您必須確保其內容已準備就緒。

例如，您不能將 Pydantic 模型放入 JSONResponse 中，而必須先將其轉換為 dict，並將所有資料類型（例如 datetime、UUID 等）轉換為 JSON 相容類型。

對於這些情況，您可以使用 jsonable_encoder 在將資料傳遞給回應之前轉換您的資料。

from datetime import datetime
from typing import Union

from fastapi import FastAPI
from fastapi.encoders import jsonable_encoder
from fastapi.responses import JSONResponse
from pydantic import BaseModel


class Item(BaseModel):
    title: str
    timestamp: datetime
    description: Union[str, None] = None


app = FastAPI()


@app.put("/items/{id}")
def update_item(id: str, item: Item):
    json_compatible_item_data = jsonable_encoder(item)
    return JSONResponse(content=json_compatible_item_data)

「技術細節」

您也可以使用 from starlette.responses import JSONResponse。

為了方便開發者，FastAPI 提供了與 starlette.responses 相同的 fastapi.responses。但大多數可用的回應都直接來自 Starlette。

返回自訂 Response

上面的範例顯示了您需要的所有部分，但它還不是很有用，因為您可以直接返回 item，FastAPI 會將其放入 JSONResponse 中，將其轉換為 dict 等等。所有這些都是預設的。

現在，讓我們看看如何使用它來返回自訂回應。

假設您要返回 XML 回應。

您可以將 XML 內容放入字串中，將其放入 Response 中，然後返回它。

from fastapi import FastAPI, Response

app = FastAPI()


@app.get("/legacy/")
def get_legacy_data():
    data = """<?xml version="1.0"?>
    <shampoo>
    <Header>
        Apply shampoo here.
    </Header>
    <Body>
        You'll have to use soap here.
    </Body>
    </shampoo>
    """
    return Response(content=data, media_type="application/xml")

注意事項

當您直接返回 Response 時，其資料不會自動驗證、轉換（序列化）或記錄。

但您仍然可以按照 OpenAPI 中的其他回應 中的描述記錄它。

您可以在後面的章節中看到如何在仍然具有自動資料轉換、文件等功能的同時使用/宣告這些自訂 Response。