1. 引言：SQLAlchemy模型JSON序列化的挑战
在构建基于python的web api时，将数据库中获取的sqlalchemy模型对象转换为json格式是常见的需求，以便前端或其他客户端能够消费这些数据。然而，直接将sqlalchemy模型对象转换为字典并序列化为json，往往会遇到以下挑战：
- 关联对象处理： 模型之间通常存在一对多、多对多等关联关系，简单的字典转换无法自动包含这些关联的子对象。
- 继承字段丢失： 对于继承的模型，默认的字段提取方法可能只包含当前模型直接定义的列，而忽略父类或其他基类中的字段。
- 递归深度控制： 关联对象可能形成复杂的循环引用，导致无限递归。
- 数据验证与结构定义： 缺乏对输出JSON结构的明确定义和验证机制。
本文将介绍三种专业且高效的方法来解决这些问题，确保SQLAlchemy模型能够完整、准确地序列化为JSON，包括其所有关联字段和继承属性。
2. 使用SQLAlchemy-serializer进行快速序列化
SQLAlchemy-serializer是一个轻量级的SQLAlchemy扩展，通过混入（Mixin）的方式为模型提供便捷的序列化功能。它允许开发者通过简单的配置，将模型及其关联对象转换为字典，进而序列化为JSON。
2.1 安装
首先，安装SQLAlchemy-serializer库：
pip install SQLAlchemy-serializer
2.2 使用示例
通过继承SerializerMixin，模型将自动获得to_dict()方法，用于将实例转换为字典。
import json
from sqlalchemy import ForeignKey, create_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, sessionmaker
from sqlalchemy_serializer import SerializerMixin
# 定义基础模型，混入SerializerMixin
class Base(DeclarativeBase, SerializerMixin):
pass
# 定义项目模型
class Project(Base):
__tablename__="projects"
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str]
owner_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
# 定义用户模型
class User(Base):
__tablename__="users"
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str]
# 定义与Project的一对多关系
projects: Mapped[list[Project]] = relationship(backref="owner")
# 序列化规则：停止对projects.owner的递归，避免循环引用
serialize_rules = ('-projects.owner',)
# 数据库初始化与会话管理
engine = create_engine("sqlite://")
Base.metadata.create_all(engine)
session_maker = sessionmaker(bind=engine)
with session_maker() as session:
user = User(name="User1")
user.projects.append(Project(name="Project 1"))
user.projects.append(Project(name="Project 2"))
session.add(user)
session.commit()
session.refresh(user) # 刷新对象以加载关系
# 将用户模型序列化为字典，再转换为JSON字符串
print(json.dumps(user.to_dict(), indent=2))2.3 输出结果
{
"id": 1,
"projects": [
{
"id": 1,
"name": "Project 1",
"owner_id": 1
},
{
"id": 2,
"name": "Project 2",
"owner_id": 1
}
],
"name": "User1"
}2.4 注意事项
- serialize_rules： 这是控制序列化行为的关键。通过元组定义规则，例如'-projects.owner'表示在序列化User时，当处理到projects关联对象时，不要再递归序列化project.owner，有效防止了循环引用。
- 灵活性： SQLAlchemy-serializer还支持包含/排除特定字段、自定义字段转换器等高级功能。
- 适用场景： 适用于需要快速、灵活地将SQLAlchemy模型转换为JSON的场景，尤其是在API响应中。
3. 利用Pydantic进行数据验证与序列化
Pydantic是一个强大的数据验证和设置管理库，它与SQLAlchemy结合可以提供类型安全的模型定义和强大的数据序列化能力。通过Pydantic模型，我们可以明确定义JSON的结构，并利用其from_attributes=True（Pydantic v2+）或orm_mode=True（Pydantic v1）特性从SQLAlchemy模型实例中自动加载数据。
3.1 安装
pip install pydantic
3.2 使用示例
首先定义SQLAlchemy模型，然后为每个SQLAlchemy模型创建对应的Pydantic模型。
from sqlalchemy import ForeignKey, create_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, sessionmaker
from pydantic import BaseModel, ConfigDict
import json # 导入json库用于美化输出
# SQLAlchemy基础模型
class Base(DeclarativeBase):
pass
# SQLAlchemy项目模型
class Project(Base):
__tablename__="projects"
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str]
owner_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
# SQLAlchemy用户模型
class User(Base):
__tablename__="users"
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str]
projects: Mapped[list[Project]] = relationship(backref="owner")
# Pydantic模型定义
# 注意：Pydantic模型通常只包含需要暴露给API的字段
class ProjectScheme(BaseModel):
# 启用from_attributes=True（Pydantic v2+）来支持从ORM对象读取属性
model_config = ConfigDict(from_attributes=True)
id: int
name: str
class UserScheme(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: int
name: str
# 关联对象在Pydantic模型中也定义为Pydantic模型列表
projects: list[ProjectScheme]
# 数据库初始化与会话管理
engine = create_engine("sqlite://")
Base.metadata.create_all(engine)
session_maker = sessionmaker(bind=engine)
with session_maker() as session:
user = User(name="User1")
user.projects.append(Project(name="Project 1"))
user.projects.append(Project(name="Project 2"))
session.add(user)
session.commit()
session.refresh(user)
# 使用Pydantic模型验证并从SQLAlchemy对象创建实例，然后转换为JSON字符串
user_json = UserScheme.model_validate(user).model_dump_json(indent=2)
print(user_json)3.3 输出结果
{
"id": 1,
"name": "User1",
"projects": [
{
"name": "Project 1",
"id": 1
},
{
"name": "Project 2",
"id": 2
}
]
}3.4 注意事项
- model_config = ConfigDict(from_attributes=True)： 这是Pydantic v2+中启用从ORM对象加载属性的关键配置。对于Pydantic v1，应使用class Config: orm_mode = True。
- 明确的API契约： Pydantic模型充当了API的输入/输出契约，强制了数据结构和类型，有助于生成API文档。
- 数据验证： Pydantic在数据加载时会自动进行类型检查和验证，提高API的健壮性。
- 性能： 相较于SQLAlchemy-serializer的动态属性访问，Pydantic在定义时明确了字段，可能在某些复杂场景下有更好的性能表现。
4. 使用SQLModel实现模型一体化
SQLModel是FastAPI的作者开发的一个库，它将SQLAlchemy和Pydantic的功能融合在一起，允许开发者使用一套模型定义同时作为数据库模型和Pydantic模型。这大大减少了模型定义的冗余。
4.1 安装
pip install sqlmodel
4.2 使用示例
SQLModel的特点是模型定义即是SQLAlchemy模型也是Pydantic模型，通过table=True指定为数据库表。
from typing import Optional
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from sqlmodel import SQLModel, Field, Relationship
import json # 导入json库用于美化输出
# 定义项目的基础结构（Pydantic部分）
class ProjectBase(SQLModel):
id: Optional[int] = Field(default=None, primary_key=True)
name: str
# 定义项目模型（SQLAlchemy部分，继承ProjectBase）
class Project(ProjectBase, table=True):
__tablename__="projects"
owner_id: Optional[int] = Field(default=None, foreign_key="users.id")
# 定义与User的关系，back_populates用于双向关系
owner: "User" = Relationship(back_populates="projects")
# 定义用户的基础结构
class UserBase(SQLModel):
id: Optional[int] = Field(default=None, primary_key=True)
name: str
# 定义用户模型（SQLAlchemy部分，继承UserBase）
class User(UserBase, table=True):
__tablename__="users"
# 定义与Project的关系
projects: list[Project] = Relationship(back_populates="owner")
# 定义用于API输出的用户模型（Pydantic部分），包含关联ProjectsBase
class UserOutput(UserBase):
projects: list[ProjectBase] = []
# 数据库初始化与会话管理
engine = create_engine("sqlite://")
SQLModel.metadata.create_all(engine) # 使用SQLModel的metadata
session_maker = sessionmaker(bind=engine)
with session_maker() as session:
user = User(name="User1")
user.projects.append(Project(name="Project 1"))
user.projects.append(Project(name="Project 2"))
session.add(user)
session.commit()
session.refresh(user)
# 直接使用UserOutput Pydantic模型进行验证和JSON输出
print(UserOutput.model_validate(user).model_dump_json(indent=2))4.3 输出结果
{
"id": 1,
"name": "User1",
"projects": [
{
"name": "Project 1",
"id": 1
},
{
"name": "Project 2",
"id": 2
}
]
}4.4 注意事项
- 模型一体化： SQLModel通过继承SQLModel类，使模型同时具备ORM和Pydantic的特性，减少了重复定义。
- Field和Relationship： Field用于定义列属性和Pydantic字段，Relationship用于定义ORM关系。
- 输出模型： 通常会定义一个专门的输出模型（如UserOutput），它继承自基础模型，并包含需要序列化的关联对象，这样可以灵活控制API的响应结构。
- 简化开发： 对于同时使用SQLAlchemy和Pydantic的项目，SQLModel能够显著简化模型管理和开发流程。
5. 总结与选择建议
将SQLAlchemy模型序列化为JSON是现代Web API开发中的核心任务。本文介绍了三种主流且高效的方法：
- SQLAlchemy-serializer： 适用于需要快速、灵活地将现有SQLAlchemy模型序列化为JSON的场景，尤其是在不希望引入Pydantic作为主要数据验证层时。它的serialize_rules机制在处理循环引用方面非常便捷。
- Pydantic： 提供强大的数据验证和明确的API契约，是构建健壮API的理想选择。通过from_attributes=True（或orm_mode=True），Pydantic可以无缝地从SQLAlchemy模型加载数据。它将数据验证和序列化职责分离，使得API响应结构清晰可控。
- SQLModel： 融合了SQLAlchemy和Pydantic的优点，通过一套模型定义同时处理数据库操作和数据验证/序列化。对于从零开始构建项目或希望最大程度减少模型冗余的开发者来说，SQLModel是一个极具吸引力的选择。
在实际项目中，选择哪种方法取决于具体需求：
- 如果项目已经有大量SQLAlchemy模型且主要关注快速序列化，SQLAlchemy-serializer可能更合适。
- 如果对API的数据验证和契约有严格要求，并希望在输入和输出都进行强类型检查，Pydantic是首选。
- 如果希望简化开发流程，减少模型定义冗余，并充分利用FastAPI的生态系统，SQLModel将是最佳实践。
无论选择哪种方法，理解其工作原理和适用场景，都能帮助开发者构建出高效、可维护且功能强大的Python API。
