Python SQLAlchemy 混合属性：用于强大数据建模的计算属性

SQLAlchemy，一个强大而灵活的 Python SQL 工具包和对象关系映射器 (ORM)，提供了一组丰富的功能，用于与数据库交互。 其中，混合属性 作为一种特别有用的工具脱颖而出，可在您的数据模型中创建计算属性。 本文提供了理解和利用 SQLAlchemy 混合属性的综合指南，使您能够构建更具表现力、可维护性和高效性的应用程序。

什么是 SQLAlchemy 混合属性？

顾名思义，混合属性是 SQLAlchemy 中一种特殊的属性类型，它可以根据访问它的上下文表现出不同的行为。 它允许您定义一个可以直接在类的实例上访问的属性（如常规属性）或在 SQL 表达式中使用（如列）。 这是通过为实例级别和类级别的访问定义单独的函数来实现的。

本质上，混合属性提供了一种定义从模型的其他属性派生的计算属性的方法。 这些计算属性可以在查询中使用，也可以直接在模型的实例上访问，从而提供一致且直观的界面。

为什么要使用混合属性？

使用混合属性具有以下几个优点：

• 表现力： 它们允许您直接在模型中表达复杂的关系和计算，使您的代码更具可读性且更易于理解。
• 可维护性： 通过将复杂逻辑封装在混合属性中，您可以减少代码重复并提高应用程序的可维护性。
• 效率： 混合属性允许您直接在数据库中执行计算，从而减少需要在应用程序和数据库服务器之间传输的数据量。
• 一致性： 无论您是使用模型的实例还是编写 SQL 查询，它们都为访问计算属性提供了一致的界面。

基本示例：全名

让我们从一个简单的例子开始：从一个人的名字和姓氏计算出他们的全名。

定义模型

首先，我们定义一个简单的 `Person` 模型，其中包含 `first_name` 和 `last_name` 列。

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from sqlalchemy.ext.hybrid import hybrid_property

Base = declarative_base()

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    def __repr__(self):
        return f""


engine = create_engine('sqlite:///:memory:') # In-memory database for example
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()

创建混合属性

现在，我们将添加一个 `full_name` 混合属性，该属性将名字和姓氏连接起来。

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    def __repr__(self):
        return f""

在此示例中，`@hybrid_property` 装饰器将 `full_name` 方法转换为混合属性。 当您访问 `person.full_name` 时，将执行此方法内的代码。

访问混合属性

让我们创建一些数据，看看如何访问 `full_name` 属性。

person1 = Person(first_name='Alice', last_name='Smith')
person2 = Person(first_name='Bob', last_name='Johnson')

session.add_all([person1, person2])
session.commit()

print(person1.full_name)  # Output: Alice Smith
print(person2.full_name)  # Output: Bob Johnson

在查询中使用混合属性

当您在查询中使用混合属性时，它的真正威力就发挥出来了。 我们可以根据 `full_name` 进行过滤，就像它是一个常规列一样。

people_with_smith = session.query(Person).filter(Person.full_name == 'Alice Smith').all()
print(people_with_smith) # Output: []

但是，上面的示例仅适用于简单的相等性检查。 对于查询中更复杂的操作（如 `LIKE`），我们需要定义一个表达式函数。

定义表达式函数

要在更复杂的 SQL 表达式中使用混合属性，您需要定义一个表达式函数。 此函数告诉 SQLAlchemy 如何将混合属性转换为 SQL 表达式。

让我们修改前面的示例以支持对 `full_name` 属性的 `LIKE` 查询。

from sqlalchemy import func

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    @full_name.expression
    def full_name(cls):
        return func.concat(cls.first_name, ' ', cls.last_name)

    def __repr__(self):
        return f""

在这里，我们添加了 `@full_name.expression` 装饰器。 这定义了一个函数，该函数将类 (`cls`) 作为参数，并返回一个 SQL 表达式，该表达式使用 `func.concat` 函数连接名字和姓氏。 `func.concat` 是一个 SQLAlchemy 函数，表示数据库的连接函数（例如，SQLite 中的 `||`，MySQL 和 PostgreSQL 中的 `CONCAT`）。

现在我们可以使用 `LIKE` 查询：

people_with_smith = session.query(Person).filter(Person.full_name.like('%Smith%')).all()
print(people_with_smith) # Output: []

设置值：Setter

混合属性也可以有 setter，允许您根据新值更新底层属性。 这是使用 `@full_name.setter` 装饰器完成的。

