RapidQuery

Ver 0.2.6

Content

Intro

Installation

Usage

删除Document

说明

返回值
Mongoose DB原型

1-Intro

一种使用JSON来查询API的接口协议，前端只需要GET/POST发送JSON到一个地址（比如下面这个API地址），就可以与MongoDB数据库进行CRUD。

比如Post/Get 下面这个JSON, 参数名为 "query" ：

{
  "read users":{
    id: 1
  }
}

至

http://localhost:8080/rapidql

就可以查询到数据

{
  users: [{
    id: 1,
    name: "tt",
    age : 29,
    gender: "male"
  }]
}

2-Installation

npm install --save rapidquery

或使用淘宝镜像

cnpm install --save rapidquery

3-Usage

const RapidQuery = require("rapidquery");

RapidQuery.connect({
  host: "mongodb://localhost:27017/rapid"
});

或使用用户名和密码

RapidQuery.connect({
    host: "mongodb://admin:12345678@localhost:27017/rapid?authSource=admin"
});

在Express或Koa下使用


router.post('/rapidquery', async function(ctx, next) {
  try {
      if (ctx.request.body.query) {
          var data = await RapidQuery.query(ctx.request.body.query);
          ctx.type = "application/json"
          ctx.body = data;
      } else {
          throw new Error("Query JSON is required.")
      }
  } catch (err) {
      ctx.status = 400;
      ctx.body = `${err.name} : ${err.message}`;
      console.error(err)
  }
})

或者可以直接使用

var data = await RapidQuery.query(ctx.request.body.query)

4-Define a Model

定义 Model

定义一个超简单的 Model

var users = RapidQuery.define({
  name: "users",
  description: "用户数据",
  fields: {
    name: String,
    email: String,
    gender: String,
    age: Number
  }
})

系统会自动添加以下字段

_id
meta:{
  createdAt
  updatedAt
}

来定义一个较完整功能的

var users = RapidQuery.define({
  name: "users",
  description: "用户数据",
  fields: {
    id: {
      type: RapidQuery.ObjectId,
      default: RapidQuery.NewObjectId //RapidQuery.NewObjectId可以生成一段新的id
    },
    firstname: String,
    lastname: String,
    email: {
      type: String,
      unique: true,
      lowercase: true, 
      trim: true,
      required: [true, "Email为必填项"],  //required说明该field不能为空
      
      //自定义验证
      validate: {
        validator: value => {   
          return /^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)+$/.test(
            value
          );
        },
        message: "{VALUE} 不是一个有效的Email地址!"
      }
    },
    userType:{
      type: String,
      default: "学生",
      enum:["学生","老师"]
    },
    age: {
      type: Number,
      //数值验证, 最小值为15, 最大值为30
      min: 15,
      max: [30, "年龄不能超过30岁"]
    },
    job:{
      type: String,
      required: function() {
        return this.age > 23; //required可变, 比如当age大于23岁时, job才是必填项
      }
    },
    school: {
      name: String
    }
  },
  options: {
    timestamp: true, //可以不填，默认为true, model会自动添加 meta: {createdAt, updatedAt}
    paranoid: true, //可以不填，默认为true, 当使用delete时, 使用逻辑删除（并不真正删除）
    discriminatorKey: "kind"
  }
});

4-1-Date Types

数据类型

所有可用的数据类型

String
Number
Date
Buffer
Boolean
Array

Mixed      // 一个啥都可以放的 SchemaType, 虽然便利，但也会让数据难以维护。在声明中使用 RapidQuery.Mixed
ObjectId   // 要指定类型为 ObjectId，在声明中使用 RapidQuery.ObjectId
Decimal128 // 在声明中使用 RapidQuery.Decimal128

所有可用的选项

所有类型相关
required: 布尔值或函数 如果值为真，为此属性添加 required 验证器
default: 任何值或函数 设置此路径默认值。如果是函数，函数返回值为默认值
validate: 函数，自定义验证
get: 函数 使用 Object.defineProperty() 定义自定义 getter
set: 函数 使用 Object.defineProperty() 定义自定义 setter
alias: 字符串 仅mongoose >= 4.10.0。 为该字段路径定义虚拟值 gets/sets

索引相关
index: 布尔值 是否对这个属性创建索引
unique: 布尔值 是否对这个属性创建唯一索引
sparse: 布尔值 是否对这个属性创建稀疏索引

String相关
lowercase: 布尔值 是否在保存前对此值调用 .toLowerCase()
uppercase: 布尔值 是否在保存前对此值调用 .toUpperCase()
trim: 布尔值 是否在保存前对此值调用 .trim()
match: 正则表达式 创建验证器检查这个值是否匹配给定正则表达式
enum: 数组 创建验证器检查这个值是否包含于给定数组

Number相关
min: 数值 创建验证器检查属性是否大于或等于该值
max: 数值 创建验证器检查属性是否小于或等于该值

Date相关
min: Date 创建验证器检查属性是否大于或等于该Date
max: Date 创建验证器检查属性是否小于或等于该Date

因 ORM 部分采用的是 Mongoose 的代码，数据类型的详细说明, 请访问: http://www.mongoosejs.net/docs/schematypes.html

4-2-Validation

数据验证

validate: {
  validator: (v) => {
    return /\d{3}-\d{3}-\d{4}/.test(v);
  },
  message: '{VALUE} is not a valid phone number!'
},

