6.2 自定义验证器

自定义验证器：FastAPI入门教程中的Python数据验证示例

FastAPI 教程

这个FastAPI入门教程专为Python初学者设计，详细讲解如何使用自定义验证器验证数据。通过简单易懂的类比和动手实践示例，快速掌握Web开发基础，建立编程信心。

FastAPI入门教程：从零开始学习自定义验证器

1. 引言：什么是FastAPI？

FastAPI是一个现代化的Python Web框架，用于快速构建API（应用程序接口）。它特别适合初学者，因为它基于Python的类型提示，代码清晰易懂，还能自动生成文档。

生活化类比：想象你经营一家餐厅，FastAPI就像是你的点餐系统。顾客（用户）通过菜单（API端点）下单（发送请求），系统快速处理订单（验证数据）并准备美食（返回响应）。整个过程高效、可靠。

2. 准备工作：安装FastAPI

在开始之前，确保你已经安装了Python（建议版本3.7或更高）。然后，打开终端或命令行，运行以下命令来安装FastAPI和运行它的服务器。

pip install fastapi uvicorn

fastapi：框架本身。
uvicorn：一个ASGI服务器，用于运行FastAPI应用。

成功时刻：安装完成后，你会看到安装成功的提示。如果没有错误，说明一切都准备好了！

3. 创建你的第一个API

让我们从一个简单的“Hello World”示例开始，体验FastAPI的威力。

创建一个新文件，命名为 main.py，并在其中写入以下代码：

from fastapi import FastAPI

# 创建一个FastAPI应用实例
app = FastAPI()

# 定义一个GET请求的路由，路径为根目录""
@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

保存文件。现在，在终端中，进入文件所在目录，运行以下命令启动服务器：

uvicorn main:app --reload

main:app 指定了模块和FastAPI应用实例。
--reload 参数让服务器在代码更改时自动重启，方便开发。

服务器启动后，打开浏览器，访问 http://127.0.0.1:8000。你会看到JSON响应：{"message": "Hello, World!"}。

成功时刻：太棒了！你刚刚创建并运行了你的第一个FastAPI应用。如果看到这个消息，说明一切正常。

4. 深入数据验证：自定义验证器的使用

在Web开发中，数据验证很重要，以确保接收到的数据是有效的。FastAPI使用Pydantic库进行验证，而自定义验证器让你可以添加自己的验证逻辑。

4.1 什么是数据验证？

数据验证就像餐厅服务员检查订单：如果顾客点了一个不存在的菜品，服务员会提醒；同样，如果API接收到的数据不符合要求（比如年龄是负数），系统会拒绝它。

4.2 使用Pydantic定义数据模型

让我们创建一个端点来接收用户信息，并使用自定义验证器检查年龄是否为正数。

更新 main.py 文件，添加以下代码：

from fastapi import FastAPI
from pydantic import BaseModel, validator  # 导入BaseModel和validator
from typing import Optional  # 用于可选字段

app = FastAPI()

# 定义一个数据模型类User，继承自BaseModel
class User(BaseModel):
    name: str  # 必填字段，字符串类型
    age: int   # 必填字段，整数类型
    email: Optional[str] = None  # 可选字段，字符串类型，默认值为None

    # 自定义验证器：检查年龄是否大于0
    @validator('age')  # 装饰器，指定要验证的字段是'age'
    def validate_age(cls, v):  # cls是类本身，v是要验证的值
        if v <= 0:
            raise ValueError('年龄必须大于0')  # 如果验证失败，抛出错误
        return v  # 如果验证通过，返回原值

# 创建一个POST请求的路由，用于接收用户数据
@app.post("/user/")
def create_user(user: User):  # 参数user会自动根据User模型进行验证
    # 如果数据验证通过，这里可以直接使用user对象
    return {"message": "用户创建成功！", "user": user}

4.3 运行和测试验证器

保存文件，服务器会自动重启（因为有 --reload）。现在，我们来测试这个验证器。

你可以使用浏览器扩展（如Postman或curl）或Python代码发送POST请求。这里，我们假设你使用一个简单工具，但为了动手实践，可以复制以下Python代码到新文件 test.py 并运行：

import requests

# 测试成功案例：年龄为正数
response = requests.post("http://127.0.0.1:8000/user/", json={"name": "Alice", "age": 25, "email": "alice@example.com"})
print("成功响应:", response.json())

# 测试失败案例：年龄为负数
response = requests.post("http://127.0.0.1:8000/user/", json={"name": "Bob", "age": -5})
print("失败响应:", response.json())

运行 test.py 前，确保安装了requests库（pip install requests）。然后执行：

python test.py

你会看到输出：

对于Alice，返回成功消息和用户数据。
对于Bob，返回一个错误，提示“年龄必须大于0”。

成功时刻：完美！你的自定义验证器工作了。当年龄无效时，API自动拒绝请求并返回错误；当有效时，它处理并响应。这就像是服务员成功拦截了错误订单，让你对系统更有信心。

4.4 解释验证器的原理

@validator('age')：这是一个装饰器，告诉Pydantic在验证 age 字段时调用这个函数。
validate_age函数：它接收要验证的值 v，如果条件不满足（v <= 0），就抛出 ValueError；否则，返回原值。
FastAPI会自动捕获这个错误，并以HTTP 422错误响应返回给用户。

类比：把验证器想象成一道安全门。用户数据（如年龄）必须通过这道门才能进入系统。如果不符合规则（如负数），门会关闭并发出警报。

5. 扩展知识和下一步

探索更多验证：Pydantic还支持内置验证，如字符串长度、正则表达式匹配。你可以通过 Field 类轻松添加这些规则。
自动文档：FastAPI自动生成交互式API文档。访问 http://127.0.0.1:8000/docs，你可以看到所有端点，并直接在浏览器中测试它们。这是一个很大的“成功时刻”——无需额外工作，就拥有了完整的文档！
尝试修改：更改验证器逻辑，比如检查邮箱格式或名称长度。动手实践是学习的关键。

6. 总结

通过这个教程，你已经学会了：

安装和设置FastAPI。
创建一个简单的API端点。
使用Pydantic数据模型和自定义验证器来验证输入数据。

记住，Web开发并不神秘。FastAPI让这个过程变得简单直观，特别是对初学者。每次你运行代码并看到预期结果，都是一次小小的成功，累积起来就是强大的信心。

鼓励的话：不要害怕犯错或修改代码。编程就像是烹饪，多尝试几次，你会越来越熟练。继续探索FastAPI的其他功能，比如路径参数、查询参数等，你会发现自己正在成为Web开发高手！

祝你学习愉快！如果有问题，记得查阅FastAPI官方文档或在线社区。

上一章 6.1 自动请求验证机制

下一章 6.3 错误处理：HTTPException