FastAPI模型定义与字段类型

引言

在FastAPI中，模型是构建API的基础，它定义了数据结构，确保数据在请求和响应中的一致性。FastAPI利用Pydantic库来实现模型定义和字段类型验证，这让API开发变得更加简单和高效。对于新手来说，掌握模型定义是学习FastAPI的关键一步。

什么是模型？

模型在FastAPI中通常指Pydantic模型，它是一个Python类，基于BaseModel，用于描述数据的形状。通过定义模型，你可以自动处理数据验证、序列化和API文档的生成。这有助于减少错误，并提高开发速度。

如何定义模型？

要定义模型，你需要从Pydantic导入BaseModel，然后创建一个继承自它的类。每个属性（字段）都用类型注释来指定。

示例：基本模型定义

from pydantic import BaseModel

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

这个User模型定义了三个字段：name（字符串类型）、age（整数类型）和email（字符串类型）。在FastAPI端点中，FastAPI会自动基于这些类型验证传入数据。

字段类型详解

字段类型决定了数据的格式和验证规则。FastAPI支持Python的标准类型，以及Pydantic的扩展类型。以下是常见的字段类型分类：

1. 基本Python类型

• int: 用于整数值，如age: int。
• str: 用于字符串值，如name: str。
• bool: 用于布尔值（True或False），如is_active: bool。
• float: 用于浮点数值，如price: float。

2. 容器类型

容器类型用于存储多个值，需要从typing模块导入。

• List[type]: 列表类型，例如tags: List[str]表示一个字符串列表。
• Dict[type, type]: 字典类型，例如metadata: Dict[str, int]表示键为字符串、值为整数的字典。

3. 可选字段

在某些情况下，字段可能缺失或为空，这时可以使用Optional[type]。这需要从typing模块导入Optional。

• 示例：age: Optional[int] = None表示age字段可以是一个整数或None（即缺失）。

4. 默认值

你可以为字段设置默认值，如果没有提供数据，将使用默认值。

• 示例：is_available: bool = True设置is_available的默认值为True。

5. Pydantic特定类型

Pydantic提供了一些高级类型，用于更严格的验证。

• EmailStr: 用于验证邮箱格式，需要从Pydantic导入，例如email: EmailStr。
• Url: 用于验证URL格式。

完整示例：结合FastAPI端点

让我们通过一个完整示例来展示如何定义模型并在FastAPI中使用它们。

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr
from typing import Optional, List

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

# 定义一个Item模型，用于商品数据
class Item(BaseModel):
    name: str
    price: float
    is_available: bool = True  # 默认值为True
    tags: List[str] = []  # 默认空列表

# 定义一个User模型，用于用户创建
class UserCreate(BaseModel):
    username: str
    email: EmailStr  # 使用EmailStr验证邮箱
    age: Optional[int] = None  # 可选字段

# API端点示例
@app.post("/items/")
async def create_item(item: Item):
    # FastAPI会自动验证请求体是否符合Item模型
    return {"item": item.dict()}  # 使用.dict()方法序列化模型

@app.post("/users/")
async def create_user(user: UserCreate):
    return {"user": user.dict()}

实践建议

1. 从简单开始: 先定义只包含基本类型字段的模型，然后逐步添加复杂类型。
2. 使用类型注释: 始终为字段指定类型，这有助于FastAPI自动生成文档和验证数据。
3. 测试验证: 发送无效数据到你的API端点，观察FastAPI如何返回错误响应，这有助于理解字段验证机制。

总结

模型定义和字段类型是FastAPI的核心概念，通过Pydantic的BaseModel，你可以轻松构建结构化数据。掌握这一点后，你将能够设计出类型安全、易于维护的API。随着实践，可以探索更多高级特性，如嵌套模型和自定义验证器。

下一步

尝试修改上述示例，添加新字段或使用其他类型（如嵌套模型或枚举），以巩固你的理解。持续学习FastAPI文档，进一步提升API开发技能。