为何SQLAlchemy、Pydantic需在__init__外定义类属性？

问题背景 #

我正在修改一款应用，尝试使用Pydantic构建应用模型、SQLAlchemy构建数据库模型。此前按照常规写法，在类的__init__方法内定义属性：

class Measure:
    def __init__(
        self,
        t_received: int,
        mac_address: str,
        data: pd.DataFrame,
        battery_V: float = 0
    ):
        self.t_received = t_received
        self.mac_address = mac_address
        self.data = data
        self.battery_V = battery_V

但根据官方文档，SQLAlchemy与Pydantic均要求将属性定义在__init__方法之外，例如Pydantic的示例：

import pydantic

class Measure(pydantic.BaseModel):
    t_received: int
    mac_address: str
    data: pd.DataFrame
    battery_V: float

针对此场景，以下是相关疑问的解答：

1. 为何要求属性定义在__init__方法之外？ #

• Pydantic层面：Pydantic的核心功能（数据校验、序列化/反序列化、自动文档生成等）完全依赖类级别的类型注解。框架需要在类加载阶段扫描这些字段定义，自动生成对应的校验逻辑、构造函数以及字段元数据。如果把属性仅放在__init__内，Pydantic无法识别这些字段，也就无法提供其核心能力。
• SQLAlchemy层面：SQLAlchemy ORM需要通过类级别的字段定义来映射数据库表的列结构，以此生成DDL语句、构建查询表达式。类级别字段是ORM识别表结构的唯一依据，__init__内的赋值只是实例化时的属性填充，无法被ORM用于构建数据库映射关系。

2. 这种写法是否属于不良实践？ #

完全不是。这种类级别字段定义是Pydantic、SQLAlchemy这类框架的标准规范，是它们实现核心功能的基础。对于普通Python类，__init__内定义属性是常规写法，但在使用这类框架时，遵循其规范才是正确实践——框架会自动处理__init__生成、字段校验等逻辑，反而能减少重复代码。

3. 会对类的其他方法（如类方法、静态方法、属性等）产生影响吗？ #

不会。类级别字段定义仅用于给框架提供元数据，不会干扰类的其他方法：

• 类方法、静态方法的定义和调用逻辑与普通类完全一致，不受类级别字段影响；
• 依然可以定义@property装饰的属性，甚至可以和类级别字段同名（但不建议，避免混淆）；
• 实例化后，这些类级别字段会成为实例的属性，和__init__内赋值的属性用法完全相同。

4. 实例化时无法获得构造函数参数提示的解决办法 #

这个问题可以通过以下方式解决：

• IDE原生支持：主流IDE（PyCharm、VS Code + Python插件）都对Pydantic、SQLAlchemy 2.0+有完善的支持，会自动识别类级别字段并生成实例化的参数提示；
• 无需手动编写__init__：Pydantic和SQLAlchemy都会自动生成类型安全的构造函数，只要IDE配置正确，就能正常显示参数提示；
• 特殊场景处理：如果IDE支持有限，可以尝试更新Python插件或使用Pydantic的model_config配置，但通常无需额外操作。

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