open-rest-helper-rest/README.md

open-rest 的 helper 插件，用来实现 CRUD 的标准操作

# open-rest-helper-rest

open-rest 的 helper 插件，用来实现 CRUD 的标准操作

[![Build status](https://api.travis-ci.org/open-node/open-rest-helper-rest.svg?branch=master)](https://travis-ci.org/open-node/open-rest-helper-rest)
[![codecov](https://codecov.io/gh/open-node/open-rest-helper-rest/branch/master/graph/badge.svg)](https://codecov.io/gh/open-node/open-rest-helper-rest)

## Node version
<pre> >= 6 </pre>

# Usage

```bash
npm instsall open-rest-helper-rest --save
```

```js
const rest = require('open-rest');
const restHelper = require('open-rest-helper-rest');

rest.plugin(restHelper);

// restHelper Equivalent to rest.helper.rest
```

## restHelper.list
标准的列表方法
```js
// Model 必选 Sequelize 定义的 Model, 表明要从哪个表获取数据
// opt 可选 特殊的 Model.findAll(options) options 的 hook 名称
// allowAttrs 可选，数组类型，指定允许返回的列，不指定则返回全部
// hook 可选，直接输出或者暂时寄存在 hooks 上

restHelper.list(Model, opt, allowAttrs, hook);

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .list
  .Model(User)
  .exec();
```

## restHelper.detail
标准的输出详情方法
```js
// hook 必选，要输出的数据在 req.hooks 的什么位置
// attachs 可选，要附加输出的数据格式为 key => value, value 是 req 上的路径字符串
// statusCode 可选，输出使用的http状态码, 默认值 200
// attrFilter 可选, 是否允许过滤属性, 默认 true

restHelper.detail(hook, attachs, statusCode, attrFilter);

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .detail
  .hook('user')
  .statusCode(201)
  .attachs({address: 'hooks.address'})
  .exec();
```

## restHelper.remove
标准删除资源的方法
```js
// hook 必选，要删除的实例在 req.hooks 的什么位置

restHelper.remove(hook);

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .remove
  .hook('user')
  .exec();
```

## restHelper.beforeModify
修改资源的前期准备，不包括save到数据库的操作
```js
// Model 必选, Sequlize 定义的Model，表明数据的原型
// hook 必选, 实例的存放位置
// cols 可选, 允许修改的字段

restHelper.beforeModify(Model, hook, cols);

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .beforeModify
  .Model(User)
  .cols(cols)
  .hook('user')
  .exec();
```

## restHelper.save
修改save到数据库的操作

```js
// 修改某个资源描述的后置方法, 将变化保存到数据库
// Model 必选, Sequlize 定义的Model，表明数据的原型
// hook 必选, 实例的存放位置

restHelper.save(hook);

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .save
  .hook('user')
  .exec();
```

## restHelper.modify
标准的修改某个资源的操作

```js
// Model 必选, Sequlize 定义的Model，表明数据的原型
// hook 必选, 实例的存放位置
// cols 可选, 允许修改的字段

restHelper.modify(Model, hook, cols);

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .modify
  .Model(User)
  .cols(cols)
  .hook('user')
  .exec();
```

## restHelper.beforeAdd
创建资源的操作，不包括 res.send 返回

```js
// Model 必选, Sequlize 定义的Model，表明数据的原型
// cols 可选, 允许设置的字段
// hook 必选, 生成实例的存放位置

restHelper.beforeAdd(Model, cols, hook);

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .beforeAdd
  .Model(User)
  .cols(['name', 'age', 'gender'])
  .hook('user')
  .exec();
```

## restHelper.add
标准的创建资源方法

```js
// Model 必选, Sequlize 定义的Model，表明数据的原型
// cols 可选, 允许设置的字段
// hook 可选, 生成实例的存放位置
// attachs 可选，要附加输出的数据格式为 key => value, value 是 req 上的路径字符串

restHelper.add(Model, cols, hook, attachs);

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .add
  .Model(User)
  .cols(['name', 'age', 'gender'])
  .hook('user')
  .exec();
```

## restHelper.batchAdd
批量创建资源方法

```js
// Model 必选, Sequlize 定义的Model，表明数据的原型
// cols 可选, 允许设置的字段
// hook 可选, 生成实例的存放位置
// attachs 可选，要附加输出的数据格式为 key => value, value 是 req 上的路径字符串

restHelper.batchAdd(Model, cols, hook, attachs);

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .batchAdd
  .Model(User)
  .cols(['name', 'age', 'gender'])
  .hook('user')
  .exec();
```

## restHelper.statistics
标准的资源统计功能方法

```js
// Model 必选，Sequlize 定义的Model，表明数据从哪里获取
// where 可选，额外的条件, req 对象上的路径，例如 'hooks.option.where',
// hook 可选, 默认为空，如果指定了hook，则数据不直接输出而是先挂在 hook上
// conf 可选，统计功能的配置，req 对象上值的路径例如 'hooks.user.conf'

restHelper.statistics(Model, 'hooks.opt.where', 'report', 'hooks.conf');

// return
// function(req, res, next) { ... };

//or 链式调用
restHelper
  .statistics
  .Model(User)
  .where('hooks.options.where')
  .conf('hooks.stats.conf')
  .hook('data')
  .exec();
```