后端页面编写

该章节将介绍如何在 Pear Admin Flask 中编写一个新后端页面，此章节将会以编写兑换码管理页面为例，编写一个兑换码管理的后台页面。

备注

前端页面制作，请参考简单前端页面示例章节。

项目初始化逻辑

我们知道，一个简单的 Flask 项目是从 app = Flask(__name__) 开始的，而 Pear Admin Flask 的初始化的逻辑同理也是在此基础上，不过稍加复杂了一点。下面这张图片将会揭示项目初始化的逻辑。（点击可查看大图）

../_images/Pear%20Admin%20Flask%20%E5%90%AF%E5%8A%A8%E6%B5%81%E7%A8%8B%E5%9B%BE.png

由此可以看出，我们想要添加自己的后端页面，可以在 “注册项目的视图函数”（蓝框）的地方添加，当然，同样页面可以作为插件的方式接入以提高项目的拓展性。下面将介绍如何在这两种方式下添加自己的后台页面。

设计数据库

兑换码一定是保存在数据库中的，我们现在要求改程序至少有以下几个功能：

可以通过 flask admin init 或者等价的命令初始化数据库
数据库存在统一管理的模型
数据库的内容方便数据转化

数据的字段可以定为：

id -- 唯一主键
key -- 兑换码
content -- 具体的内容
enable -- 是否启用
used -- 是否使用
create_at -- 创建时间

根据上述需求，我们可以设计出这样一个数据库 Model ：

import datetime
from applications.extensions import db


class Gift(db.Model):
    __tablename__ = 'admin_gift'
    id = db.Column(db.Integer, primary_key=True, comment="唯一ID")
    key = db.Column(db.String(50), comment="兑换码")
    content = db.Column(db.String(), comment="具体的内容")
    enable = db.Column(db.Integer, default=0, comment='是否启用')
    used = db.Column(db.Integer, default=0, comment='是否已经使用')
    create_at = db.Column(db.DateTime, default=datetime.datetime.now, comment='创建时间')

我们将该文件命名为 admin_gift.py 放置在 applications/models/admin_gift.py ，而后为了使程序可以调用到这个模型，需要在 applications/models/__init__.py 中导入这个模型。

from .admin_gift import Gift

备注

由于 Gift 模型是 db.Model 的子类，在使用 flask db init 等命令行初始化数据库时，自动对 Gift 表进行创建，前提是这个类已经被 Python 加载，换而言之，Python 会自动将 db.Model 的子类作为数据库的一部分，加入到数据库初始化中。

初始化数据库

通过上面的操作，我们已经成功将数据库中的 admin_gift 表进行创建。现在我们希望在使用 flask admin init 的时候，可以将我们已经定义的数据写入到数据表中。

在 applications/common/script 目录中，撰写了默认数据的写入脚本（也就是 Flask 启动最后加载的项目），我们要做的是在 applications/common/script/admin.py 中添加自己需要的数据，我们可以对其进行修改，添加如下的代码：

...
from applications.models import Gift

...
now_time = datetime.datetime.now()
...
powerdata = [
    ...
    Power(
        id=60,
        name='兑换码管理',
        type='1',
        code='system:gift:main',
        url='/system/gift/',
        open_type='_iframe',
        parent_id='1',
        icon='layui-icon layui-icon layui-icon layui-icon-diamond',
        sort=8,
        create_time=now_time,
        enable=1
    ), Power(
        id=61,
        name='兑换码添加',
        type='2',
        code='system:gift:add',
        url='',
        open_type='',
        parent_id='60',
        icon='',
        sort=0,
        create_time=now_time,
        enable=1
    ), Power(
        id=62,
        name='兑换码删除',
        type='2',
        code='system:gift:remove',
        url='',
        open_type='',
        parent_id='60',
        icon='',
        sort=0,
        create_time=now_time,
        enable=1
    ), Power(
        id=63,
        name='兑换码编辑',
        type='2',
        code='system:gift:edit',
        url='',
        open_type='',
        parent_id='60',
        icon='',
        sort=0,
        create_time=now_time,
        enable=1
    ),
    ...
]
giftdata = [
    Gift(
        id=0,
        key='myTestCode',
        content='8折优惠',
        enable=1,
        used=0,
        create_at=now_time
    ),
    Gift(
        id=1,
        key='DisableCode',
        content='1折优惠',
        enable=0,
        used=0,
        create_at=now_time
    )
]

