FastAPI自定义验证器详细教程

引言

FastAPI 是一个现代、快速的 Web 框架，用于构建 API，基于 Python 3.6+ 并依赖 Pydantic 进行数据验证和序列化。在 FastAPI 中，验证器是确保输入数据符合预期格式的关键部分。默认情况下，Pydantic 提供了许多内置验证器，但有时我们需要根据业务逻辑创建自定义验证器。本教程将详细讲解如何在 FastAPI 中实现自定义验证器，适合新手学习。

什么是自定义验证器？

自定义验证器允许你定义自己的验证逻辑，以检查数据的特定条件。这可以用于复杂的验证规则，比如检查电子邮件格式、验证密码强度或确保数据一致性。在 FastAPI 中，自定义验证器通过 Pydantic 的装饰器实现，帮助你在数据进入路由前进行精确控制。

为什么需要自定义验证器？

• 业务逻辑验证：内置验证器可能无法满足特定需求，例如验证用户年龄必须在 18 岁以上。
• 复杂条件检查：例如，验证一个字段的值依赖于另一个字段，或者多个字段之间的逻辑关系。
• 重用验证逻辑：通过自定义验证器，可以封装通用验证逻辑，并在多个模型中重用，提高代码复用性和维护性。

在 FastAPI 中实现自定义验证器

FastAPI 使用 Pydantic 进行数据验证，因此自定义验证器通过 Pydantic 的装饰器实现。主要包括两种方法：使用 @field_validator 验证单个字段，和使用 @model_validator 验证整个模型。

使用 @field_validator 装饰器

@field_validator 用于验证单个字段，它接收字段名和要验证的值作为参数。

示例代码

from pydantic import BaseModel, field_validator

class User(BaseModel):
    username: str
    email: str
    age: int

    @field_validator('email')
    def validate_email(cls, v):
        # 检查电子邮件是否包含 "@"
        if "@" not in v:
            raise ValueError('电子邮件必须包含 "@" 符号')
        return v

    @field_validator('age')
    def validate_age(cls, v):
        # 检查年龄是否大于 18
        if v < 18:
            raise ValueError('年龄必须大于或等于 18 岁')
        return v

在这个示例中，validate_email 函数验证电子邮件字段是否包含 "@"，而 validate_age 验证年龄是否满足要求。如果验证失败，会抛出 ValueError 异常，FastAPI 会自动将其转换为 HTTP 400 错误响应。

使用 @model_validator 装饰器

@model_validator 用于验证整个模型，它可以访问所有字段的值，适合跨字段的逻辑验证。

示例代码

from pydantic import BaseModel, model_validator

class User(BaseModel):
    username: str
    email: str
    age: int

    @model_validator(mode='after')
    def check_consistency(self):
        # 检查用户名是否包含在电子邮件中
        if self.username not in self.email:
            raise ValueError('用户名必须是电子邮件的一部分')
        return self

这里，check_consistency 函数在模型所有字段验证后运行，检查用户名和电子邮件之间的一致性。mode='after' 表示在数据验证后执行此检查。

在 FastAPI 路由中使用自定义验证器

一旦定义了带有自定义验证器的 Pydantic 模型，你可以在 FastAPI 路由中使用它来自动验证请求数据。

示例代码

from fastapi import FastAPI
from pydantic import BaseModel, field_validator

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

    @field_validator('price')
    def validate_price(cls, v):
        if v < 0:
            raise ValueError('价格必须为正数')
        return v

@app.post("/items/")
async def create_item(item: Item):
    # 数据会自动通过自定义验证器验证
    return {"message": "数据验证通过", "item": item}

在这个例子中，当客户端发送 POST 请求到 /items/ 端点时，FastAPI 会使用 Item 模型验证输入数据。如果价格字段为负数，验证器会抛出错误，API 将返回 400 状态码和错误信息。

最佳实践

1. 保持验证器简单：每个验证器应专注于一个特定任务，避免过于复杂的逻辑，以提高可读性和可维护性。
2. 提供清晰的错误消息：在验证失败时，抛出带有描述性错误信息的 ValueError，帮助 API 使用者快速理解问题。
3. 测试验证器：编写单元测试来验证自定义验证器按预期工作，确保数据验证的可靠性。
4. 重用验证逻辑：如果多个模型需要相同的验证规则，考虑将验证器提取到基类或辅助函数中，实现代码重用。
5. 结合 FastAPI 错误处理：了解 FastAPI 的错误处理机制，以便更好地处理验证失败情况。

总结

自定义验证器是 FastAPI 中强大的一环，它允许你根据业务需求扩展数据验证功能。通过使用 Pydantic 的装饰器，如 @field_validator 和 @model_validator，你可以轻松实现从简单到复杂的验证逻辑，确保 API 数据的一致性和安全性。对于新手，建议从单个字段验证开始，逐步学习更高级的模型验证方法。希望本教程能帮助你快速掌握自定义验证器的使用，提升 FastAPI 开发技能！

如需进一步学习，可以查阅 FastAPI 官方文档或探索更多高级验证场景，如异步验证或与数据库交互的验证。