基本完成文档
This commit is contained in:
wojiaoyishang
@@ -1,7 +1,13 @@
|
||||
.. _后端页面编写:
|
||||
|
||||
后端页面编写
|
||||
======================
|
||||
|
||||
该章节将介绍如何在 Pear Admin Flask 中编写一个新后端页面，此章节将会以编写积分兑奖系统为例，编写一个兑换码管理的后台页面。
|
||||
该章节将介绍如何在 Pear Admin Flask 中编写一个新后端页面，此章节将会以编写兑换码管理页面为例，编写一个兑换码管理的后台页面。
|
||||
|
||||
.. note::
|
||||
|
||||
前端页面制作，请参考 :ref:`简单前端页面示例` 章节。
|
||||
|
||||
.. _项目初始化逻辑:
|
||||
|
||||
@@ -22,6 +28,468 @@
|
||||
由此可以看出，我们想要添加自己的后端页面，可以在 “注册项目的视图函数”（蓝框） 的地方添加，当然，同样页面可以作为插件的方式接入以提高项目的拓展性。
|
||||
下面将介绍如何在这两种方式下添加自己的后台页面。
|
||||
|
||||
设计数据库
|
||||
-----------------------
|
||||
|
||||
兑换码一定是保存在数据库中的，我们现在要求改程序至少有以下几个功能：
|
||||
|
||||
* 可以通过 flask admin init 或者等价的命令初始化数据库
|
||||
* 数据库存在统一管理的模型
|
||||
* 数据库的内容方便数据转化
|
||||
|
||||
数据的字段可以定为：
|
||||
|
||||
* id -- 唯一主键
|
||||
* key -- 兑换码
|
||||
* content -- 具体的内容
|
||||
* enable -- 是否启用
|
||||
* used -- 是否使用
|
||||
* create_at -- 创建时间
|
||||
|
||||
根据上述需求，我们可以设计出这样一个数据库 Model ：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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` 中导入这个模型。
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from .admin_gift import Gift
|
||||
|
||||
.. note::
|
||||
|
||||
由于 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` 中添加自己需要的数据，我们可以对其进行修改，添加如下的代码：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
...
|
||||
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)
|
||||
...
|
||||
|
||||
这样就可以将数据库内容写入了。
|
||||
|
||||
.. note::
|
||||
|
||||
powerdata 中添加了对兑换码的操作权限，可以先去“权限管理”中添加，而后再从数据中抄取。
|
||||
或者忽略初始化时对 powerdata 的添加，在初始化之后，手动在权限管理中添加。
|
||||
|
||||
使用 Schema 序列化
|
||||
---------------------------
|
||||
|
||||
与前端交互大多用的是 JSON 格式的数据，这就涉及到将数据库查询的结果对象（Query）转化为 JSON 这一步骤。
|
||||
我们可以使用 flask_marshmallow 中的 SQLAlchemyAutoSchema 将数据库查询对象转换为 JSON 格式。
|
||||
|
||||
创建文件 `applications/schemas/admin_gift.py` ，并继承 SQLAlchemyAutoSchema ，更改其中的目标模型为我们创建的 Gift 模型。
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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 # 序列化阶段是否也一并返回主键
|
||||
|
||||
.. note::
|
||||
|
||||
更多序列化参数可以参考 :ref:`Schema 序列化` 章节。
|
||||
|
||||
随后，在 `applications/schemas/__init__.py` 引用，
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
...
|
||||
from .admin_gift import GiftSchema
|
||||
|
||||
这一步不是必须的，但是应通过这一步的引用，可以在蓝图页面中，方便的使用 `from applications.schemas import *` 的方式导入。
|
||||
|
||||
编写后端视图函数
|
||||
-----------------------
|
||||
|
||||
注册蓝图
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
接着我们需要设计后端的数据增删改查部分的视图函数，创建文件 `applications/view/system/gift.py` ，并写上基本的蓝图初始化逻辑：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from flask import Blueprint
|
||||
|
||||
bp = Blueprint('gift', __name__, url_prefix='/gift')
|
||||
|
||||
根据流程图，我们需要在 `applications/view/system/__init__.py` 中，注册 `gift.py` 的蓝图：
|
||||
|
||||
.. code-block::
|
||||
|
||||
...
|
||||
from applications.view.system.gift import bp as gift_bp
|
||||
...
|
||||
|
||||
def register_system_bps(app: Flask):
|
||||
...
|
||||
system_bp.register_blueprint(gift_bp)
|
||||
...
|
||||
|
||||
|
||||
.. _编写数据获取路由:
|
||||
|
||||
编写数据获取路由
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. important::
|
||||
|
||||
因为目标是让前端 layui 的动态表格获取数据，而根据 layui 的文档，表格将会提供 limit 和 page 两个查询参数来进行分页查询，所以要对 limit 和 page 进行处理。
|
||||
|
||||
现在开始编写数据获取路由，路由是以 JSON 格式响应数据库中 `admin_gift` 的数据，下面提供一种实现方法：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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` 方法：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
...
|
||||
@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` 函数完成了分页、解析与转化，适用于一些比较简单数据转化场景。
|
||||
|
||||
.. warning::
|
||||
|
||||
对于任何形式的后台管理员路由，切记不要忘记添加 `authorize` 装饰函数对请求效验权限！！！！！！
|
||||
|
||||
.. note::
|
||||
|
||||
对于 layui_paginate 方法定义，可以查看 :ref:`与 layui 的数据格式同步` 章节。
|
||||
|
||||
访问路由 `/system/gift/data` 可以获得如下数据：
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"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": ""
|
||||
}
|
||||
|
||||
随后，我们加入查询：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
...
|
||||
@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` 以此可以使用项目已经封装好的函数。
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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="禁用失败")
|
||||
|
||||
.. note::
|
||||
|
||||
对于上述的 `enable_status` `disable_status` 函数，可以参考文档 :ref:`简单增删改查模块` 章节。
|
||||
|
||||
数据的修改经历如下步骤：获取目标兑换码 ID、获取对应修改的新数据、应用修改，而数据的添加仅没有“获取目标兑换码 ID”这一步骤。
|
||||
|
||||
我们先来撰写添加这一部分的视图函数，
|
||||
|
||||
编写删除视图函数
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
删除的视图函数，实则和启用禁用是一样的，这里直接给出代码：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@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` 模块的封装，使编写路由变的简洁。
|
||||
|
||||
.. _编写增加视图函数:
|
||||
|
||||
编写增加视图函数
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
添加视图函数经历下面几个步骤：获取参数、效验参数、写入数据库。
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@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="添加失败")
|
||||
|
||||
.. important::
|
||||
|
||||
效验参数是必不可少的，要尽可能一切不相信用户的输入。
|
||||
|
||||
.. _编写修改视图函数:
|
||||
|
||||
编写修改视图函数
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
修改视图函数的编写就照葫芦画瓢即可，代码如下：
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@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="编辑失败")
|
||||
|
||||
Reference in New Issue
Block a user