Python SQLAlchemy全栈开发学习进阶指南：从零基础到项目实战

最新推荐文章于 2025-10-20 17:02:57 发布

原创最新推荐文章于 2025-10-20 17:02:57 发布 · 909 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#python #学习 #开发语言 #pip #fastapi #flask #django

Python 专栏收录该内容

101 篇文章

订阅专栏

文章目录

Python SQLAlchemy全栈开发学习进阶指南：从零基础到项目实战

Python SQLAlchemy全栈开发学习进阶指南：从零基础到项目实战

SQLAlchemy作为Python生态中最强大的ORM（对象关系映射）工具，以其灵活的架构、完整的SQL功能覆盖和对多种数据库的支持，成为连接Python应用与数据库的首选方案。从零基础掌握SQLAlchemy，需要经历从核心概念理解到CRUD操作、关系映射、再到项目工程化的系统化过程。本文将拆解这一过程的核心步骤，明确每个阶段的必备知识点、实践方法及注意事项，通过代码示例具象化关键概念，帮助学习者构建从理论到应用的完整知识体系。

一、阶段一：基础准备与核心概念（1-2周）

核心目标

理解ORM的基本思想，搭建SQLAlchemy开发环境，掌握核心组件（引擎、会话、模型）的概念与关系，能定义简单数据模型。

必备知识点

ORM基础认知
- ORM（对象关系映射）：将数据库表映射为Python类，记录映射为对象，操作对象即操作数据库（无需直接编写SQL）。
- 优势：屏蔽不同数据库语法差异，简化代码，提高可读性；劣势：复杂查询可能不如原生SQL高效。
- SQLAlchemy架构：分为Core（SQL表达式语言，偏向底层SQL操作）和ORM（基于Core的高层抽象，面向对象）。
环境配置与安装
- 安装：pip install sqlalchemy（核心库），根据数据库类型安装驱动（如PostgreSQL需psycopg2-binary，MySQL需pymysql）。
- 数据库连接字符串：格式为dialect+driver://username:password@host:port/database（如SQLite：sqlite:///mydb.db；MySQL：mysql+pymysql://user:pass@localhost:3306/mydb）。
核心组件
- Engine：数据库连接引擎，管理连接池，通过create_engine()创建（如engine = create_engine('sqlite:///mydb.db')）。
- Session：数据库会话，用于执行CRUD操作，通过sessionmaker创建（如Session = sessionmaker(bind=engine)）。
- Base：模型基类，所有数据模型需继承declarative_base()生成的基类，用于映射表结构。
- Model：映射数据库表的Python类，类属性对应表字段（通过Column定义）。

实践示例：第一个SQLAlchemy程序

# 1. 导入核心组件
from sqlalchemy import create_engine, Column, Integer, String, Text
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# 2. 创建基类（所有模型的父类）
Base = declarative_base()

# 3. 定义数据模型（映射到数据库表）
class Article(Base):
    """文章模型（对应articles表）"""
    __tablename__ = 'article'  # 表名
    
    # 字段定义：Column(类型, 约束)
    id = Column(Integer, primary_key=True, autoincrement=True)  # 主键，自增
    title = Column(String(200), nullable=False, index=True)  # 标题，非空，建索引
    content = Column(Text, nullable=False)  # 内容，长文本
    author = Column(String(100), nullable=False)  # 作者
    
    def __repr__(self):
        """打印对象时显示的信息（便于调试）"""
        return f"<Article(title='{self.title}', author='{self.author}')>"

# 4. 创建数据库引擎（连接数据库）
# SQLite：文件型数据库，无需服务器；其他数据库需提前创建数据库
engine = create_engine('sqlite:///blog.db', echo=True)  # echo=True：打印执行的SQL（开发用）

# 5. 创建表（根据模型自动生成表结构）
Base.metadata.create_all(engine)  # 仅创建不存在的表，不会覆盖已有表

# 6. 创建会话（用于操作数据库）
Session = sessionmaker(bind=engine)
session = Session()

注意事项

表名与模型名：模型类名通常为单数（如Article），表名__tablename__建议用复数（如articles），符合数据库命名习惯。
字段约束：根据业务需求添加约束（nullable=False确保非空，unique=True确保唯一），避免数据不一致。
echo参数：开发环境设为True（打印SQL）便于调试，生产环境设为False（减少日志开销）。
驱动安装：连接非SQLite数据库时必须安装对应驱动（如pip install psycopg2-binary用于PostgreSQL），否则会报连接错误。

