使用 Dataclasses¶

FastAPI 构建于 Pydantic 之上，我一直在向您展示如何使用 Pydantic 模型来声明请求和响应。

但 FastAPI 也支持以相同的方式使用 dataclasses

Python 3.8+

from dataclasses import dataclass
from typing import Union

from fastapi import FastAPI


@dataclass
class Item:
    name: str
    price: float
    description: Union[str, None] = None
    tax: Union[float, None] = None


app = FastAPI()


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

这仍然受支持，感谢 Pydantic，因为它内部支持 dataclasses。

因此，即使上面的代码没有显式使用 Pydantic，FastAPI 仍然会使用 Pydantic 将这些标准 dataclass 转换为 Pydantic 自有的 dataclass 形式。

当然，它支持相同的

数据验证
数据序列化
数据文档等。

这与 Pydantic 模型的工作方式相同。并且在底层，它实际上也是以相同的方式通过 Pydantic 实现的。

信息

请记住，dataclass 无法完成 Pydantic 模型能做的一切。

因此，您可能仍然需要使用 Pydantic 模型。

但是，如果您有一堆 dataclass，这是一个不错的技巧，可以使用它们来支持 FastAPI 的 Web API。🤓

`response_model` 中的 Dataclasses¶

您还可以在 response_model 参数中使用 dataclasses

Python 3.8+

from dataclasses import dataclass, field
from typing import List, Union

from fastapi import FastAPI


@dataclass
class Item:
    name: str
    price: float
    tags: List[str] = field(default_factory=list)
    description: Union[str, None] = None
    tax: Union[float, None] = None


app = FastAPI()


@app.get("/items/next", response_model=Item)
async def read_next_item():
    return {
        "name": "Island In The Moon",
        "price": 12.99,
        "description": "A place to be playin' and havin' fun",
        "tags": ["breater"],
    }

dataclass 将自动转换为 Pydantic dataclass。

这样，它的模式将显示在 API 文档用户界面中

嵌套数据结构中的 Dataclasses¶

您还可以将 dataclasses 与其他类型注解结合使用，以创建嵌套数据结构。

在某些情况下，您可能仍然必须使用 Pydantic 版本的 dataclasses。例如，如果自动生成的 API 文档出现错误。

在这种情况下，您可以简单地将标准 dataclasses 替换为 pydantic.dataclasses，后者是一个直接替代品

Python 3.8+

from dataclasses import field  # (1)
from typing import List, Union

from fastapi import FastAPI
from pydantic.dataclasses import dataclass  # (2)


@dataclass
class Item:
    name: str
    description: Union[str, None] = None


@dataclass
class Author:
    name: str
    items: List[Item] = field(default_factory=list)  # (3)


app = FastAPI()


@app.post("/authors/{author_id}/items/", response_model=Author)  # (4)
async def create_author_items(author_id: str, items: List[Item]):  # (5)
    return {"name": author_id, "items": items}  # (6)


@app.get("/authors/", response_model=List[Author])  # (7)
def get_authors():  # (8)
    return [  # (9)
        {
            "name": "Breaters",
            "items": [
                {
                    "name": "Island In The Moon",
                    "description": "A place to be playin' and havin' fun",
                },
                {"name": "Holy Buddies"},
            ],
        },
        {
            "name": "System of an Up",
            "items": [
                {
                    "name": "Salt",
                    "description": "The kombucha mushroom people's favorite",
                },
                {"name": "Pad Thai"},
                {
                    "name": "Lonely Night",
                    "description": "The mostests lonliest nightiest of allest",
                },
            ],
        },
    ]

我们仍然从标准 dataclasses 中导入 field。
pydantic.dataclasses 是 dataclasses 的直接替代品。
Author dataclass 包含一个 Item dataclass 列表。
Author dataclass 用作 response_model 参数。
您可以将其他标准类型注解与 dataclass 作为请求体一起使用。

在这种情况下，它是一个 Item dataclass 列表。
这里我们返回一个包含 items 的字典，items 是一个 dataclass 列表。

FastAPI 仍然能够将数据序列化为 JSON。
这里 response_model 使用了 Author dataclass 列表的类型注解。

同样，您可以将 dataclasses 与标准类型注解结合使用。
请注意，此路径操作函数使用常规的 def 而不是 async def。

与往常一样，在 FastAPI 中，您可以根据需要组合使用 def 和 async def。

如果您需要回顾何时使用哪种，请查看有关async 和 await 文档中的 “赶时间？” 部分。
此路径操作函数不返回 dataclass（尽管它可以），而是返回一个包含内部数据的字典列表。

FastAPI 将使用 response_model 参数（其中包含 dataclass）来转换响应。

您可以将 dataclasses 与其他类型注解以多种不同组合方式结合，以形成复杂的数据结构。

查看上面的代码内注解提示，了解更具体的详细信息。

了解更多¶

您还可以将 dataclasses 与其他 Pydantic 模型结合使用，从它们继承，将它们包含在您自己的模型中等等。

要了解更多信息，请查看Pydantic 关于 dataclass 的文档。

版本¶

此功能从 FastAPI 版本 0.67.0 开始可用。🔖

使用 Dataclasses¶

response_model 中的 Dataclasses¶

嵌套数据结构中的 Dataclasses¶

了解更多¶

版本¶

`response_model` 中的 Dataclasses¶