Flask-邮件发送和数据模型

这篇讲什么

  • 前半篇用 Flask-Mail 发邮件:配置必须写在 Mail(app) 之前、Message 与 send() 的用法、异步发送的封装,以及测试时靠 record_messages 不真发。
  • 后半篇进 Flask-SQLAlchemy:建表删表、db.Model 的增删改查、字段类型与选项对照表、Alembic 迁移(Flask-Migrate 4.1.0)。
  • 实测环境 Flask 3.1.3 + Flask-SQLAlchemy 3.1.1 + SQLAlchemy 2.1.8,邮件那段是拿本机 SMTP 靶子跑出来的。

Flask-Mail 发邮件

  • 老笔记这节用的 flask_mail 现在仍然是官方生态里的那一个:PyPI 上最新是 0.10.0(2024-05-23 发布),仓库挂在 pallets-eco 组织下,依赖只有 flask 和 blinker。装法:

    1
    pip install flask-mail
  • 配置必须在 Mail(app) 之前写好。老笔记那句「必须先写配置,然后再创建Mail对象,否则配置无效」是对的,原因在源码里:init_app 会调 init_mail(app.config, ...),把所有 MAIL_* 读成一个固定的 state 挂到 app.extensions['mail']。实测:

    1
    2
    建 Mail 之后再改 config -> state.server='smtp-before.example'(改不动)
    再调一次 init_app(app) -> state.server='smtp-after.example'
  • 配置项与默认值(本机实测):

    键 默认值 说明
    MAIL_SERVER 127.0.0.1 SMTP 服务器
    MAIL_PORT 25 端口,TLS 常用 587、SSL 常用 465
    MAIL_USE_TLS False 587 端口用这个
    MAIL_USE_SSL False 465 端口用这个
    MAIL_USERNAME / MAIL_PASSWORD None 登录凭据
    MAIL_DEFAULT_SENDER None 默认发件人
    MAIL_SUPPRESS_SEND 等于 testing 只测试时设 True,不真发
    MAIL_DEBUG 等于 app.debug
    MAIL_MAX_EMAILS None 一次连接最多发几封
    MAIL_ASCII_ATTACHMENTS False 附件名转 ASCII
  • 用户名和密码走环境变量,不要把明文写进代码:

    app.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    import os
    from flask import Flask
    from flask_mail import Mail

    app = Flask(__name__)
    app.config['MAIL_SERVER'] = os.environ.get('MAIL_SERVER', 'smtp.163.com')
    app.config['MAIL_USERNAME'] = os.environ.get('MAIL_USERNAME')
    app.config['MAIL_PASSWORD'] = os.environ.get('MAIL_PASSWORD')
    app.config['MAIL_DEFAULT_SENDER'] = os.environ.get('MAIL_USERNAME')
    mail = Mail(app)

发一封真的邮件

app.py
1
2
3
4
5
6
7
8
9
10
from flask_mail import Message

@app.route('/send/')
def send():
msg = Message(subject='账户激活', recipients=['recv@example.com'])
msg.body = '邮件发送测试,请点击链接完成账户激活!'
msg.html = '<h1>邮件发送测试,请点击链接完成账户激活!</h1>'
msg.attach('note.txt', 'text/plain', '激活链接见附件')
mail.send(msg)
return '已发送'
  • 本机起了一个只监听 127.0.0.1 的最小 SMTP 桩,真跑一遍抓到的完整会话是:

    1
    2
    3
    4
    5
    6
    7
    ehlo [172.30.48.1]
    AUTH LOGIN cHJvYmUtdXNlcg==
    cHJvYmUtcGFzc3dvcmQ=
    mail from:<sender@example.com>
    rcpt to:<recv@example.com>
    data
    quit
  • 正文 1076 字节,头部长这样(中文主题被编码成 base64 是正常的):

    1
    2
    3
    4
    5
    Content-Type: multipart/mixed; boundary="===============5638105417725480875=="
    MIME-Version: 1.0
    Subject: =?utf-8?b?6LSm5oi35r+A5rS7?=
    From: sender@example.com
    To: recv@example.com

    body 和 html 组成 multipart/alternative,附件再套一层 multipart/mixed,实测两个都在。

  • Message 的构造参数是位置敏感的:Message(subject, recipients, sender, body, html),推荐全用关键字。不写 sender 时取 MAIL_DEFAULT_SENDER,两者都没有实测报:

    1
    AssertionError: The message does not specify a sender and a default sender has not been configured
  • 附件在 0.10 里不再是元组:实测 msg.attachments 里是 Attachment 对象,字段为 data / filename / content_type / disposition / headers,老笔记那种 msg.attachments[0][0] 的下标写法会 TypeError: 'Attachment' object is not subscriptable。