让我们向 `full_name` 属性添加一个 setter，该 setter 将全名拆分为名字和姓氏。

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    @full_name.expression
    def full_name(cls):
        return func.concat(cls.first_name, ' ', cls.last_name)

    @full_name.setter
    def full_name(self, full_name):
        parts = full_name.split()
        self.first_name = parts[0]
        self.last_name = ' '.join(parts[1:]) if len(parts) > 1 else ''

    def __repr__(self):
        return f""

现在您可以设置 `full_name` 属性，它将更新 `first_name` 和 `last_name` 属性。

person = Person(first_name='Alice', last_name='Smith')
session.add(person)
session.commit()

person.full_name = 'Charlie Brown'
print(person.first_name)  # Output: Charlie
print(person.last_name)   # Output: Brown

session.commit()

删除器

与 setter 类似，您还可以使用 `@full_name.deleter` 装饰器为混合属性定义一个删除器。 这允许您定义尝试 `del person.full_name` 时发生的情况。

对于我们的示例，让我们删除全名以清除名字和姓氏。

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    @full_name.expression
    def full_name(cls):
        return func.concat(cls.first_name, ' ', cls.last_name)

    @full_name.setter
    def full_name(self, full_name):
        parts = full_name.split()
        self.first_name = parts[0]
        self.last_name = ' '.join(parts[1:]) if len(parts) > 1 else ''

    @full_name.deleter
    def full_name(self):
        self.first_name = None
        self.last_name = None

    def __repr__(self):
        return f""

person = Person(first_name='Charlie', last_name='Brown')
session.add(person)
session.commit()

del person.full_name
print(person.first_name) # Output: None
print(person.last_name)  # Output: None

session.commit()

高级示例：从出生日期计算年龄

让我们考虑一个更复杂的示例：从一个人的出生日期计算出他们的年龄。 这展示了混合属性在处理日期和执行计算方面的强大功能。

添加出生日期列

首先，我们向 `Person` 模型添加一个 `date_of_birth` 列。

from sqlalchemy import Date
import datetime

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)
    date_of_birth = Column(Date)

    # ... (previous code)

使用混合属性计算年龄

现在我们创建 `age` 混合属性。 此属性根据 `date_of_birth` 列计算年龄。 我们需要处理 `date_of_birth` 为 `None` 的情况。

from sqlalchemy import Date
import datetime

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)
    date_of_birth = Column(Date)

    @hybrid_property
    def age(self):
        if self.date_of_birth:
            today = datetime.date.today()
            age = today.year - self.date_of_birth.year - ((today.month, today.day) < (self.date_of_birth.month, self.date_of_birth.day))
            return age
        return None # Or another default value

    @age.expression
    def age(cls):
        today = datetime.date.today()
        return func.cast(func.strftime('%Y', 'now') - func.strftime('%Y', cls.date_of_birth) - (func.strftime('%m-%d', 'now') < func.strftime('%m-%d', cls.date_of_birth)), Integer)

    # ... (previous code)

重要注意事项：

• 数据库特定的日期函数： 表达式函数使用 `func.strftime` 进行日期计算。 此函数特定于 SQLite。 对于其他数据库（如 PostgreSQL 或 MySQL），您需要使用适当的数据库特定日期函数（例如，PostgreSQL 中的 `EXTRACT`，MySQL 中的 `YEAR` 和 `MAKEDATE`）。
• 类型转换： 我们使用 `func.cast` 将日期计算的结果转换为整数。 这确保 `age` 属性返回一个整数值。
• 时区： 处理日期时，请注意时区。 确保您的日期以一致的时区存储和比较。
• 处理 `None` 值 该属性应处理 `date_of_birth` 为 `None` 的情况，以防止错误。

使用年龄属性

person1 = Person(first_name='Alice', last_name='Smith', date_of_birth=datetime.date(1990, 1, 1))
person2 = Person(first_name='Bob', last_name='Johnson', date_of_birth=datetime.date(1985, 5, 10))

session.add_all([person1, person2])
session.commit()

print(person1.age)  # Output: (基于当前日期和出生日期)
print(person2.age)  # Output: (基于当前日期和出生日期)

people_over_30 = session.query(Person).filter(Person.age > 30).all()
print(people_over_30) # Output: (根据当前日期大于 30 岁的人)

更复杂的示例和用例

计算电子商务应用程序中的订单总额

在电子商务应用程序中，您可能有一个 `Order` 模型，它与 `OrderItem` 模型具有关系。 您可以使用混合属性来计算订单的总价值。

from sqlalchemy import ForeignKey, Float
from sqlalchemy.orm import relationship

