使用SQLModel实现FastAPI分页查询功能详解

使用SQLModel实现FastAPI分页查询功能详解

【免费下载链接】sqlmodel SQL databases in Python, designed for simplicity, compatibility, and robustness. 项目地址: https://gitcode.com/gh_mirrors/sq/sqlmodel

SQLModel是一个强大的Python库，它结合了SQLAlchemy和Pydantic的优点，为开发者提供了简洁高效的数据库操作体验。本文将重点讲解如何利用SQLModel在FastAPI中实现分页查询功能。

项目结构与模型定义

首先我们来看项目中的核心模型定义。这里定义了一个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)

这种分层设计模式非常值得学习：

• HeroBase包含基础字段定义
• Hero继承基础类并添加表特性
• 还定义了HeroCreate和HeroPublic用于不同场景

数据库初始化

项目使用SQLite作为数据库，初始化代码如下：

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)

echo=True参数会在控制台输出SQL语句，非常适合调试阶段使用。

FastAPI应用设置

在FastAPI应用中，我们在启动时创建数据库表：

@app.on_event("startup")
def on_startup():
    create_db_and_tables()

分页查询实现

重点来看分页查询的实现，这是本文的核心内容：

@app.get("/heroes/", response_model=List[HeroPublic])
def read_heroes(offset: int = 0, limit: int = Query(default=100, le=100)):
    with Session(engine) as session:
        heroes = session.exec(select(Hero).offset(offset).limit(limit)).all()
        return heroes

这个端点实现了两个关键分页参数：

1. offset：跳过前N条记录，默认为0
2. limit：限制返回记录数，默认100，最大不超过100

分页参数详解

• offset参数表示从第几条记录开始获取，常用于实现"下一页"功能
• limit参数限制每次返回的记录数量，防止一次返回过多数据
• Query的le=100参数确保了limit最大值不超过100，这是API设计的最佳实践

其他端点功能

除了分页查询，项目还实现了：

1. 创建英雄
2. 根据ID查询单个英雄

这些端点共同构成了一个完整的CRUD示例。

技术要点总结

1. 分页实现：使用SQLAlchemy的offset()和limit()方法实现高效分页
2. 参数验证：利用FastAPI的Query进行输入参数验证
3. 会话管理：使用上下文管理器(with语句)自动处理数据库会话
4. 响应模型：严格定义返回数据结构，确保API一致性

实际应用建议

在实际项目中，可以考虑：

1. 添加更复杂的分页策略，如基于游标的分页
2. 实现排序功能，允许客户端指定排序字段
3. 添加过滤条件，实现更精确的查询
4. 考虑性能优化，特别是大数据量下的分页效率

通过这个示例，我们可以看到SQLModel如何与FastAPI完美配合，快速构建出高效、类型安全的API接口。分页功能作为Web开发中的常见需求，这个实现方案既简洁又实用，值得在实际项目中参考应用。

【免费下载链接】sqlmodel SQL databases in Python, designed for simplicity, compatibility, and robustness. 项目地址: https://gitcode.com/gh_mirrors/sq/sqlmodel