升级SQLAlchemy至2.0.3后动态生成Marshmallow Schema遇Relationship错误

问题背景 #

之前参考Stack Overflow方案，通过装饰器为SQLAlchemy模型动态生成Marshmallow的SQLAlchemyAutoSchema，在SQLAlchemy 1.4下运行正常。升级至SQLAlchemy 2.0.3后，出现AttributeError: columns错误。

经排查，错误出在marshmallow-sqlalchemy的_get_field_class_for_property方法中：SQLAlchemy Relationship的direction属性未被动态加载，导致条件判断失败，代码错误尝试访问Relationship对象的columns属性。

目前已通过在装饰器中预加载模型关系（用sqlalchemy.inspect枚举relationships）解决问题，但希望能通过调整模型定义实现正常运行，无需预加载关系。

相关代码示例 #

1. 模型定义

@derive_schema
class Foo(db.Model):
    id = db.Column(UUID(as_uuid=True), primary_key=True, server_default=sqlalchemy.text("uuid_generate_v4()"))
    name = db.Column(String, nullable=False)
    def __repr__(self):
        return self.name

@derive_schema
class FooSettings(db.Model):
    foo_id = Column(UUID(as_uuid=True), ForeignKey('foo.id'), primary_key=True, nullable=False)
    my_settings = db.Column(JSONB, nullable=True)
    foo = db.relationship('Foo', backref=db.backref('foo_settings'))

2. 初始装饰器（报错版本）

import marshmallow
from marshmallow_sqlalchemy import SQLAlchemyAutoSchema
def derive_schema(cls):
    class Schema(SQLAlchemyAutoSchema):
        class Meta:
            include_fk = True
            include_relationships = True
            load_instance = True
            model = cls
    marshmallow.class_registry.register(f'{cls.__name__}.Schema', Schema)
    cls.Schema = Schema
    return cls

3. 报错关键信息

AttributeError: columns

4. 修复后的装饰器（预加载关系版本）

import marshmallow
from marshmallow_sqlalchemy import SQLAlchemyAutoSchema
from sqlalchemy import inspect
def derive_schema(cls):
    mapper = inspect(cls)
    _ = [_ for _ in mapper.relationships]
    class Schema(SQLAlchemyAutoSchema):
        class Meta:
            include_fk = True
            include_relationships = True
            load_instance = True
            model = cls
    marshmallow.class_registry.register(f'{cls.__name__}.Schema', Schema)
    cls.Schema = Schema
    return cls

根源分析 #

SQLAlchemy 2.0对关系属性的延迟加载机制做了调整：Relationship的direction等元数据属性不再在模型定义时立即初始化，而是需要触发映射器（Mapper）的初始化流程才会加载。而marshmallow-sqlalchemy在自动生成Schema时，会直接尝试访问direction属性判断关系类型，若该属性未加载，代码会错误地认为当前属性是列（Column），进而尝试访问columns属性，最终抛出异常。

无需预加载的模型定义调整方案 #

1. 显式声明关系的uselist参数 #

在定义relationship时，通过uselist显式指定关系是一对一（uselist=False）还是一对多（uselist=True，默认值）。这个参数会触发SQLAlchemy在模型定义阶段就初始化direction属性，无需等到inspect时才加载。

修改FooSettings的关系定义：

class FooSettings(db.Model):
    # ... 其他字段 ...
    foo = db.relationship('Foo', backref=db.backref('foo_settings', uselist=False))

这里uselist=False明确foo_settings是一对一关系，SQLAlchemy会直接设置direction为ONETOONE，marshmallow-sqlalchemy就能正确识别关系类型，不会去访问columns属性。

2. 提前触发全局映射器初始化 #

在所有模型定义完成后，调用sqlalchemy.orm.configure_mappers()强制初始化所有模型的映射器，这样所有关系的元数据都会被提前加载。可以在应用启动时执行该操作，之后再生成Schema：

# 先定义所有模型
class Foo(db.Model): ...
class FooSettings(db.Model): ...

# 初始化所有映射器
from sqlalchemy.orm import configure_mappers
configure_mappers()

# 再统一应用装饰器生成Schema
derive_schema(Foo)
derive_schema(FooSettings)

这种方式不需要修改模型定义，但需要调整装饰器的应用时机，确保在映射器初始化之后再生成Schema。

3. 确保模型引用的顺序合理性 #

如果使用字符串形式引用关联模型（如db.relationship('Foo')），确保被引用的模型（Foo）在引用它的模型（FooSettings）之前定义，或者确保所有模型都被加载到SQLAlchemy的元数据中。不过这种方式依赖定义顺序，不如前两种方案可靠。

总结 #

• 显式声明uselist参数是最优雅的方案：既明确了关系的语义，又从源头解决了元数据延迟加载的问题，无需修改装饰器逻辑。
• 全局初始化映射器适合已有大量模型的场景，无需逐个修改模型，但需要调整代码执行顺序。

内容的提问来源于stack exchange，提问作者Yuval Itzchakov