数据库操作

对 Zion 内置的数据库执行增删改查操作。

更多系统表和字段的信息请参考系统表与系统字段

添加

向指定的数据表中插入一条或多条新数据。

常用场景

• 用户提交表单后，将表单内容保存到数据库中。
• 批量导入多条记录到指定数据表。

参数配置

行为参数配置

其他配置

1. 字段校验配置

用于在添加数据前，校验某个字段的数据是否合法。同一个字段可以添加多个校验条件，只有所有条件都满足，校验才通过，才会真正发起请求。未通过则不发起请求，并进入“失败时”分支，并显示提示信息。

配置方式为：点击“参数”标题旁的“字段校验”，在出现的弹窗中添加需要校验的数据表字段，并为每个字段添加校验条件和提示。

2. 数据冲突处理

若数据表中配置了唯一约束，在添加数据时，如果数据重复，可以通过配置数据冲突处理来决定后续操作。

配置方式为：在“数据冲突处理”参数项选择唯一约束，并选择“处理方式”：

• 忽略并跳过：不添加冲突的那一行数据，其他的正常添加。

• 修改原有数据：用新的数据覆盖冲突的那一行数据。

运行结果与输出

• 行为结果：如果是单条添加，会返回添加的数据；如果是批量添加，会返回添加的数据数组的首位元素（通常是 id 最小的那一条）。
• 成功时：数据成功插入数据库后触发；批量添加时，在所有数据添加成功时触发一次。
• 失败时：数据插入操作被阻断或执行异常时触发。

运行机制

Zion 的“添加”行为用于在数据库中创建新记录。这一动作的流转是一个涉及前端预校验、数据预处理、网络加密传输、后端行级权限审查以及物理事务提交的完整闭环，具体运行机制和端到端全生命周期如下：

1. 前端收集参数：

• 单条添加：当用户触发行为时，前端页面引擎立即收集对应输入组件的值（如输入框的文本、下拉选择的值），组装成一个单独的数据对象。
• 批量添加：读取绑定的数组数据源，遍历数组成员，将每一个元素的字段动态映射为数据表的字段。

2. 执行本地校验：自动检查前端配置的“字段校验规则”。一旦发现任何字段不满足格式规则，前端会立刻终止后续的发送流程，直接宣告行为失败并流转至“失败时”分支，绝不向后端发起无意义的网络请求。

3. 参数预处理：自动处理媒体类型字段的数据绑定，将媒体类型字段的数据绑定转换为媒体文件的 id，并重写参数键名。

4. 组装 GraphQL 报文：参数预处理完毕后，将单条添加组装为 insert_xxx_one 的 GraphQL 树，批量添加组装为 insert_xxx 的对象数组，完整结构见API 结构文档 - 添加数据。

5. 网关身份校验：请求通过 HTTPS 传输至 Zion 服务端的统一网关。网关解析请求 Header 中注入的 JWT 会话令牌，校验当前用户身份，并将解析出的受信任用户属性，作为后续权限控制的合法事实源。

6. 统一事务包裹：

   • 单条添加：后端在单个数据库事务内执行物理 INSERT INTO SQL。
   • 批量添加：其本质是**“前端单请求组装 + 后端事务包裹的循环添加”**。后端在最外层开启一个统一的 PostgreSQL 事务，按序循环为每一个数组元素生成并执行独立的 INSERT INTO SQL，并处理好表级级联关系，确保“同生共死”。
   ⚠️

   因为批量添加在数据库底层需要为每一个数组成员循环生成独立的 SQL 并维护事务边界，在面对超大规模数据时极易带来长事务锁表和连接池占满的系统级风险。因此，前端引擎在组装批量请求时，限制了单次批量添加的最大数据量为 1000 条。若超出限制，只保留前 1000 条数据继续执行，超出的部分会被自动丢弃。

7. 权限和数据冲突审查：

   • 数据写入磁盘前，物理数据库引擎会自动检查表级权限、行级权限。
   • 数据冲突处理：如果插入的数据与已有记录在唯一字段上发生冲突，若处理方式设为 “忽略并跳过”，数据库会静默忽略该冲突行不予添加，继续执行其他非冲突行的插入；若处理方式设为 “修改原有数据”，则会触发 Upsert 机制，将已有冲突行的数据覆盖更新为新传入的值。

8. 提交与回滚：

   • 全员成功：若所有单条/批量添加动作全部顺利执行完毕且通过校验，后端正式提交事务并回传出参。前端页面引擎在获得回执后触发行为流的 “成功时” 分支。
   • 任意失败触发回滚：若添加动作中任意一步触发了报错（如唯一性冲突未配置处理方式、敏感内容违反了微信安全检测、必填项缺失、外键 id 不存在等），数据库会强行回滚整个事务。前端接收到异常回执后，直接流转到行为的 “失败时” 分支。

常见错误