二、阶段二：CRUD操作与查询基础（2-3周）

核心目标

掌握SQLAlchemy的增删改查（CRUD）操作，熟悉基础查询语法（过滤、排序、分页），能独立完成单表数据操作。

必备知识点

CRUD核心操作
- 创建（Create）：实例化模型对象→session.add(obj)添加到会话→session.commit()提交事务。
- 查询（Read）：session.query(Model)生成查询对象→链式调用filter()/filter_by()过滤、order_by()排序等→all()/first()获取结果。
- 更新（Update）：查询对象→修改属性→session.commit()提交。
- 删除（Delete）：查询对象→session.delete(obj)删除→session.commit()提交。
查询方法详解
- 过滤：filter(Model.field == value)（支持复杂条件，如and_/or_）；filter_by(field=value)（仅支持简单等值条件，语法更简洁）。
- 排序：order_by(Model.field)（升序）、order_by(Model.field.desc())（降序）。
- 限制结果：limit(n)（最多返回n条）、offset(m)（跳过前m条），结合实现分页。
- 聚合：count()（计数）、sum()、avg()（需配合func）。
会话管理
- 事务特性：会话操作默认在事务中，commit()提交所有更改，rollback()回滚错误操作。
- 上下文管理器：with Session() as session自动管理会话生命周期（退出时自动关闭）。

实践示例：完整CRUD操作

# 延续上例的Article模型、engine、Session

# 1. 创建数据（Create）
def create_article(title, content, author):
    # 实例化模型
    article = Article(
        title=title,
        content=content,
        author=author
    )
    # 添加到会话
    session.add(article)
    try:
        # 提交事务（实际写入数据库）
        session.commit()
        print(f"创建成功：{article}")
        return article
    except Exception as e:
        # 出错时回滚
        session.rollback()
        print(f"创建失败：{e}")

# 创建示例数据
create_article("SQLAlchemy入门", "ORM是个好工具...", "张三")
create_article("Python基础", "变量、函数、类...", "李四")
create_article("SQL进阶", "JOIN、索引、事务...", "张三")


# 2. 查询数据（Read）
def query_articles():
    # 2.1 查询所有文章
    all_articles = session.query(Article).all()
    print("\n所有文章：")
    for art in all_articles:
        print(art)  # 调用__repr__方法
    
    # 2.2 条件查询：查询作者为"张三"的文章（两种方式）
    zhang_articles1 = session.query(Article).filter(Article.author == "张三").all()
    zhang_articles2 = session.query(Article).filter_by(author="张三").all()  # 更简洁
    print("\n张三的文章：")
    print(zhang_articles1)
    
    # 2.3 排序与分页：按id降序，取前2条
    sorted_articles = session.query(Article).order_by(Article.id.desc()).limit(2).all()
    print("\n按ID降序的前2篇：")
    print(sorted_articles)
    
    # 2.4 复杂条件：标题包含"SQL"且作者不是"李四"
    sql_articles = session.query(Article).filter(
        Article.title.like("%SQL%"),  # 模糊查询
        Article.author != "李四"
    ).all()
    print("\n标题含SQL且作者不是李四的文章：")
    print(sql_articles)

query_articles()


# 3. 更新数据（Update）
def update_article(article_id, new_title):
    # 查询要更新的对象
    article = session.query(Article).filter_by(id=article_id).first()
    if not article:
        print(f"未找到ID为{article_id}的文章")
        return
    
    # 修改属性
    article.title = new_title
    try:
        session.commit()
        print(f"更新成功：{article}")
    except Exception as e:
        session.rollback()
        print(f"更新失败：{e}")

# 更新ID=1的文章标题
update_article(1, "SQLAlchemy入门与实践")


# 4. 删除数据（Delete）
def delete_article(article_id):
    article = session.query(Article).get(article_id)  # get()通过主键查询
    if not article:
        print(f"未找到ID为{article_id}的文章")
        return
    
    session.delete(article)
    try:
        session.commit()
        print(f"删除成功：ID={article_id}")
    except Exception as e:
        session.rollback()
        print(f"删除失败：{e}")

# 删除ID=2的文章（谨慎操作！）
# delete_article(2)


# 关闭会话（程序结束时）
session.close()

最佳实践

会话生命周期：每个请求/操作使用独立会话，避免长期持有会话（可能导致连接池耗尽），推荐用上下文管理器：

with Session() as session:  # 自动关闭会话
    article = Article(title="上下文管理器示例", content="...", author="测试")
    session.add(article)
    session.commit()

