云南道普科技 服务端框架使用说明

一、快速开始

在开发前，请自行安装Nodejs环境，mysql，redis。

建议将npm的源地址设置为淘宝镜像：npm config set registry http://registry.npm.taobao.org/

 

编辑器推荐使用 vscode ，请自行下载

 

一个空项目，如下图 1.1 所示

、

图1.1 

.git 为仓库目录，请自行忽略

src 目录为源代码的仓库 

.gitignore 为git的忽略文件，请自行忽略

debug.bat  为启动项目的脚本文件，下面详细说明

devInit.bat 为项目的初始化脚本。

 

1.1 项目启动流程：

step1、双击运行devInit.bat ，并等待项目初始化结束 

 

step2、修改配置文件，在src/config.json中修改配置文件，db,redis,为必须配置的两个选项，项目的启动依赖mysql，以及redis。 如下图1.2所示

图 1.2 配置选项

 

其他配置选项，可以选择性的更改，例如 下图所示的配置，如图1.3所示

图1.3  监听ip 以及端口

 

step3、 启动，直接运行debug.bat 文件即可。看到如下图1.4，项目启动成功。

图 1.4 

 

二、http请求处理流程：

①、客户端发送http请求-----> ②、控制器接受请求，调用logic   -------> ③、执行logic的代码，调用model 层代码   -----> ④、执行model代码，操作数据模型。

 

说明：

 ①、略。

 ②、控制器接收到请求，将请求转交给logic ，一个controller方法（控制器的定义方法详见三、控制器的定义），可能调用多个logic。调用logic的方法为 $logic("逻辑文件名称.逻辑方法",调用的参数) （详见附录1.1） 。

③、执行logic代码，在控制器中掉了$logic方法来执行指定的逻辑层，在逻辑层中，通过$dataChecker方法检测数据合法性（详见附录1.2）,通过$model("model文件名称.方法",参数)来调用指定的模型 （详见附录1.3）。

④、model执行，对应的model的方法被调用， 在model中可以操作数据库，通过this.model("数据模型名").findOne/findAll/create/update/destory 进行对应的数据模型的操作，详见附录1.4。

 

流程说明：

在开发过程中，首先开启typescript的自动编译功能，如下图我2.0所示

图 2.0  

 

 

step1：写模型。

模型文件统一放在src/dataModel文件夹中，模型统一以.data.ts结尾。如下图2.1说所示

图 2.1 模型文件夹。

模型的定义如下图2.2 所示

图2.2 模型定义

 

本框架的模型是基于squelize框架，详细见 https://itbilu.com/nodejs/npm/VkYIaRPz-.html

注意，在定义模型字段时，除了主键外，其他字段，请加入alias（字段别名，在做业务时，均已）属性，如下图2.3所示

图 2.3 字段定义 

 

数据表之间的关系，可以在relation字段中定义，如下图2.4所示。定义方式可以参考

 

 

图 2.4 模型间关系

 

创建索引，参考sequelize 的创建方法，如图2.4所示

图 2.5 创建索引

 

 

》step2：写控制器。

控制器的目录在src/controller 下。定义的方法，请参考 《三、Controller的定义》

 

》step3：写logic。 待续...

 

》step4：写model。 待续...

 

三、Controller的定义

 控制器文件在src/controller中， 文件命名规范为 xxx.Controller.ts。

代码规范如下图3.1所示

图 3.1

在图1.3中Controller 是控制器的基础类，所有控制器均需要继承Controller。

3.1 _init方法

在控制类中，_init 是每次请求时，最先被执行的方法，如果未定义该方法，则无需理会，否则该方法必须返回一个bool值，为true则继续往下执行，否则，请求将在此被拦截。

   在该法中可以定义一些基础的验证，例如登录验证，该方法只有一个参数actionName，即本次请求的方法的名字，例如 请求 test方法，则actionName的值为test。

 

3.2 Router 注解

注解的使用方法为@Router(path),例如@Router("/api/admin")，表示该控制器的所有方法将会被路由到/api/admin/对应方法名

下，例如图3.1 中的get方法，将会被路由到 http://xxx/api/admin/get 地址中。

 