...
def add_role_power():
    admin_powers = Power.query.filter(Power.id.in_([1, 3, 4, 9, 12, 13, 17, 18, 44, 48, 60])).all()
    ...

@admin_cli.command("init")
def init_db():
    ...
    db.session.add_all(giftdata)
    ...

这样就可以将数据库内容写入了。

备注

powerdata 中添加了对兑换码的操作权限，可以先去“权限管理”中添加，而后再从数据中抄取。或者忽略初始化时对 powerdata 的添加，在初始化之后，手动在权限管理中添加。

使用 Schema 序列化

与前端交互大多用的是 JSON 格式的数据，这就涉及到将数据库查询的结果对象（Query）转化为 JSON 这一步骤。我们可以使用 flask_marshmallow 中的 SQLAlchemyAutoSchema 将数据库查询对象转换为 JSON 格式。

创建文件 applications/schemas/admin_gift.py ，并继承 SQLAlchemyAutoSchema ，更改其中的目标模型为我们创建的 Gift 模型。

from flask_marshmallow.sqla import SQLAlchemyAutoSchema
from applications.models import Gift


class GiftSchema(SQLAlchemyAutoSchema):
    class Meta:
        model = Gift  # table = models.Album.__table__
        include_fk = True  # 序列化阶段是否也一并返回主键

备注

更多序列化参数可以参考 Schema 序列化章节。

随后，在 applications/schemas/__init__.py 引用，

...
from .admin_gift import GiftSchema

这一步不是必须的，但是应通过这一步的引用，可以在蓝图页面中，方便的使用 from applications.schemas import * 的方式导入。

编写后端视图函数

注册蓝图

接着我们需要设计后端的数据增删改查部分的视图函数，创建文件 applications/view/system/gift.py ，并写上基本的蓝图初始化逻辑：

from flask import Blueprint

bp = Blueprint('gift', __name__, url_prefix='/gift')

根据流程图，我们需要在 applications/view/system/__init__.py 中，注册 gift.py 的蓝图：

...
from applications.view.system.gift import bp as gift_bp
...

def register_system_bps(app: Flask):
    ...
    system_bp.register_blueprint(gift_bp)
    ...

编写数据获取路由

重要

因为目标是让前端 layui 的动态表格获取数据，而根据 layui 的文档，表格将会提供 limit 和 page 两个查询参数来进行分页查询，所以要对 limit 和 page 进行处理。

现在开始编写数据获取路由，路由是以 JSON 格式响应数据库中 admin_gift 的数据，下面提供一种实现方法：

from flask import Blueprint

from applications.models import Gift
from applications.schemas import GiftSchema
from applications.extensions import db

from applications.common.utils.http import table_api
from applications.common.utils.rights import authorize

bp = Blueprint('gift', __name__, url_prefix='/gift')


@bp.get('/data')
@authorize("system:gift:main")
def data():

    query = db.session.query(Gift).layui_paginate()

    return table_api(
        data=GiftSchema(many=True).dump(query),
        count=query.total,
        limit=query.per_page
    )

可以发现，在没有搜索的情况下，正确处理前端的分页查询，实际上只有简单 5 行代码就可以完成（自动处理了 limit 和 page 参数），另外，也可以采用已经封装好的 layui_paginate_json 方法：

...
@bp.get('/data')
@authorize("system:gift:main")
def data():

    data, total, page, limit = db.session.query(Gift).layui_paginate_json(GiftSchema)

    return table_api(
        data=data,
        count=total,
        limit=limit
    )

layui_paginate_json 函数完成了分页、解析与转化，适用于一些比较简单数据转化场景。

警告

对于任何形式的后台管理员路由，切记不要忘记添加 authorize 装饰函数对请求效验权限！！！！！！

备注

对于 layui_paginate 方法定义，可以查看与 layui 的数据格式同步章节。

访问路由 /system/gift/data 可以获得如下数据：

