云软普创 API框架 简要说明

一、快速开始

 下载项目文件，项目文件如下 

step1  在src/config.json 中配置好数据库（mysql），以及redis的信息。这两项必须配置。

step2 在命令行启动运行devInit.bat 脚本

step3  运行debug.bat 脚本

如下图所示

 

typescript 自动编译开启，以vscode为例，终端 》运行任务》tsc:监视...     即可，如下图

开发过程中，请必须开启 typescript 自动编译，否则最新的代码将无法自动更新

二、目录结构以及说明

如下所示。

1.1  概要

output文件夹为代码输出文件夹，开发过程中，无需理会。

src 文件夹为源码文件夹，开发时所有的源码都在该文件夹中。

defined 文件夹作为 typescript 的类型定义文件（如不清楚，请自行百度）。

devInit.bat 为开发环境初始化脚本，在正式运行项目前，请以管理员身份运行该脚本。

debug.bat 为启动项目的脚本。双击运行即可。

1.2  详情

 defined 目录：包含app.d.ts 和sys.d.ts  ，系统级的定义请写在sys.d.ts中，应用级的定义请写在app.d.ts中

 

 src 目录：包含如下图所示的文件夹。

     

 ①、common文件夹 ，包含了如下的文件

分别是：db.ts (数据模型配置文件),middleware.ts(中间件配置文件)，response.ts(无需理会，在开发中禁止改动)，router.ts(路由配置文件)，start.ts(系统初始化文件），utils.ts(公共函数文件)，validate.ts文件。下面详细介绍各个程序文件的用法

 

db.ts:

 代码如下图所示

第8号行以后代码基本很少变动， 无法就是一些配置信息。在第8行以前的代码，表示的是：本项目导入了两个数据模型（通俗讲两张表），在开发中即可操作这两个数据表的CRUD方法。over，so easy

 

 

middleware.ts：
 

中间件配置文件，这是一个标准的express的中间件，很简单，上代码

 

response.ts：

略

 

router.ts：

路由配置文件，将URL和对应的控制器文件绑定，很简单，上代码

 

start.ts：

系统初始化完成后，将执行该文件中的代码，且每次运行系统，只会执行一次，很多初始化的工作可以在这写。

熟悉express的同学就很清楚，上代码

 

utils.ts：

公共函数文件，开发过程中，如果有一些函数经常用到，可以统一将其放到该文件中，格式如下图所示。调用也很简答，直接通过全局对象 $common.xxx() 即可调用，注意：新增一个函数，需要到defined/sys.d.ts 类型定义文件中的$common 中新增。

 

validate.ts:

导入数据校验方法，详细介绍，见 3.1 数据校验。

 

 ②、controller 文件夹 ，这里存放本应用所有的控制器对象。

控制器的命名必须以“xx.Controller.ts” 形式，否则将会报错

控制器的写法如下图。

说明：

控制器文件中的函数，返回两个对象，router，和 middle（函数，middle函数的详细说明见如下） 。

controller目前支持两种请求方式，controller.post() 和controller.get()

post和get两个方法参数一致，第一个参数：路由路径、第二个参数：文字描述，这里可以填写该请求的名字，用于后台自动生成权限方法、第三个参数：回调函数，回调函数中的req是标准的express的req对象，res对象为express 的res对象的扩展，这里新增了 ok，display、error，stop 方法，详细说明如下：

/**

* 输出格式化json数据 数据结构为 {err_code:0,data:数据对象}

* @param obj 数据对象

*/

ok:(obj:any)=>{

},

 

/**

* 输出模板数据

* @param tplName 模板的摸名，不含html后缀

* @param data 数据对象

*/

display:(tplName:string,data:any)=>{

},

 

/**

* 向请求端输出错误信息

* @param obj 错误对象 输出的格式为 {err_code:0,data:obj}

*/

error:(obj:any)=>{

}

 

/**

* 向请求端输出 中断处理信息

* @param msg 错误对象 输出的格式为 {err_code:-1,data:msg}

*/

stop:(msg:any)=>{

}

 

注意：在控制器方法中，不做数据校验，控制器方法的的主要作用：收集异常，输入异常，读取http请求参数，将请求参数提交给逻辑器。本框架的欧 http的请求流程 ，参照 附录1。

控制器中的middle 函数 作为 本控制器的一个中间件，在本控制器的任何方法执行之前执行。

 

 

 

 ③、dataModel文件夹 ，存放本应用的数据模型，数据模型的说明详见 附录三 数据模型。

数据模型在此定义，在common/db.ts中被导入，详见上述 db.ts  文件的描述。

 

 

④、dataModel文件夹 ，存放本应用的数据模型，数据模型的说明详见 附录三 数据模型。

⑤、lib文件夹，存放框架核心库文件，一般不允许修改。

⑥、 logic 文件夹，存放逻辑器代码文件。逻辑器的文件以 xxx.Logic.ts 命名，例如user.Logic.ts

逻辑器的定义如下图所示

访问逻辑器的方法可以参照附录二的 ①$lgc方法。逻辑器的主要功能是：

第一 、对控制器的数据进行校验。

    校验的方法为通过 $dataChecker全局函数校验，详见附录四 数据逻辑校验

第二、将校验的干净数据提交给指定的Model方法使用。通过$model 全局方法调用，详见附件二 ④ $model("a.b",data)。模型调用。

 

⑦、model文件夹，存放所有的业务model。

 model的命名方法为 xxx.Model.ts 

model的写法如下图所示

model中操作 数据模型的方法 

this.model("模型名").操作方法【findOne，findAll，create,update,destroy,】，在sequelize的基础上新增一些选项，sequelize原生 参数详见 https://itbilu.com/nodejs/npm/V1PExztfb.html 中的  3. Model类的API

    findOne，findAll 两个方法的参数对象中，新增了$fields属性，表示查询中筛选哪些字段，例如$fields:['tln','pwd']。注意：所有的字段都是alias别名，如果数据模型中的字段没有定义alias别名属性，默认和 原字段名相同。

示例

 

findAll 返回值的数据格式为 {res，count} ，其中res 结果数组，count为本次查询的记录数

create，update 两个方法的第二个参数对象中（选项参数），新增了$ignoreFields属性，表示本次操作忽略哪些字段，例如

 

  

 

 

 

附录一、http请求过程概述。

    本框架基本express，因业务需求，做了如下改动。

通常的mvc架构的请求流程都是：====（请求）---》Controller 控制器 =====》业务模型 Model 

本框架的请求流程 ：====（请求）---》Controller 控制器 =====》逻辑验证 Logic ====》业务模型 Model 

很显然，本框架的请求流程中，多了Logic验证这一层。 

 

附录二、常用的全局对象及方法。

①、$lgc("user.login",req,req.body)。返回Promise对象。调用user.Logic.ts 中的 login 方法，req默认写，req.body 作为调用login的参数传入。该方法主要在控制器中使用。

②、$common。返回Promise对象。这是公共函数对象，挂在了common/utils.ts 下的所有方法。访问时，直接写 $common.xxx() 即可调用。注意：新增一个函数，需要到defined/sys.d.ts 类型定义文件中的$common 中新增。

 ③、$dataChecker。返回Promise对象。详见附录四 数据逻辑校验。

 ④、$model("a.b",data)。返回Promise对象。模型调用。参数以“a.b”形式，表示调用model/a.Model.ts 中的b方法,参数是data

⑤、$cache。返回Promise对象。缓存对象。挂载的方法以及用法见如下。

⑥、$config。读取配置信息，config.json 下的所有属性，都可以读取到，例如 $config.port,读取系统监听的端口。在项目的根目录，有两个配置文件，分别是config.json、app.config.json。config.json为系统配置，app.config.json为用户自定义的配置项，用户开发过程中，需要添加配置项，请在app.config.json中添加，读取的方法不变，如果两个配置文件的存在相同的配置项，则系统将以app.config.json中为主。

附录三、数据模型。

 数据模型的定义，首先，文件名以 xxx.data.ts 形式, 模型定义的结构如下。

详细说明 ：

本框架的数据模型以sequelize 库作为基础，sequelize文档详见 https://itbilu.com/nodejs/npm/VkYIaRPz-.html

模型属性

①、name 模型名

②、tableName 对应数据库的表名

③、body 模型的属性，对应表的字段。如下图

type，表示该字段的数据类型，支持的数据类型详见 https://itbilu.com/nodejs/npm/V1PExztfb.html 中的  1.2 Data types - 数据类型

allowNull ,该字段是否允许为空

primaryKey ，是否为主键

autoIncrement ，是否自增

alias ，字段的别名，在api的交互过程中，只要该属性定义了，那么系统在程序调用过程中，将使用该别名作为业务逻辑，以此来保护数据表中真实的字段名

 

④、relation 模型建的关系 ，与sequelize的模型间关系保持一致 详见文档  https://itbilu.com/nodejs/npm/41qaV3czb.html

⑤、indexs 索引 ，详见如下图

 

附录四、数据逻辑校验。

 校验函数 ，$dataChecker，返回Promise对象，所以，调用时，请 await 。例如

await $dataChecker([

{

data: "tln", // 字段名

require: true,// 是否为必传数值

msg:"tln校验失败",// 验证错误时的提示信息

dataType:"number",// 数据类型

exParams:"",//附加参数

handler:"Common@checkTelNum" // 调用验证的方法

},], data);

 

 

参数：

参数一 ，校验对象数组。 校验对象的完整结构如下

解释：

 data，校验目标数据属性的键，比如待校验的数据为 {tln:"123"}, 则如果需要校验tln字段，在校验对象中 将data属性的值设置为‘tln’即可

require， 表示待校验的字段是否为必传值，true表示必传，待校验的数据中，指定的属性为空，将会校验不通过

msg， 验证错误时的提示信息

dataType， 待校验字段的数据类型约束，可选的值为 

  isArray,数组

  isNumber,数值

  isObject,对象

  isBoolean,布尔值

   isString,字符串

  isUndefined,undefined

  isNull,null值

  isFunction,函数

  isRegExp,正则表达式

  isDate，时间类型

 

handler， 调用自定义验证方法，调用的方式为“a@b”,表示调用a验证模块中的b验证方法。 验证模块存放在 validate文件夹中，验证模块的命名为xxx.validate.ts。验证模块的写法如下图所示

例如 Common.validate.ts，是在调用之前，请先导入该验证模块，导入的方法为：在common/validate.ts 文件中导入，如下下图所示

导入验证模块后，接口调用，如要调用如下Common模块中的checkTelNum方式，则可以写“Common/checkTelNum”，对应待校验的数据将作为第一个参数自动传进去，校验方法的写法如下图所示，返回值的形式为数组[true/false,'提示信息']。

exParams，将作为调用自定义校验函数的第二个参数，所以，只有填了handler自定义校验方法后，本属性才生效 

 

参数二、待校验的数据。一般是接口上传的数据。