comment-koa-router v0.2.7

comment-koa-router

In a production environment, use with caution. This package currently does not have enough testing

Download and run the npm test in lib's directory, then visit localhost:3000 to experience how it works.

comment-koa-router (ckr) is designed to achieve the following effect :

/*
@route(get /this)
#validate({
  $type:{
    q.a: Number,
    q.b: ?Number
  },
  $default:{
    q.b: 16730
  },
  $compare:[
    q.a - q.b > 1000
  ]
})
*/
exports.routeThis = function* () {
  let {a, b} = this.query;
  this.body = "this is a: " + a + " and b: " + b;
}

Let you focus on your business code, easy to configure route, reduce data verification code.

• @route used to configure route, each config should begin with it, you can configure multiple requests use '|' to split, for example 'get|post'.
• #validate is a plugin, each plugin starts with '#', on the request before they reach your business code that will go through the configuration of the plugins, you can also customize your own plugin.

Plugin's parameter must be looks like JSON formatted data, keys and values will be in double quotation marks ({key:value} => {"key":"value"}) and give it to the JSON function parse to a JSON object, validate plugin is ckr's default plugin, it supports three kinds of functions :

• $type used to validate the request parameter type, support Number,Date,Regexp,Array,Equal,Null, key beginning with q/p/b/h corresponding 'this.query', 'this.params', 'this.request.body', 'this.headers', is shorthand for them, you can also use query,params,body,headers. The value start with '?', such as (?Number / ?Date / ?[]), means this parameter can be null, but if it not null, it must comply with the following types. Array form of value, such as 2,4,6 that represents the requested parameter must exist in the array, when the Array have '?' mark, like ?1,2 means the requested parameter can be null, if it not null, it must be in following config values. The value start with '!', means the request parameter can't equal config type or value. if you want to specify a date value should use Date like: Date(2018-08-18). The remaining value of the form will only determine for Equal.
• $default used to set the default value for the corresponding parameter when the parameter is null, it will convert to corresponding type, e.g if q.c set type is ?Date and set default value is 2016-08-08 then the q.c value will set to be Date('2016-08-08'). notice $default can't set value to Array, because Array value can't use to $compare.
• $compare use eval() to do the expression verification, if the expression return true the verification Pass.

You can also use double slashes '//' to do configuration, like this :

// @route(get /that/:a)
// #validate({
//   $type:{
//     p.a: Number,
//     q.b: [1,3]
//   },
//   $compare:[
//     p.a == 10
//   ]
// })
// #token({})
exports.routeThat = function* () {
  let a = this.params.a;
  let b = this.query.b;
  this.body = "that: a: " + a + " and b: " + b;
}

In your project you should use this library like this :

let router = require('koa-router')();
let ckr = require('comment-koa-router');
ckr(router, './routes', {});

• The first argument is a koa-router instance, cannot be null.
• The second argument is the directory where you store the routes and cannot be null.

