校验器

校验器用于数据操作时校验操作的合法性，是对数据表 ACL 权限的自定义校验。 数据表关联了校验器后，在进行数据操作时，后台会调用该校验器进行校验。 校验器通过返回 true、false 或抛出错误来对操作合法性做出评判。

校验器的使用场景主要分为以下几个方面：

• 对数据表操作方法进行校验（create、update、delete、bulk_create、bulk_update、bulk_delete等）

• 对操作者进行校验

• 对用户传入数据—— payload 进行校验

info 3.13.0 版本前，校验器 payload 字段可以拿到整个数据对象；

3.13.0 版本后（包括 3.13.0），校验器 payload 字段仅能拿到用户输入数据。

快速开始

只需两步，即可成功创建校验器：

1. 在控制台数据表中创建校验器 查看文档。

2. 校验器创建成功后，进入编辑页面，只需要在默认提供的校验器模版代码对应的 handler 如 onCreate 中加入判定逻辑即可，校验器模版代码如下。

BaaS.useVersion('v3.4')
exports.main = async function (event) {
  const handlers = {
   /**
    * handler 会在对应的操作事件中被触发，请在下方对应的事件 handler 如 onCreate 中添加判定逻辑并修改返回值。
    *
    * <<输入>>:
    * | 属性        | 类型   | 说明                                                                                          |
    * | :---------- | :----- | :-------------------------------------------------------------------------------------------- |
    * | event       | String | 触发事件类型，包括：`create`、`update`、`delete`、`bulk_create`、`bulk_update`、`bulk_delete` |
    * | schema_id   | String | 校验器关联的数据表 ID                                                                         |
    * | schema_name | String | 校验器关联的数据表名称                                                                        |
    * | user_id     | String | 触发事件的用户 ID                                                                             |
    * | payload     | Object | 用户传入数据，`delete`/`bulk_delete` 事件中不包含该参数                                       |
    * | before      | Object | 原始数据，`create`/`bulk_create`/`bulk_update`/`bulk_delete` 事件中不包含该参数               |
    * | filter      | Object | 用户筛选条件，仅 `bulk_update`/`bulk_delete` 包含该参数                                       |
    *
    * <<输出>>:
    * 返回 true 为 “验证通过”
    * 返回 false 为 “验证不通过（未提供理由）”
    * 抛出 Error 为 “验证不通过（Error.message 为理由）”
    *
    * <<举例>>:
    * return data.user_id == 1001 // 只允许 ID 为 1001 的用户进行操作
    * 或者:
    * if (data.user_id == 1001) {
    *   return true
    * } else {
    *   throw Error(`用户 ${data.user_id} 无操作权限`)
    * }
    */
    async onCreate(data) {
      // “创建”操作时触发，
      return true
    },
    async onUpdate(data) {
      // “更新”操作时触发
      return true
    },
    async onDelete(data) {
      // “删除”操作时触发
      return true
    },
    async onBulkCreate(data) {
      // “批量创建”操作时触发
      return true
    },
    async onBulkUpdate(data) {
      // “批量更新”操作时触发
      return true
    },
    async onBulkDelete(data) {
      // “批量删除”操作时触发
      return true
    },
  }
  const validator = new BaaS.Validator(handlers)
  return validator.validate(event)
}

使用示例

下方是一个完整的校验器例子，实现了以下规则：

• 所有用户可以创建订单

• 只允许用户 1001 删除订单

• 禁止了批量创建、批量更新、批量删除

• 禁止取消已过期订单

BaaS.useVersion('v3.4')
exports.main = async function (event) {
  const handlers = {
    async onCreate(data) {
      return true
    },
    async onUpdate(data) {
      if (event.data.before.status === '已过期' && event.data.payload.status === '已取消') {
        throw Error('已过期的订单不可取消')
      }
      return true
    },
    async onDelete(data) {
      if (data.user_id == 1001) {
        return true
      } else {
        throw Error(`用户 ${data.user_id} 无操作权限`)
      }
    },
    async onBulkCreate(data) {
      return false
    },
    async onBulkUpdate(data) {
      return false
    },
    async onBulkDelete(data) {
      return false
    },
  }
  const validator = new BaaS.Validator(handlers)
  return validator.validate(event)
}

Validator

SDK 提供了 Validator 类来帮助开发者快速实现校验器。

info SDK >= v3.4。

• Validator(handlers) 创建 Validator 对象

• Validator#validate(event) 执行校验

参数说明

属性	类型	必填	说明
handlers	Handlers	是	数据表操作 handler 集合
event	Object	是	云函数 event 参数

