高效将SQLAlchemy模型序列化为JSON的专业指南-Python教程-PHP中文网

高效将SQLAlchemy模型序列化为JSON的专业指南

本文旨在为Python后端开发者提供将SQLAlchemy模型对象及其关联关系高效序列化为JSON格式的专业指南。针对传统方法难以处理继承字段和关联对象的问题，文章详细介绍了三种主流解决方案：SQLAlchemy-serializer、Pydantic以及SQLModel，并通过详细代码示例和解释，帮助读者理解并掌握如何在API开发中实现复杂SQLAlchemy模型的完整JSON输出，确保数据传输的准确性和灵活性。

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是一个极具吸引力的选择。

在实际项目中，选择哪种方法取决于具体需求：