零（Zero）框架上手说明--参考

Zero框架上手说明（供大家参考）

一、Zero框架简介

Zero框架是前期开发“稽查联合惩戒名单处理”需求的过程中，为方便开发、便于后续复用，针对其中需要的一些经常会用到的部分，抽象固化编写了一些公共函数及可供调用的模版，这就是Zero框架的来源。
　　Zero框架主要解决了两个问题：一是帮助快速生成数据查询应用。对于简单的数据查询，借助Zero框架，三行语句可以生成一个数据查询结果页面，可降低数据应用开发难度，让大家可以把注意力更多放到业务逻辑、数据挖掘提炼上，能更方便的将数据转换成生产力。二是实现了Excel文件格式数据表格数据的方便采集。目前Excel表格形式存放数据在我们系统内还用得很多，Zero框架提供了文件上传功能，并提供了读入函数可以将上传的Excel文件内的表格数据导入到Oracle数据库中，使得数据平台与我们目前手上现有的数据的衔接变得更方便。为此达到上述两目的，Zero框架选择了处理Excel文件比较方便的Python语言，并引入了Bottle包，用于支撑网页应用的骨干。
　　取名为Zero的意思是从零开始，它提供了一个开放框架，其中的功能函数、页面模板、组件模板、甚至框架都可以简单被修改、新增、替换。目前它实现了一些基础功能，虽不完美，但已可以使用；期待在未来使用过程中，慢慢积累，逐步完善，给更多的人带来便利，在数据应用生态体系中发挥作用。

二、运行环境安装配置

（一）安装Python运行环境

1、安装Python3（Zero开发时使用的版本是Python3.8.5）。
2、安装需要的Python附加包。
备注：
1）按装Python附加包的命令：
pip install XXXXXXX.whl
2）需要附加包（Zero开发时使用的附加包及版本）
Package Version

---

bottle 0.12.23
cx-Oracle 8.3.0
numpy 1.23.5
pip 22.3
python-dateutil 2.8.2
six 1.16.0
wheel 0.37.1
xlrd 2.0.1
xlwt 1.3.0

（二）运行Zero框架示例

1、将Zero框架的示例压缩文件解压缩；
2、修改example.py文件中的“第零部分 （用户）初始化参数”，设置正确的“Oracle数据库连接串”、“当前所在路径”；
3、运行example.py启动示例应用。在操作系统命令行下进入对应目录执行：
python example.py
4、打开浏览器，输入地址“http://127.0.0.1/”，验证示例应用功能（默认用户：xy 默认口令：8888）。

图一 示例应用界面

三、示例应用example.py介绍

示例应用example.py程序分为六个部分，如下：

第零部分 （用户）初始化参数

第一部分 公共通用部分

第二部分 公共功能部分

第三部分 基础公共页面

第四部分 用户页面

第五部分 功能示例

第六部分 （公共）应用主体

其中，第零部分，用户配置参数，要求根据实际情况进行修改。
　　第一部分，包含了系统配置参数、用户身份认证、用户权限管理、来访IP地址验证等功能的实现。
　　第二部分，包含了获取oracle数据库数据函数、读Excel表格数据到oracle数据库表函数的实现。
　　第三部分，包含了静态文件提供处理页面、退出登录执行页面、更改用户口令执行页面。
　　第四部分、第五部分是和具体应用有关的部分，要根据实际需求进行开发，是开发者需要投入精力实现具体需求的地方。其中第四部分，包含了网站首页、用户信息（含用户密码修改）页面；第五部分，是具体功能页面，演示了页面模版、组件模版的使用，实现了查询显示当前oracle数据库用户名下的表，并可以跳转查看选中表的字段等信息的功能。
　　第六部分，应用主体（main过程），实现了读取配置文件、启动网站监听服务。配置文件主要是提供数据存储能力，配合第一部分中的函数实现用户身份认证、用户权限管理、来访IP地址验证等功能。当配置文件不存在时，会生成初始化配置文件，初始化配置文件中提供了默认管理员用户xy（默认口令：8888）。示例提供了几种启动网站监听服务的模式，可通过输入参数，可以控制允许访问的范围，开启调试模式，方便应用调试开发。