查询性能：避免query(Model).all()加载大量数据（内存占用过高），改用分页（limit+offset）或流式读取（yield_per）。
get()与filter_by()：通过主键查询时优先用get(primary_key)（更高效，直接命中索引），非主键查询用filter_by()。

三、阶段三：关系映射与复杂查询（3-4周）

核心目标

掌握表之间的关系映射（一对一、一对多、多对多），理解relationship的用法，能处理关联数据的CRUD操作，编写复杂联合查询。

必备知识点

关系类型与映射
- 一对多：最常见关系（如“用户-文章”：一个用户可发表多篇文章）。
  - 子表（文章）用ForeignKey关联父表（用户）主键。
  - 父表模型用relationship("子表模型", backref="父表反向引用名")定义关联。
- 一对一：特殊的一对多（限制子表只能有一条关联记录），通过uselist=False实现。
- 多对多：需中间表（如“学生-课程”：一个学生可选多门课，一门课可有多个学生），通过Table定义中间表，双方模型用relationship关联。
关联查询与加载策略
- 正向查询：通过父表对象的relationship属性获取子表数据（如user.articles）。
- 反向查询：通过子表对象的反向引用获取父表数据（如article.author）。
- 加载策略：
  - 懒加载（lazy="select"，默认）：访问关联数据时才执行查询（可能导致N+1问题）。
  - 即时加载（lazy="joined"）：查询主表时通过JOIN一次性加载关联数据（适合一对一/多对一）。
  - 批量加载（lazy="selectin"）：查询主表时批量加载关联数据（适合一对多/多对多）。
复杂查询
- 联合查询：query(Model1, Model2).join(Model2)（内连接）、outerjoin（外连接）。
- 子查询：subquery()生成子查询，作为主查询的条件或数据源。
- 聚合分组：group_by()结合func.count()等聚合函数（如统计每个作者的文章数）。

实践示例：一对多与多对多关系

from sqlalchemy import create_engine, Column, Integer, String, Text, ForeignKey, Table
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, relationship, joinedload, selectinload

Base = declarative_base()

# 1. 一对多关系：User(父) → Article(子)
class User(Base):
    __tablename__ = 'user'
    id = Column(Integer, primary_key=True)
    username = Column(String(50), unique=True, nullable=False)
    # 关联文章：backref="author"表示Article对象可通过author属性访问User
    articles = relationship("Article", backref="author", lazy="selectin")  # 批量加载关联文章

class Article(Base):
    __tablename__ = 'article'
    id = Column(Integer, primary_key=True)
    title = Column(String(200), nullable=False)
    content = Column(Text)
    # 外键：关联user表的id
    user_id = Column(Integer, ForeignKey('user.id'), nullable=False)


# 2. 多对多关系：Article ↔ Tag（需中间表）
# 定义中间表（无需模型，仅用于关联）
article_tag = Table(
    'article_tag',  # 表名
    Base.metadata,
    Column('article_id', Integer, ForeignKey('article.id'), primary_key=True),
    Column('tag_id', Integer, ForeignKey('tag.id'), primary_key=True)
)

class Tag(Base):
    __tablename__ = 'tag'
    id = Column(Integer, primary_key=True)
    name = Column(String(50), unique=True, nullable=False)
    # 关联文章：secondary指定中间表
    articles = relationship("Article", secondary=article_tag, backref="tags")


# 初始化数据库
engine = create_engine('sqlite:///relations.db', echo=True)
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()


# 3. 操作关联数据
def create_related_data():
    # 创建用户
    user = User(username="张三")
    session.add(user)
    session.commit()  # 先提交用户，获取id（外键需要）
    
    # 创建文章并关联用户
    article1 = Article(
        title="Python ORM教程",
        content="SQLAlchemy基础...",
        author=user  # 直接关联用户对象（自动设置user_id）
    )
    article2 = Article(
        title="Flask开发指南",
        content="Flask+SQLAlchemy集成...",
        user_id=user.id  # 也可直接设置外键
    )
    session.add_all([article1, article2])
    session.commit()
    
    # 创建标签并关联文章
    tag1 = Tag(name="Python")
    tag2 = Tag(name="Web开发")
    article1.tags = [tag1, tag2]  # 文章1关联两个标签
    article2.tags = [tag2]  # 文章2关联标签2
    session.add_all([tag1, tag2])
    session.commit()