class Order(Base):
    __tablename__ = 'orders'
    id = Column(Integer, primary_key=True)
    items = relationship("OrderItem", back_populates="order")

    @hybrid_property
    def total(self):
        return sum(item.price * item.quantity for item in self.items)

    @total.expression
    def total(cls):
        return session.query(func.sum(OrderItem.price * OrderItem.quantity)).\
            filter(OrderItem.order_id == cls.id).scalar_subquery()

class OrderItem(Base):
    __tablename__ = 'order_items'
    id = Column(Integer, primary_key=True)
    order_id = Column(Integer, ForeignKey('orders.id'))
    order = relationship("Order", back_populates="items")
    price = Column(Float)
    quantity = Column(Integer)

此示例演示了一个更复杂的表达式函数，该函数使用子查询直接在数据库中计算总计。

地理计算

如果您正在处理地理数据，您可以使用混合属性来计算点之间的距离或确定点是否在某个区域内。 这通常涉及使用数据库特定的地理函数（例如，PostgreSQL 中的 PostGIS 函数）。

from geoalchemy2 import Geometry
from sqlalchemy import cast

class Location(Base):
    __tablename__ = 'locations'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    coordinates = Column(Geometry(geometry_type='POINT', srid=4326))

    @hybrid_property
    def latitude(self):
        if self.coordinates:
            return self.coordinates.x
        return None

    @latitude.expression
    def latitude(cls):
        return cast(func.ST_X(cls.coordinates), Float)

    @hybrid_property
    def longitude(self):
        if self.coordinates:
            return self.coordinates.y
        return None

    @longitude.expression
    def longitude(cls):
        return cast(func.ST_Y(cls.coordinates), Float)

此示例需要 `geoalchemy2` 扩展，并假定您正在使用启用了 PostGIS 的数据库。

使用混合属性的最佳实践

• 保持简单： 将混合属性用于相对简单的计算。 对于更复杂的逻辑，请考虑使用单独的函数或方法。
• 使用适当的数据类型： 确保混合属性中使用的数据类型与 Python 和 SQL 兼容。
• 考虑性能： 虽然混合属性可以通过在数据库中执行计算来提高性能，但必须监视查询的性能并根据需要对其进行优化。
• 彻底测试： 彻底测试您的混合属性，以确保它们在所有上下文中都能产生正确的结果。
• 记录您的代码： 清楚地记录您的混合属性，以解释它们的作用以及它们如何工作。

常见陷阱以及如何避免它们

• 数据库特定的函数： 确保您的表达式函数使用数据库无关的函数或提供数据库特定的实现，以避免兼容性问题。
• 不正确的表达式函数： 仔细检查您的表达式函数是否正确地将您的混合属性转换为有效的 SQL 表达式。
• 性能瓶颈： 避免将混合属性用于过于复杂或资源密集型的计算，因为这会导致性能瓶颈。
• 冲突的名称： 避免对混合属性和模型中的列使用相同的名称，因为这会导致混淆和错误。

国际化注意事项

在国际化的应用程序中使用混合属性时，请考虑以下事项：

• 日期和时间格式： 为不同的区域设置使用适当的日期和时间格式。
• 数字格式： 为不同的区域设置使用适当的数字格式，包括小数分隔符和千位分隔符。
• 货币格式： 为不同的区域设置使用适当的货币格式，包括货币符号和小数位。
• 字符串比较： 使用区域设置感知的字符串比较函数，以确保在不同的语言中正确比较字符串。

例如，在计算年龄时，请考虑世界各地使用的不同日期格式。 在某些地区，日期写为 `MM/DD/YYYY`，而在其他地区，日期写为 `DD/MM/YYYY` 或 `YYYY-MM-DD`。 确保您的代码正确解析所有格式的日期。

连接字符串（如在 `full_name` 示例中）时，请注意姓名排序中的文化差异。 在某些文化中，姓氏在名字之前。 考虑为用户提供自定义姓名显示格式的选项。

结论

SQLAlchemy 混合属性是用于在数据模型中创建计算属性的强大工具。 它们允许您直接在模型中表达复杂的关系和计算，从而提高代码的可读性、可维护性和效率。 通过了解如何定义混合属性、表达式函数、setter 和删除器，您可以利用此功能来构建更复杂和健壮的应用程序。

通过遵循本文中概述的最佳实践并避免常见陷阱，您可以有效地利用混合属性来增强 SQLAlchemy 模型并简化数据访问逻辑。 请记住考虑国际化方面，以确保您的应用程序能够为世界各地的用户正常工作。 通过仔细的规划和实施，混合属性可以成为 SQLAlchemy 工具包中不可或缺的一部分。