四、Zero框架快速上手说明

（一）快速应用页面生成

应用Zero框架最快的方式是直接基于example.py示例直接进行修改。当example.py示例可以正常运行的情况下，我们只需要对其中第四、五部分按实际应用需要进行修改替换。
1、“hello world!”页面
　　在第四部分的标题下，增加如下代码，新生成一个显示“hello world!”的页面，通过地址“http://127.0.0.1/new”可以进行访问。

图二 例1 hello world页面
　　上述代码定义了一个名为helloworldPage的页面处理函数，函数前面以“@”开始的装饰器指明了该页面在主机上的访问路径，函数的返回值是访问该页面时用户获得的返回内容。一般页面返回信息是html语法的格式化文本，此处作为演示直接返回文本信息。

2、利用组件模板快速生成数据查询结果页面
　　利用模板可以方便html页面的生成。我们可以修改函数体，借助iOracleGet函数（获取oracle数据库数据函数）和DataBox数据展示组件模板很简单的显示数据查询结果。

图三 例2 组件模板DataBox使用
3、利用页面模板给数据查询结果套用统一页面风格
　　可以利用页面模板给依据组件模板生成的内容加上统一风格，美化显示效果。如下，通过调用app_example页面模板，美化数据显示，增加菜单、标题。

图四 例3 页面模板app_example使用
　　模板可以通过view装饰器或者template函数进行调用，两者效果等价，也可以联合使用。在app_example模板中预留了content变量，借此可以传入页面的主要内容。模板统一存放于\views目录下，以tpl或者html作为文件扩展名。

图五 例3 页面模板app_example使用效果
4、通过装饰器提供的附加功能
　　Zero框架还提供了几种实用的装饰器，加载在页面处理函数上，提供了用户身份认证、用户权限管理、来访IP地址验证等功能。例如下面代码：

图六 装饰器应用示例代码
　　其中，auth_basic装饰器提供用户身份认证，传入参数是用户身份甄别函数；check_remote_addr装饰器提供来访IP地址验证，默认的用户对应允许的IP地址在配置文件中进行配置；check_purview装饰器提供了用户权限验证功能，可以验证用户是否有访问该页面的权限，用户拥有的权限默认在配置文件中进行配置。上述相关装饰器验证的实现代码在example.py文件的第一部分，可根据需要进行修改。
5、应用程序页面组织与开发过程
　　网页应用程序是由一组有一定层次结构的网页组成的。创建新的应用时，首先要对页面组织要有一个规划；接着依据规划，对example.py的第四、第五部分进行重写，利用空函数占位，用装饰器明确页面与处理函数的对应关系，先行实现页面组织；然后定制本应用的页面模板（可基于示例提供的模板基础上进行修改），依据页面组织情况，修改页面模板中的菜单项，指向特定的页面；最后根据应用需求，逐一实现应用页面，最终完成应用编写。
　　目前示例程序设计成需要登录才能访问，如果设计允许匿名访问的页面，务必需要将example.py第三部分处理静态文件的staticsPage函数前的auth_basic装饰器声明删除。

（二）Excel文件格式数据表格数据的采集

Excel文件格式数据表格数据的采集有可能涉及两个操作，一是数据文件上传；二是数据中文件读入。
1、Zero框架中的文件上传实现
　　需要实现两个页面，一个是文件选择上传页面，用于让用户选择需要上传的文件，并发起文件上传请求，另一个是上传文件处理页面，处理用户发起的文件上传请求，将文件有序的保存到服务器对应目录中。
1）文件选择上传页面
　　Zero框架编写了UploadFile组件模板，方便文件选择上传页面的生成。具体示例代码如下：