# 4. 查询关联数据（避免N+1问题）
def query_related_data():
    # 4.1 查用户及其所有文章（用selectinload优化）
    # 错误方式（N+1问题）：先查用户，再访问user.articles时触发多次查询
    # user = session.query(User).first()
    # print(user.articles)  # 触发额外查询
    
    # 正确方式：一次性加载用户和文章
    user = session.query(User).options(selectinload(User.articles)).first()
    print(f"\n用户{user.username}的文章：")
    for art in user.articles:
        print(f"- {art.title}")
    
    # 4.2 查文章及其作者和标签（联合加载）
    article = session.query(Article).options(
        joinedload(Article.author),  # 即时加载作者（一对一）
        selectinload(Article.tags)   # 批量加载标签（多对多）
    ).first()
    print(f"\n文章《{article.title}》的作者：{article.author.username}")
    print(f"标签：{[tag.name for tag in article.tags]}")
    
    # 4.3 多表联合查询：查询所有带"Python"标签的文章及其作者
    python_articles = session.query(Article).join(Article.tags).join(Article.author).filter(
        Tag.name == "Python"
    ).all()
    print("\n带Python标签的文章：")
    for art in python_articles:
        print(f"- {art.title}（作者：{art.author.username}）")


# 执行操作
create_related_data()
query_related_data()

session.close()

注意事项

N+1查询问题：循环中访问关联数据（如for user in users: print(user.articles)）会触发1次用户查询+N次文章查询，需通过options(selectinload/joinedload)优化为1-2次查询。

backref与back_populates：推荐用back_populates显式定义双向关系（更清晰），替代backref（隐式）：

# 双向显式关联
class User(Base):
    articles = relationship("Article", back_populates="author")
class Article(Base):
    author = relationship("User", back_populates="articles")

多对多中间表：中间表名建议用两个关联表名的组合（如article_tag），字段为两个表的外键且联合为主键。

四、阶段四：事务管理与数据库迁移（2-3周）

核心目标

掌握事务ACID特性与SQLAlchemy的事务管理机制，学会用Alembic工具管理数据库schema变更（迁移），确保生产环境表结构迭代安全。

必备知识点

事务管理
- ACID特性：原子性（Atomicity）、一致性（Consistency）、隔离性（Isolation）、持久性（Durability）。
- SQLAlchemy事务：会话（Session）默认开启事务，commit()提交所有操作，rollback()回滚错误（如异常时）。
- 保存点（Savepoint）：复杂事务中用session.begin_nested()创建保存点，支持部分回滚。
数据库迁移（Alembic）
- 作用：管理表结构变更（新增字段、修改类型、添加索引等），替代Base.metadata.create_all()（仅能创建新表，无法修改已有表）。
- 流程：
  - 初始化：alembic init migrations（生成迁移环境）。
  - 配置：修改migrations/env.py，指定目标元数据（target_metadata = Base.metadata）和数据库连接。
  - 生成迁移：alembic revision --autogenerate -m "描述变更"（自动检测模型变更）。
  - 应用迁移：alembic upgrade head（将变更应用到数据库）。
迁移最佳实践
- 手动检查：自动生成的迁移文件可能遗漏变更（如索引、约束），需手动检查并补充。
- 版本控制：迁移文件纳入Git管理，确保团队成员使用相同的表结构。
- 回滚机制：alembic downgrade -1（回滚上一个版本），生产环境迁移前备份数据。

实践示例：事务处理与Alembic迁移

# 1. 事务处理示例
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from models import Base, User, Article  # 假设模型定义在models.py

engine = create_engine('sqlite:///transaction.db')
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)

def transfer_articles(old_user_id, new_user_id):
    """将旧用户的文章转移到新用户（事务确保原子性）"""
    session = Session()
    try:
        # 查询用户
        old_user = session.query(User).get(old_user_id)
        new_user = session.query(User).get(new_user_id)
        if not old_user or not new_user:
            raise ValueError("用户不存在")
        
        # 转移所有文章
        for article in old_user.articles:
            article.author = new_user
        
        # 提交事务（所有操作要么全成功，要么全失败）
        session.commit()
        print(f"成功将{old_user.username}的{len(old_user.articles)}篇文章转移到{new_user.username}")
    except Exception as e:
        # 出错回滚（不修改数据库）
        session.rollback()
        print(f"转移失败：{e}")
    finally:
        session.close()

# 创建测试用户并执行转移（略）