自定义检验器可以是异步的

validate: (v) => {
  return new Promise(function(resolve, reject) {
    setTimeout(function() {
      resolve(false);
    }, 5);
  });
}

因 ORM 部分采用的是 Mongoose 的代码，关于验证的详细说明, 请访问: http://www.mongoosejs.net/docs/validation.html

4-3-Model Options

选项

timestamp: true   // 默认为true, model会自动添加 meta: {createdAt, updatedAt}
paranoid: true    // 默认为true, 当使用delete时, 使用逻辑删除（并不真正删除）,删除时添加deletedAt

5-Create a document

创建 Document

5-1-Create

创建

使用GET方法:

http://localhost:8080/rapidquery?query={"create user":{"firstname":"tt"}}

推荐使用POST方法（参数为query）

{
  "create users": {
    firstname: "tt",
    lastname: "zhang",
    age: 29,
    school: {
      name: "UCLA"
    }
  }
}

5-2-Create Multi

创建多个documents

{
  "create users": [
    {
      firstname: "tt",
      lastname: "zhang",
      age: 29,
      school: {
        name: "UCLA"
      }
    },
    {
      firstname: "jinchuang",
      lastname: "huang",
      age: 21,
      school: {
        name: "MIT"
      }
    }
  ]
}

6-Read documents

查询 Document

6-1-Read

查询名为"tt"的user

{
  "read users": {
    firstname: "tt"
  }
}

结果:

{
  users:[
    {
      _id: 5e4b97490cc84609513cf8fa,
      firstname: 'tt',
      lastname: 'zhang',
      age: 29,
      school: { name: 'UCLA' },
      __v: 0
    }
  ]
}

查询所有Users

{
  "read users": {
  }
}

6-2-Comparison Operatiors

使用比较运算符

{
  "read users": {
    age: {
      $lt: 25
    }
  }
}

还有其他比较运算符可以使用.
```key
$gt: greater than    大于
$lt: less than       小于
$gte: greater than equal   大于等于
$lte: less than equal      小于等于
$ne: not equal       不等于

6-3-Logical Operators

使用逻辑运算符

{
  "read users": {
    $or:[
      {age: 21},
      {age: 23}
    ]
  }
}

6-4-Regular Expression

使用正则表达式进行模糊查询

{
  "read users": {
    firstname: /t/
  }
}

6-5-Order

排序

按年龄进行倒序

{
  "read users": {
    $order:{
      age: -1
    }
  }
}

6-6-PageSize and PageNum

pageSize来控制每页返回数据的行数，pageNum来控制第几页

注意：pageNum从1开始，而不是0

{
  "read users": {
    firstname: /t/,
    $pageSize: 1,
    $pageNum: 1
  }
}

6-7-Select

过滤查询字段

$select可以选择只要查询的字段

{
  "read users": {
    $select:"firstname age school.name"
  }
}

或者使用 "-" 排除字段

{
  "read users": {
    $select:"-firstname -age"
  }
}

6-8-In or NotIn

使用 In 和 NotIn

$in:

{
  "read users": {
    "school.name": {
      $in: ["MIT"]
    }
  }
}

$nin:

{
  "read users": {
    "school.name": {
      $nin: ["UCLA"]
    }
  }
}

6-9-Count

计数

使用 $count 计算学校名为MIT用户数量

{
  "count users": {
    "school.name": {
      $in: ["MIT"]
    }
  }
}

结果:

{
  count_users: 1
}

6-10-Multi Query

并行查询多个Collections

查询名为"tt"的user和"alice"的student
注意：查询为并行，所以不能有先后顺序。

{
  "read users": {
    firstname: "tt"
  },
  "read students": {
    name: "alice"
  }
}

结果:

{
  users:[
    {...}
  ],
  students:[
    {...}
  ]
}

7-Update Document

更改 Document

7-1-Update

更新名字为 "tt" 的用户的年龄为 35

{
  "update users": {
    age: 35,
    $update:{
      firstname: "tt"
    }
  }
}

结果:

{
  update_users: { n: 1, nModified: 1, ok: 1 }
}

7-2-Push

将数值添加到数组

更改名字为 "tt" 的用户
注意：Update至少需要一个条件，否则无法执行

{
  "update users": {
    firstname: "tt",
    $update:{
      $push: {
        cars: ["porsche", "ford f-150"]
      }
    }
  }
}

7-3-Inc

增加某个数值

更改名字为 "tt" 的用户，age+1

{
  "update users": {
    firstname: "tt",
    $update:{
      $inc:{
        age:1
      }
    }
  }
}

8-Delete Document

删除 Document

删除年龄为35的一个用户.
注意：Delete至少需要一个条件，否则无法执行

{
  "delete users": {
    age: 35
  }
}

Notes

说明

Returns

返回结果

***为Collection名

{
  create_***:{},
  ***:[],
  update_***:{},
  delete_***:{},
  count_***:{},
  aggregate_***:{},
}

Mongoose DB

获取Mongoose的db原型

db中包含了所有定义的Models, Schemas, Connections等，如果需要进行扩展开发，可以使用await RapidQuery.connect来获取。只能通过异步来获取。

var db = await RapidQuery.connect({
  host: "mongodb://localhost:27017/rapid"
});

timetzhang / RapidQuery .gitee-modal { width: 500px !important; }