JBDAP-Node-Mysql 文档

一、简介

JBDAP-Node-Mysql 是 JBDAP 在 nodejs 环境下针对 Mysql/MariaDB 数据库的官方实现，使用它可以快速开发一个基于 Mysql/MariaDB 的数据库应用（可以是 Native 或者 B/S 或者 C/S 架构），操作数据的后端代码量可以减少 80% 以上。

如果您的项目采用了其它数据库，我们也有相应的实现可供使用：

• Sqlite
  • Github 仓库: JBDAP-Node-Sqlite
  • npm 包: jbdap-sqlite

也欢迎您编写更多其它数据库的 JBDAP 实现贡献给社区。

二、基本用法

注：支持 nodejs 8 及更高版本

1、安装

npm i jbdap-mysql --save

// 或者

yarn add jbdap-mysql

注意，因为包内自带了 mysql2 引擎，所以无需单独安装

2、示例代码

我们假定在本地 Mysql 服务器有一个叫做 jbdap_test 的数据库，里面有个 [User] 表已经填充了一些数据

// 引用
const JBDAP = require('jbdap-mysql')

// 创建连接
const conn = JBDAP.getConn({
    host: 'localhost',
    user: 'root',
    pass: '***********',
    dbName: 'jbdap_test'
})

// 参数配置
let config = {
    language: 'zh-cn',  // 以简体中文作为交流语言
    printSql: true,     // 是否打印 sql 语句（方便调试，生产环境可关闭）
}

// JBDAP指令描述（取出全部用户列表）
let json = {
    commands: [
        {
            name: 'allUsers',
            type: 'list',
            target: 'User',
        }
    ]
}

// 执行查询
JBDAP.manipulate(conn,json,config)
    .then((res)=>{
        console.log(JSON.stringify(res,null,4))
    })
    .catch((err)=>{
        console.log(err)
    })

// 打印出的返回结果如下
{
    "code": 200,
    "message": "ok",
    "data": {
        "allUsers": [
            {
                "id": 1,
                "username": "user1",
                "password": "password1",
                "avatar": null,
                "email": null,
                "gender": "FEMALE",
                "createdAt": "2020-07-08 14:42:44",
                "updatedAt": "2020-07-08 14:42:44"
            },
            ...
        ]
    }
}

很简单吧，我们只需要改变 json 的内容，就可以使用上述代码进行 JBDAP 规范下的任何数据库查询或者操作。

三、更多能力

由于 JBDAP-Node-Mysql 是对 JBDAP 协议的实现，因此它的能力其实也就是 JBDAP 的能力，在查看实例代码之前，我们先看一下 JBDAP 的能力全景图：

• JBDAP 指令
  • 单条指令
  • 多条指令
• 创建数据
  • 单条或多条插入
  • 大量数据自动分批插入
• 查询数据
  • 基本查询类型
    • entity - 查询单条记录
    • list - 查询多条记录
    • distinct - 对指定字段去重查询
  • fields - 查询字段控制
  • query - 查询条件约束
    • where 条件 - 支持单表任意复杂查询
    • order - 排序
    • size/page - 分页支持
  • values - 统计、汇总、二次加工
  • cascaded 级联查询
• 操作已有数据
  • query - 操作条件约束
  • 操作类型
    • delete - 删除
    • update - 更新
    • increase - 原子自增
    • decrease - 原子自减
• 逻辑能力
  • expression - 通过表达式实现特定值的输入
  • onlyIf - 前置条件约束
  • after - 后续指令操作
  • reference - 指令间的结果集引用
    • 引用值参与查询条件
    • 引用值作为数据源
  • visibility - 指令结果可见性
  • transaction - 事务支持
• 开发辅助
  • 自动填充时间戳
  • 日志输出 - 前端可以查看执行过程
  • 错误跟踪 - 前端可以查看错误跟踪
• 高级能力
  • decorator - 数据预处理
  • 服务端函数 - 个性化逻辑处理
  • 缓存支持 - 有助于提升查询性能
  • 安全性 - 应用程序的命脉
    • 身份校验
    • 权限控制
    • 敏感数据屏蔽

以上是 JBDAP 规范赋予的能力，jbdap-Mysql 还额外提供了基本的数据库结构操作能力

• createTable - 根据数据 model 描述 json 自动创建数据表
• dropTable - 根据表名删除数据表

具体用法你会在实例代码手册中看到。

四、实例代码手册

请参见这里（建议新窗口打开）

五、需要特别注意的地方