# 2. Alembic迁移步骤（命令行操作）
"""
# 安装Alembic
pip install alembic

# 初始化迁移环境
alembic init migrations

# 配置数据库连接（修改migrations/env.py）
# 在env.py中找到target_metadata，设置为模型基类的metadata
# target_metadata = Base.metadata
# 并修改sqlalchemy.url为实际连接字符串（如sqlalchemy.url = "sqlite:///mydb.db"）

# 生成第一次迁移（创建初始表）
alembic revision --autogenerate -m "initial tables: user, article"

# 应用迁移（创建表）
alembic upgrade head

# 后续修改模型（如给Article添加publish_time字段）后，生成新迁移
alembic revision --autogenerate -m "add publish_time to article"

# 应用新迁移
alembic upgrade head

# 如需回滚，执行（回滚上一个版本）
# alembic downgrade -1
"""

最佳实践

事务边界：将相关操作放在同一事务中（如“创建订单+扣减库存”），确保数据一致性，避免部分成功部分失败。
迁移自动化限制：Alembic无法自动检测所有变更（如字段类型修改、索引删除），需手动编辑迁移文件的upgrade()和downgrade()方法。
生产迁移流程：
1. 备份数据库；
2. 在测试环境验证迁移；
3. 生产环境执行alembic upgrade head；
4. 验证数据正确性。

五、阶段五：性能优化与高级特性（2-3周）

核心目标

掌握SQLAlchemy性能优化技巧（索引、批量操作、查询优化），了解高级特性（事件监听、自定义类型），解决高并发场景下的性能问题。

必备知识点

性能优化技巧
- 索引优化：为频繁查询的字段添加索引（index=True），复合索引（Index('idx_name', Model.field1, Model.field2)）优化多字段查询。
- 批量操作：session.bulk_insert_mappings(Model, [dict1, dict2])（批量插入）、session.bulk_update_mappings(Model, [dict1, dict2])（批量更新），比逐条操作快10-100倍。
- 原生SQL：复杂查询用text()执行原生SQL（session.execute(text("SELECT ..."))），避免ORM转换开销。
- 连接池配置：创建引擎时设置pool_size（连接池大小）、max_overflow（最大临时连接），优化并发性能（如create_engine(..., pool_size=10, max_overflow=20)）。
高级特性
- 事件监听：通过event.listen()监听模型生命周期事件（如after_insert、before_update），执行额外逻辑（如自动更新修改时间）。
- 自定义类型：继承TypeDecorator实现自定义字段类型（如加密字符串、JSON字段）。
- 编译扩展：自定义SQL生成逻辑，适配特定数据库特性（如PostgreSQL的JSONB类型）。

实践示例：性能优化与事件监听

from sqlalchemy import create_engine, Column, Integer, String, DateTime, event
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from datetime import datetime

Base = declarative_base()

# 1. 带索引和自动时间字段的模型
class OptimizedArticle(Base):
    __tablename__ = 'optimized_article'
    
    id = Column(Integer, primary_key=True)
    title = Column(String(200), nullable=False, index=True)  # 索引优化查询
    content = Column(String)
    author_id = Column(Integer, index=True)  # 外键索引
    created_at = Column(DateTime, default=datetime.utcnow)  # 创建时间
    updated_at = Column(DateTime, default=datetime.utcnow)  # 更新时间

# 2. 事件监听：自动更新updated_at
@event.listens_for(OptimizedArticle, 'before_update')
def update_modified_time(mapper, connection, target):
    """更新前自动设置updated_at为当前时间"""
    target.updated_at = datetime.utcnow()


# 3. 批量操作示例
def bulk_operations():
    engine = create_engine('sqlite:///optimize.db', echo=True)
    Base.metadata.create_all(engine)
    Session = sessionmaker(bind=engine)
    session = Session()
    
    # 批量插入1000条数据（比逐条add快很多）
    articles = [
        {"title": f"批量文章{i}", "content": f"内容{i}", "author_id": 1}
        for i in range(1000)
    ]
    session.bulk_insert_mappings(OptimizedArticle, articles)
    session.commit()
    print("批量插入完成")
    
    # 批量更新：将author_id=1的文章改为author_id=2
    update_data = [
        {"id": i+1, "author_id": 2}  # 需包含主键
        for i in range(1000)
    ]
    session.bulk_update_mappings(OptimizedArticle, update_data)
    session.commit()
    print("批量更新完成")
    
    session.close()


# 4. 原生SQL查询示例
def raw_sql_query():
    engine = create_engine('sqlite:///optimize.db')
    with engine.connect() as conn:
        # 执行原生SQL（适合复杂查询）
        result = conn.execute(
            "SELECT title, created_at FROM optimized_article WHERE author_id = :aid",
            {"aid": 2}  # 参数化查询，防止SQL注入
        )
        for row in result.fetchmany(5):  # 取前5条
            print(f"标题：{row.title}，创建时间：{row.created_at}")


