跳到内容

使用 Dataclasses

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

但 FastAPI 也同样支持使用 dataclasses。

from dataclasses import dataclass

from fastapi import FastAPI


@dataclass
class Item:
    name: str
    price: float
    description: str | None = None
    tax: float | None = None


app = FastAPI()


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

得益于 Pydantic 对 标准库 dataclasses 的内置支持，这一功能得以实现。

因此，即使在上述没有显式使用 Pydantic 的代码中，FastAPI 也会使用 Pydantic 将这些标准 dataclasses 转换为 Pydantic 特有的 dataclasses。

当然，它同样支持：

  • 数据验证
  • 数据序列化
  • 数据文档生成等。

这与使用 Pydantic 模型的方式相同。实际上，它们在底层都是通过 Pydantic 以相同的方式实现的。

注意

请记住，dataclasses 无法实现 Pydantic 模型能做的所有事情。

所以，你可能仍然需要使用 Pydantic 模型。

但如果你手头已经有一堆 dataclasses，利用它们来驱动 FastAPI Web API 是一个很棒的技巧。🤓

response_model 中的 Dataclasses

你也可以在 response_model 参数中使用 dataclasses。

from dataclasses import dataclass, field

from fastapi import FastAPI


@dataclass
class Item:
    name: str
    price: float
    tags: list[str] = field(default_factory=list)
    description: str | None = None
    tax: 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。

这样，它的模式（schema）就会显示在 API 文档用户界面中。

嵌套数据结构中的 Dataclasses

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

在某些情况下，你可能仍然需要使用 Pydantic 版本的 dataclasses。例如，当你遇到自动生成的 API 文档出现错误时。

在这种情况下，你可以简单地将标准 dataclasses 替换为 pydantic.dataclasses，它是直接的替代品。 

from dataclasses import field  # (1)

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


@dataclass
class Item:
    name: str
    description: 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",
                },
            ],
        },
    ]

  1. 我们仍然从标准库 dataclasses 中导入 field。

  2. pydantic.dataclasses 是 dataclasses 的直接替代品。

  3. Author dataclass 包含一个 Item dataclass 的列表。

  4. Author dataclass 被用作 response_model 参数。

  5. 你可以将其他标准类型注解与 dataclasses 一起用于请求体。

    在本例中，它是一个 Item dataclass 的列表。

  6. 这里我们返回一个包含 items 的字典，其中 items 是一个 dataclass 列表。

    FastAPI 仍然能够将数据序列化为 JSON。

  7. 这里的 response_model 使用了一个包含 Author dataclass 列表的类型注解。

    同样，你可以将 dataclasses 与标准类型注解组合使用。

  8. 注意，此路径操作函数使用常规的 def 而不是 async def。

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

    如果你需要复习何时使用哪种方式，请查看关于 async 和 await 文档中 "赶时间吗？" (In a hurry?) 的章节。

  9. 此路径操作函数并没有返回 dataclasses（虽然它可以），而是返回了一个包含内部数据的字典列表。

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

你可以将 dataclasses 与其他类型注解进行多种组合，以形成复杂的数据结构。

查看上面的代码内注解提示以获取更多详细信息。

了解更多

你还可以将 dataclasses 与其他 Pydantic 模型组合使用、进行继承、包含在自己的模型中等。

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

版本

此功能自 FastAPI 版本 0.67.0 起可用。🔖