当前位置：首页 > article >正文

解锁数据库简洁之道：FastAPI与SQLModel实战指南

article 2025/6/12 21:11:26

在构建现代Web应用程序时，与数据库的交互无疑是核心环节。虽然传统的数据库操作方式（如直接编写SQL语句与psycopg2交互）赋予了我们精细的控制权，但在面对日益复杂的业务逻辑和快速迭代的需求时，这种方式的开发效率和可维护性可能会面临挑战。本文将引领你进入对象关系映射器（ORM） 的世界，并重点介绍FastAPI官方推荐的SQLModel，展示如何在FastAPI应用中以更高效、更Pythonic、类型更安全的方式驾驭数据库操作。

1. ORM 是什么？为何选择它？

ORM，即对象关系映射器（Object Relational Mapper），是一种巧妙的编程技术。它在你的关系型数据库（如PostgreSQL）和你使用的面向对象编程语言（如Python）之间搭建了一座桥梁，一个抽象层。简单来说，ORM允许你：

用Python的类 (Class) 来代表数据库中的表 (Table)。
用这些类的实例 (Instance/Object) 来代表表中的行 (Row)。
用类实例的属性 (Attribute) 来代表行中的列 (Column) 数据。

ORM如何作为“翻译官”：

在没有ORM的情况下，你的FastAPI应用需要通过数据库驱动（如psycopg2）直接向数据库管理系统（DBMS）发送原始的SQL命令。DBMS执行这些命令后，将结果返回给应用。

引入ORM（特别是SQLModel）后，情况大为改观。你的FastAPI应用不再需要直接“说”SQL。取而代之的是，你使用Python代码和ORM提供的API（比如创建Python对象、调用对象方法）来表达你的数据库操作意图。ORM（SQLModel在底层利用了SQLAlchemy Core的功能）会接收这些Python指令，并将它们翻译成相应的SQL语句，然后通过数据库驱动发送给DBMS。

使用ORM（特别是SQLModel）的核心优势：

告别手写SQL，提升开发效率：
- 开发者可以直接通过操作Python对象来完成增删改查（CRUD），而无需记忆复杂的SQL语法或担心表/列名的拼写错误。
- SQLModel与Pydantic的深度集成意味着你的数据库模型同时也是数据校验模型，减少了重复定义。
增强的类型安全与编辑器支持：
- SQLModel基于Python类型提示构建。这意味着你的IDE（如VS Code）可以为你提供强大的自动补全、类型检查和重构支持，在编码阶段就能发现潜在错误。
- FastAPI会利用这些类型提示进行自动的数据校验和文档生成。
有效防止SQL注入：
- SQL注入是常见的Web安全漏洞。ORM在将Python操作转换为SQL时，通常会使用参数化查询等机制，自动安全地处理用户输入，从而有效防止此类攻击。
更Pythonic的代码风格：
- ORM使数据库操作代码更符合Python的编程习惯。查询数据、创建记录等操作变得像操作普通Python对象和列表一样自然，代码更易读、易维护。
潜在的数据库后端灵活性：
- SQLModel底层依赖SQLAlchemy Core，这意味着它继承了SQLAlchemy对多种数据库后端的支持。理论上，如果将来需要更换数据库类型（如从PostgreSQL到MySQL或SQLite），主要修改的是数据库连接字符串，大部分业务逻辑代码可能无需大的改动。

2. SQLModel：FastAPI的现代数据层伙伴

SQLModel由FastAPI的作者Sebastián Ramírez (tiangolo) 创建，旨在提供一个与FastAPI和Pydantic无缝集成的数据库操作库。它巧妙地结合了Pydantic的数据校验能力和SQLAlchemy的数据库交互能力。

核心特性：

一个模型，多种用途： SQLModel定义的类既是Pydantic模型（用于数据校验、序列化、API文档），也是SQLAlchemy模型（用于数据库表映射和操作）。
基于类型提示： 充分利用Python的类型提示，提供卓越的编辑器支持和运行时数据校验。
简洁易用： API设计力求简单直观，易于上手。

3. SQLModel核心配置：连接你的数据库

在FastAPI应用中集成SQLModel，首先需要配置数据库连接。

3.1 创建数据库引擎（Engine）

引擎（Engine） 是SQLModel (通过SQLAlchemy Core)与特定数据库建立连接的入口点。它负责管理数据库连接池和处理特定数据库的方言（SQL翻译规则）。

