在现代web应用开发中，后端api经常需要将数据库中检索到的数据以json格式返回给前端。当使用sqlalchemy作为orm时，直接将sqlalchemy模型对象转换为json并非总是直观，尤其当模型包含复杂的关系（如一对多、多对多）或继承结构时。传统的通过遍历__table__.columns来构建字典的方法，往往无法捕获到这些关联数据，导致序列化结果不完整。本文将介绍几种高效且专业的解决方案来应对这一挑战。
1. 使用 SQLAlchemy-serializer 简化序列化
SQLAlchemy-serializer是一个为SQLAlchemy模型提供简单序列化功能的混入（Mixin）库。它允许你通过继承SerializerMixin来为模型添加to_dict()方法，该方法能够自动处理模型字段和关系。
核心特性与使用方法
- 继承 SerializerMixin: 将 SerializerMixin 添加到你的 DeclarativeBase 或每个需要序列化的模型中。
- to_dict() 方法: 继承后，模型实例将拥有 to_dict() 方法，可以直接将其转换为字典。
- serialize_rules 控制递归: 对于存在循环引用（如用户拥有项目，项目又关联回用户）的关系，可以使用 serialize_rules 来指定何时停止递归，防止无限循环。
示例代码
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]
projects: Mapped[list[Project]] = relationship(backref="owner")
# 指定序列化规则，'-projects.owner' 表示在序列化 projects 列表时，不包含其 owner 属性，
# 避免 user -> projects -> owner (user) 的循环引用
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()))输出示例:
立即学习“Python免费学习笔记（深入）”；
{"id": 1, "projects": [{"id": 1, "name": "Project 1", "owner_id": 1}, {"id": 2, "name": "Project 2", "owner_id": 1}], "name": "User1"}注意事项
- SQLAlchemy-serializer提供了一种快速简便的序列化方式，特别适用于简单的API场景。
- serialize_rules功能强大，可以控制包含/排除特定字段、深度以及处理循环引用。
2. 使用 Pydantic 进行数据验证与序列化
Pydantic 是一个基于 Python 类型提示的数据验证和设置管理库。它不仅能验证数据，还能方便地将复杂对象（包括 SQLAlchemy 模型）序列化为字典或JSON。通过定义与SQLAlchemy模型对应的Pydantic模型，可以实现灵活且类型安全的数据转换。
核心特性与使用方法
- 定义 Pydantic 模型: 为每个需要序列化的 SQLAlchemy 模型定义一个对应的 Pydantic BaseModel。
- ConfigDict(from_attributes=True): 在 Pydantic 模型配置中设置 from_attributes=True（Pydantic v2+）或 orm_mode=True（Pydantic v1），允许 Pydantic 从 SQLAlchemy 模型的属性（包括关系属性）中读取数据。
- model_validate() 和 model_dump_json(): 使用 Pydantic 模型的 model_validate() 方法从 SQLAlchemy 实例创建 Pydantic 实例，然后使用 model_dump_json() 方法将其序列化为 JSON 字符串。
示例代码
from sqlalchemy import ForeignKey, create_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, sessionmaker
from pydantic import BaseModel, ConfigDict
# 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 项目 Schema
class ProjectScheme(BaseModel):
model_config = ConfigDict(from_attributes=True) # 允许从ORM属性读取
id: int
name: str
# Pydantic 用户 Schema，包含项目列表
class UserScheme(BaseModel):
model_config = ConfigDict(from_attributes=True) # 允许从ORM属性读取
id: int
name: str
projects: list[ProjectScheme] # 嵌套 Pydantic 模型来处理关系
# 数据库初始化与会话管理
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 实例
user_json = UserScheme.model_validate(user).model_dump_json()
print(user_json)输出示例:
立即学习“Python免费学习笔记（深入）”；
{"id":1,"name":"User1","projects":[{"name":"Project 1","id":1},{"name":"Project 2","id":2}]}注意事项
- Pydantic 提供了强大的数据验证功能，确保输出数据的质量和类型安全。
- 需要为每个 SQLAlchemy 模型手动创建对应的 Pydantic 模型，这可能会增加一些样板代码。
- 非常适合需要严格数据验证和清晰API响应结构的场景。
3. 使用 SQLModel 简化模型定义与序列化
SQLModel 是一个结合了SQLAlchemy和Pydantic优点的库，旨在减少模型定义中的冗余。它允许你使用单一的模型定义同时作为数据库模型（SQLAlchemy）和数据验证/序列化模型（Pydantic）。
scala中文手册 scala入门与进阶
下载
Scala也是一种函数式语言，其函数也能当成值来使用。Scala提供了轻量级的语法用以定义匿名函数，支持高阶函数，允许嵌套多层函数，并支持柯里化 。Scala的Case Class及其内置的模式匹配相当于函数式编程语言中常用的代数类型（Algebraic Type）。 Scala课堂是Twitter启动的一系列讲座，用来帮助有经验的工程师成为高效的Scala 程序员。Scala是一种相对较新的语言，但借鉴了许多熟悉的概念。因此，课程中的讲座假设听众知道这些概念，并展示了如何在Scala中使用它们。我们发现
核心特性与使用方法
- 统一模型定义: 使用 SQLModel 定义的模型既是数据库表结构，也是 Pydantic BaseModel。
- Field 和 Relationship: 使用 Field 定义列属性，使用 Relationship 定义模型关系。
- 输出模型: 可以定义一个简化的 Pydantic 模型作为输出模型，以控制最终 JSON 的结构。
示例代码
from typing import Optional
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from sqlmodel import SQLModel, Field, Relationship
# 定义项目基础模型（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")
# 定义用户基础模型（Pydantic部分）
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")
# 定义用于输出的Pydantic模型，可以控制输出的字段和嵌套结构
class UserOutput(UserBase):
projects: list[ProjectBase] = [] # 使用ProjectBase作为嵌套类型
# 数据库初始化与会话管理
engine = create_engine("sqlite://")
SQLModel.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)
# 使用输出模型验证并序列化
print(UserOutput.model_validate(user).model_dump_json())输出示例:
立即学习“Python免费学习笔记（深入）”；
{"id":1,"name":"User1","projects":[{"name":"Project 1","id":1},{"name":"Project 2","id":2}]}注意事项
- SQLModel 极大地减少了ORM模型和Pydantic模型之间的重复定义。
- 它内置了 Pydantic 的验证和序列化能力，使用 model_validate() 和 model_dump_json() 进行操作。
- 非常适合那些希望在一个地方管理数据库模式和API模式的项目。
总结与最佳实践
将 SQLAlchemy 模型序列化为 JSON 是构建 API 的关键一环。选择哪种方法取决于项目的具体需求和团队偏好：
- SQLAlchemy-serializer: 适用于需要快速、简单地为现有 SQLAlchemy 模型添加序列化功能的场景，特别是对递归控制有需求时。
- Pydantic: 适用于需要强大数据验证、清晰API模式定义以及类型安全的项目。它提供了最大的灵活性来定义输出结构，但需要维护两套模型（SQLAlchemy和Pydantic）。
- SQLModel: 适用于希望将数据库模型和API验证/序列化模型合二为一，减少冗余代码的项目。它在易用性和功能性之间取得了很好的平衡。
无论选择哪种方法，以下是一些通用的最佳实践：
- 处理关系加载: 确保在序列化之前，所有需要包含在 JSON 中的关联数据都已被加载（例如，使用 session.refresh() 或在查询时使用 joinedload/selectinload）。
- 避免循环引用: 对于复杂的关系，务必处理循环引用，否则可能导致无限递归或性能问题。SQLAlchemy-serializer的serialize_rules和Pydantic/SQLModel的显式模型定义都能有效解决此问题。
- 控制输出字段: 仅输出API消费者所需的数据，避免暴露敏感信息或不必要的内部字段。Pydantic和SQLModel的输出模型非常适合实现这一点。
- 性能考量: 对于大量数据或深度嵌套关系，序列化操作可能会消耗较多资源。考虑分页、限制关系深度或使用更高效的序列化库。
通过上述方法，开发者可以根据项目需求，灵活高效地将 SQLAlchemy 模型转换为结构清晰、易于消费的 JSON 数据，从而构建健壮的后端API。
