# @ioa/rest

> 数据库查询通用rest api组件

Latest version **9.7.2** (published 2019-11-21) · ISC license · 0 weekly downloads

## Install

```sh
npm install @ioa/rest
pnpm add @ioa/rest
yarn add @ioa/rest
bun add @ioa/rest
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 9.7.2 |
| Published | 2019-11-21 |
| First published | 2019-03-26 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 20.2 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | xiangle |
| Maintainers | xiangle |

## Links

- npm: https://www.npmjs.com/package/@ioa/rest
- npm.io page: https://npm.io/package/@ioa/rest

## Dependencies (1)

- [@koa/cors](https://npm.io/package/@koa/cors.md) ^3.0.0

## Recent versions

- 9.7.2 (latest) — 2019-11-21
- 9.7.1 — 2019-11-21
- 9.2.2 — 2019-09-04
- 9.1.6 — 2019-08-13
- 9.1.5 — 2019-08-12
- 9.1.3 — 2019-07-09
- 9.1.2 — 2019-07-09
- 9.1.1 — 2019-07-07
- 9.1.0 — 2019-07-07
- 9.0.1 — 2019-07-05
- 9.0.0 — 2019-07-02
- 8.1.3 — 2019-06-28
- 8.1.2 — 2019-06-28
- 8.1.1 — 2019-06-11
- 8.1.0 — 2019-06-11
- … 10 more at https://npm.io/package/@ioa/rest/versions

## README

## @ioa/rest

数据库查询通用rest api组件，集成角色、模型、字段级的权限管理，数据类型校验REST API。

在api开发过程中，经常需要向客户端提供一些纯数据库操作的CRUD接口，这些接口的共同特征是除访问权限外的其它业务逻辑几乎是相同的。为了避免编写重复的接口代码，减少接口数量，@ioa/rest通过在数据模型与用户api之间加入权限控制中间件，实现安全、快捷的抽象api。

api设计借鉴于postgrest简约的url查询表达式，@ioa/rest废除了原来臃肿的json方案，使用更为扁平化、更简洁、更易于读写的函数链表达式替换。

### 查询示例

#### select

```
http://localhost:9900/model/user?select=title,age,name
```

#### select! 反选

```
http://localhost:9900/model/user?select!=title,age,name
```

#### where

```
http://localhost:9900/model/user?where=name.eq(Wilburn);email.eq(Janae.Kiehn95@yahoo.com);age.eq(94580)
```

#### where、and

```
http://localhost:9900/model/user?where=name.eq(Wilburn)&and=name.eq(12);age.scope(1,45)
```

#### where、or

```
http://localhost:9900/model/user?where=name.eq(Wilburn)&or=name.eq(12);age.scope(1,45)
```

#### where、and、or

```
http://localhost:9900/model/user?where=age.gte(12).lt(100)&and=name.eq(12)&or=name.eq(12);age.scope(1,45)
```

```
http://localhost:9900/model/user?where=age.gte(12).lt(100);name.eq(12)||name.eq(12);age.gte(1);age.lte(100)
```

#### 链式条件

```
http://localhost:9900/model/user?where=age.gte(10).lt(100)
```

### 分号分隔符

用于隔离多个字段

```js
where=name.eq(Wilburn);email.eq(Janae.Kiehn95@yahoo.com)
```

#### 点连接符

用函数链的语法为单个字段声明多个and条件，只是一种快捷方式

```js
email.gte(12).lt(100) // 快捷函数链表达式

email.gte(12);email.lt(100) // 等效冗余表达式
```


### ormv库运算符

@ioa/rest支持ormv中的所有运算符

参考链接：[https://github.com/xiangle/ormv](https://github.com/xiangle/ormv)

### 编码转换

由于url参数存在保留关键字限制，当输入参数值中包含类似于&=()的保留关键字时需要使用encodeURIComponent()进行编码转换

(：%28

)：%29

#### 示例
```
// 错误，赋值中包含非法的保留字()
http://localhost:9900/model/user?where=phone.eq((559)-150-5961)

// 正确，()被转换为对应的url编码
http://localhost:9900/model/user?where=phone.eq(%28559%29-150-5961)
```

### 角色

当允许客户端通过api直接操作数据库时会涉及到很多安全问题，因此角色、权限的控制必不可少。

@ioa/rest中的角色是针对数据库的操作权限分组，并非常规的按照路由进行角色权限分组概念。

### 角色权限配置文件

为了方便集中管理权限配置项，@ioa/rest仅支持为$main组件扩展role目录，以角色名作为目录进行分组，每个配置文件名都需要有对应的数据模型。


#### 配置示例

```js
const common = {
   fields: {
      'name': true,
      'age': true,
   },
   where(ctx) {
      const { uid } = ctx.auth;
      return {
         'id': uid
      };
   }
}

module.exports = {
   'GET': { ...common },
   'POST': { ...common },
   'PUT': { ...common },
   'DELETE': { ...common },
}
```

#### 辅助配置函数

由于role字段配置繁琐且容易出错，为了简化配置过程，可以通过辅助函数来提高工作效率

```js
const { restModel } = require('@ioa/rest');

const fields = restModel('document').fields(); // 获取document模型的所有字段

const fields = restModel('document').fields('id', 'name', 'age', 'email'); // 获取document模型的指定字段

const fields = restModel('user').fieldsExclude('password'); // 获取user模型，不含password的所有字段

module.exports = {
   'GET': {
      fields,
      where(ctx) {
         const { uid } = ctx.auth;
         return {
            'id': uid
         };
      }
   },
   'POST': {
      fields,
      where(ctx) {
         const { uid } = ctx.auth;
         return {
            'id': uid
         };
      }
   },
}
```

### query查询参数

支持Ormv中的所有运算符和查询语句。除此之外@ioa/rest还扩展了一部分专用选项，用于简化查询语句。以下凡标注为“扩展参数”的选项均为@ioa/rest私有。

#### 通用参数

* *where* “与”逻辑条件表达式，和sql语法类似，必须用where开头，否则and、or条件会被忽略

* *and* “与”逻辑条件表达式

* *or* “或”逻辑条件表达式

#### select专用参数

* *select* 选择字段，select=name,title,email

* *select!* 反选字段，select!=uid,password

#### select查询列表专用参数

* order 限定排序条件，order=name.desc;title.desc;

* offset 起始位置

* page 限定当前第几页

* limit 限制单页最大条数

* total 是否显示总量

---
_Source: https://npm.io/package/@ioa/rest · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._