From ae81e8a9ffb0b3ce60b8314b7aef72a16360ad37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=AE=87=E5=A4=A9?= Date: Mon, 23 Aug 2021 19:25:20 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Readme.md | 61 ++--- Readme_CN.md | 68 ++++++ docs/3.x._CN.md | 630 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/3.x.md | 354 ++++++++++++++------------- lib/method.js | 19 +- package.json | 2 +- 6 files changed, 926 insertions(+), 208 deletions(-) create mode 100644 Readme_CN.md create mode 100644 docs/3.x._CN.md diff --git a/Readme.md b/Readme.md index e3b7e7d..90ca1fa 100644 --- a/Readme.md +++ b/Readme.md @@ -1,61 +1,62 @@ ![module info](https://nodei.co/npm/mysqli.png?downloads=true&downloadRank=true&stars=true) +[中文说明](./Readme_CN.md) + # mysqli -> 本模块基于 node-mysql 模块二次封装，将 SQL 语法转为类似 MongoDB 的 API。对常用的增删改查提供了简单的 API, 并且进行了 SQL 注入过滤, 对新手非常友好。 +> This module is based on the `node-mysql` module and converts the SQL syntax to the API similar to MongoDB. Some simple APIs is provided for commonly used additions, deletions, and changes, and xss injection, which is very friendly to novices. -## 使用 npm 安装 +## installation ```bash -# 3.x 版的安装 +# 3.x recommend npm i mysqli # or npm i mysqli@3.x -# 2.x 旧版的安装 +# 2.x old version npm i mysqli@2.x ``` -## 实例化 +## Quick Start + +> One or more configurations can be passed in for instantiation. When there is only one database, the default is the `master library`; when there is more than one database service, the first one is automatically used as the `master library`, and the other `slave libraries`. so, `pay attention to the order` when using. -> 实例化可以传入一个数组,或单个 object 配置。只有一个数据库时，默认是主库 ; 多于 1 个数据库服务时，自动以第 1 个为主库，其他的从库，故实例化时，`注意顺序`。 ```javascript let Mysqli = require('mysqli') -//传入json +// one config let conn = new Mysqli({ - host: '', // IP/域名 - post: 3306, //端口， 默认 3306 - user: '', //用户名 - passwd: '', //密码 - charset: '', // 数据库编码，默认 utf8 【可选】 - db: '' // 可指定数据库，也可以不指定 【可选】 + host: '', // IP/domain + post: 3306, //port, default 3306 + user: '', // username + passwd: '', // password + charset: '', // CHARSET of database, default to utf8 【optional】 + db: '' // the default database name 【optional】 }) -// 传入数组 +// two or more configs let conn = new Mysqli([ { - host: 'host1', // IP/域名 - post: 3306, //端口， 默认 3306 - user: '', //用户名 - passwd: '', //密码 - charset: '', // 数据库编码，默认 utf8 【可选】 - db: '' // 可指定数据库，也可以不指定 【可选】 + host: 'host1', // + ... }, { - host: 'host2', // IP/域名 - post: 3306, //端口， 默认 3306 - user: '', //用户名 - passwd: '', //密码 - charset: '', // 数据库编码，默认 utf8 【可选】 - db: '' // 可指定数据库，也可以不指定 【可选】 - } + host: 'host2', // + ... + }, + ... ]) ``` -## 文档 +## Document -* [2.x 版文档](docs/2.x.md) -* [3.x 版文档](docs/3.x.md) +* [v3.x](docs/3.x.md) + + +👎 Deprecated + + +* [v2.x](docs/2.x.md) diff --git a/Readme_CN.md b/Readme_CN.md new file mode 100644 index 0000000..1509a8d --- /dev/null +++ b/Readme_CN.md @@ -0,0 +1,68 @@ +![module info](https://nodei.co/npm/mysqli.png?downloads=true&downloadRank=true&stars=true) + +[English Readme](./Readme.md) + +# mysqli + +> 本模块基于 `node-mysql` 模块二次封装，将 SQL 语法转为类似 MongoDB 的 API。对常用的增删改查提供了简单的 API, 并且进行了 SQL 注入过滤, 对新手非常友好。 + +## 使用 npm 安装 + +```bash +# 3.x 版的安装 +npm i mysqli +# or +npm i mysqli@3.x + + +# 2.x 旧版的安装 +npm i mysqli@2.x +``` + +## 实例化 + +> 实例化可以传入一个或多个配置。只有一个数据库时，默认是主库 ; 多于 1 个数据库服务时，自动以第 1 个为主库，其他的从库，故实例化时，`注意顺序`。 + +```javascript +let Mysqli = require('mysqli') + +//传入json +let conn = new Mysqli({ + host: '', // IP/域名 + post: 3306, //端口， 默认 3306 + user: '', //用户名 + passwd: '', //密码 + charset: '', // 数据库编码，默认 utf8 【可选】 + db: '' // 可指定数据库，也可以不指定 【可选】 +}) + +// 传入数组 +let conn = new Mysqli([ + { + host: 'host1', // IP/域名 + post: 3306, //端口， 默认 3306 + user: '', //用户名 + passwd: '', //密码 + charset: '', // 数据库编码，默认 utf8 【可选】 + db: '' // 可指定数据库，也可以不指定 【可选】 + }, + { + host: 'host2', // IP/域名 + post: 3306, //端口， 默认 3306 + user: '', //用户名 + passwd: '', //密码 + charset: '', // 数据库编码，默认 utf8 【可选】 + db: '' // 可指定数据库，也可以不指定 【可选】 + } +]) +``` + +## 文档 + +* [3.x 版文档](docs/3.x_CN.md) + + +👎 Deprecated + + +* [2.x 版文档](docs/2.x.md) diff --git a/docs/3.x._CN.md b/docs/3.x._CN.md new file mode 100644 index 0000000..0573c05 --- /dev/null +++ b/docs/3.x._CN.md @@ -0,0 +1,630 @@ +## 实例化 + +> 实例化可以传入一个或多个 配置。只有 1 个数据库时，默认是主库; +> 多于 1 个数据库服务时,自动以第 1 个为主库,其他的从库，故实例化时`注意顺序`。 + +```javascript +let Mysqli = require('mysqli') + +//传入json +let conn = new Mysqli({ + host: '', // IP/域名 + post: 3306, //端口， 默认 3306 + user: '', //用户名 + passwd: '', //密码 + charset: '', // 数据库编码，默认 utf8mb4 【可选】 + db: '' // 可指定数据库，也可以不指定 【可选】 +}) + +// 传入数组 +let conn = new Mysqli([ + { + host: 'host1', // IP/域名 + ... + }, + ... +]) +``` + +## 实例 API + +### 静态方法 escape(val) + +> 可以对 sql 的各种类型的值进行安全转义。 + +### emit([slave], [db]) + +* slave `` [可选]是否"从库", 默认为 false, +* db `` [可选]要连接的数据库名, 默认为空 + +> 返回一个 db 实例, 这个方法是必须要的, 所有的 sql 操作,都要先实例一个 db 对象。 + +```javascript +let db = conn.emit(false, 'test') + +db.debug = true // 可开启debug模式 v3.1.0 开始支持 + +db + .tableList() + .then(list => { + console.log(list) + }) + .catch(err => { + console.log(err) + }) +``` + +## DB API + +> 是指直接对 db 进行操作的接口。如果没有特别说明,以下所有的方法, 返回的都是一个 Promise 对象。 + +### query(sql) + +* sql `` sql 语句, [必传] + +> 直接执行 sql 语句, 用于在内置的 API 不满足需求的情况下, 可以自己手写 sql 执行。 + +```javascript +db.query('select * from `student` limit 10').then(result => { + console.log(result) +}) + +// 前面没有指定数据库时, 也可以在这里写上 +db.query('select * from `test`.`student` limit 10').then(result => { + console.log(result) +}) +``` + +### drop(db) + +* db `` [可选] 要删除 db 名, 不传则删除当前连接的数据库 + +> 删除当前或指定数据库。 + +```javascript +db.drop() + +// 也可以删除指定的数据库 +db.drop('foo') +``` + +### dbList() + +> 返回当前账号权限下的所有的数据名(数组) + +```javascript +db.dbList().then(list => { + console.log(list) +}) +``` + +### tableList() + +> 返回当前连接的数据库下的所有的表名(数组) + +```javascript +db.tableList().then(list => { + console.log(list) +}) +``` + +### dbCreate(name, options) + +* name `` [必传], 数据库名字 +* options ``, [选传], 数据库的配置 + - charset `` 默认 utf8mb4 + + +> 创建新的数据库, 成功返回true。 + +```javascript +db.dbCreate('foo', { charset: 'utf8' }) // 默认是utf8mb4 +``` + + + +### tableCreate(name, columns ,options) + +* name `` [必传], 表名字 +* columns ``, [必传], 表字段的配置 + - name `` 字段名, 区分大小写, 建议全小写+下划线 + - type `` 字段类型, 不区分大小写 + - primary `` 是否主键(有且只能有 1 个主键) + - inc `` 是否自增(只允许主键设置,且为整型时才可设置) + - notnull `` 是否允许非空 + - index `` 是否设为索引 + - unique `` 是否为 唯一索引 + - default `` 设置默认值 + - update `` 是否自动更新(只有 datetime & timestamp 可以设) +* options ``, [选传], 表的配置 + - charset `` 默认 utf8mb4 + - engine `` 默认 InnoDB + + +> 创建新的数据表, 成功返回true。 + +```javascript +db.tableCreate('student', + [ + { + name: 'id', + type: 'int(5)', + primary: true, + inc: true + }, + { + name: 'name', + type: 'varchar(64)', + index: true + }, + { + name: 'age', + type: 'int(3)' + }, + { + name: 'sex', + type: 'tinyint(1)', + index: true + }, + ... + ]) +``` + + + + + +### table(name) + +* name `` [必传], 数据表名字 + +> 选择指定表。 返回一个表操作的 API 实例 + +```javascript +let table = db.table('student') // +``` + + + + + +## TABLE API + +> 是指直接对 table 进行操作的接口。 + +### leftJoin(tables) + +* tables `` 左联, 可以联多个表 + - table `` 表名 + - on `` 左联的条件 + + +```javascript +db.table('student') + .leftJoin([ + { + table: 'classroom', + on: 'student.classroom = classroom.id' + }, + ... + ]) +``` + + + +### rightJoin(tables) +> 参考 leftJoin() + + + + +### join(tables) +> 参考 leftJoin() + + + +### filter(options) +* options `` + +> 查询过滤, 这个方法是增删改查中使用率最高的。 也是 Mysqli 模块的核心方法之一。也是参数最复杂的方法, 一条查询里, 只能出现一次 filter, 多次调用, 会覆盖之前的条件. +> options 里有几个特殊的关键字 +> +> * $and (逻辑"且") +> * $or (逻辑"或") +> * $like 模糊查询 +> * $sql 以某个 sql 语句的结果作为查询条件 +> * $in 包含 +> * $between 在某某值和某某值之间 +> * $lt 小于 +> * $lte 小于等于 +> * $gt 大于 +> * $gte 大于等于 +> * $eq 等于 +> * $ne 不等于 + + +```javascript +db + .table('student') + .filter({ id: 1234 }) // 最基本的过滤查询, 即条件为 找"id=1234"的 + + .filter({ name: { $like: '李%' } }) // 模糊查询, 找所有"李姓的学生" + + // 现有的API不满足时, 可以自己写sql条件, 更复杂自己根据需求写即可 + .filter({ name: { $sql: 'IS NULL' } }) + .filter({ score: { $sql: 'score + 1' } }) + + .filter({ id: { $in: [11, 13, 29] } }) // 查询id在给定的这几个值的所有学生 + + .filter({ age: { $between: [15, 17] } }) // 查询年龄在 15~17岁的所有学生 + + .filter({ age: { $lt: 16 } }) // 查询年龄小于16岁的所有学生 + .filter({ age: { $lt: 16, $gt: 13 } }) // 查询年龄小于16岁且大于13岁的所有学生 + + // ***** 以下是多条件的示例 ********* + // 查询所有姓李的,年龄15岁以上, 且为男生(假设 男生是1,女生是2) + .filter({ name: { $like: '李%' }, age: { $gt: 15 }, sex: 1 }) + + // **** 从上面的示例可以看出,多个字段时, 自动为"AND" 查询 **** + // **** 所以下面该 $and 和 $or 出场了 **** + + // 查询所有 姓李的, 或 年龄在15岁以上的 + .filter({ + $or: [{ name: { $like: '李%' } }, { age: { $gt: 15 } }] + }) + + // 姓李的 或 年龄15岁以上且为男生的 + .filter({ + $or: [{ name: { $like: '李%' } }, { age: { $gt: 15 }, sex: 1 }] + }) + + // 姓李的或15岁以上的, 且必须是男生的 + .filter({ + $and: [ + { + $or: [{ name: { $like: '李%' } }, { age: { $gt: 15 } }] + }, + { sex: 1 } + ] + }) + +// filter基本上满足了你日常绝大部分的查询需求, 如果还有没满足的, 可以自己写sql语句. +``` + + + + + +### sort(keys) +* keys `` + +> 对结果集排序 + +```javascript +db + .table('student') + .sort({ age: -1 }) // -1为逆序, 1为正序 + + // 先排年龄(逆序), 再排学号(正序) + .sort({ age: -1, id: 1 }) +``` + + + + + + + + +### skip(num) + +* num `` + +> 跳过指定条数, 可用于分页。 + +```javascript +db.table('student').skip(10) // 跳过前9条, 即从第10条结果开始返回 +``` + + + + + + +### limit(num) + +* num `` + +> 限制返回的结果总数, 做分页时, 配合 skip 方法使用。 + +```javascript +db.table('student').limit(10) // 限制只返回10条记录 +``` + + + + + + + +### slice(start, end) + +* start `` +* end `` + +> 截取指定范围的结果集, 这是 skip & limit 结合体。 + +```javascript +db + .table('student') + .slice(11, 20) // 限制只返回10条记录 + + // 等价于 + .skip(11) + .limit(10) +``` + + + + + + +### withFields(fields) + +* fields `` [可选], 不传则返回所有的字段; v3.1.0, 支持传入多个参数, 效果等同于传入一个数组。 + +> 指定要返回的字段 + +```javascript +db.table('student').withFields(['id', 'name', 'sex']) // 只取 学号,姓名,性别3个字段返回 + +// 等价于 +db.table('student').withFields('id', 'name', 'sex') // v3.1.0后支持 +``` + + + + +### getAll([ids]) + +* ids `` [可选],返回指定 id 的结果集; 不传则返回所有结果集。(仅当没有调用过 filter 的情况下,本参数才有效) + +> 返回符合条件的所有记录, 这个方法是 查询必须要调用的方法之一, 上面 .filter, .sort 等方法, 只是组件条件, 并不会返回结果, 只有调用了 getAll/get 之后, 才会返回结果集。 +> `这里有一个地方要注意的, 传入的参数ids, 即意味着, 该数据表里, 必须有一个字段为"id", 否则会出错, 没有id的表, 查询时请使用 .filter过滤。` + +```javascript +db + .table('student') + .withFields(['id', 'name', 'sex']) + .getAll() + .then(list => { + console.log(list) + }) + +// 以下是查询学号为 11,13,28的学生 +db + .table('student') + .withFields(['id', 'name', 'sex']) + .getAll([11, 13, 28]) + .then(list => { + console.log(list) + }) + +// 等价于 +db + .table('student') + .withFields(['id', 'name', 'sex']) + .filter({ id: { $in: [11, 13, 28] } }) + .getAll() + .then(list => { + console.log(list) + }) + +// 在getAll()方法里传参数, 只是一种快捷的filter, +// 没有"id"字段的表, 请使用 .filter()方法来查询 +``` + + + + + +### get(id) + +* id `` [可选], 传入单个 ID。 + +> 该方法是对 getAll 的补充, 它最终是调用 getAll 来实现, 目的在于返回 单个结果集(不是数组)。 + +```javascript +// 以下是查询学号为 11的学生 +db + .table('student') + .withFields(['id', 'name', 'sex']) + .getAll(11) + .then(doc => { + console.log(doc) + }) + +// 等价于 +db + .table('student') + .withFields(['id', 'name', 'sex']) + .filter({ id: 11 }) + .get() + .then(doc => { + console.log(doc) + }) +``` + + + + + +### count() + +> 该方法同样是对 getAll 的补充, 它最终是调用 getAll 来实现, 返回结果集的总数。 + +```javascript +// 返回所有姓李的学生的总数 +db + .table('student') + .filter({name: {$like: '李%'}}) + .count() + .then(total => { + console.log(total) + }) +``` + + + + +### insert(doc) +* doc `` 要插入的记录 + +> 用于插入单条记录。如果有自增ID的话, 返回执行的结果。 + +```javascript +db + .table('student') + .insert({ + name: '张三', + age: 18, + sex: 1, + ... + }) + .then(res => { + console.log(res) + // { + // fieldCount: 0, + // affectedRows: 1, + // insertId: 4, + // serverStatus: 2, + // warningCount: 0, + // message: '', + // protocol41: true, + // changedRows: 0 + // } + }) +``` + + + +### update(doc) +* doc `` 要插入的记录 + +> 用于更新指定条件的记录, 返回执行的结果 + +```javascript +// 将张三的年龄改为 17岁 +db + .table('student') + .filter({name: '张三'}) + .update({ + age: 17 + }) + .then(successNum => { + console.log(successNum) + }) +``` + + + +### remove() +> 删除记录。返回执行的结果。 + +```javascript +// 将姓名为空的记录全删除了。 +db + .table('student') + .filter({name: {$sql: 'IS NULL'}}) + .remove() + .then(successNum => { + console.log(successNum) + }) +``` + + + +### drop() +> 删除当前数据表, 属于`危险操作`哦。 返回执行的结果。 + +```javascript +// 将学生表给删除了 +db + .table('student') + .drop() + .then(result => { + console.log(result) + }) +``` + + + +### renameTo(name) +> 重命名表。返回执行的结果。 + +```javascript +db + .table('student') + .renameTo('student_bac') + .then(result => { + console.log(result) + }) +``` + + +### indexList() +> 返回当前表的索引列表. + +```javascript +db + .table('student') + .indexList() + .then(list => { + console.log(list) + // { + // name, + // column, + // unique, + // cardinality, + // collation, + // } + }) +``` + + + +### indexDrop(name) +* name `` 索引名 + +> 删除当前表的指定索引. 返回执行的结果。 + +```javascript +// +db + .table('student') + .indexDrop('name_idx') + .then(result => { + console.log(result) + }) +``` + + + +### indexCreate(name, options) +* name `` 索引名 +* options `` 索引的配置 + - field `` 该索引绑定的字段 + - unique `` 是否是唯一索引 + + +> 给当前表创建索引. 返回执行的结果。 + +```javascript +// +db + .table('student') + .indexCreate('name_idx', {field: 'name'}) + .then(result => { + console.log(result) + }) +``` diff --git a/docs/3.x.md b/docs/3.x.md index 4878fbd..a57626f 100644 --- a/docs/3.x.md +++ b/docs/3.x.md @@ -1,147 +1,167 @@ -## 实例化 +## Document -> 实例化可以传入一个数组,或单个 object 配置。只有 1 个数据库时，默认是主库; -> 多于 1 个数据库服务时,自动以第 1 个为主库,其他的从库，故实例化时`注意顺序`。 +> One or more configurations can be passed in for instantiation. When there is only one database, the default is the `master library`; when there is more than one database service, the first one is automatically used as the `master library`, and the other `slave libraries`. ```javascript let Mysqli = require('mysqli') -//传入json +// one config let conn = new Mysqli({ - host: '', // IP/域名 - post: 3306, //端口， 默认 3306 - user: '', //用户名 - passwd: '', //密码 - charset: '', // 数据库编码，默认 utf8mb4 【可选】 - db: '' // 可指定数据库，也可以不指定 【可选】 + host: '', // IP/domain + post: 3306, //port, default 3306 + user: '', // username + passwd: '', // password + charset: '', // CHARSET of database, default to utf8 【optional】 + db: 'test' // the default database name 【optional】 }) -// 传入数组 +// two or more configs let conn = new Mysqli([ { - host: 'host1', // IP/域名 + host: 'host1', // + ... + }, + { + host: 'host2', // ... }, ... ]) + +let db = conn.emit() // use master library +// let db = conn.emit(false, 'test') +// let db = conn.emit(true, 'test') + +db.table('test').getAll().then(list => { + console.log(list) +}) + ``` -## 实例 API -### 静态方法 escape(val) -> 可以对 sql 的各种类型的值进行安全转义。 +## Static Function + +### escape(val) + +> Various types of values ​​of sql can be safely escaped + + + +## Instance APIs ### emit([slave], [db]) -* slave `` [可选]是否"从库", 默认为 false, -* db `` [可选]要连接的数据库名, 默认为空 +* slave `` [optional] use the slave libraries, default to false +* db `` [optional] declare the database's name, default to this config passed. + +> This method will return a DB instance. -> 返回一个 db 实例, 这个方法是必须要的, 所有的 sql 操作,都要先实例一个 db 对象。 ```javascript let db = conn.emit(false, 'test') -db.debug = true // 可开启debug模式 v3.1.0 开始支持 +db.debug = true // debugger mode. supported in ^3.1.0 db .tableList() .then(list => { - log(list) + console.log(list) }) .catch(err => { - log(err) + console.log(err) }) ``` -## DB API -> 是指直接对 db 进行操作的接口。如果没有特别说明,以下所有的方法, 返回的都是一个 Promise 对象。 +## DB APIs + +> All method will return a `Promise` if not declare. ### query(sql) * sql `` sql 语句, [必传] -> 直接执行 sql 语句, 用于在内置的 API 不满足需求的情况下, 可以自己手写 sql 执行。 +> Execute the sql if you need. ```javascript db.query('select * from `student` limit 10').then(result => { - log(result) + console.log(result) }) -// 前面没有指定数据库时, 也可以在这里写上 +// if not declare a database before. you can code like that. db.query('select * from `test`.`student` limit 10').then(result => { - log(result) + console.log(result) }) ``` ### drop(db) -* db `` [可选] 要删除 db 名, 不传则删除当前连接的数据库 +* db `` [optional] the database's name what you want to delete. It will delete the current connected database if not given. -> 删除当前或指定数据库。 +> delete the current connected database or what you want. ```javascript -db.drop() +db.drop() // delete self connected -// 也可以删除指定的数据库 +// delete foo db.drop('foo') ``` ### dbList() -> 返回当前账号权限下的所有的数据名(数组) +> return all the databases, base current account. ```javascript db.dbList().then(list => { - log(list) + console.log(list) }) ``` ### tableList() -> 返回当前连接的数据库下的所有的表名(数组) +> return all the tables of current connect database. ```javascript db.tableList().then(list => { - log(list) + console.log(list) }) ``` ### dbCreate(name, options) -* name `` [必传], 数据库名字 -* options ``, [选传], 数据库的配置 - - charset `` 默认 utf8mb4 +* name `` [required], database's name +* options ``, [optional], optional setting + - charset `` default to utf8mb4 -> 创建新的数据库, 成功返回true。 +> create a database, return `true` if success. ```javascript -db.dbCreate('foo', { charset: 'utf8' }) // 默认是utf8mb4 +db.dbCreate('foo', { charset: 'utf8' }) // default to utf8mb4 ``` ### tableCreate(name, columns ,options) -* name `` [必传], 表名字 -* columns ``, [必传], 表字段的配置 - - name `` 字段名, 区分大小写, 建议全小写+下划线 - - type `` 字段类型, 不区分大小写 - - primary `` 是否主键(有且只能有 1 个主键) - - inc `` 是否自增(只允许主键设置,且为整型时才可设置) - - notnull `` 是否允许非空 - - index `` 是否设为索引 - - unique `` 是否为 唯一索引 - - default `` 设置默认值 - - update `` 是否自动更新(只有 datetime & timestamp 可以设) -* options ``, [选传], 表的配置 - - charset `` 默认 utf8mb4 - - engine `` 默认 InnoDB +* name `` [required], table name +* columns ``, [required], table columns + - name `` field name, Case sensitive. recommend `lowercase` and `_` + - type `` field type, Not case sensitive + - primary `` is primary key or not.(Only one) + - inc `` is auto_increment or not.(must be primary key and int) + - notnull `` if value can be null + - index `` if create index + - unique `` if create unique index + - default `` the default value + - update `` auto update(only `datetime` | `timestamp`) +* options ``, [optional], other configs + - charset `` default to utf8mb4 + - engine `` default to InnoDB -> 创建新的数据表, 成功返回true。 +> create a table, return `true` if success. ```javascript db.tableCreate('student', @@ -176,9 +196,9 @@ db.tableCreate('student', ### table(name) -* name `` [必传], 数据表名字 +* name `` [required], table name -> 选择指定表。 返回一个表操作的 API 实例 +> select a table. return a Table instance. ```javascript let table = db.table('student') // @@ -188,15 +208,14 @@ let table = db.table('student') // -## TABLE API +## TABLE APIs -> 是指直接对 table 进行操作的接口。 ### leftJoin(tables) -* tables `` 左联, 可以联多个表 - - table `` 表名 - - on `` 左联的条件 +* tables `` left join one or more tables. + - table `` table name + - on `` condition ```javascript @@ -213,72 +232,79 @@ db.table('student') ### rightJoin(tables) -> 参考 leftJoin() +> see leftJoin() ### join(tables) -> 参考 leftJoin() +> see leftJoin() ### filter(options) * options `` -> 查询过滤, 这个方法是增删改查中使用率最高的。 也是 Mysqli 模块的核心方法之一。也是参数最复杂的方法, 一条查询里, 只能出现一次 filter, 多次调用, 会覆盖之前的条件. -> options 里有几个特殊的关键字 -> -> * $and (逻辑"且") -> * $or (逻辑"或") -> * $like 模糊查询 -> * $sql 以某个 sql 语句的结果作为查询条件 -> * $in 包含 -> * $between 在某某值和某某值之间 -> * $lt 小于 -> * $lte 小于等于 -> * $gt 大于 -> * $gte 大于等于 -> * $eq 等于 -> * $ne 不等于 +> Some keywords in `options`. + +> * `$and` +> * `$or` +> * `$like` fuzzy query +> * `$sql` Use the result of a certain sql statement as the query condition +> * `$in` +> * `$between` +> * `$lt` +> * `$lte` +> * `$gt` +> * `$gte` +> * `$eq` equal +> * `$ne` not equal ```javascript db .table('student') - .filter({ id: 1234 }) // 最基本的过滤查询, 即条件为 找"id=1234"的 + .filter({ id: 1234 }) // a simple search. find the item which it's id is 1234 - .filter({ name: { $like: '李%' } }) // 模糊查询, 找所有"李姓的学生" - // 现有的API不满足时, 可以自己写sql条件, 更复杂自己根据需求写即可 + // find the items which it's name starts with Lee + .filter({ name: { $like: 'Lee%' } }) + + // you can use sql to search items if needs .filter({ name: { $sql: 'IS NULL' } }) .filter({ score: { $sql: 'score + 1' } }) - .filter({ id: { $in: [11, 13, 29] } }) // 查询id在给定的这几个值的所有学生 + // find the items which it's id is 11,13,29 + .filter({ id: { $in: [11, 13, 29] } }) - .filter({ age: { $between: [15, 17] } }) // 查询年龄在 15~17岁的所有学生 - .filter({ age: { $lt: 16 } }) // 查询年龄小于16岁的所有学生 - .filter({ age: { $lt: 16, $gt: 13 } }) // 查询年龄小于16岁且大于13岁的所有学生 + // find all items which it's age is between 15 and 17 + .filter({ age: { $between: [15, 17] } }) - // ***** 以下是多条件的示例 ********* - // 查询所有姓李的,年龄15岁以上, 且为男生(假设 男生是1,女生是2) - .filter({ name: { $like: '李%' }, age: { $gt: 15 }, sex: 1 }) + // find all items which it's age is smaller than 16 + .filter({ age: { $lt: 16 } }) - // **** 从上面的示例可以看出,多个字段时, 自动为"AND" 查询 **** - // **** 所以下面该 $and 和 $or 出场了 **** + // find all items which it's age is smaller than 16 and elder than 13 + .filter({ age: { $lt: 16, $gt: 13 } }) - // 查询所有 姓李的, 或 年龄在15岁以上的 + // ***** multi conditions ********* + // find all which it's name starts with Lee, and it's age is elder than 15, and it'sex is 1 + .filter({ name: { $like: 'Lee%' }, age: { $gt: 15 }, sex: 1 }) + + // find all which it's name starts with Lee, or it's age is elder than 15 .filter({ - $or: [{ name: { $like: '李%' } }, { age: { $gt: 15 } }] + $or: [{ name: { $like: 'Lee%' } }, { age: { $gt: 15 } }] }) - // 姓李的 或 年龄15岁以上且为男生的 + // find all which it's name starts with Lee, or it's age is elder than 15 but it'sex is 1 .filter({ - $or: [{ name: { $like: '李%' } }, { age: { $gt: 15 }, sex: 1 }] + $or: [ + { name: { $like: 'Lee%' } }, // condition 1 + { age: { $gt: 15 }, sex: 1 } // condition 2 + ] }) - // 姓李的或15岁以上的, 且必须是男生的 + // find all which it's name starts with Lee or it's age is elder than 15, but it'sex must be 1 .filter({ $and: [ { @@ -288,7 +314,6 @@ db ] }) -// filter基本上满足了你日常绝大部分的查询需求, 如果还有没满足的, 可以自己写sql语句. ``` @@ -298,14 +323,14 @@ db ### sort(keys) * keys `` -> 对结果集排序 +> sort the result by fields. ```javascript db .table('student') - .sort({ age: -1 }) // -1为逆序, 1为正序 + .sort({ age: -1 }) // -1: Reverse sequence, 1: Positive sequence - // 先排年龄(逆序), 再排学号(正序) + // sort the age(Reverse sequence), then sort the id(Positive sequence) .sort({ age: -1, id: 1 }) ``` @@ -320,10 +345,10 @@ db * num `` -> 跳过指定条数, 可用于分页。 +> skip the nums from match list. ```javascript -db.table('student').skip(10) // 跳过前9条, 即从第10条结果开始返回 +db.table('student').skip(10) // return this 10th from match list ``` @@ -335,10 +360,11 @@ db.table('student').skip(10) // 跳过前9条, 即从第10条结果开始返回 * num `` -> 限制返回的结果总数, 做分页时, 配合 skip 方法使用。 +> limit the nums of the result. + ```javascript -db.table('student').limit(10) // 限制只返回10条记录 +db.table('student').limit(10) // only 10 items will be return ``` @@ -352,14 +378,14 @@ db.table('student').limit(10) // 限制只返回10条记录 * start `` * end `` -> 截取指定范围的结果集, 这是 skip & limit 结合体。 +> truncate the result. a friendly method for `skip` and `limit` ```javascript db .table('student') - .slice(11, 20) // 限制只返回10条记录 + .slice(11, 20) - // 等价于 + // equal to .skip(11) .limit(10) ``` @@ -371,15 +397,15 @@ db ### withFields(fields) -* fields `` [可选], 不传则返回所有的字段; v3.1.0, 支持传入多个参数, 效果等同于传入一个数组。 +* fields `` [optional], default to all fields; -> 指定要返回的字段 +> declare the fields what you need. ```javascript db.table('student').withFields(['id', 'name', 'sex']) // 只取 学号,姓名,性别3个字段返回 -// 等价于 -db.table('student').withFields('id', 'name', 'sex') // v3.1.0后支持 +// equal to +db.table('student').withFields('id', 'name', 'sex') // supported in ^3.1.0 ``` @@ -387,10 +413,8 @@ db.table('student').withFields('id', 'name', 'sex') // v3.1.0后支持 ### getAll([ids]) -* ids `` [可选],返回指定 id 的结果集; 不传则返回所有结果集。(仅当没有调用过 filter 的情况下,本参数才有效) +* ids `` [optional], return all items which you search. -> 返回符合条件的所有记录, 这个方法是 查询必须要调用的方法之一, 上面 .filter, .sort 等方法, 只是组件条件, 并不会返回结果, 只有调用了 getAll/get 之后, 才会返回结果集。 -> `这里有一个地方要注意的, 传入的参数ids, 即意味着, 该数据表里, 必须有一个字段为"id", 否则会出错, 没有id的表, 查询时请使用 .filter过滤。` ```javascript db @@ -398,30 +422,28 @@ db .withFields(['id', 'name', 'sex']) .getAll() .then(list => { - log(list) + console.log(list) }) -// 以下是查询学号为 11,13,28的学生 +// find the students which it's id is 11,13,28 db .table('student') .withFields(['id', 'name', 'sex']) .getAll([11, 13, 28]) .then(list => { - log(list) + console.log(list) }) -// 等价于 +// equal to db .table('student') .withFields(['id', 'name', 'sex']) .filter({ id: { $in: [11, 13, 28] } }) .getAll() .then(list => { - log(list) + console.log(list) }) -// 在getAll()方法里传参数, 只是一种快捷的filter, -// 没有"id"字段的表, 请使用 .filter()方法来查询 ``` @@ -430,28 +452,28 @@ db ### get(id) -* id `` [可选], 传入单个 ID。 +* id `` [optional], the ID you want to search。 -> 该方法是对 getAll 的补充, 它最终是调用 getAll 来实现, 目的在于返回 单个结果集(不是数组)。 +> return only one item. ```javascript -// 以下是查询学号为 11的学生 +// find the student which it's id is 11 db .table('student') .withFields(['id', 'name', 'sex']) .getAll(11) .then(doc => { - log(doc) + console.log(doc) }) -// 等价于 +// equal to db .table('student') .withFields(['id', 'name', 'sex']) .filter({ id: 11 }) .get() .then(doc => { - log(doc) + console.log(doc) }) ``` @@ -461,16 +483,16 @@ db ### count() -> 该方法同样是对 getAll 的补充, 它最终是调用 getAll 来实现, 返回结果集的总数。 +> count the num of result. ```javascript -// 返回所有姓李的学生的总数 +// get the num which it's name starts with Lee db .table('student') - .filter({name: {$like: '李%'}}) + .filter({name: {$like: 'Lee%'}}) .count() .then(total => { - log(total) + console.log(total) }) ``` @@ -478,99 +500,109 @@ db ### insert(doc) -* doc `` 要插入的记录 +* doc `` -> 用于插入单条记录。如果有自增ID的话, 将返回刚插入的记录的自增ID。 +> insert data. ```javascript db .table('student') .insert({ - name: '张三', + name: 'Tom', age: 18, sex: 1, ... }) - .then(lastId => { - log(lastId) // 如果表结构里没有自增ID, 则这个返回值永远为0 + .then(res => { + console.log(res) + // { + // fieldCount: 0, + // affectedRows: 1, + // insertId: 4, + // serverStatus: 2, + // warningCount: 0, + // message: '', + // protocol41: true, + // changedRows: 0 + // } }) ``` ### update(doc) -* doc `` 要插入的记录 +* doc `` -> 用于更新指定条件的记录, 返回成功修改的总数 +> update the data. ```javascript -// 将张三的年龄改为 17岁 +// db .table('student') - .filter({name: '张三'}) + .filter({name: 'Tom'}) .update({ age: 17 }) - .then(successNum => { - log(successNum) + .then(res => { + console.log(res) }) ``` ### remove() -> 删除记录。返回成功删除的总数。 +> delete items. ```javascript -// 将姓名为空的记录全删除了。 + db .table('student') .filter({name: {$sql: 'IS NULL'}}) .remove() - .then(successNum => { - log(successNum) + .then(res => { + console.log(res) }) ``` ### drop() -> 删除当前数据表, 属于`危险操作`哦。 成功返回true。 +> delete current table. it is `danger action`. ```javascript -// 将学生表给删除了 +// db .table('student') .drop() .then(result => { - log(result) + console.log(result) }) ``` ### renameTo(name) -> 重命名表。成功返回true。 +> rename current table. ```javascript db .table('student') .renameTo('student_bac') .then(result => { - log(result) + console.log(result) }) ``` ### indexList() -> 返回当前表的索引列表. +> return the index list. ```javascript db .table('student') .indexList() .then(list => { - log(list) + console.log(list) // { // name, // column, @@ -584,37 +616,37 @@ db ### indexDrop(name) -* name `` 索引名 +* name `` index name -> 删除当前表的指定索引. 成功返回true。 +> delete an index ```javascript -// 将学生表给删除了 +// db .table('student') .indexDrop('name_idx') .then(result => { - log(result) + console.log(result) }) ``` -### indexDrop(name, options) +### indexCreate(name, options) * name `` 索引名 * options `` 索引的配置 - field `` 该索引绑定的字段 - unique `` 是否是唯一索引 -> 给当前表创建索引. 成功返回true。 +> create an index for a field. ```javascript -// 将学生表给删除了 +// db .table('student') .indexCreate('name_idx', {field: 'name'}) .then(result => { - log(result) + console.log(result) }) ``` diff --git a/lib/method.js b/lib/method.js index 7797dd0..cba9511 100644 --- a/lib/method.js +++ b/lib/method.js @@ -128,18 +128,7 @@ class Method { } } - let { - table, - leftJoin, - rightJoin, - join, - filter, - fields, - sort, - skip, - size, - limit - } = this.cache + let { table, leftJoin, rightJoin, join, filter, fields, sort, skip, size, limit } = this.cache // 没有使用 slice方法的前提下, 通过skip/limit补全 if (!limit) { @@ -296,7 +285,7 @@ class Method { return this._query(sql) } - // 删除指定索引 + // 创建指定索引 indexCreate(name, opt = {}) { if (!name) { return Promise.reject('Empty index name') @@ -310,9 +299,7 @@ class Method { unique = 'UNIQUE' } - let sql = `ALTER TABLE ${ - this.cache.table - } ADD ${unique} INDEX \`${name}\` (${opt.field})` + let sql = `ALTER TABLE ${this.cache.table} ADD ${unique} INDEX \`${name}\` (${opt.field})` return this._query(sql) } diff --git a/package.json b/package.json index bef336f..6249814 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mysqli", - "version": "3.1.3", + "version": "3.1.4", "description": "MySQL tool", "main": "index.js", "dependencies": {