# 执行优化示例
bulk_operations()
raw_sql_query()

注意事项

索引并非越多越好：索引加速查询但减慢插入/更新（需维护索引），仅为频繁查询的字段添加索引（如WHERE、JOIN、ORDER BY中使用的字段）。
批量操作限制：bulk_insert_mappings不触发模型的__init__方法和事件监听（如default值需手动设置），适合纯数据插入。
SQL注入风险：使用原生SQL时必须用参数化查询（:param），避免字符串拼接（如f"SELECT * FROM user WHERE name = '{name}'"）。

六、阶段六：项目实战与工程化（3-4周）

核心目标

综合运用SQLAlchemy开发完整项目，掌握模型模块化、会话管理、配置分离等工程化实践，结合Web框架（如Flask）实现数据持久层。

必备知识点

项目结构设计
- 模块化组织：按功能拆分模型（如models/user.py、models/article.py），通过models/__init__.py统一导出。
- 会话管理：封装会话工厂（db/session.py），提供全局会话入口，自动处理连接与关闭。
- 配置分离：开发/测试/生产环境的数据库配置分离（如config.py中定义不同类），通过环境变量切换。
与Web框架集成
- Flask集成：使用Flask-SQLAlchemy（简化版SQLAlchemy，自动管理会话与应用上下文）。
- Django集成：Django ORM与SQLAlchemy可共存，复杂查询用SQLAlchemy补充。
测试与部署
- 单元测试：用pytest测试模型方法、查询逻辑，使用内存数据库（sqlite:///:memory:）加速测试。
- 部署注意：生产环境使用连接池（避免频繁创建连接），监控数据库性能（慢查询、连接数）。

实践示例：Flask+SQLAlchemy项目结构

# 项目结构
/myproject
  /app
    /models           # 数据模型
      __init__.py
      user.py         # 用户模型
      article.py      # 文章模型
    /db               # 数据库相关
      __init__.py
      session.py      # 会话管理
    /routes           # 路由（Flask）
      __init__.py
      auth.py         # 认证路由
      blog.py         # 博客路由
    __init__.py       # Flask应用工厂
  /migrations         # Alembic迁移文件
  /tests              # 测试
    test_models.py
    test_routes.py
  config.py           # 配置
  run.py              # 启动脚本
  requirements.txt    # 依赖

1. 模型定义（app/models/user.py）：

from sqlalchemy import Column, Integer, String
from app.db.base import Base  # 共享基类

class User(Base):
    __tablename__ = 'user'
    id = Column(Integer, primary_key=True)
    username = Column(String(50), unique=True, nullable=False)
    email = Column(String(100), unique=True, nullable=False)
    password_hash = Column(String(128), nullable=False)

2. 会话管理（app/db/session.py）：

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from app.db.base import Base
from config import get_config  # 配置工厂函数

# 加载配置
config = get_config()
engine = create_engine(
    config.DATABASE_URI,
    pool_size=config.POOL_SIZE,
    max_overflow=config.MAX_OVERFLOW
)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# 依赖项：供Flask路由获取会话（自动关闭）
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

3. Flask集成（app/init.py）：

from flask import Flask
from app.routes.auth import auth_bp
from app.routes.blog import blog_bp

def create_app(config=None):
    app = Flask(__name__)
    if config:
        app.config.from_object(config)
    
    # 注册蓝图
    app.register_blueprint(auth_bp)
    app.register_blueprint(blog_bp)
    
    return app

4. 路由中使用（app/routes/blog.py）：

from flask import Blueprint, jsonify
from app.db.session import get_db
from app.models.article import Article

blog_bp = Blueprint('blog', __name__, url_prefix='/blog')

@blog_bp.get('/articles')
def get_articles():
    db = next(get_db())  # 获取会话
    articles = db.query(Article).limit(10).all()
    return jsonify([
        {"id": art.id, "title": art.title, "author": art.author.username}
        for art in articles
    ])

最佳实践

模型继承：定义基础模型（BaseModel）包含id、created_at、updated_at等公共字段，其他模型继承（减少重复代码）。
会话依赖：Web框架中用依赖注入（如Flask的get_db）管理会话，确保每个请求独立会话，避免线程安全问题。
测试隔离：测试时使用独立数据库（如SQLite内存库），每个测试用例前创建表，后销毁，避免测试间干扰。