flask-admin 的 SQLAlchemy 后端:ModelView 配置、搜索过滤与内联表单全解析
flask-admin 的 SQLAlchemy 后端:ModelView 配置、搜索过滤与内联表单全解析
导读
flask_admin.contrib.sqla 是 Flask-Admin 官方提供的 SQLAlchemy 模型后端(model backend),它把 ORM 模型与 Flask-Admin 的管理界面无缝衔接起来:只需一行 admin.add_view(ModelView(User, db.session)),即可获得列表、搜索、过滤、分页、排序、增删改查等完整后台能力。本文将围绕 doc/api/mod_contrib_sqla.rst 中记载的 ModelView 及其全部配置项,结合 view.py、filters.py、form.py 等源码与 examples/sqla 实战示例,讲解如何从零搭建 SQLAlchemy 后台、如何利用搜索语法与过滤体系做数据筛选、如何通过内联模型和 AJAX 外键优化编辑体验,以及批量删除、查询定制等进阶玩法。
一、认识 SQLAlchemy 模型后端
Flask-Admin 的架构中,"model backend" 负责把某个 ORM(SQLAlchemy、Peewee、MongoEngine、PyMongo 等)映射为一套统一的 CRUD 视图。flask_admin.contrib.sqla 就是这套体系里的 SQLAlchemy 实现,核心入口只有一个类:
from flask_admin.contrib.sqla import ModelView
__init__.py 中直接导出了该符号(见 flask_admin/contrib/sqla/init.py),最简用法如下(与 view.py 中类文档示例一致):
from flask_admin import Admin
from flask_admin.contrib.sqla import ModelView
admin = Admin(app)
admin.add_view(ModelView(User, db.session))
它继承自 flask_admin/model/base.py 的 BaseModelView,因此所有通用配置(column_list、column_sortable_list、can_create、form_columns 等)同样生效;同时它又针对 SQLAlchemy 增加了与 ORM 强相关的配置项,这正是本篇文章的主体。
说明:文档中
ModelView的通用配置继承自BaseModelView,本文聚焦 SQLAlchemy 特有的部分;通用配置可参考 mod_model.rst。
二、构造参数与 session 的传递方式
ModelView.__init__ 的完整签名(见 view.py):
ModelView(
model, # 模型类
session, # flask_sqlalchemy.SQLAlchemy / flask_sqlalchemy_lite.SQLAlchemy 对象(推荐),或 scoped session(已废弃)
name=None, # 视图名,默认取模型名
category=None, # 菜单分类名
endpoint=None, # 端点名,默认取模型名
url=None, # 基础 URL,默认 '/admin/' + endpoint
static_folder=None,
menu_class_name=None, # 菜单项可选 class
menu_icon_type=None, # 菜单图标类型:ICON_TYPE_GLYPH / ICON_TYPE_FONT_AWESOME / ICON_TYPE_IMAGE / ICON_TYPE_IMAGE_URL
menu_icon_value=None, # 图标字形名或 URL
)
关于 session 的关键细节:构造函数内部调用 _warn_session_deprecation(session)(见 view.py)。当前仓库推荐直接传入 flask_sqlalchemy.SQLAlchemy 扩展对象,框架会通过其 .session 属性访问会话;直接传 scoped session 属于废弃用法。例如 examples/sqla/admin/main.py 中的写法:
admin.add_view(UserAdmin(User, db))
admin.add_view(ModelView(Tag, db))
admin.add_view(PostAdmin(db))
初始化时框架还会自动完成两件事(见 view.py):
- 调用
scaffold_pk()获取主键,若模型没有主键则直接抛异常; - 若未显式设置
column_select_related_list,则自动计算_auto_joins(关联加载路径),否则使用手动配置。
三、列表查询的性能配置
3.1 column_auto_select_related:自动关联加载
默认值为 True。开启后,Flask-Admin 会扫描列表视图中展示的外键关系,自动对相关模型做 joined loading,避免 N+1 查询。
需要特别注意的是(源码 docstring 明确说明):该检测不是递归的。如果关联模型的 __str__/__unicode__ 方法内部又访问了另一张表,仍会产生单独的数据库调用。
3.2 column_select_related_list:手动指定关联加载
类型为列名序列,优先级高于 column_auto_select_related。传给 SQLAlchemy 的 subqueryload,支持字符串或属性两种写法:
class PostAdmin(ModelView):
column_select_related_list = ('user', 'city')
# 等价写法
column_select_related_list = (Post.user, Post.city)
从实现看(view.py),只要设置了该属性,_auto_joins 就直接取用这个列表;而 get_list 中会为 _auto_joins 里的每个关系执行 query.options(joinedload(j))(见 view.py)。
3.3 column_display_all_relations:控制关系列展示
默认 False,此时列表只展示多对一(MANYTOONE)关系列;设为 True 则展示所有关系(一对多、多对多等)。相关逻辑在 scaffold_list_columns 中(view.py)。
3.4 多列排序与关联表排序
column_sortable_list 支持元组形式对关联表字段排序(见 view.py),examples/sqla 中就有典型用法:
column_sortable_list = [
"id",
"title",
"date",
"user.email", # 关联表字段排序,点号路径
("user", ("user.last_name", "user.first_name")), # 多列联合排序
]
若排序字段位于关联表,路径必须以 '<relation>.<column>' 字符串形式给出,否则会抛异常提示(view.py)。
四、搜索体系:column_searchable_list 与搜索语法
4.1 配置方式
column_searchable_list 接受字段名序列或列对象序列(见 view.py):
class MyModelView(ModelView):
column_searchable_list = ('name', 'email')
# 或
column_searchable_list = (User.name, User.email)
还可以搜索关联表的字段,如 examples 中的 PostAdmin(examples/sqla/admin/main.py):
column_searchable_list = [
"title",
"tags.name",
"user.first_name",
"user.last_name",
]
点号路径由 tools.get_field_with_path 解析,框架会自动生成所需的 JOIN(view.py)。hybrid property 也可以作为搜索字段(需要显式指定 expression 实现)。
4.2 三种搜索语法(重要)
在界面的搜索框中输入不同前缀会生成不同的 SQL 条件(源码 docstring 与 tools.parse_like_term 完全一致,见 tools.py):
| 输入 | 生成的语句 | 含义 |
|---|---|---|
ZZZ |
ILIKE '%ZZZ%' |
包含匹配 |
^ZZZ |
ILIKE 'ZZZ%' |
前缀匹配(^ 开头) |
=ZZZ |
ILIKE 'ZZZ' |
精确匹配(= 开头) |
- 输入多个词(以空格分隔)时,每个词被单独搜索,只有同时命中所有词的行才会显示。例如搜索
abc def,会找出在任一或多个搜索列中同时包含abc与def的行。 - 底层实现(
_apply_search,view.py):对每个词生成sql_cast(column, Unicode).ilike(stmt)条件,多列之间用or_组合、多词之间用 AND 叠加。 - 若设置了
column_labels,搜索框占位符会自动生成,如"Name, Last Name"(search_placeholder方法,view.py)。
五、过滤体系:column_filters、filter_converter 与自定义 Filter
5.1 基本配置
column_filters 可以包含字段名,也可以包含 BaseSQLAFilter 实例(见 view.py):
class MyModelView(ModelView):
column_filters = ('user', 'email')
界面展示时,同名的过滤器会自动分组,组内是"等于/不等于/包含"等不同操作。
5.2 BaseSQLAFilter:两种列传参方式
BaseSQLAFilter 位于 filters.py,column 参数既可以是真实的 SQLAlchemy 列 / InstrumentedAttribute,也可以是点号路径字符串:
class PostAdmin(ModelView):
column_filters = [
# 直接传列对象:
FilterEqual(column=Post.title, name="Title"),
# 或使用点号路径,绑定到视图模型后自动解析并生成 JOIN:
FilterLike(column="author.account.email", name="Author Email"),
]
注意两个使用约束(源码 bind 方法中的明确语义,filters.py):
- 用点号字符串构造的过滤器会缓存第一次解析出的属性和 JOIN 路径;如果同一个过滤器实例复用到不同模型的视图上,会抛出
RuntimeError,此时必须为每个视图新建过滤器实例。 - 用真实列/属性构造的过滤器可以自由共享。
5.3 filter_converter:类型到过滤器的映射
默认值为 sqla_filters.FilterConverter()(filters.py 起)。它按 SQLAlchemy 列类型自动生成一组可用过滤操作:
- 字符串(String/Text 等):
FilterLike、FilterNotLike、FilterEqual、FilterNotEqual、FilterEmpty、FilterInList、FilterNotInList - 整数:
IntEqualFilter、IntNotEqualFilter、IntGreaterFilter、IntSmallerFilter、FilterEmpty、IntInListFilter、IntNotInListFilter - 浮点:对应的
Float*Filter系列 - 布尔:
BooleanEqualFilter、BooleanNotEqualFilter(其clean方法把"1"转为布尔值,以兼容 psycopg3 严格的类型转换) - Enum:
EnumEqualFilter、EnumFilterNotEqual、EnumFilterEmpty、EnumFilterInList、EnumFilterNotInList - 日期/时间:
DateEqualFilter、DateBetweenFilter、DateNotBetweenFilter、DateTime*Filter、Time*Filter等 - UUID:
UuidFilterEqual、UuidFilterInList等
如果列类型没有对应的转换规则,convert 会返回 None(无过滤操作)。覆盖 filter_converter 属性即可使用自定义的转换器。
5.4 内置过滤操作类
常用的操作类(filters.py):
| 类 | 操作 | 说明 |
|---|---|---|
FilterEqual / FilterNotEqual |
equals / not equal | 等于 / 不等于 |
FilterLike / FilterNotLike |
contains / not contains | 大小写不敏感包含 |
FilterGreater / FilterSmaller |
greater than / smaller than | 大于 / 小于 |
FilterEmpty |
empty | 判断 NULL |
FilterInList / FilterNotInList |
in list / not in list | 多选,data_type="select2-tags" |
注意 FilterNotInList 的实现特别补了 or_(~column.in_(value), column == None),因为 SQL 的 NOT IN 会排除 NULL 值(filters.py)。
5.5 自定义过滤器:完整例子
column_filters 文档给出了自写过滤器的范式(view.py),examples/sqla 中有对应的可运行实现:
from flask_admin.contrib.sqla.filters import BaseSQLAFilter
class FilterLastNameBrown(BaseSQLAFilter):
def apply(self, query, value, alias=None):
if value == '1':
return query.filter(self.column == "Brown")
else:
return query.filter(self.column != "Brown")
def operation(self):
return 'is Brown'
class MyModelView(ModelView):
column_filters = [
FilterLastNameBrown(
User.last_name, 'Last Name', options=(('1', 'Yes'), ('0', 'No'))
)
]
自定义过滤器被应用于查询时,会先 clean(value) 再 apply(query, clean_value, alias)(见 view.py);旧式只接收 3 个参数(不含 alias)的 apply 方法仍会被兼容(发出 warnings.warn 提示补全 alias 参数)。
六、表单生成:model_form_converter、form_choices 与 form_optional_types
6.1 model_form_converter:模型到表单的转换器
默认值为 form.AdminModelConverter(form.py)。它负责把 SQLAlchemy 列转换成 WTForms 字段,覆盖了大量类型:
String(含 VARCHAR、CHAR、Unicode)→StringField,并根据column.type.length自动附加Length(max=...)校验;Text/LargeBinary/Binary/CIText→TextAreaField;Boolean→BooleanField;Date/DateTime/Time→ 对应日期字段;Integer(含 BigInteger、SmallInteger)→IntegerField,无符号列附加NumberRange(min=0);Numeric(含 DECIMAL、Float 等)→DecimalField,默认places=None遵循数据库精度;Enum→Select2Field,附带AnyOf校验;- PostgreSQL 专有类型:
INET→IP 校验、MACADDR→MAC 校验、UUID→UUID 校验、ARRAY→Select2TagsField(并自动推断元素 Python 类型做coerce)、HSTORE→内联键值编辑; - JSON →
JSONField; sqlalchemy_utils扩展类型:EmailType、URLType、IPAddressType、ColorType、CurrencyType、TimezoneType、ArrowType、ChoiceType、UUIDType 均有专门转换器。
自定义转换逻辑的方式(view.py):
class MyModelConverter(AdminModelConverter):
pass
class MyAdminView(ModelView):
model_form_converter = MyModelConverter
6.2 表单生成时的列级处理
AdminModelConverter.convert 中的关键规则(form.py):
- 主键默认不显示(除非显式列入
form_columns,或hidden_pk=True时转为HiddenField); - 外键列默认不显示,改为显示关系选择字段;
- 唯一列自动附加
Unique校验器(多列主键除外); - 非空且无默认值、类型不在
form_optional_types中的列自动附加InputRequired();可空列附加Optional(); - 关系字段(MANYTOONE / ONETOMANY / MANYTOMANY)会被转换为
QuerySelectField或QuerySelectMultipleField;若配置了form_ajax_refs则升级为AjaxSelectField/AjaxSelectMultipleField; - 若设置了
form_choices,则直接渲染为Select2Field。
6.3 form_choices:字段固定选项
把表单字段映射为固定下拉选项(view.py):
class MyModelView(ModelView):
form_choices = {'my_form_field': [
('db_value', 'display_value'),
]}
examples/sqla 中的实际用法:
form_choices = {
"type": AVAILABLE_USER_TYPES, # [('admin', 'Admin'), ('content-writer', 'Content writer'), ...]
}
6.4 form_optional_types:可空类型的白名单
默认 (Boolean,)。含义是:即使列被定义为 NOT NULL,只要其类型在此列表中,就不强制必填。例如把字符串列也放行:
form_optional_types = (Boolean, Unicode)
form_args、form_widget_args、form_overrides、column_labels、column_descriptions 等通用配置同样会参与转换过程(见 form.py 的 _get_label / _get_field_override 等辅助方法)。
七、内联模型:inline_models 与 inline_model_form_converter
7.1 三种声明方式
inline_models 用于父子关系模型在同一表单页内编辑(见 view.py):
# 1. 直接给子模型类
class MyModelView(ModelView):
inline_models = (Post,)
# 2. 子模型类 + 额外选项
class MyModelView(ModelView):
inline_models = [(Post, dict(form_columns=['title']))]
# 3. Django 风格的 InlineFormAdmin 实例
from flask_admin.model.form import InlineFormAdmin
class MyInlineModelForm(InlineFormAdmin):
form_columns = ('title', 'date')
class MyModelView(ModelView):
inline_models = (MyInlineModelForm(MyInlineModel),)
7.2 字段名定制与 OneToOne
- 通过
form_label定制生成的字段名:inline_models = ((Post, dict(form_label='Hello'))); - 或使用正向外键关系名 +
column_labels:column_labels = {'models': 'Hello'}。
默认使用 ManyToMany 关系;若模型是 OneToOne,需要为内联表单指定专门的 inline_converter:
from flask_admin.contrib.sqla.form import InlineOneToOneModelConverter
class MyInlineModelForm(InlineFormAdmin):
form_columns = ('title', 'date')
inline_converter = InlineOneToOneModelConverter
class MyModelView(ModelView):
inline_models = (MyInlineModelForm(MyInlineModel),)
7.3 底层映射机制
InlineModelConverter(form.py)会通过 _calculate_mapping_key_pair 在父模型与子模型之间自动查找前向/反向关系键对,并处理继承(base_mapper)情况;找不到反向关系时会抛出 Exception("Cannot find reverse relation for model ...")。
7.4 inline_model_form_converter:后处理钩子
若需要对内联表单做后处理,可自定义(view.py):
class MyInlineModelConverter(InlineModelConverter):
def post_process(self, form_class, info):
form_class.value = wtf.StringField('value')
return form_class
class MyAdminView(ModelView):
inline_model_form_converter = MyInlineModelConverter
八、批量删除与数据安全:fast_mass_delete
默认 False。批量删除时的行为差异(view.py 与 action_delete 实现 view.py):
False(默认):先从数据库读回每条记录,再逐条delete_model(),给 SQLAlchemy 机会清理多对多关联等依赖,安全但较慢;True:直接执行一条DELETE语句(query.delete(synchronize_session=False)),更快,但如果模型未配置DELETE CASCADE,可能留下脏数据。
class MyModelView(ModelView):
fast_mass_delete = True
删除动作默认已注册(@action("delete", ...)),并受 can_delete 与 action_disallowed_list 控制(examples/sqla 演示了如何禁用内置删除)。
九、查询定制:get_query / get_count_query / get_one
列表页的数据来源是 get_query(),可通过覆写它实现"持久过滤"(view.py):
class MyView(ModelView):
def get_query(self):
return super().get_query().filter(User.username == current_user.username)
def get_count_query(self):
return super().get_count_query().filter(User.username == current_user.username)
def get_one(self, id):
return self.get_query().filter(self.model.id == id).one()
源码特别提醒:覆写 get_query 时必须同步覆写 get_count_query(列表页总数)与 get_one(编辑页取记录),否则列表计数与编辑页会展示"未过滤"的数据。
get_count_query 默认使用 query(func.count("*")).select_from(self.model),避免 query(self.model).count() 产生的多余子查询(view.py)。
get_list(view.py)完整串联了整条查询流水线:搜索 → 过滤 → 计数 → 自动关联加载(joinedload)→ 排序 → 分页。它还支持 simple_list_pager 时跳过计数查询,page_size=0/False 表示不分页。
十、CRUD 流程、异常处理与钩子
10.1 创建 / 更新 / 删除
create_model(form):build_new_instance()构造实例 →form.populate_obj(model)→session.add→_on_model_change→commit;失败时回滚并 flash 错误(view.py)。update_model(form, model):populate_obj→_on_model_change→commit(view.py)。delete_model(model):先on_model_delete→flush→session.delete→commit(view.py)。
build_new_instance 使用 SQLAlchemy 的 class manager 创建实例,以便模型有自定义 __init__ 时仍能正确工作(view.py)。
10.2 唯一性约束冲突处理
handle_view_exception(view.py)对 IntegrityError 做了专门处理:若 Flask 配置 FLASK_ADMIN_RAISE_ON_INTEGRITY_ERROR(或回退到 FLASK_ADMIN_RAISE_ON_VIEW_EXCEPTION)为真则继续抛出;否则向用户 flash "Integrity error. ..." 并吞掉异常。
10.3 钩子方法
_on_model_change(form, model, is_created)、on_model_delete(model)、after_model_change、after_model_delete 等在 CRUD 各阶段被调用,可用于审计、级联、清理等业务逻辑。
十一、前端外键选择:form_ajax_refs
form_ajax_refs 让关系字段变成 Select2 AJAX 搜索框,适合数据量大的外键(examples/sqla):
form_ajax_refs = {
"user": {"fields": (User.first_name, User.last_name)},
"tags": {
"fields": (Tag.name,),
"minimum_input_length": 0, # 无输入也显示建议
"placeholder": "Please select",
"page_size": 5,
},
}
底层由 ajax.py 的 create_ajax_loader 创建 QueryAjaxModelLoader(见 view.py 的 _create_ajax_loader)。内联表单也支持 AJAX 外键(InlineModelConverter.process_ajax_refs,form.py)。
十二、完整的实战示例解读
仓库自带的 examples/sqla 是本文所有概念的"合订本",非常值得通读。其目录结构:
- examples/sqla/admin/init.py:Flask 应用与
SQLAlchemy扩展的初始化(SQLite 数据库); - examples/sqla/admin/models.py:
User、Post、Tag、Tree、Account五个模型,涵盖 UUID 主键、hybrid property、多对多表、递归关系、ChoiceType/ColorType/CurrencyType/TimezoneType等sqlalchemy_utils类型; - examples/sqla/admin/main.py:
UserAdmin、PostAdmin、TreeView三个视图与注册逻辑; - examples/sqla/main.py:入口,首次运行自动
build_sample_db()建库灌数据,随后app.run(debug=True)。
运行方式(在仓库根目录):
cd examples/sqla
pip install -e . # 或按 pyproject.toml 安装依赖
python main.py
然后访问 http://127.0.0.1:5000/admin/。该示例中值得关注的组合技巧:
- 搜索 + 点号路径:
PostAdmin.column_searchable_list同时搜索title、tags.name、user.first_name、user.last_name,跨两跳关联; - 过滤组合:
column_filters混用字段名、FilterEqual(User.last_name, "Last Name")、自定义FilterLastNameBrown、点号路径filters.FilterLike(column="user.email", name="Author Email")以及带选项的filters.FilterInList(column="user.account.provider", ...)——后者演示了跨Post -> user -> account -> provider多级关系的自动 JOIN(examples/sqla/admin/main.py); - 可编辑列表:
column_editable_list = ["type", "currency", "timezone"]实现表格内联编辑; - 多列默认排序:
column_default_sort = [("last_name", False), ("first_name", False)]; - 表单定制:
form_columns控制字段顺序、form_args传 WTForms 参数、form_widget_args控制 widget 属性、form_choices提供下拉选项; - 编辑时动态限制外键:覆写
edit_form修改featured_post.query_factory,只允许选择当前用户自己的文章(examples/sqla/admin/main.py); - 导出:
can_export = True、export_max_rows = 1000、export_types = ["csv", "xls"]。
十三、关联模块速览
flask_admin.contrib.sqla 包内其他文件也是该后端的重要组成部分:
- ajax.py:
QueryAjaxModelLoader与create_ajax_loader,支撑form_ajax_refs; - fields.py:
QuerySelectField、QuerySelectMultipleField、InlineModelFormList、InlineModelOneToOneField、HstoreForm等专用字段; - typefmt.py:
DEFAULT_FORMATTERS,列表页列的默认格式化器(column_type_formatters默认值来源); - validators.py:
Unique、TimeZoneValidator、valid_color、valid_currency等校验器; - widgets.py:X-Editable 等列表编辑组件;
- tools.py:
get_field_with_path、parse_like_term、get_primary_key、has_multiple_pks、tuple_operator_in(多列主键的 IN 查询,兼容 SQLite)等工具函数; - 字段与类型格式化细节可继续查阅 mod_contrib_sqla_fields.rst。
结语
flask_admin.contrib.sqla.ModelView 是 Flask-Admin 在 SQLAlchemy 生态中的"主战场":它以极低的样板代码换取开箱即用的后台能力,而 column_searchable_list 的三种搜索前缀、按类型自动生成的 column_filters 过滤组、可挂载自定义 BaseSQLAFilter 的扩展点、inline_models 的父子同页编辑、form_ajax_refs 的大表外键选择,以及 fast_mass_delete / get_query 覆写等机制,共同构成了从"能用"到"好用"再到"可深度定制"的完整梯度。结合 examples/sqla 通读 view.py 与 filters.py,即可全面掌握这一后端的能力边界与扩展方式。