3.3 控制器方法注解(Get,Post,Delete,Put,All) 

 Get,Post,Delete,Put 方法分别代表 http的四种请求方式,All注解表示可以匹配任何类型的http请求。在方法注解中可以加入路由地址（可选参数），例如@Get("/a") 或者 @Get("a")，效果一样。

如果将图3.1中的test 方法的注解改成@Get("a")，如下图3.2所示，之前的http://xxx/api/admin/get将无法访问，访问的url为

http://xxx/api/admin/a。所以方法注解中，不填参数，则将会以方法名作为访问的url

图3.2

一个方法能被多个注解修饰，如下图3.3所示，可以通过 isGet,isPost,isPut,isDelete等属性来判定是哪种请求类型。

图 3.3

 

读取请求的参数，如果发送ajax的参数是通过url传值，则通过 this.req.query读取参数，如果是通过body传值，则需要通过this.req.body取值。

 

3.3 url后缀 

如果在config.json文件中定义了 的值，则在请求的url中，请自行添加后缀惊醒访问，例如 "urlPostfix":".html"，则访问 http://xxx/api/admin/a的url将改为http://xxx/api/admin/a.html

注意：如果在方法注解中已经添加了含有“.”的路由，例如图3.3的@Get("get.json")，那么"urlPostfix":".html"的配置将会对该方法失效（其他方法以此类推），访问该方法时，路由依旧为 http://xxx/api/admin/a.json。

 

3.4 输出数据。

本框架基于express框架，response输出对象挂载到控制器的this.res中，所以this.res 中含有express框架的response对象的所有方法。

在此基础上，本框架新增了几个方法，用户快速输出指定的数据对象

this.res.ok(数据) ====>输出 {err_code:0,data:数据}

this.res.error(数据) ====>输出 {err_code:-1,data:数据}

this.res.stop(数据) ====>输出 {err_code:1,data:数据}

 

3.5 注册控制器。

将控制器定义好后，只需要将其注册到src/common/map.ts中即可使用，如图3.4所示

图 3.4

 

 

 

附录

1.1  $logic。全局方法。$logic用于调用指定的logic方法。调用方法：$logic("逻辑文件名称.逻辑方法",调用的参数)。例如调用user.Logic.ts 中的get 方法，只需要 var result = await  $logic("user.get",{name:""})。所以在定义Logic文件的时候，请参照命名规则，"逻辑名.Logic.ts"

1.2 $dataChecker。顾名思义，主要做数据校验的，使用方法为 $dataCheck(规则对象数组,校验数据)。例如 

图1.2.1

说明：在上图中，对data数据进行了校验，校验的字段为 id，通过require属性标志，该字段不能为空。

完整的规则对象如下图所示

图1.2.2

dataType 属性 支持如下 几种数据：

isArray, //数组类型

isNumber,// 数值类型

isObject,// 对象类型

isBoolean,// bool类型

isString,// 字符串类型

isUndefined,// undefined类型

isNull,// null类型

isFunction,// 函数类型

isRegExp,// 正则类型

isDate// 日期类型

 

require 属性，表示该字段是否为必填。

msg 属性，表示 验证失败后的提示信息

handler 属性，表示使用高级验证方法。 高级验证方法指的是，如果验证数据类型时，存在复杂的逻辑，则需要单独写成验证函数，如上图所示的写法“Common.checkTelNum” （也可以写成“Common@checkTelNum”） 表示，本字段的验证调用了 src/validate/Common.validate.ts 中的checkTelNum方法进行验证，其中方法的定义如下图所示。

图1.2.3

checkTelNum 方法中， 有两个参数，第一参数，value，则是对应字段的值，也是上图1.2.2中的tln字段的值。第二个参数，exParam则是上图1.2.2的exParam属性的值，作为一个附加的参数，可按照业务需求进行添加。

验证方法的返回值是一个数组，格式如 [是否验证通过（boolean，必填项）,提示信息（string，选填项）]   如果“提示信息”存在，将会覆盖 图1.2.2 中的msg属性。

注意，定义好Common.validate.ts之后，需要注册才能调用，注册文件为 src/common/validate.ts ,如下图1.2.4所示

图 1.2.4