# database.py
from sqlmodel import create_engine# 数据库连接URL格式：postgresql://用户名:密码@主机:端口/数据库名
# 确保替换为你的实际数据库凭据和名称
SQLALCHEMY_DATABASE_URL = "postgresql://[你的用户名]:[你的密码]@localhost:5432/[你的数据库名]"engine = create_engine(SQLALCHEMY_DATABASE_URL, echo=True) # echo=True 会打印执行的SQL语句，便于调试

create_engine(): 根据提供的数据库URL创建引擎实例。URL中清晰地指明了数据库类型 (postgresql)、用户名、密码、主机、端口和数据库名称。
echo=True: 在开发时非常有用，它会让你在控制台看到SQLModel实际执行的SQL语句，帮助理解其工作方式和调试问题。生产环境中通常会关闭它。

3.2 创建数据库和表（一次性操作）

SQLModel可以根据你定义的模型类自动在数据库中创建相应的表结构。这通常在应用启动时执行一次。

# database.py (接上文)
from sqlmodel import SQLModel # 导入SQLModel基类def create_db_and_tables():# SQLModel.metadata.create_all() 会检查数据库中是否存在表# 如果不存在，则根据定义的SQLModel模型创建它们SQLModel.metadata.create_all(engine)

然后在你的主应用文件 (main.py) 中，可以在应用启动时调用这个函数：

# main.py
from fastapi import FastAPI
from .database import create_db_and_tablesapp = FastAPI()@app.on_event("startup") # FastAPI应用启动时执行
def on_startup():create_db_and_tables()# ... 其他应用代码 ...

重要提示： SQLModel.metadata.create_all(engine) 只会创建不存在的表。如果你的模型后续发生了更改（如添加新字段、修改字段类型），create_all 不会自动更新已存在表的结构。对于生产环境中的数据库结构变更，你需要使用数据库迁移工具，如 Alembic。

3.3 数据库会话（Session）与依赖注入

会话（Session） 是执行所有数据库操作（增删改查）的“工作区”。每个数据库请求通常在它自己的会话中处理。FastAPI通过**依赖注入（Dependency Injection）**来优雅地管理会话的生命周期。

# main.py (或一个专门的 dependencies.py 文件)
from fastapi import Depends
from sqlmodel import Session # 注意这里导入的是SQLModel的Session
from .database import engine # 导入之前创建的engine# 定义一个依赖项函数，用于获取数据库会话
def get_session(): # FastAPI 教程中常命名为 get_dbwith Session(engine) as session: # 使用SQLModel的Session，并确保引擎被传入yield session# 当请求处理完毕后，with语句会自动处理session.close()# 如果在会话块内发生异常，事务会自动回滚# 如果没有异常，且你调用了 session.commit()，事务会被提交

这个get_session函数将在你的路径操作函数中作为依赖项使用。FastAPI会在处理每个请求前调用它来获取一个新的数据库会话，并在请求结束后（无论成功或失败）确保会话被正确关闭。with Session(engine) as session: 这种用法是推荐的，它能更好地管理会话的生命周期和事务。

4. 定义SQLModel模型：Python类映射数据库表

使用SQLModel，你可以通过定义Python类来描述数据库表的结构，这些类同时也是Pydantic模型。

以一个Post（社交媒体帖子）模型为例：

# models.py
from datetime import datetime
from typing import Optional
from sqlmodel import SQLModel, Field # 导入SQLModel基类和Field
from sqlalchemy import text # 用于定义服务器端默认值# 定义Post模型，它既是Pydantic模型，也是SQLAlchemy表模型
class Post(SQLModel, table=True): # table=True 表明这是一个数据库表模型__tablename__ = "posts" # 可选，如果省略，SQLModel会尝试根据类名推断表名# 定义字段，Field用于提供额外的数据库列信息和Pydantic校验信息id: Optional[int] = Field(default=None, primary_key=True, index=True) # 主键，自动生成，建立索引title: str = Field(index=True) # 标题，建立索引以便快速搜索content: str = Field(nullable=False) # nullable=False 表示该字段不能为空published: bool = Field(default=True, sa_column_kwargs={"server_default": text("true")}) # 是否发布，默认Truecreated_at: Optional[datetime] = Field(default=None, # Pydantic层面允许不传，数据库层面有默认值sa_column_kwargs={"server_default": text("now()")} # 数据库级别默认值为当前时间)

