SQLModel教程：在FastAPI中使用多个模型处理数据

SQLModel教程：在FastAPI中使用多个模型处理数据

理解模型分层设计

在构建Web API时，一个常见需求是对同一数据实体使用不同的模型表示形式。SQLModel结合FastAPI提供了优雅的解决方案，让我们能够清晰地分离不同场景下的数据模型。

为什么需要多个模型？

1. 数据库模型：直接映射到数据库表结构
2. 创建模型：定义创建资源时所需的字段
3. 公共模型：定义返回给客户端的字段

这种分层设计带来了诸多好处：

• 安全性：避免暴露敏感字段
• 灵活性：不同场景使用不同字段集合
• 可维护性：各模型职责单一明确

代码解析

数据库模型定义

class Hero(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    name: str = Field(index=True)
    secret_name: str
    age: Optional[int] = Field(default=None, index=True)

Hero类继承自SQLModel并设置table=True，表示这是一个数据库模型。关键点：

• id字段作为主键，使用Optional表示创建时可空
• name和age字段添加了索引以提高查询性能
• secret_name是必填字段但不建立索引

创建模型定义

class HeroCreate(SQLModel):
    name: str
    secret_name: str
    age: Optional[int] = None

HeroCreate模型用于创建英雄时的输入验证：

• 不包含id字段，因为由数据库自动生成
• 所有字段与数据库模型对应，但去除了数据库特定配置

公共模型定义

class HeroPublic(SQLModel):
    id: int
    name: str
    secret_name: str
    age: Optional[int] = None

HeroPublic模型定义了API返回给客户端的数据结构：

• 包含id字段，因为创建后需要返回给客户端
• 字段与数据库模型一致，但可根据需要隐藏或转换某些字段

FastAPI集成实践

数据库初始化

sqlite_file_name = "database.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"
engine = create_engine(sqlite_url, echo=True, connect_args={"check_same_thread": False})

def create_db_and_tables():
    SQLModel.metadata.create_all(engine)

这段代码配置了SQLite数据库并创建表结构：

• echo=True会在控制台输出执行的SQL语句，方便调试
• check_same_thread=False是SQLite在多线程环境下的必要配置

API端点实现

创建英雄端点：

@app.post("/heroes/", response_model=HeroPublic)
def create_hero(hero: HeroCreate):
    with Session(engine) as session:
        db_hero = Hero.model_validate(hero)
        session.add(db_hero)
        session.commit()
        session.refresh(db_hero)
        return db_hero

关键点：

• 使用HeroCreate模型作为输入参数类型
• response_model=HeroPublic指定返回数据类型
• model_validate方法将创建模型转换为数据库模型
• 使用上下文管理器自动处理会话生命周期

获取英雄列表端点：

@app.get("/heroes/", response_model=List[HeroPublic])
def read_heroes():
    with Session(engine) as session:
        heroes = session.exec(select(Hero)).all()
        return heroes

特点：

• 直接返回数据库查询结果，FastAPI会自动转换为HeroPublic模型
• 使用SQLModel的select构建查询语句
• response_model指定返回的是列表形式

最佳实践建议

1. 模型命名规范：保持一致的命名约定，如XxxCreate、XxxPublic等
2. 字段一致性：确保不同模型间相同含义的字段使用相同类型
3. 最小暴露原则：公共模型只暴露必要字段
4. 文档注释：为每个模型和字段添加文档字符串，便于生成API文档
5. 模型验证：利用Pydantic的验证功能在模型层面保证数据质量

通过这种分层模型设计，我们的API能够更好地应对需求变化，同时保持代码的清晰和可维护性。SQLModel与FastAPI的结合为Python开发者提供了强大而简洁的工具，让数据模型的定义和使用变得更加高效。