SQLModel 教程：使用 FastAPI 实现单条英雄数据查询

最新推荐文章于 2025-06-10 23:11:22 发布

原创最新推荐文章于 2025-06-10 23:11:22 发布 · 375 阅读

CC 4.0 BY-SA版权

SQLModel 教程：使用 FastAPI 实现单条英雄数据查询

概述

本文将深入讲解如何使用 SQLModel 结合 FastAPI 框架实现单条英雄数据的查询功能。SQLModel 是一个强大的 Python 库，它结合了 SQLAlchemy 和 Pydantic 的优点，为数据库操作提供了简洁高效的接口。

项目结构解析

数据模型定义

首先，我们定义了英雄(Hero)的数据模型：

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

class Hero(HeroBase, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)

这里使用了 SQLModel 的继承特性：

HeroBase 定义了英雄的基本字段
Hero 继承 HeroBase 并添加了数据库表特性(table=True)和主键字段

数据库配置

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

我们使用 SQLite 作为数据库，echo=True 参数可以在控制台输出 SQL 语句，方便调试。

核心功能实现

单条数据查询接口

@app.get("/heroes/{hero_id}", response_model=HeroPublic)
def read_hero(hero_id: int):
    with Session(engine) as session:
        hero = session.get(Hero, hero_id)
        if not hero:
            raise HTTPException(status_code=404, detail="Hero not found")
        return hero

这个端点实现了根据 ID 查询单个英雄的功能：

使用 session.get() 方法直接通过主键查询
如果查询不到则返回 404 错误
使用 response_model=HeroPublic 确保返回的数据符合定义的模型

错误处理机制

当查询不到指定 ID 的英雄时，我们使用 FastAPI 的 HTTPException 返回 404 状态码：

raise HTTPException(status_code=404, detail="Hero not found")

这是 RESTful API 的标准做法，让客户端能够明确知道请求的资源不存在。

最佳实践建议

会话管理：使用 with 语句管理数据库会话，确保会话在使用后正确关闭
响应模型：始终定义响应模型(response_model)，这可以：
- 确保返回数据的结构一致
- 自动过滤掉不应返回的字段
- 提供 API 文档的准确描述
错误处理：为所有可能的错误情况提供明确的错误响应
索引优化：在频繁查询的字段上添加索引(如 name 和 age 字段)