1、创建数据库时 Charset 要选择 utf8mb4，而非 utf8

2、字段类型问题

• 使用 jbdap-mysql 内置的 helper（背后是 knex） 在 Mysql 中创建数据表，若选择 increments/bigIncrements 类型的主键，它会创建对应的 unsigned integer/bigInteger，使用外键时要注意与之匹配，否则会失败
• Mysql 的 datetime 字段存在时区转换问题导致数据表直观可读性降低，为了杜绝这个麻烦，jbdap-mysql 在存储 datetime 字段时都会自动将 js 的 Date 数据类型统一转成当前时区的 'YYYY-MM-DD HH:mm:ss' 格式字符串。与此同时，客户端输入 Date 类型值参与 where 条件查询的时候，也会自动进行同样的转换。当然，这一切对于开发者来讲是无感的。

3、外键问题

• Mysql 对 foreignKey 的使用限制非常严格，比如
  • 创建表时需要严格控制顺序，先创建右表才能再创建左表
  • 删除表格时则反过来，先删除左表，然后才能删除右表
  • 而删除右表数据时，必须先把左表中的关联数据全删掉才行
• 如果实在不想遇到这个麻烦，建议不要给数据表设置 foreignKey 了，通过程序逻辑来控制跨表约束吧

4、统计汇总查询返回值问题

• Mysql 在进行统计汇总类查询时，count 查询返回的值是 integer，其余 sum/avg/min/max 等计算可能以字符串格式来表示数字，考虑到 js 的数字精度问题，这是正确的方式，不过前端使用时要注意格式的转换

以上是使用 Mysql 数据时需要了解的主要内容，总的来说，Mysql 的约束严谨程度比 Sqlite 要强的多，从 Sqlite 转来的开发者需要特别注意。

六、完整 API 说明

说实话，如果你能看完前面的实例代码手册，那么已经可以满足正常开发需要了。以下 API 可以帮助你更好的理解 JBDAP 实现的逻辑结构，对于想要开发自己 JBDAP 引擎的朋友来说会比较有用。先了解大体结构之后再去看源码效率会更高一些。

let JBDAP = require('jbdap-mysql')

• version - String - 当前版本
• getConn - Function - 生成一个 Mysql 数据库连接
  • params - 参数
    • dbFile - String - 数据库文件的完整路径，建议通过 path.join() 方式生成
  • return - 返回一个 knex 连接实例
• knex - Object - 对于 knex 包的引用，方便用户自己创建其它数据库连接
• manipulate - Function - JBDAP 的核心方法，通过它来执行 JBDAP json 描述中的指令
  • params - 参数
    • conn - Object - knex 数据库连接实例，可以通过 getConn 函数获得
    • json - Object - 将要被执行的 JBDAP 指令描述内容
    • config - Object - 配套参数
      • printSql? - Boolean - 是否在控制台打印出 sql 语句，默认为 true
      • autoTimestamp? - Boolean - 是否自动填充 'createdAt' 和 'updatedAt' 字段，默认为 true
      • language? - String - 系统交互使用的语言（目前只支持简体中文和英语），默认为 'zh-cn'
      • decorator? - Function - 数据预处理器
      • recognizer? - async Function - 通过 json 中的 Security 信息完成用户身份识别
      • doorman? - async Function - 通过用户身份控制其对数据的访问权限
      • scanner? - async Function - 对即将返回前端的数据进行扫描，防止敏感数据泄露（比如 password/token 等字段）
      • cacher? - async Function - 缓存操作模块，提升系统处理能力
      • dispatcher? - async Function - 服务端函数调度器，如果使用服务端函数功能就必须配置它
  • return - Object - 返回执行结果，成员如下：
    • code - Integer - 状态码
    • message - String - 执行结果或者错误提示信息（如果失败的话）
    • data - Object - 每个 property 对应一条指令的名字
    • logs? - Array - 执行过程日志
    • trace? - String - 错误跟踪信息
• helper - Object - Mysql 数据库快捷操作工具
  • createTable - async Function - 根据 schema 创建数据表
    • params - 参数
      • conn - knex 连接实例
      • schema - Object - 数据表结构描述 json 内容，具体结构参见下文
      • lang - String - 默认交互提示信息语言
  • dropTable - async Function - 删除数据表
    • params - 参数
      • conn - knex 连接实例
      • tableName - String - 数据表名
      • lang - String - 默认交互提示信息语言

以上就是全部的 API 了。

Enjoy It :-)