YaoDocs

外观

数据处理器与钩子（Data Processors and Hooks） ​

概述 ​

Yao 是一个低代码开发框架，提供了丰富的数据处理能力。本文档详细介绍了 Yao 在模型数据读取与处理方面提供的处理器（Processors）与 API 入口，以及相关的钩子（Hooks）机制。

数据处理器是 Yao 框架中用于操作数据的函数集合，而钩子则允许开发者在数据处理的不同阶段插入自定义逻辑。

核心概念 ​

  • 处理器（Processor）：预定义的函数，用于执行特定操作（如查询、创建、更新等）
  • 模型（Model）：对应数据库表的结构定义
  • 钩子（Hook）：在数据处理前后执行的自定义函数，分为 before 和 after 两种
  • MODEL_ID：模型的唯一标识符，用于在处理器中引用特定模型

模型处理器（Model Processors） ​

操作模型相当于操作数据库表，每个操作都需要指定模型的 ID（MODEL_ID）。下面按功能分类列出所有模型处理器：

查询操作 ​

javascript
// 示例：按ID查询用户
const user = Process('models.user.find', 1); // 查询ID为1的用户

  • models.MODEL_ID.find：按主键ID查询单条记录

    • 参数：主键值
    • 返回：单条记录对象

  • models.MODEL_ID.get：根据条件查询多条记录，不分页

    • 参数：查询条件、字段选择等
    • 返回：记录数组

  • models.MODEL_ID.paginate：根据条件查询，支持分页

    • 参数：页码、每页数量、查询条件等
    • 返回：分页结果对象（包含数据和分页信息）

  • models.MODEL_ID.selectoption：获取字段的选项列表，常用于前端下拉菜单

    • 参数：字段名、查询条件等
    • 返回：选项数组

创建与更新操作 ​

javascript
// 示例：创建新用户
const userId = Process('models.user.create', { name: '张三', age: 25 });

  • models.MODEL_ID.create：创建单条记录

    • 参数：记录数据对象
    • 返回：新创建记录的ID

  • models.MODEL_ID.update：更新单条记录

    • 参数：主键值、更新数据对象
    • 返回：更新后的记录ID

  • models.MODEL_ID.save：保存单条记录（不存在则创建，存在则更新）

    • 参数：记录数据对象（需包含主键）
    • 返回：记录ID

  • models.MODEL_ID.insert：批量一次性保存多条记录

    • 参数：记录数据对象数组
    • 返回：操作影响的行数

  • models.MODEL_ID.updatewhere：根据条件批量更新记录

    • 参数：查询条件、更新数据对象
    • 返回：更新的行数

  • models.MODEL_ID.eachsave：批量逐条保存记录

    • 参数：记录数据对象数组
    • 返回：保存的记录ID数组

  • models.MODEL_ID.eachsaveafterdelete：先删除指定ID的记录，再批量保存

    • 参数：要删除的ID数组、要保存的记录数组
    • 返回：保存的记录ID数组

删除操作 ​

javascript
// 示例：删除用户
Process('models.user.delete', 1); // 软删除ID为1的用户

  • models.MODEL_ID.delete：软删除单条记录（标记删除）

    • 参数：主键值
    • 返回：删除结果

  • models.MODEL_ID.destroy：硬删除单条记录（物理删除）

    • 参数：主键值
    • 返回：删除结果

  • models.MODEL_ID.deletewhere：根据条件软删除记录

    • 参数：查询条件
    • 返回：删除的行数

  • models.MODEL_ID.destroywhere：根据条件硬删除记录

    • 参数：查询条件
    • 返回：删除的行数

表单处理器（Form Processors） ​

表单处理器用于处理与表单相关的数据操作。表单处理器的第一个参数始终是表单ID。值得注意的是，同一个模型可以对应多个不同的表单配置。

重要提示：在表单处理器中，before 钩子函数的返回值必须是数组类型。

数据操作处理器 ​

javascript
// 示例：通过表单创建用户
Process('yao.form.create', 'user', { name: '李四', age: 30 });

  • yao.form.create：创建记录

    • 对应：models.<MODEL_ID>.Create
    • 钩子：before:create, after:create

  • yao.form.delete：删除记录

    • 对应：models.<MODEL_ID>.Delete
    • 钩子：before:delete, after:delete

  • yao.form.find：查询单条记录

    • 对应：models.<MODEL_ID>.Find
    • 钩子：before:find, after:find

  • yao.form.save：保存记录

    • 对应：models.<MODEL_ID>.Save
    • 钩子：before:save, after:save

  • yao.form.update：更新记录

    • 对应：models.<MODEL_ID>.Update
    • 钩子：before:update, after:update

文件处理器 ​

  • yao.form.upload：文件上传处理
  • yao.form.download：文件下载处理

UI与配置处理器 ​

  • yao.form.xgen：生成表单的前端配置
  • yao.form.setting：读取表单设置
  • yao.form.component：处理表单组件的操作

配置管理处理器 ​

  • yao.form.load：从文件或源代码加载表单配置
  • yao.form.reload：重新加载表单配置
  • yao.form.unload：从内存中卸载表单配置
  • yao.form.read：读取表单配置
  • yao.form.exists：检查表单配置是否存在

表单API端点 ​

表单对应的RESTful API端点列表：

API路径说明
/api/__yao/form/:id/setting获取表单设置
/api/__yao/form/:id/component/:xpath/:method操作表单组件
/api/__yao/form/:id/upload/:xpath/:method表单文件上传
/api/__yao/form/:id/download/:field表单文件下载
/api/__yao/form/:id/find/:primary按主键查询记录
/api/__yao/form/:id/save保存记录
/api/__yao/form/:id/create创建记录
/api/__yao/form/:id/insert批量插入记录
/api/__yao/form/:id/delete/:primary删除记录