发生以下错误时，均会进入失败时分支：

1. 参数校验未通过：前端本地的基础规则校验未满足或未通过微信内容安全检查。
2. 数据冲突（违反唯一约束）：插入的数据与已有数据重复，且未配置数据冲突处理。
3. 权限不足：当前用户的角色没有该表的添加权限，或者提交的数据违反了权限设置。
4. 数据库约束报错：必填字段缺失导致后端落盘失败，或绑定的关联表 id（外键）在数据库中并不存在。
5. 网络或服务异常：用户设备断网、请求发送超时，或后端服务器内部处理故障（500 错误）。

用法举例

修改

修改指定数据表中符合条件的一条或多条现有数据。

常用场景

• 用户在个人中心修改自己的个人资料。
• 更改订单的状态 (如从待支付修改为已支付)。

参数配置

运行结果与输出

• 结果：对多行操作均仅返回第一条记录。若需在后续步骤中引用，可在参数绑定中选择 行为结果 -> [当前操作的名称] -> id。
• 成功时：数据成功修改后触发，可配置刷新数据源或显示提示。
• 失败时：数据修改失败 (如参数校验未通过、无符合条件的数据) 时触发，可配置错误提示。

运行机制

Zion 的“修改”行为用于更新数据库中符合特定筛选条件的一条或多条现有数据。其流转生命周期具体运行机制如下：

1. 前端收集筛选条件与更新参数：

• 选择数据筛选：如果配置了多个「数据筛选」条件，前端引擎会自上而下顺次对各个筛选进行条件检验：
  • 首个命中即停：一旦发现某个筛选条件成立，系统会立即锁定并选取该分支下的筛选参数，同时完全忽略后面配置的所有筛选。如果所有筛选条件都不成立，则采用Default筛选。
  • 最终装配：最终只会将这个唯一的筛选条件编译入 GraphQL 请求中。

2. 执行字段校验：自动检查前端配置的「字段校验」规则。一旦发现任何修改的数据不满足规则，前端会立刻终止后续的发送流程，直接宣告行为失败并流转至“失败时”分支。

3. 参数预处理：自动处理媒体类型字段的数据绑定，将绑定的媒体对象转换为媒体中心的唯一 id，并重写参数键名为 [字段名]_id（长整型外键）。

4. 组装 GraphQL 报文：将筛选条件转换为 GraphQL 的 where 条件对象，设值或原子增减数值转换装载至 _set 或者是 _inc 中，具体格式请参考 API 结构文档 - 修改数据。

5. 网关身份校验：请求通过 HTTPS 传输至网关。网关解析 JWT 会话令牌，校验当前用户身份，并将解析出的受信任用户属性作为安全会话上下文下发给后端。

6. 统一事务包裹：后端将 GraphQL 变更为对应 PostgreSQL 的原子扣减/覆盖 SQL，在同一个数据库事务隔离边界内顺序执行。针对库存累减，物理 SQL 如下：

   UPDATE "goods" SET "stock" = "stock" + $1 WHERE "id" = $2 AND "stock" >= $3;

   由于更新在事务内是串行排他的，能从底层完美解决并发和脏读问题。

7. 权限和数据冲突审查：

   • 数据写入磁盘前，会检查权限规则。即使恶意用户通过抓包删去了前端行为中的数据筛选条件（如删去了 库存数 >= 购买数量 绕过校验），后端依旧会强制在 SQL 层面拼入权限限制（如 AND "stock" >= 0）。
   • 数据冲突处理：如果修改后的数据与已有记录在唯一字段上发生冲突，则直接终止并抛出错误。

8. 提交与回滚：

   • 成功：行数发生变更，提交事务，数据永久生效，前端流向行为的 “成功时” 分支。
   • 失败：触发了权限拦截、数据冲突导致报错。事务自动回退，前端流向行为的 “失败时” 分支。

常见错误

• 参数校验失败：修改的数据不符合在参数校验中配置的规则，导致修改被拒绝。
• 筛选条件错误：数据筛选条件配置不当，导致未匹配到任何数据或错误地修改了其他数据。

用法举例

删除

从指定的数据表中移除符合条件的一条或多条数据。

常用场景

• 用户在购物车列表中移除某件商品。
• 管理员在后台管理系统中删除违规的评论。

参数配置

运行结果与输出

• 结果：对多行操作均仅返回第一条记录。若需在后续步骤中引用，可在参数绑定中选择 行为结果 -> [当前操作的名称] -> id。
• 成功时：数据成功删除后触发。
• 失败时：删除失败（如无删除权限）时触发。

运行机制

Zion 的“删除”行为用于从指定数据表中永久移除符合条件的一条或多条数据。其流转生命周期具体运行机制如下：

1. 前端收集筛选条件：

