FastAPI 基础知识:请求和响应模型

FastAPI 是一个现代、快速（高性能）的 Web 框架，用于基于标准 Python 类型提示使用 Python 3.7+ 构建 API。FastAPI 脱颖而出的关键功能之一是它能够自动生成交互式 API 文档以及请求和响应的验证。在本博客中，我们将探讨 FastAPI 中请求和响应模型的基础知识，并提供一些演示来说明它们的用法。

1. FastAPI 简介

FastAPI 旨在易于使用和学习，同时功能强大，足以构建强大的 API。它基于 Starlette 构建 Web 部分，基于 Pydantic 构建数据部分。主要功能包括：

快速编码：将开发功能的速度提高约 200% 至 300%。

更少的错误：减少约 40% 的人为（开发人员）错误。

直观：出色的编辑器支持。随处完成。更少的调试时间。

简单：设计易于使用和学习。更少的文档阅读时间。

简短：最大限度地减少代码重复。每个参数声明都有多个功能。更少的错误。

2. 设置 FastAPI

要开始使用 FastAPI，您需要安装它。您可以使用 pip 执行此操作：

pip install fastapi
pip install "uvicorn[standard]"

创建一个名为 main.py 的文件并添加以下代码：

from fastapi import FastAPI


app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}

使用 Uvicorn 运行服务器：

uvicorn main:app --reload

您现在可以导航到 http://127.0.0.1:8000 查看“Hello, World!”消息。

3. 请求模型

FastAPI 中的请求模型用于定义传入数据的结构。这是使用 Pydantic 模型完成的。让我们为用户注册端点创建一个简单的请求模型示例。

from pydantic import BaseModel


class User(BaseModel):
    username: str
    email: str
    password: str

现在，让我们在 FastAPI 应用程序中使用此模型：

from fastapi import FastAPI
from pydantic import BaseModel


app = FastAPI()


class User(BaseModel):
    username: str
    email: str
    password: str


@app.post("/register")
def register_user(user: User):
    return {"username": user.username, "email": user.email}

在此示例中，register_user 端点需要与 User 模型匹配的 JSON 主体。FastAPI 将自动验证传入数据，如果数据无效，则返回 422 状态代码。

4. 响应模型

响应模型用于定义 API 返回的数据结构。让我们为用户注册端点创建一个响应模型。

from fastapi import FastAPI
from pydantic import BaseModel


app = FastAPI()


class User(BaseModel):
    username: str
    email: str
    password: str


class UserResponse(BaseModel):
    username: str
    email: str


@app.post("/register", response_model=UserResponse)
def register_user(user: User):
    return user

在此示例中，UserResponse 模型用于定义 register_user 端点返回的数据结构。FastAPI 将自动转换响应以匹配 UserResponse 模型。

5. 组合请求和响应模型

您可以组合请求和响应模型来创建更复杂的 API。让我们创建一个示例，其中我们有一个同时使用请求和响应模型的登录端点。

from fastapi import FastAPI
from pydantic import BaseModel


app = FastAPI()


class LoginRequest(BaseModel):
    username: str
    password: str


class LoginResponse(BaseModel):
    username: str
    message: str


@app.post("/login", response_model=LoginResponse)
def login_user(login_request: LoginRequest):
    # Here you would normally authenticate the user
    return {"username": login_request.username, "message": "Login successful"}

在此示例中，login_user 端点需要与 LoginRequest 模型匹配的 JSON 主体，并返回与 LoginResponse 模型匹配的响应。

6. 嵌套模型

有时，您可能拥有带有嵌套模型的更复杂的数据结构。FastAPI 无缝处理嵌套模型。

1).为用户配置文件创建嵌套模型

from fastapi import FastAPI
from pydantic import BaseModel


app = FastAPI()


class Address(BaseModel):
    street: str
    city: str
    state: str
    zip_code: str


class UserProfile(BaseModel):
    username: str
    email: str
    full_name: str
    address: Address


@app.post("/create-profile", response_model=UserProfile)
def create_profile(profile: UserProfile):
    return profile

在此示例中，UserProfile 模型包含一个 Address 模型，演示如何处理嵌套模型。

7. 可选字段和默认值

您可能需要一些字段是可选的或具有默认值。

1).具有默认值的可选字段

from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel


app = FastAPI()


class User(BaseModel):
    username: str
    email: str
    full_name: Optional[str] = None


@app.post("/create-user", response_model=User)
def create_user(user: User):
    return user

此处，full_name 字段是可选的，如果未提供，则默认为 None。

8. 在模型中使用枚举

枚举对于定义字段的一组有效值很有用。

1).使用枚举表示用户角色

from enum import Enum
from fastapi import FastAPI
from pydantic import BaseModel


app = FastAPI()


class Role(str, Enum):
    admin = "admin"
    user = "user"
    guest = "guest"


class User(BaseModel):
    username: str
    email: str
    role: Role


@app.post("/assign-role", response_model=User)
def assign_role(user: User):
    return user

在此示例中，角色字段必须是角色枚举中定义的值之一。

9. 使用 Pydantic 进行自定义验证

Pydantic 允许在模型中使用自定义验证方法。

1).自定义密码强度验证

from pydantic import BaseModel, validator, ValidationError
from fastapi import FastAPI


app = FastAPI()


class User(BaseModel):
    username: str
    email: str
    password: str


    @validator('password')
    def password_strength(cls, value):
        if len(value) < 8:
            raise ValueError('Password must be at least 8 characters long')
        return value


@app.post("/register", response_model=User)
def register_user(user: User):
    return user

此处，自定义验证器确保密码至少为 8 个字符长。

10. 处理文件上传

FastAPI 通过定义文件数据的请求模型来支持处理文件上传。

1).文件上传端点

from fastapi import FastAPI, File, UploadFile
from pydantic import BaseModel


app = FastAPI()


class FileUploadResponse(BaseModel):
    filename: str
    content_type: str


@app.post("/upload-file", response_model=FileUploadResponse)
async def upload_file(file: UploadFile = File(...)):
    return FileUploadResponse(filename=file.filename, content_type=file.content_type)

在此示例中，upload_file 端点接受文件并返回文件名和内容类型。

11. 带有附加元数据的响应

您可以自定义响应模型以包含附加元数据。

1).带有元数据的响应模型

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List


app = FastAPI()


class Item(BaseModel):
    name: str
    description: str


class ResponseModel(BaseModel):
    data: List[Item]
    total_items: int


@app.post("/items", response_model=ResponseModel)
def create_items(items: List[Item]):
    return ResponseModel(data=items, total_items=len(items))

在此示例中，响应模型包括数据和附加元数据 (total_items)。

这些演示展示了在 FastAPI 中使用请求和响应模型的各个方面，包括嵌套模型、可选字段、枚举、自定义验证、文件上传和带有附加元数据的响应。FastAPI 与 Pydantic 的集成使定义和验证数据结构变得容易，从而确保 API 的健壮性和可维护性。

FastAPI 的请求和响应模型提供了一种定义和验证 API 数据结构的强大方法。通过使用 Pydantic 模型，您可以确保您的 API 端点以一致的格式接收和返回数据，从而降低出错的可能性并使您的代码更易于维护。

使用 FastAPI，您可以获得开箱即用的自动验证和序列化，从而更轻松地构建强大而可靠的 API。无论您是构建简单的 API 还是复杂的应用程序，FastAPI 的请求和响应模型都可以帮助您更有效地管理数据。

文章来源于攻城狮奶爸杂货铺，作者williamsun2020

原文链接：https://mp.weixin.qq.com/s/l0qKbWMRAhMs-TnHPtIz2g