在这个模型中：

class Post(SQLModel, table=True): 表明Post是一个SQLModel表模型。
id: Optional[int] = Field(default=None, primary_key=True, index=True):
- Optional[int]: 类型提示，ID是整数，在创建时可以不提供（由数据库生成）。
- default=None: Pydantic层面的默认值。
- primary_key=True: 声明此字段为主键。
- index=True: 建议为常用于查询条件的字段创建数据库索引以提高性能。
title: str = Field(index=True): 普通字符串字段，也创建了索引。
published: bool = Field(default=True, sa_column_kwargs={"server_default": text("true")}):
- default=True: Pydantic层面的默认值。
- sa_column_kwargs={"server_default": text("true")}: 使用sa_column_kwargs传递SQLAlchemy特定的列参数。这里通过text("true")设置了数据库服务器端的默认值为TRUE。
created_at: Optional[datetime] = Field(default=None, sa_column_kwargs={"server_default": text("now()")}): 创建时间，数据库服务器端默认为当前时间。

5. 使用SQLModel实现CRUD操作

现在，让我们看看如何在FastAPI路径操作中使用SQLModel和get_session依赖来实现数据的增删改查。

5.1 创建（Create）帖子

目标： 在posts表中插入一条新帖子。

# main.py
from fastapi import FastAPI, Response, status, HTTPException, Depends
from typing import List
from sqlmodel import Session, select # 导入SQLModel的Session和select# ... (app, on_startup, get_session 定义如前) ...
from .models import Post # 导入Post模型@app.post("/posts", status_code=status.HTTP_201_CREATED, response_model=Post)
def create_new_post(post_payload: Post, session: Session = Depends(get_session)):# post_payload 是一个已经通过Pydantic校验的Post实例# 注意：如果Post模型中的id是Optional且primary_key=True, default=None# 在创建时，我们不应该给id赋值，数据库会自动生成。# 如果post_payload传入了id，你可能需要:# db_post = Post.model_validate(post_payload) # Pydantic v2# 或 db_post = Post(**post_payload.dict(exclude_unset=True, exclude={'id'})) # 确保不传入iddb_post = Post.model_validate(post_payload) # 确保从请求体创建的实例符合模型定义# 如果ID是可选的，且数据库自动生成，# 传入的post_payload不应包含ID，或者需要处理它session.add(db_post)  # 将新帖子对象添加到会话中，准备插入session.commit()     # 提交事务，将更改写入数据库session.refresh(db_post) # 从数据库刷新对象，获取自动生成的值 (如ID, created_at)return db_post

post_payload: Post: FastAPI会自动将请求体JSON转换为PostPydantic模型实例，并进行校验。
session.add(db_post): 将新创建的（或从请求体转换来的）SQLModel对象添加到当前数据库会话中，标记为待插入。
session.commit(): 提交当前会话中的所有更改（新增、修改、删除），这些更改将真正写入数据库。
session.refresh(db_post): 在提交后，如果对象有数据库自动生成或更新的字段（如自增ID、服务器端默认的时间戳），此方法会从数据库重新加载这些值到db_post对象中。

5.2 读取（Read）帖子

获取所有帖子：

# main.py (接上文)@app.get("/posts", response_model=List[Post])
def get_all_existing_posts(session: Session = Depends(get_session)):statement = select(Post) # 创建一个SQLModel查询语句results = session.exec(statement) # 执行查询语句posts_list = results.all() # 获取所有结果行return posts_list

select(Post): SQLModel（以及SQLAlchemy 2.0+风格）使用select()函数来构建查询。select(Post)表示查询Post表的所有列。
session.exec(statement): 执行构建好的查询语句。
results.all(): 从执行结果中获取所有匹配的行，每行都会被转换为一个Post模型实例。

获取单个帖子：

# main.py (接上文)@app.get("/posts/{post_id}", response_model=Post)
def get_single_post(post_id: int, session: Session = Depends(get_session)):# db.get(ModelClass, primary_key_value) 是获取单个对象最高效的方式post = session.get(Post, post_id)if not post:raise HTTPException(status_code=status.HTTP_404_NOT_FOUND,detail=f"ID为 {post_id} 的帖子未找到")return post

session.get(Post, post_id): 这是SQLModel (和SQLAlchemy) 通过主键获取单个对象的推荐方式，非常简洁高效。