图七 文件选择上传示例
　　UploadFile组件详见附件1中的介绍，其中keyName、keyValue参数不是必须的，可以不提供。

图八 文件选择上传效果
2）上传文件处理页面
　　上传文件处理页面的监听地址在文件选择上传页面调用uploadFile模板时通过传递的url参数确定。原则每个上传文件处理页面负责处理一类文件，需要独立编写，下面给出了一个示例，实现了将上传的文件以“文件数据类型_ 关键字_yyyymmdd-hhmmss_原始文件名”做为文件名保存到程序所在路径下的upload目录中。

图九 上传文件处理示例

实际使用中，可以在上述例子基础上增加文件名称、文件类型等校验，还可以在文件保存完成后，触发相应的后续数据处理操作。
2、Excel文件格式数据表格数据读入实现
　　Zero框架编写了iExcelToOracle函数，实现将Excel文件中的表格数据读入oracle数据库表。约定要导入的表格数据存放于Excel文件的第一个sheet页中，iExcelToOracle函数会自动适配sheet页情况，忽略正式数据表上方和左边的空白单元格。iExcelToOracle函数仅有两个必须输入的参数，excelFile（带路径的Excel文件名）、TableName（要存入数据的Oracle表名），格式如下：

iExcelToOracle( excelFile=’e:\\Excel文件名.xls’, TableName='ORACLE_TABLENAME')

为方便使用，iExcelToOracle还提供了四个可选参数，方便适配一些特殊情况。Columns，存入表的字段名，以存入数据次序排列，当Excel表格字段顺序和Oracle数据表的相应字段顺讯不一致或者Excel表格字段仅是Orcel表中的部分字段时，可启用该参数。keyValue，存入数据的关键字，例如数据所属年月，该值默认存入columns的第一个字段中，借助此字段为本次导入的数据设置了一个关键字，未来可以对一批次导入数据进行统一处理。deleteFirst，数据删除标记，默认为True，表示数据先删除再插入。dataStyle，表示Excel中的表格数据的格式，目前提供了三种抽象格式：hasColumnNameLine 【有列名称行】、hasTitleAndColumnNameLine 【有标题和列名称行】、beginWithNumber 【有效数据行以数字（序号）开头】，借此可以进一步在尽量不改Excel文件的情况下识别出真正的需要导入的数据，去除有效数据之上和之下的无效内容。

（三）其他说明

1、中国式报表的复杂表头实现与模板创建
　　Zero框架可以很方便的扩充、修改，网页前台可以使用的各种技术都可以使用，不会因平台而限制开发者的能力。中国式报表的复杂报表头是查询应用中经常会遇到的情况，但由于复杂表头很难像一维表头一样用简单的数据直接描述，所以Zero并未直接提供此类模板，但可以通过创建专用模板的方式来提供对复杂表头数据报表的支持。
　　Zero框架中所用的模板本身其实就是一段html语法的文本块，其间可以通过特殊标记嵌入执行Python语句、输出传入模板的变量。首先可以复制一份组件模板并给新生成的模板取一个新名字，然后用网页编辑工具例如Dreamweaver等编辑一张空表，将其表头按需要编辑好，最后将编辑好的复杂表头复制到新生成的模板中替换原先的报表表头部分，这样带复杂表头的模板就可以使用了。

五、后记

Zero框架在我手里打造出来，为了能让更多人能了解它进而可以体会到它带来的方便，特地花了时间整理了此文。希望Zero框架就像投入湖中的石子激起的涟漪，给大家带来新的气息，也欢迎大家多多交流，共享自己的经验成果，让工作变得轻松高效。

附件：

1. Zero框架(v0.03)模板说明

2. zero_example.txt（Zero框架-示例程序结构说明文档）

                                                                                  银河软件工作室
                                                                                  2023年2月23日