使用SQLModel与FastAPI构建英雄团队管理API教程

使用SQLModel与FastAPI构建英雄团队管理API教程

sqlmodel SQL databases in Python, designed for simplicity, compatibility, and robustness. 项目地址: https://gitcode.com/gh_mirrors/sq/sqlmodel

概述

本文将介绍如何使用SQLModel和FastAPI构建一个完整的英雄团队管理API系统。SQLModel是一个强大的Python库，它结合了SQLAlchemy和Pydantic的优点，让我们能够用Python类型注解来定义数据库模型和API数据模型。

环境准备

在开始之前，请确保已安装以下Python包：

• fastapi
• sqlmodel
• uvicorn

可以通过pip命令安装这些依赖项。

数据模型设计

团队(Team)模型

首先我们定义了团队模型，包含以下字段：

• id: 主键，自增长整数
• name: 团队名称，建立索引以提高查询效率
• headquarters: 团队总部所在地

class TeamBase(SQLModel):
    name: str = Field(index=True)
    headquarters: str

class Team(TeamBase, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    heroes: List["Hero"] = Relationship(back_populates="team")

英雄(Hero)模型

英雄模型包含以下字段：

• id: 主键，自增长整数
• name: 英雄名称，建立索引
• secret_name: 英雄秘密身份
• age: 英雄年龄，可选字段
• team_id: 外键，关联到团队表

class HeroBase(SQLModel):
    name: str = Field(index=True)
    secret_name: str
    age: Optional[int] = Field(default=None, index=True)
    team_id: Optional[int] = Field(default=None, foreign_key="team.id")

class Hero(HeroBase, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    team: Optional[Team] = Relationship(back_populates="heroes")

数据库配置

我们使用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})

echo=True参数会在控制台输出SQL语句，便于调试。

API路由设计

英雄相关API

1. 创建英雄 - POST /heroes/

   • 接收HeroCreate模型数据
   • 返回创建后的英雄信息

2. 获取英雄列表 - GET /heroes/

   • 支持分页参数offset和limit
   • limit最大值为100，防止过多数据返回

3. 获取单个英雄 - GET /heroes/{hero_id}

   • 根据ID获取特定英雄
   • 如果不存在返回404错误

4. 更新英雄 - PATCH /heroes/{hero_id}

   • 部分更新英雄信息
   • 只更新提供的字段

5. 删除英雄 - DELETE /heroes/{hero_id}

   • 根据ID删除英雄

团队相关API

团队API设计与英雄类似，同样包含创建、查询、更新和删除操作。

核心实现细节

数据库会话管理

使用FastAPI的依赖注入系统管理数据库会话：

def get_session():
    with Session(engine) as session:
        yield session

模型验证与更新

SQLModel提供了方便的模型验证和更新方法：

# 创建时验证
db_hero = Hero.model_validate(hero)

# 更新时只更新提供的字段
hero_data = hero.model_dump(exclude_unset=True)
db_hero.sqlmodel_update(hero_data)

关系处理

团队和英雄之间的一对多关系通过Relationship定义：

# 在Team模型中
heroes: List["Hero"] = Relationship(back_populates="team")

# 在Hero模型中
team: Optional[Team] = Relationship(back_populates="heroes")

启动应用

在应用启动时自动创建数据库表：

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

总结

通过本教程，我们学习了如何使用SQLModel和FastAPI构建一个完整的RESTful API。SQLModel的强大之处在于：

1. 使用Python类型注解同时定义数据库模型和API数据模型
2. 内置的模型验证功能
3. 简洁的关系定义方式
4. 与FastAPI无缝集成

这种组合非常适合快速开发数据驱动的Web应用，既能保证代码的简洁性，又能提供强大的功能和良好的性能。

sqlmodel SQL databases in Python, designed for simplicity, compatibility, and robustness. 项目地址: https://gitcode.com/gh_mirrors/sq/sqlmodel