5.3 更新（Update）帖子

目标： 更新posts表中特定ID的帖子。

# main.py (接上文)# 为了更新，通常我们会定义一个不包含只读字段（如id, created_at）的Pydantic模型
class PostUpdate(SQLModel): # Pydantic模型，用于更新，字段都设为Optionaltitle: Optional[str] = Nonecontent: Optional[str] = Nonepublished: Optional[bool] = None@app.put("/posts/{post_id}", response_model=Post)
def update_existing_post(post_id: int,post_update_payload: PostUpdate, # 使用专门的Update模型session: Session = Depends(get_session)
):db_post = session.get(Post, post_id) # 获取要更新的帖子对象if not db_post:raise HTTPException(status_code=status.HTTP_404_NOT_FOUND,detail=f"ID为 {post_id} 的帖子未找到")# post_update_payload.model_dump(exclude_unset=True) 获取请求中实际传递的字段值# exclude_unset=True 确保只获取客户端明确设置的字段，用于部分更新(PATCH)# 对于PUT，客户端应该提供所有可修改字段的新值update_data = post_update_payload.model_dump(exclude_unset=True)for key, value in update_data.items():setattr(db_post, key, value) # 更新帖子对象的属性session.add(db_post) # 即使是更新，SQLModel也需要add来追踪对象变化session.commit()session.refresh(db_post)return db_post

PostUpdate模型：通常为了更新操作（尤其是部分更新/PATCH），我们会定义一个所有字段都是Optional的Pydantic模型。这样，客户端可以只发送他们想修改的字段。
post_update_payload.model_dump(exclude_unset=True): 这个方法非常关键。它将Pydantic模型实例转换为字典，但exclude_unset=True确保了只有那些在请求中被客户端实际设置了值的字段才会包含在字典中。
setattr(db_post, key, value): 遍历包含更新数据的字典，并使用setattr动态更新db_post对象的相应属性。
session.add(db_post): SQLModel (和SQLAlchemy) 通过将会话中的对象标记为“脏”(dirty)来追踪更改。即使是更新，也需要将修改后的对象add回会话（如果它之前已存在于会话中且被修改，它已经被追踪了，但显式add无害且有时是必要的，特别是如果对象是从会话分离后又重新附加的场景）。
然后是熟悉的session.commit()和session.refresh().

5.4 删除（Delete）帖子

目标： 删除posts表中特定ID的帖子。

# main.py (接上文)@app.delete("/posts/{post_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_existing_post(post_id: int, session: Session = Depends(get_session)):db_post = session.get(Post, post_id)if not db_post:raise HTTPException(status_code=status.HTTP_404_NOT_FOUND,detail=f"ID为 {post_id} 的帖子未找到")session.delete(db_post) # 从会话中标记此对象为待删除session.commit()       # 提交事务，将删除操作写入数据库# 对于204 No Content，不应返回任何响应体return Response(status_code=status.HTTP_204_NO_CONTENT)

session.delete(db_post): 将指定的SQLModel对象标记为待删除。
session.commit(): 真正执行删除操作。

6. SQLModel的额外优势

与Pydantic的无缝集成：由于SQLModel类本身就是Pydantic模型，你可以直接在FastAPI的路径操作函数中使用它们进行请求体验证和响应模型定义，无需创建额外的schemas.py文件（除非你有特定理由需要分离）。
编辑器极致体验：得益于类型提示，VS Code等现代编辑器能提供非常棒的自动补全、错误检查和代码导航。
SQLAlchemy的强大后盾：虽然SQLModel提供了更简洁的API，但它底层利用了SQLAlchemy Core。这意味着当你需要更复杂或底层的数据库操作时，仍然可以利用SQLAlchemy的强大功能。

总结：拥抱SQLModel，简化FastAPI数据库开发

SQLModel为FastAPI开发者提供了一种现代、Pythonic且类型安全的方式来与数据库交互。它通过将Pydantic的数据模型能力与SQLAlchemy的数据库操作能力相结合，显著简化了从模型定义到CRUD操作的整个流程。

通过使用SQLModel，你可以：

减少模板代码。
提高开发效率。
增强代码的可读性和可维护性。
获得出色的编辑器支持和类型安全性。

对于希望以更高效、更简洁的方式构建数据驱动的FastAPI应用的开发者而言，SQLModel无疑是一个值得投入学习和使用的优秀工具。