表格处理器（Table Processors） ​

表格处理器用于处理与表格相关的数据操作。表格处理器的第一个参数始终是表格ID。同一个模型可以对应多个不同的表格配置。

重要提示：在表格处理器中，before 钩子函数的返回值必须是数组类型。

创建操作处理器 ​

javascript
// 示例：通过表格批量创建记录
Process('yao.table.insert', 'users', [
  { name: '王五', age: 28 },
  { name: '赵六', age: 32 }
]);

  • yao.table.create：创建单条记录

    • 对应：models.<MODEL_ID>.Create
    • 钩子：before:create, after:create

  • yao.table.save：保存单条记录

    • 对应：models.<MODEL_ID>.Save
    • 钩子：before:save, after:save

  • yao.table.insert：批量插入记录

    • 对应：models.<MODEL_ID>.Insert
    • 钩子：before:insert, after:insert

查询操作处理器 ​

javascript
// 示例：表格搜索
const results = Process('yao.table.search', 'users', {
  page: 1,
  pagesize: 20,
  where: [['age', '>', 25]]
});

  • yao.table.find：按主键查询单条记录

    • 对应：models.<MODEL_ID>.Find
    • 钩子：before:find, after:find

  • yao.table.get：按条件查询多条记录

    • 对应：models.<MODEL_ID>.Get
    • 钩子：before:get, after:get

  • yao.table.search：分页查询

    • 对应：models.<MODEL_ID>.Paginate
    • 钩子：before:search, after:search

更新操作处理器 ​

  • yao.table.update：更新单条记录

    • 对应：models.<MODEL_ID>.Update
    • 钩子：before:update, after:update

  • yao.table.updatein：按ID列表批量更新记录

    • 内部调用：models.<MODEL_ID>.UpdateWhere
    • 参数1：主键值（单个或逗号分隔的多个）
    • 钩子：before:update-in, after:update-in

  • yao.table.updatewhere：按条件更新记录

    • 对应：models.<MODEL_ID>.UpdateWhere
    • 钩子：before:update-where, after:update-where

删除操作处理器 ​

  • yao.table.delete：删除单条记录

    • 对应：models.<MODEL_ID>.Delete
    • 钩子：before:delete, after:delete

  • yao.table.deletein：按ID列表批量删除

    • 内部调用：models.<MODEL_ID>.DeleteWhere
    • 钩子：before:delete-in, after:delete-in

  • yao.table.deletewhere：按条件删除记录

    • 对应：models.<MODEL_ID>.DeleteWhere
    • 钩子：before:delete-where, after:delete-where

特殊功能处理器 ​

  • yao.table.setting：读取表格设置

  • yao.table.download：下载文件（注意：文件后缀名有白名单限制）

  • yao.table.export：导出数据到Excel文件

    • 可指定每次读取的数据量
    • 支持按查询条件筛选导出数据

  • yao.table.component：读取XGen组件的实际值

  • yao.table.upload：处理文件上传

  • yao.table.xgen：读取表格的XGen UI配置

配置管理处理器 ​

  • yao.table.load：从文件或源代码加载表格配置
  • yao.table.reload：重新加载表格配置
  • yao.table.unload：从内存中卸载表格配置
  • yao.table.read：读取表格配置
  • yao.table.exists：检查表格配置是否存在

表格API端点 ​

表格对应的RESTful API端点列表：

API路径说明
/api/__yao/table/:id/setting获取表格设置
/api/__yao/table/:id/component/:xpath/:method操作表格组件
/api/__yao/table/:id/upload/:xpath/:method表格文件上传
/api/__yao/table/:id/download/:field表格文件下载
/api/__yao/table/:id/search分页查询
/api/__yao/table/:id/get按条件查询（不分页）
/api/__yao/table/:id/find/:primary按主键查询记录
/api/__yao/table/:id/save保存记录
/api/__yao/table/:id/create创建记录
/api/__yao/table/:id/insert批量插入记录
/api/__yao/table/:id/update/:primary更新单条记录
/api/__yao/table/:id/update/in按ID列表批量更新
/api/__yao/table/:id/update/where按条件更新
/api/__yao/table/:id/delete/:primary删除单条记录
/api/__yao/table/:id/delete/in按ID列表批量删除
/api/__yao/table/:id/delete/where按条件删除

钩子函数的使用 ​

钩子函数是在数据操作前后执行的自定义处理逻辑。Yao提供了两种类型的钩子：

  1. before钩子：在数据操作前执行，可用于数据验证、转换等
  2. after钩子：在数据操作后执行，可用于后处理、触发其他操作等

示例：表单钩子函数 ​

javascript
// 用户表单的before:create钩子
function BeforeCreate(payload) {
  // 处理输入数据
  if (!payload.password) {
    payload.password = '默认密码';
  }

  // 重要：必须返回数组
  return [payload];
}

// 用户表单的after:create钩子
function AfterCreate(id, payload) {
  // 创建后的操作，如发送通知
  Process('scripts.notification.send', id, '用户创建成功');
  return id;
}

钩子函数注意事项 ​

  • before 钩子的返回值必须是数组类型
  • 钩子函数可以通过配置文件中的 hooks 节点进行定义
  • 钩子可用于实现数据验证、权限检查、数据转换等功能

总结 ​

Yao 框架提供了丰富的数据处理能力，通过处理器和钩子机制，可以灵活地实现各种数据操作和业务逻辑。开发者可以根据不同的场景选择适合的处理器，并使用钩子函数扩展自定义功能。