• 选择数据筛选：如果配置了多个「数据筛选」条件，前端引擎会自上而下顺次对各个筛选进行条件检验：
• 首个命中即停：一旦发现某个筛选条件成立，系统会立即锁定并选取该分支下的筛选参数，同时完全忽略后面配置的所有筛选。如果所有筛选条件都不成立，则采用Default筛选。
• 最终装配：最终只会将这个唯一的筛选条件编译入 GraphQL 请求中。

2. 执行字段校验：无参数需要校验。

3. 参数预处理：由于不进行数据写入，因此无多媒体等数据类型降维等预处理。

4. 组装 GraphQL 报文：将获取到的参数组装成带有 where 过滤参数的标准 delete_xxx 格式的 GraphQL 报文，具体格式请参考 API 结构文档 - 删除数据。

5. 网关身份校验：请求通过 HTTPS 传输至网关。网关解析 JWT 会话令牌，建立包含当前用户的受信任会话上下文下发给后端。

6. 统一事务包裹：请求由后端接收，后端在编译 SQL 前会静默注入权限系统的 RLS 行级安全限制条件。

7. 行级权限与物理约束审查：

   • 后端将where 条件直接翻译编译为原生的 SQL 并在数据库执行：

     DELETE FROM "order" WHERE "id" = $1 AND "user_id" = $2;

   • 数据库引擎尝试物理删除。与其建立关联的其他表中引用该数据的字段，默认会被自动置空（设为 NULL）。

8. 提交与回滚：

   • 成功：物理删除成功，数据库提交事务，前端接收回执并流向行为的 “成功时” 分支，刷新数据源。
   • 失败：权限拦截失败。事务自动回滚，流向行为的 “失败时” 分支。

常见错误

• 筛选条件缺失：未配置数据筛选条件，导致误删全表数据。
• 关联数据限制：尝试删除的数据被其他表的外键关联，导致数据库拒绝删除请求。

用法举例

事务处理

将多个数据库变更操作 (添加、修改、删除) 打包执行，确保按照配置的顺序执行，确保事务性（要么全部成功，要么全部失败并自动撤销并恢复原状）。

常用场景

• 提交包含主表和子表数据的复杂表单 (如同时添加订单和订单明细)。
• 资金转账场景，同时扣减 A 账户余额并增加 B 账户余额。

参数配置

运行结果与输出

• 结果：无
• 成功时：事务内所有行为均执行成功后触发。
• 失败时：事务内任意一个行为执行失败时触发，所有已执行的变更将被自动撤销并恢复原状。

运行机制

Zion 的“事务处理”行为用于在单个请求中以原子事务的方式批量执行多个数据库写操作（添加、修改、删除）。其流转生命周期具体运行机制如下：

1. 前端链式收集参数

• 顺序收集：前端页面引擎按顺序收集事务行为列表中配置的每一个行为的设值与筛选条件。
• 子回调隐藏：为保障事务整体的强原子性，子动作的成功/失败事件被强制隐藏且禁用。只暴露事务整体的成功或失败时。因此事务内的行为不支持引用前一步的执行结果（如修改商品库存去引用前一步添加订单生成的动态 订单id）。

2. 执行字段校验：依次对列表内的所有子行为执行基础规则本地校验，任一不通过则整体拦截并触发整体事务的“失败时”。

3. 参数预处理：自动处理媒体类型字段的数据绑定，将绑定的媒体对象转换为媒体中心的唯一 id，并重写参数键名为 [字段名]_id（长整型外键）。

4. 组装 GraphQL 报文：页面引擎将所有添加、修改或删除子行为统一拼接在同一个请求中发出，具体格式请参考 API 结构文档 - 事务处理。

5. 网关身份校验：请求通过 HTTPS 传输至网关。网关解析 JWT 验证当前用户身份，并构建受信任的安全会话上下文流转至后端服务器。

6. 统一事务包裹：Zion 后端接收请求时，会立刻为当前 HTTP 请求开启一个 PostgreSQL 级别的 物理事务隔离边界，多个子别名操作会在物理事务内被后端按严格配置的先后顺序同步顺序执行。

7. 行级权限与物理约束审查：数据库顺序执行 SQL，任何一步触发异常都会被拦截器捕捉，并强制数据库执行整体回滚。

8. 提交与回滚：

   • 成功：若所有配置的操作全部无报错且成功执行，后端提交整个物理数据库事务，数据永久生效，触发顶层 “成功时” 回调。
   • 失败：执行序列中只要有任意一步触发了异常，后端拦截器立即自动发出回滚命令，撤销全部修改，并流转至事务整体的 “失败时” 回调。

常见错误

• 包含不支持的行为：在事务行为列表中添加了非数据库变更行为 (如跳转页面、网络请求)，导致事务配置无效。
• 单步行为失败导致整体回滚：事务内某个修改操作因筛选条件未匹配到数据或参数校验失败，导致整个事务被自动撤销并恢复原状。

用法举例