封装与异步发送

  • 常见封装是模板渲染加发送:

    app.py
    1
    2
    3
    4
    5
    6
    def send_mail(to, subject, template, **kwargs):
    msg = Message(subject, recipients=[to])
    msg.html = render_template(template + '.html', **kwargs)
    msg.body = render_template(template + '.txt', **kwargs)
    mail.send(msg)
    return msg

    所以要准备成对的 activate.html 和 activate.txt 两个模板。

  • 发真邮件是慢 IO,放线程里做。这里有个必须理解的点:线程里没有请求上下文,所以不能把 current_app 这个代理直接传过去,要取原对象:

    app.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    from threading import Thread
    from flask import current_app

    def async_send(app_obj, msg):
    with app_obj.app_context():
    mail.send(msg)

    def send_mail_async(to, subject, template, **kwargs):
    app_obj = current_app._get_current_object()
    msg = Message(subject, recipients=[to])
    msg.html = render_template(template + '.html', **kwargs)
    msg.body = render_template(template + '.txt', **kwargs)
    thr = Thread(target=async_send, args=[app_obj, msg])
    thr.start()
    return thr
  • 实测对照:在新线程里直接 Message(...) 得到 RuntimeError: Working outside of application context.;把 current_app._get_current_object() 传进去再 with app.app_context(): 就正常。

  • 老笔记那段代码里还留着 manager.run(),flask_script 已经不能用,启动方式见 Flask-基本入门。

测试与不真发

  • 单测里不要连 SMTP,用 Flask-Mail 自带的信号收集:

    app.py
    1
    2
    3
    with mail.record_messages() as outbox:
    mail.send(Message('测试主题', recipients=['r@example.com'], body='正文'))
    mail.send(Message('第二封', recipients=['s@example.com'], body='b2'))

    实测 outbox 长度 2,元素就是发出去的 Message,subject / recipients / html / body 都能直接断言。

  • MAIL_SUPPRESS_SEND=True 时 send() 什么都不连也不报错,实测抓不到任何会话。

  • 另一个选择是 Flask-Mailman 1.1.1(Django email 后端的移植)。它用的键和 Flask-Mail 是同一套 MAIL_*(源码里读 MAIL_SERVER、MAIL_PORT、MAIL_USERNAME…),再加一个 MAIL_BACKEND;Mail(app, testing=True) 会把后端自动切成 locmem。网上流传的 MAILMAN_* 前缀并不存在,别照抄。