{
  "code": 0,
  "count": 2,
  "data": [
    {
      "content": "8折优惠",
      "create_at": "2025-01-28T19:10:48.607165",
      "enable": 1,
      "id": 0,
      "key": "myTestCode",
      "used": 0
    },
    {
      "content": "1折优惠",
      "create_at": "2025-01-28T19:10:48.607165",
      "enable": 0,
      "id": 1,
      "key": "DisableCode",
      "used": 0
    }
  ],
  "limit": 10,
  "msg": ""
}

随后，我们加入查询：

...
@bp.get('/data')
@authorize("system:gift:main")
def data():
    key = request.args.get('key', type=str)

    mf = ModelFilter()
    if key:
        mf.vague('key', key)  # 模糊查询

    data, total, page, limit = db.session.query(Gift).filter(mf.get_filter(Gift)).layui_paginate_json(GiftSchema)

    return table_api(
        data=data,
        count=total,
        limit=limit
    )

编写启用与禁用视图函数

启用与禁用的基本思路是通过 ID 筛选到合适的记录行并设置其 enable 为 1 或者 0。在设计数据库时，我们有意将表示启用禁用字段设置为 enable 以此可以使用项目已经封装好的函数。

from applications.common.curd import enable_status, disable_status

@bp.put('/enable')
@authorize("system:gift:edit")
def enable_api():
    data = request.get_json(force=True)

    if enable_status(Gift, data.get('id')):
        return success_api(msg="启用成功")

    return success_api(msg="启用失败")


@bp.put('/disable')
@authorize("system:gift:edit")
def disable_api():
    req_json = request.get_json(force=True)

    if disable_status(Gift, req_json.get('id')):
        return success_api(msg="禁用成功")

    return success_api(msg="禁用失败")

备注

对于上述的 enable_status disable_status 函数，可以参考文档 curd -- 简单增删改查模块章节。

数据的修改经历如下步骤：获取目标兑换码 ID、获取对应修改的新数据、应用修改，而数据的添加仅没有“获取目标兑换码 ID”这一步骤。

我们先来撰写添加这一部分的视图函数，

编写删除视图函数

删除的视图函数，实则和启用禁用是一样的，这里直接给出代码：

@bp.delete('/remove/<int:_id>')
@authorize("system:gift:remove")
def remove_api(_id):

    if delete_one_by_id(Gift, _id):
        return success_api(msg="删除成功")

    return success_api(msg="删除失败")

你会注意到，由于 curd 模块的封装，使编写路由变的简洁。

编写增加视图函数

添加视图函数经历下面几个步骤：获取参数、效验参数、写入数据库。

@bp.post('/save')
@authorize("system:gift:add", log=True)
def save():
    req_json = request.get_json(force=True)

    data = {
        'key': req_json.get('key'),
        'content': req_json.get('content'),
        'enable': req_json.get('enable'),
        'used': 0
    }

    # 效验参数
    if not all(list(data.keys())):
        return fail_api(msg="参数不全")

    if not data['enable'].isdigit():
        return fail_api(msg="参数 enable 错误")

    try:
        db.session.add(Gift(**data))
        db.session.commit()
        return success_api(msg="添加成功")
    except Exception as e:
        return fail_api(msg="添加失败")

重要

效验参数是必不可少的，要尽可能一切不相信用户的输入。

编写修改视图函数

修改视图函数的编写就照葫芦画瓢即可，代码如下：

@bp.post('/update')
@authorize("system:gift:edit", log=True)
def update():
    req_json = request.get_json(force=True)

    _id = req_json.get('id')

    data = {
        'key': req_json.get('key'),
        'content': req_json.get('content'),
        'enable': req_json.get('enable'),
        'used': 0
    }

    # 效验参数
    if not all(list(data.keys())):
        return fail_api(msg="参数不全")

    if not data['enable'].isdigit():
        return fail_api(msg="参数 enable 错误")

    try:
        db.session.query(Gift).filter(Gift.id == _id).update(data)
        db.session.commit()
        return success_api(msg="编辑成功")
    except Exception as e:
        return fail_api(msg="编辑失败")

备注

插件方式接入项目，请查看以插件的方式接入项目章节。