# 自訂回應——HTML、串流、檔案與其他 { #custom-response-html-stream-file-others }

預設情況下，**FastAPI** 會回傳 JSON 回應。

你可以像在[直接回傳 Response](response-directly.md)中所示，直接回傳一個 `Response` 來覆寫它。

但如果你直接回傳一個 `Response`（或其子類別，例如 `JSONResponse`），資料將不會被自動轉換（即使你宣告了 `response_model`），而且文件也不會自動產生（例如，在產生的 OpenAPI 中包含 HTTP 標頭 `Content-Type` 的特定「media type」）。

你也可以在「路徑操作裝飾器」中使用 `response_class` 參數，宣告要使用的 `Response`（例如任意 `Response` 子類別）。

你從「路徑操作函式」回傳的內容，會被放進該 `Response` 中。

/// note

若你使用的回應類別沒有 media type，FastAPI 會假設你的回應沒有內容，因此不會在產生的 OpenAPI 文件中記錄回應格式。

///

## JSON 回應 { #json-responses }

FastAPI 預設回傳 JSON 回應。

如果你宣告了[回應模型](../tutorial/response-model.md)，FastAPI 會使用 Pydantic 將資料序列化為 JSON。

如果你沒有宣告回應模型，FastAPI 會使用在[JSON 相容編碼器](../tutorial/encoder.md)中解釋的 `jsonable_encoder`，並將結果放進 `JSONResponse`。

如果你宣告的 `response_class` 具有 JSON 的 media type（`application/json`），像 `JSONResponse`，你回傳的資料會自動以你在「路徑操作裝飾器」中宣告的任何 Pydantic `response_model` 進行轉換（與過濾）。但資料不會由 Pydantic 直接序列化成 JSON 位元組；取而代之，會先經由 `jsonable_encoder` 轉換，然後交給 `JSONResponse` 類別，該類別會使用 Python 標準的 JSON 函式庫將其序列化為位元組。

### JSON 效能 { #json-performance }

簡而言之，若你想要最佳效能，請使用[回應模型](../tutorial/response-model.md)，並且不要在「路徑操作裝飾器」中宣告 `response_class`。

{* ../../docs_src/response_model/tutorial001_01_py310.py ln[15:17] hl[16] *}

## HTML 回應 { #html-response }

要直接從 **FastAPI** 回傳 HTML，使用 `HTMLResponse`。

- 匯入 `HTMLResponse`。
- 在「路徑操作裝飾器」中，將 `HTMLResponse` 傳給 `response_class` 參數。

{* ../../docs_src/custom_response/tutorial002_py310.py hl[2,7] *}

/// note

參數 `response_class` 也會用來定義回應的「media type」。

在此情況下，HTTP 標頭 `Content-Type` 會被設為 `text/html`。

而且它會以此形式被記錄到 OpenAPI 中。

///

### 回傳 `Response` { #return-a-response }

如[直接回傳 Response](response-directly.md)所示，你也可以在「路徑操作」中直接回傳以覆寫回應。

上面的相同範例，回傳 `HTMLResponse`，可以像這樣：

{* ../../docs_src/custom_response/tutorial003_py310.py hl[2,7,19] *}

/// warning

由你的「路徑操作函式」直接回傳的 `Response` 不會被記錄進 OpenAPI（例如不會記錄 `Content-Type`），也不會出現在自動產生的互動式文件中。

///

/// note

當然，實際的 `Content-Type` 標頭、狀態碼等，會來自你回傳的 `Response` 物件。

///

### 在 OpenAPI 中文件化並覆寫 `Response` { #document-in-openapi-and-override-response }

如果你想在函式內覆寫回應，同時又要在 OpenAPI 中記錄「media type」，你可以同時使用 `response_class` 參數並回傳一個 `Response` 物件。

此時，`response_class` 只會用於記錄該 OpenAPI「路徑操作」，而你回傳的 `Response` 將會如實使用。

#### 直接回傳 `HTMLResponse` { #return-an-htmlresponse-directly }

例如，可能會像這樣：

{* ../../docs_src/custom_response/tutorial004_py310.py hl[7,21,23] *}

在這個例子中，函式 `generate_html_response()` 已經產生並回傳了一個 `Response`，而不是把 HTML 當作 `str` 回傳。

透過回傳 `generate_html_response()` 的結果，你其實已經回傳了一個 `Response`，這會覆寫 **FastAPI** 的預設行為。

但因為你同時也在 `response_class` 中傳入了 `HTMLResponse`，**FastAPI** 便能在 OpenAPI 與互動式文件中，將其以 `text/html` 的 HTML 形式記錄：

<img src="/img/tutorial/custom-response/image01.png">

## 可用的回應 { #available-responses }

以下是一些可用的回應類別。

記得你可以用 `Response` 回傳其他任何東西，甚至建立自訂的子類別。

/// note | 技術細節

你也可以使用 `from starlette.responses import HTMLResponse`。

**FastAPI** 將 `starlette.responses` 以 `fastapi.responses` 提供給你（開發者）做為方便之用。但大多數可用的回應其實直接來自 Starlette。

///

### `Response` { #response }

主要的 `Response` 類別，其他回應皆繼承自它。

你也可以直接回傳它。

它接受以下參數：

- `content` - `str` 或 `bytes`。
- `status_code` - `int` 類型的 HTTP 狀態碼。
- `headers` - 由字串組成的 `dict`。
- `media_type` - 描述 media type 的 `str`。例如 `"text/html"`。

FastAPI（實際上是 Starlette）會自動包含 Content-Length 標頭。也會根據 `media_type`（並為文字型別附加 charset）包含 Content-Type 標頭。

{* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *}

### `HTMLResponse` { #htmlresponse }

接收文字或位元組並回傳 HTML 回應，如上所述。

### `PlainTextResponse` { #plaintextresponse }

接收文字或位元組並回傳純文字回應。

{* ../../docs_src/custom_response/tutorial005_py310.py hl[2,7,9] *}

### `JSONResponse` { #jsonresponse }

接收資料並回傳 `application/json` 編碼的回應。

這是 **FastAPI** 的預設回應，如上所述。

/// note | 技術細節

但如果你宣告了回應模型或回傳型別，將會直接用它來把資料序列化為 JSON，並直接回傳具有正確 JSON media type 的回應，而不會使用 `JSONResponse` 類別。

這是取得最佳效能的理想方式。

///

### `RedirectResponse` { #redirectresponse }

回傳一個 HTTP 重新導向。預設使用 307 狀態碼（Temporary Redirect）。

你可以直接回傳 `RedirectResponse`：

{* ../../docs_src/custom_response/tutorial006_py310.py hl[2,9] *}

---

或者你可以在 `response_class` 參數中使用它：

{* ../../docs_src/custom_response/tutorial006b_py310.py hl[2,7,9] *}

若這麼做，你就可以在「路徑操作函式」中直接回傳 URL。

在此情況下，所使用的 `status_code` 會是 `RedirectResponse` 的預設值 `307`。

---

你也可以同時搭配 `status_code` 與 `response_class` 參數：

{* ../../docs_src/custom_response/tutorial006c_py310.py hl[2,7,9] *}

### `StreamingResponse` { #streamingresponse }

接收一個 async 產生器或一般的產生器／疊代器（帶有 `yield` 的函式），並以串流方式傳送回應本文。

{* ../../docs_src/custom_response/tutorial007_py310.py hl[3,16] *}

/// note | 技術細節

一個 `async` 任務只能在抵達某個 `await` 時才能被取消。如果沒有 `await`，該產生器（帶有 `yield` 的函式）將無法被正確取消，甚至在請求取消後仍可能持續執行。

因為這個小範例不需要任何 `await` 陳述式，我們加入 `await anyio.sleep(0)`，讓事件迴圈有機會處理取消。

對於大型或無限的串流來說，這點更為重要。

///

/// tip

與其直接回傳 `StreamingResponse`，你大概會想遵循[資料串流](./stream-data.md)中的作法，這樣更方便，並且會在底層幫你處理取消。

如果你要串流 JSON Lines，請參考教學：[串流 JSON Lines](../tutorial/stream-json-lines.md)。

///

### `FileResponse` { #fileresponse }

以非同步串流方式將檔案作為回應。

它在初始化時所需的參數與其他回應型別不同：

- `path` - 要串流的檔案路徑。
- `headers` - 要包含的自訂標頭，字典形式。
- `media_type` - 描述 media type 的字串。若未設定，將根據檔名或路徑推斷 media type。
- `filename` - 若設定，會包含在回應的 `Content-Disposition` 中。

檔案回應會包含適當的 `Content-Length`、`Last-Modified` 與 `ETag` 標頭。

{* ../../docs_src/custom_response/tutorial009_py310.py hl[2,10] *}

你也可以使用 `response_class` 參數：

{* ../../docs_src/custom_response/tutorial009b_py310.py hl[2,8,10] *}

在此情況下，你可以在「路徑操作函式」中直接回傳檔案路徑。

## 自訂回應類別 { #custom-response-class }

你可以建立自己的自訂回應類別，繼承自 `Response` 並加以使用。

例如，假設你要使用 [`orjson`](https://github.com/ijl/orjson) 並套用一些設定。

假設你想回傳縮排且格式化的 JSON，因此要使用 orjson 選項 `orjson.OPT_INDENT_2`。

你可以建立 `CustomORJSONResponse`。你主要需要做的是建立一個 `Response.render(content)` 方法，將內容以 `bytes` 回傳：

{* ../../docs_src/custom_response/tutorial009c_py310.py hl[9:14,17] *}

現在，不再是回傳：

```json
{"message": "Hello World"}
```

...這個回應會回傳：

```json
{
  "message": "Hello World"
}
```

當然，你大概能找到比格式化 JSON 更好的方式來利用這個能力。😉

### `orjson` 或回應模型 { #orjson-or-response-model }

如果你追求效能，使用[回應模型](../tutorial/response-model.md) 大概會比使用 `orjson` 回應更好。

有了回應模型，FastAPI 會使用 Pydantic 直接將資料序列化為 JSON，而不需要像其他情況那樣先經過 `jsonable_encoder` 之類的中介步驟。

而且在底層，Pydantic 用來序列化為 JSON 的 Rust 機制和 `orjson` 相同，因此用回應模型已經能獲得最佳效能。

## 預設回應類別 { #default-response-class }

在建立 **FastAPI** 類別實例或 `APIRouter` 時，你可以指定預設要使用哪個回應類別。

用來設定的是 `default_response_class` 參數。

在下面的例子中，**FastAPI** 會在所有「路徑操作」中預設使用 `HTMLResponse`，而不是 JSON。

{* ../../docs_src/custom_response/tutorial010_py310.py hl[2,4] *}

/// tip

你仍然可以在「路徑操作」中像以前一樣覆寫 `response_class`。

///

## 其他文件化選項 { #additional-documentation }

你也可以在 OpenAPI 中使用 `responses` 宣告 media type 與其他許多細節：[在 OpenAPI 中的額外回應](additional-responses.md)。