flask-admin 的 SQLAlchemy 后端:ModelView 配置、搜索过滤与内联表单全解析

原创2026-10-09 23:12:361,977 阅读
文章标签:后端

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/。该示例中值得关注的组合技巧:

  1. 搜索 + 点号路径:PostAdmin.column_searchable_list 同时搜索 title、tags.name、user.first_name、user.last_name,跨两跳关联;
  2. 过滤组合: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);
  3. 可编辑列表:column_editable_list = ["type", "currency", "timezone"] 实现表格内联编辑;
  4. 多列默认排序:column_default_sort = [("last_name", False), ("first_name", False)];
  5. 表单定制:form_columns 控制字段顺序、form_args 传 WTForms 参数、form_widget_args 控制 widget 属性、form_choices 提供下拉选项;
  6. 编辑时动态限制外键:覆写 edit_form 修改 featured_post.query_factory,只允许选择当前用户自己的文章(examples/sqla/admin/main.py);
  7. 导出: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,即可全面掌握这一后端的能力边界与扩展方式。

登录后查看全文
flask-admin