Flask-SQLAlchemy 模型与表定义完全指南

Flask-SQLAlchemy 模型与表定义完全指南

flask-sqlalchemy 项目地址: https://gitcode.com/gh_mirrors/fla/flask-sqlalchemy

前言

在Web开发中，数据库操作是核心环节之一。Flask-SQLAlchemy作为Flask生态中最受欢迎的ORM工具，为开发者提供了简洁高效的数据库操作方式。本文将深入讲解如何使用Flask-SQLAlchemy定义数据模型和表结构，帮助开发者构建健壮的数据库层。

基础类初始化

在SQLAlchemy 2.x版本中，模型定义有了新的基础类选择。我们需要先创建一个基础类，作为所有模型的父类。

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

这种声明式基类的方式比旧版更加清晰，也更符合现代Python的编码风格。

数据类支持

如果你喜欢使用Python的数据类(dataclass)特性，可以轻松地将其与SQLAlchemy模型结合：

from sqlalchemy.orm import DeclarativeBase, MappedAsDataclass

class Base(DeclarativeBase, MappedAsDataclass):
    pass

这种方式会自动为模型添加__init__方法，使得实例化模型时可以直接使用关键字参数，大大提升了代码的可读性。

元数据配置

对于需要数据库迁移的项目，建议配置约束命名约定(naming convention)，这能让生成的约束名称更加规范和可预测：

from sqlalchemy import MetaData

class Base(DeclarativeBase):
    metadata = MetaData(naming_convention={
        "ix": 'ix_%(column_0_label)s',
        "uq": "uq_%(table_name)s_%(column_0_name)s",
        "ck": "ck_%(table_name)s_%(constraint_name)s",
        "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
        "pk": "pk_%(table_name)s"
    })

这种配置特别适合使用Alembic进行数据库迁移的项目，能确保迁移脚本中的约束名称保持一致。

初始化扩展

定义好基础类后，就可以创建SQLAlchemy实例了：

db = SQLAlchemy(model_class=Base)

这个db对象将成为我们操作数据库的主要入口。

定义模型

模型是ORM的核心，它代表了数据库中的表结构。Flask-SQLAlchemy简化了模型定义过程：

from sqlalchemy.orm import Mapped, mapped_column

class User(db.Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    username: Mapped[str] = mapped_column(unique=True)
    email: Mapped[str]

这里有几个要点需要注意：

1. 使用类型注解(Mapped)明确字段类型
2. mapped_column用于配置列属性
3. 如果没有指定__tablename__，Flask-SQLAlchemy会自动生成表名
4. 必须至少定义一个主键列

创建数据库表

定义模型后，需要显式创建对应的数据库表：

with app.app_context():
    db.create_all()

注意：所有模型必须在调用create_all之前被导入，否则对应的表不会被创建。

定义表结构

虽然大多数情况下使用模型类就足够了，但有时我们可能需要直接定义表结构，特别是在处理多对多关系时：

import sqlalchemy as sa

user_book_m2m = db.Table(
    "user_book",
    sa.Column("user_id", sa.ForeignKey(User.id), primary_key=True),
    sa.Column("book_id", sa.ForeignKey(Book.id), primary_key=True),
)

这种表结构定义方式特别适合中间表，因为它不需要额外的模型类。

表反射

如果你需要连接到一个已存在的数据库，可以使用表反射功能自动获取表结构：

with app.app_context():
    db.reflect()

class Book(db.Model):
    __table__ = db.metadata.tables["book"]

表反射虽然方便，但在实际项目中需要注意：

1. 反射会获取所有表结构，包括你可能不需要的
2. 反射的表结构无法享受IDE的智能提示
3. 迁移工具可能无法正确识别变更

因此，建议仅在快速原型开发或已有数据库集成时使用反射功能，生产环境还是应该明确定义模型结构。

最佳实践

1. 明确命名：始终为模型指定__tablename__，避免依赖自动生成
2. 类型注解：使用Mapped类型注解提高代码可读性和IDE支持
3. 分离关注点：将模型定义放在单独的模块中，保持代码组织清晰
4. 谨慎使用反射：仅在必要时使用，生产环境推荐明确定义模型

通过遵循这些实践，你可以构建出既灵活又易于维护的数据库层，为Flask应用提供坚实的数据基础。

flask-sqlalchemy 项目地址: https://gitcode.com/gh_mirrors/fla/flask-sqlalchemy