Handlers:

interface Handlers {
  [key: string]: (data: typeof event.data) => boolean
}

• event.data 的数据结构，请参照 event.data 说明 。

• key 的规则是：'on_' + 操作事件名，再转化为 CamelCase。例如：onCreate、onBulkCreate。

info 某个操作事件的 handler 如果未定义，默认返回 true。

使用方法：

1. 创建 Validator 对象

const validator = new Validator(handlers)

1. 执行校验并返回结果

return validator.validate(event)

代码示例

参考上文。

高阶使用

除了直接使用 Validator 类，开发者还可用自定义逻辑实现校验器。

event.data说明

校验器的 event.data 参数中，包含了触发该校验器的数据操作的详细信息，校验器可以对这些信息进行校验，最终给出判定。

属性	类型	说明
event	String	触发事件类型，包括：create、update、delete、bulk_create、bulk_update、bulk_delete
schema_id	String	校验器关联的数据表 ID
schema_name	String	校验器关联的数据表名称
user_id	String	触发事件的用户 ID
payload	Object	用户传入数据，delete/bulk_delete 事件中不包含该参数
before	Object	原始数据，create/bulk_create/bulk_update/bulk_delete 事件中不包含该参数
filter	Object	用户筛选条件，仅 bulk_update/bulk_delete 包含该参数

event.data.event 说明：

属性	说明
create	创建
update	更新
delete	删除
bulk_create	批量创建
bulk_update	批量更新
bulk_delete	批量删除

返回说明

返回	说明
true	合法操作，校验通过
false	非法操作，校验不通过（未提供拒绝理由）
<Error>	非法操作，校验不通过（Error.message 为拒绝理由）

拒绝所有操作/允许所有操作

校验器直接返回判定结果。

代码示例

不返回拒绝理由：

BaaS.useVersion('v3.4')
exports.main = async function (event) {
  return false
}

返回拒绝理由：

BaaS.useVersion('v3.4')
exports.main = async function (event) {
  throw '数据表已锁定，不允许任何操作'
}

对数据表操作方法进行校验

校验器中默认所有操作方法都是打开的，如果需要关闭某个或某写方法的操作权限， 只需要判断操作方法并返回 false 即可。

代码示例

不返回拒绝理由：

BaaS.useVersion('v3.4')
const whitelist = ['create', 'update']
exports.main = async function (event) {
  return whitelist.includes(event.data.event)
}

返回拒绝理由：

BaaS.useVersion('v3.4')
const whitelist = ['create', 'update']
exports.main = async function (event) {
  if (!whitelist.includes(event.data.event)) {
    throw Error(`不允许 ${event.data.event} 操作`)
  }
  return true
}

对操作者进行校验

对操作者进行验证与数据表操作方法验证类似，判定并返回判定结果即可。

代码示例

不返回拒绝理由：

BaaS.useVersion('v3.4')
const whitelist = [1001, 1002]
exports.main = async function (event) {
  return whitelist.includes(event.data.user_id)
}

返回拒绝理由：

BaaS.useVersion('v3.4')
const whitelist = [1001, 1002]
exports.main = async function (event) {
  if (!whitelist.includes(event.data.user_id)) {
    throw Error(`用户 ${event.data.user_id} 无操作权限`)
  }
  return true
}

对用户传入数据进行校验

对用户传入数据进行校验时，一般是通过与更新前的数据进行对比，或通过数据查询，判定操作是否合法。

代码示例

不返回拒绝理由：

BaaS.useVersion('v3.4')
exports.main = async function (event) {
  return !(event.data.before.status === '已过期' && event.data.payload.status === '已取消')
}

返回拒绝理由：

BaaS.useVersion('v3.4')
exports.main = async function (event) {
  if (event.data.before.status === '已过期' && event.data.payload.status === '已取消') {
    throw Error('已过期的订单不可取消')
  }
  return true
}

注意事项

1. “校验器”与“云函数”使用同一个“云函数”引擎，但使用场景并不一样， 不要在“校验器”中包含跟数据校验无关的业务代码。

2. 由于 JavaScript 函数默认返回 undefined，是个 falsy 值，所以校验通过时，需要明确返回 true。

例如，下文的代码中，开发者的意图是只禁止 ID 为 1001 的用户创建数据。但实际上， 所有用户都被禁止操作了。

...
async onCreate(data) {
  if (data.user_id == 1001) {
    return false
  }
},
...

正确的做法：

...
async onCreate(data) {
  if (data.user_id == 1001) {
    return false
  }
  return true
},
...