• The third argument is the config object, which can be null :

  config.plugin is used to configure a custom plugin, can be array, each plugin should be a Object and it kept couple method that method return generator function (more detail, looking for ckr's plugin.js file).

  config.mount false indicates that do not mount the default plugin, the default value is true.

  config.match to filtering what files you do not want to import, for example: /^(?![a-z0-9_.]*index)(.+)\\.js$/ means don't import the files end with index.js

  config.predir set a directory, in the pre config directory, each request will be through the same name file and function as the route file with comment config, and you should yield next to let request arrive route function. actually #validate plugin's functionality and performance is not good, so configure predir to do the validation by yourself. for more detail, see the test.js file.

You can also comment-config in the class or anywhere else, such as :

module.exports = class Query {
  constructor () {}

  /*
  @route(get /query)
  */
  * query () {..}
};
//ckr determine the Query is a function type and create instance of it
//and then import it's methods.

Finally, bad english, forgive me

中文文档

在生产环境请谨慎使用，目前还没有做充分的测试

下载包并在包的目录下运行 npm test, 访问localhost:3000来体验下

comment-koa-router(ckr)的目的是为了达到如下的效果:

/*
@route(get /this)
#validate({
  $type:{
    q.a: Number,
    q.b: ?Number
  },
  $default:{
    q.b: 16730
  },
  $compare:[
    q.a - q.b > 1000
  ]
})
*/
exports.routeThis = function* () {
  let {a, b} = this.query;
  this.body = "this a: " + a + " and b: " + b;
}

让你专注于业务逻辑，轻松配置路由，减少数据校验代码

• @route 用于配置路由，每个配置都应以它开头 可以配置多种请求方式，以'|'分割，例如 'get|post'
• #validate 是一个插件，每个插件以'#'开头 在请求到达你的业务代码之前会先经过这些配置的插件，你也可以自定义自己的插件

插件的参数必须是看起来像JSON格式的数据，键和值会被加上双引号 ({key:value} => {"key":"value"})然后交给JSON去转换成JSON对象 validate 插件是ckr自带的插件，它支持三种功能:

• $type 用于验证参数类型，支持 Number,Date,RegExp,Array,Equal,Null， 键以 q/p/b/h 开头， 对应着this.query,this.params,this.request.body,this.headers，是他们的简写形式 你也可以使用全称 query,params,body,headers 以'?'开头的值，例如 (?Number / ?Date / ?[])，表示这个参数可以为null 但若不为null，则必须符合其后的类型，Array形式的值， 例如2,4,6，表示请求参数必须存在于数组中，当Array以 '?' 开头，例如：?1,2， 意味着对应的请求参数可以为空，若不为空则其值必须在数组中。 以'!'开头的值，意味着请求参数不应与配置的类型或值相同。 若要指定具体的日期值，Date应为这样的形式：Date(2018-08-18)。 其余形式的值都只会作Equal判断
• $default 用于在对应参数没有值时为其设置默认值，并被转换成对应类型， 例如：设置参数 q.c 的类型为 ?Date，设置其默认值为 2016-08-08， 它的值将会被设置为 Date('2016-08-08')， 注意 $default 不能设置值为Array数组，因为其无法用于 $compare 中进行比较
• $compare 使用eval()函数来做表达式校验，如果表达式返回为true则验证通过

你也可以使用双斜杠'//'来做配置，像下面这样:

// @route(get /that/:a)
// #validate({
//   $type:{
//     p.a: Number,
//     q.b: [1,3]
//   },
//   $compare:[
//     p.a == 10
//   ]
// })
// #token({})
exports.routeThat = function* () {
  let a = this.params.a;
  let b = this.query.b;
  this.body = "that: a: " + a + " and b: " + b;
}

在你的项目中你应这样使用这个库:

let router = require('koa-router')();
let ckr = require('comment-koa-router');
ckr(router, './routes', {});

• 第一个参数是koa-router实例，不能为null
• 第二个参数为你路由存放的目录，不能为null

• 第三个参数是配置对象config，可以为null:

  config.plugin 用于配置自定义插件，可以为数组形式， 每个插件应为保存了几个可以返回generator函数方法的对象 (具体形式查看 ckr 的plugin.js文件)

  config.mount false表示不使用默认插件，默认为true

  config.match 用于过滤不想导入的路由文件，例如: /^(?![a-z0-9_.]*index)(.+)\\.js$/过滤以index.js结尾的文件

  config.predir 配置一个目录， 每个请求到达配置的路由之前会经过此目录下与route同名文件内的同名方法， #validate插件的功能和性能并不是很好，配置predir来自己对参数做校验， 更多细节请查看test.js文件

你也可以在类中或其他地方进行配置，例如:

module.exports = class Query {
  constructor () {}

  /*
  @route(get /query)
  */
  * query () {..}
};
//ckr判断Query为function类型，会创建它的实例然后导入它的方法