每個 `yield` 的項目都會以 JSON 編碼並放在 SSE 事件的 `data:` 欄位中送出。

如果你把回傳型別宣告為 `AsyncIterable[Item]`，FastAPI 會用它來透過 Pydantic 進行**驗證**、**文件化**與**序列化**。

{* ../../docs_src/server_sent_events/tutorial001_py310.py ln[1:25] hl[10:12,23] *}

/// tip

因為 Pydantic 會在 **Rust** 端進行序列化，如果你有宣告回傳型別，效能會比未宣告時高很多。

///

### 非 async 的路徑操作函式 { #non-async-path-operation-functions }

But this guide shows you, more or less, how they are intended to be used.

///

### Using Pydantic's `exclude_unset` parameter { #using-pydantics-exclude-unset-parameter }

If you want to receive partial updates, it's very useful to use the parameter `exclude_unset` in Pydantic's model's `.model_dump()`.

Like `item.model_dump(exclude_unset=True)`.

如果你想保護 API，有許多更好的作法，例如：

- 確保針對請求本文與回應，具備定義良好的 Pydantic 模型。
- 透過依賴設定所需的權限與角色。
- 切勿儲存明文密碼，只儲存密碼雜湊。
- 實作並使用成熟且廣為人知的密碼學工具，例如 pwdlib 與 JWT 權杖等。
- 視需要以 OAuth2 scopes 新增更細緻的權限控管。
- ...等。

儘管如此，在某些特定情境下，你可能確實需要在某些環境（例如正式環境）停用 API 文件，或依據環境變數的設定來決定是否啟用。

## 透過設定與環境變數的條件式 OpenAPI { #conditional-openapi-from-settings-and-env-vars }

你可以用相同的 Pydantic 設定，來配置產生的 OpenAPI 與文件 UI。

例如：

<img src="/img/tutorial/path-params/image02.png">

同样，还有很多兼容工具，包括多种语言的代码生成工具。

## Pydantic { #pydantic }

FastAPI 充分地利用了 [Pydantic](https://docs.pydantic.dev/) 的优势，用它在后台校验数据。众所周知，Pydantic 擅长的就是数据校验。

同样，`str`、`float`、`bool` 以及很多复合数据类型都可以使用类型声明。

接下来的章节会介绍其中的好几种。

## 顺序很重要 { #order-matters }

有时，*路径操作*中的路径是写死的。

用同樣的方法，你可以使用 Pydantic 模型來定義 JSON Schema，並把它包含到該*路徑操作*的自訂 OpenAPI 區段中。

即使請求中的資料型別不是 JSON 也可以這麼做。

例如，在這個應用中，我們不使用 FastAPI 內建的從 Pydantic 模型擷取 JSON Schema 的功能，也不使用 JSON 的自動驗證。實際上，我們將請求的 content type 宣告為 YAML，而非 JSON：

{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py310.py hl[15:20, 22] *}

儘管沒有使用預設的內建功能，我們仍透過 Pydantic 模型手動產生想以 YAML 接收之資料的 JSON Schema。

*path operation デコレータ*に `responses` パラメータを渡せます。

これは `dict` を受け取り、キーは各レスポンスのステータスコード（例: `200`）、値は各レスポンスの情報を含む別の `dict` です。

それぞれのレスポンス `dict` には、`response_model` と同様に Pydantic モデルを格納する `model` キーを含められます。

FastAPI はそのモデルから JSON Schema を生成し、OpenAPI の適切な場所に含めます。

例えば、ステータスコード `404` と Pydantic モデル `Message` を持つ別のレスポンスを宣言するには、次のように書けます:

{* ../../docs_src/additional_responses/tutorial001_py310.py hl[18,22] *}

/// note | 備考

def test_get(client: TestClient):
    response = client.get("/")
    assert response.json() == {"custom_field": [1.0, 2.0, 3.0]}


def test_typeadapter():
    # This test is only to confirm that Pydantic alone is working as expected
    from pydantic import (
        BaseModel,
        ConfigDict,
        PlainSerializer,
        TypeAdapter,
        WithJsonSchema,
    )

    class FakeNumpyArray:
        def __init__(self):

import types
from collections.abc import Callable
from enum import Enum
from typing import Any, TypeVar, Union

from pydantic import BaseModel
from pydantic.main import IncEx as IncEx

DecoratedCallable = TypeVar("DecoratedCallable", bound=Callable[..., Any])
UnionType = getattr(types, "UnionType", Union)
ModelNameMap = dict[type[BaseModel] | type[Enum], str]

### 追加のオプション依存関係 { #additional-optional-dependencies }

追加でインストールしたい依存関係があります。

追加のオプション Pydantic 依存関係:

* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - 設定管理のため。
* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - Pydantic で使用する追加の型のため。

追加のオプション FastAPI 依存関係:

並不是「`one_person` 就是名為 `Person` 的『類別（class）』」。

## Pydantic 模型 { #pydantic-models }

[Pydantic](https://docs.pydantic.dev/) 是一個用來做資料驗證的 Python 程式庫。

你以帶有屬性的類別來宣告資料的「形狀」。

而每個屬性都有其型別。

接著你用一些值建立這個類別的實例，它會驗證這些值、在需要時把它們轉換成適當的型別，然後回給你一個包含所有資料的物件。

你也會對這個產生的物件得到完整的編輯器支援。

以下是來自 Pydantic 官方文件的例子：

{* ../../docs_src/python_types/tutorial011_py310.py *}

/// info | 資訊