Flask-SQLAlchemy

  • Flask-SQLAlchemy 把 SQLAlchemy 接到 Flask 的应用上下文上,本机版本 3.1.1 + SQLAlchemy 2.1.8。装法:

    1
    pip install flask-sqlalchemy
  • 连接串 SQLALCHEMY_DATABASE_URI 说的是「用哪个库、怎么连」:

    数据库 写法
    SQLite(Windows) sqlite:///C:/path/to/data.sqlite
    SQLite(Linux/macOS) sqlite:////path/to/data.sqlite
    MySQL(官方推荐,C 扩展) mysql+mysqldb://user:password@127.0.0.1:3306/dbname?charset=utf8mb4
    MySQL(纯 Python 备选) mysql+pymysql://user:password@127.0.0.1:3306/dbname?charset=utf8mb4
    PostgreSQL postgresql+psycopg://user:password@127.0.0.1:5432/dbname
    • SQLite 后面那几个斜杠不是笔误:sqlite:/// 之后接路径,绝对路径要四个斜杠。
    • 老笔记写的 mysql + pymysql://... 中间有空格,charset-utf8 也少了等号,照抄一定连不上。
    • MySQL 驱动按 SQLAlchemy 官方口径用 C 扩展 mysqlclient(连接串里写 mysql+mysqldb)。本机 flask 环境实测:pip install mysqlclient 直接拿到 mysqlclient-2.3.0-cp314 的 wheel,不用编译;create_engine('mysql+mysqldb://...') 建得起来,dialect.driver 是 mysqldb。纯 Python 的 PyMySQL 同样实测可用(dialect.driver 为 pymysql),装不了 C 扩展时用它。
    • PyMySQL 的版本别看错:importlib.metadata.version('pymysql') 和 pymysql.VERSION 都是 1.2.3(包版本),而 pymysql.__version__ 给出的是 2.2.8——那是它链接的 MySQL 客户端库版本。写版本号要用前者。
    • 取驱动版本别写 MySQLdb.__version__,实测这个属性不存在,要写 MySQLdb.version_info(得到 (2, 3, 0, 'final', 0))或 importlib.metadata.version('mysqlclient')。
    • 装法与真实连库的实测见 Django 系列,本系列不重复;连接串里的 password 走环境变量,不要把明文写进代码。
  • 初始化有两种写法。实测 SQLAlchemy(app) 在 3.1.1 上不报警告,但同一个 app 上注册两次会直接报错:

    1
    2
    SQLAlchemy(app) -> 建成,警告 0 条
    再 init_app(app) -> RuntimeError: A 'SQLAlchemy' instance has already been registered on this Flask app.

    项目稍大就建议拆成「模块级 db = SQLAlchemy() + 工厂里 db.init_app(app)」,这样模型文件不会反向依赖 app 实例。

建表与删表

app.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import os
from flask import Flask
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///' + os.path.join(
app.root_path, 'data.sqlite')
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
db = SQLAlchemy(app)


class User(db.Model):
__tablename__ = 'users'
id = db.Column(db.Integer, primary_key=True)
username = db.Column(db.String(20), unique=True)
email = db.Column(db.String(60), unique=True)
age = db.Column(db.Integer, default=20)
  • create_all() / drop_all() 必须在应用上下文里调用,这是 FSA 3.x 的硬要求,实测在上下文外直接:

    1
    RuntimeError: Working outside of application context.
    app.py
    1
    2
    3
    with app.app_context():
    db.create_all()
    db.drop_all() # 同样必须在上下文里,实测上下文外调用报上面那句 RuntimeError
  • 实测建出来的表清单跟着模型走:['long_name_model', 'user_profile', 'users']。

  • SQLALCHEMY_TRACK_MODIFICATIONS 默认就是 None(不追踪),显式设 False 只是把话说明白;设 True 会给每个对象记一份变更快照,白耗内存。

  • 老笔记里的 SQLALCHEMY_COMMIT_ON_TEARDOWN 已经彻底失效(FSA 2.0 就删了,键留着没人读)。实测:

    1
    2
    3
    同一会话里 add 不 commit -> 查得到 ['没提交']
    新上下文里再查 -> []
    正常 commit 后新上下文查 -> ['提交了']

    第一行看得到是因为同一会话有身份映射(identity map),并不是已经落库,rollback() 之后它就消失。结论:想提交就自己 db.session.commit()。

数据的CURD操作

  • 增删改都在 db.session 上,改完必须 commit:

    app.py
    1
    2
    3
    4
    5
    6
    7
    @app.route('/insert/')
    def insert():
    fei = User(username='fei', email='fei@163.com')
    ouya = User(username='ouya', email='ouya@163.com', age=31)
    db.session.add_all([fei, ouya])
    db.session.commit()
    return '数据已插入'
  • 按主键查:老笔记的 User.query.get(2) 还能用,但实测会发 LegacyAPIWarning——SQLAlchemy 2.x 起 Query.get() 属于遗留 API,新写法是 db.session.get():

    1
    2
    session.get(User, 1) -> 'qiqi' age=20(default 生效)
    User.query.get(2) -> 'fei',警告 1 条:LegacyAPIWarning
  • 改:拿到对象后直接改属性再 commit,实测 age 从 20 改成 33 生效。老笔记说「add 带 ID 的对象会自动识别成更新」,其实从上下文里 get 出来的对象本来就在这个会话的脏集合里,add 是多余的。

  • 删:db.session.delete(obj) 再 commit,实测删一条后 count 从 3 变 2。

  • 回滚:db.session.rollback() 丢掉未提交的改动,实测 ['qiqi','fei','tmp'] 回滚后变 ['qiqi','fei']。

  • 项目里常用的是逻辑删除:加一个 is_deleted 布尔列,删除只改这一列,查询统一带 filter_by(is_deleted=False)。

模型设计参考

字段类型

  • 老笔记的类型表在本机逐个核对过都对得上,只有 BigInteger 的 Python 类型要按 3.x 改成 int(早就没有 long 了):

    类型 Python 类型 说明
    Integer int 32 位整数
    SmallInteger int 16 位
    BigInteger int 大整数
    Float float 浮点
    String str 变长字符串,要给长度
    Text str 长文本
    Boolean bool 布尔
    Date datetime.date 日期
    Time datetime.time 时刻
    DateTime datetime.datetime 日期时间
    Interval datetime.timedelta 时间间隔
  • db.TEXT 这种大写别名实测还在(hasattr(db, 'TEXT') 为 True),但 SQLAlchemy 2.x 的写法是小写类名。

字段选项

选项 默认值 说明
primary_key False 主键,FSA 要求每个模型至少一个,习惯叫 id
unique False 唯一索引
index False 普通索引
nullable True 能否为空
default 无 Python 侧默认值,插入时才生效
server_default 无 建表时写进 DDL 的默认值
  • 实测三列的取值:age 是 nullable=True default=ScalarElementColumnDefault(20);active 设了 nullable=False, server_default='1' 之后 default 仍是 None(默认值交给数据库);note 两者皆空。
  • 不写 __tablename__ 时表名由类名转换,实测 UserProfile -> user_profile、LongNameModel -> long_name_model。

数据库的迁移

  • drop_all() + create_all() 会把数据一起清掉,改表结构必须用迁移:Flask-Migrate(底层是 Alembic)对比模型和库的差异,生成脚本再执行,数据不丢。

  • 装与接:

    1
    pip install flask-migrate
    app.py
    1
    2
    3
    4
    from flask_migrate import Migrate

    db = SQLAlchemy(app)
    Migrate(app, db)
  • 老笔记的 MigrateCommand 和 manager.add_command('db', MigrateCommand) 已经不存在了(那是 flask-script 时代的东西)。FSA 3.x + Flask-Migrate 4.1.0 只要 Migrate(app, db),命令自动挂到 flask db 下面。

  • 三步走,实测本机 Flask-Migrate 4.1.0 的子命令齐全(init / migrate / upgrade / downgrade / revision / history / current / check / merge / stamp / show / edit / heads / branches / list-templates):

    1
    2
    3
    flask db init
    flask db migrate -m "first"
    flask db upgrade

    实测输出:

    1
    2
    3
    4
    db init    -> rc=0,提示去编辑 migrations/alembic.ini 与 env.py
    db migrate -> Generating ...\migrations\versions\43612e1d6ea3_first.py ... done
    db upgrade -> rc=0
    migrations 目录 -> ['README', 'alembic.ini', 'env.py', 'script.py.mako', 'versions']
  • init 只跑一次(建 migrations/ 目录,这个目录要进版本库),之后每次改模型都是 migrate + upgrade。

  • 自动对比不是万能的:改列名会被识别成「删一列 + 加一列」,数据就丢了;约束、索引、服务器默认值也不一定抓得到。所以 migrate 生成的脚本要先打开看一眼再 upgrade——实测脚本就落在 versions/ 下,upgrade 之前改它完全可行。

  • 生产库上跑之前先备份;flask db downgrade 只能回退脚本里写了 downgrade() 的部分。

参考

本文结束 感谢您的阅读
正在加载今日诗词....