功能最佳实践

Prev Next

Who can use Functions

As of r380, Functions is generally available.

Read more in the Community thread.


使用 Functions 向表中写入数据

推荐方法

当多个应用或应用步骤向同一表写入数据,且需要强制执行以下要求时,请创建函数:

  • 必填字段
  • 有效值(例如,状态必须来自已批准的列表)
  • 一致的元数据(创建者、创建时间)

为何这很重要

当公民开发者直接在触发器中创建表记录时,可能会:

  • 未遵循ID命名规范
  • 遗漏必填字段
  • 字段值拼写错误(例如“in progress”与“in-progress”)
  • 元数据填写不一致

函数可强制执行统一的模式,从而防止这些错误。

示例

与其让每个应用程序开发人员创建字段和内容不一致的“样本”记录,不如创建一个**“创建样本**”函数,该函数应:

  • 要求输入内容保持一致(任务 ID、样本类型、数量、时间戳、用户、应用名称)
  • 验证样本类型是否来自已批准列表

函数:CreateSample 输入参数: - job_id(文本) - sample_type(文本) - quantity(数字) - app name(文本) - user requesting(用户)

逻辑:1. 验证 sample_type 是否在 ["A", "B", "C"] 之中2. 若无效,返回错误信息3. 创建表记录,包含: - ID:在函数内生成 - 任务 ID:输入值 - 样本类型:输入值 - 数量:输入值 - 批号:输入值(若未提供则为空) - 创建者:输入值4. 返回成功消息

输出: - 状态(文本):"success" 或 "error" - 消息(文本):失败时的错误描述

当需要为一个样本创建表记录时,将输入参数传递给函数,剩下的由函数处理。

应避免的模式

不要为每次表写入操作(即使是简单的操作)都创建一个函数。

为何这会引发问题

  • 会导致函数泛滥(数百个仅用一次的函数)
  • 在简单的写入操作中增加了复杂性却无实际收益
  • 使调试更加困难(需要检查的位置更多)

何时应避免为表写入操作使用函数

  • 更新现有表中的记录(例如,更新状态或减少数量)
  • 单个应用程序对表的写入操作
  • 无需治理或验证

将函数用于重复性的多步骤逻辑

推荐做法

如果同一系列触发操作在多个应用的多个步骤中反复出现,请将其提取到函数中。

示例:获取用于打印标签的 ZPL 代码

函数:获取 ZPL代码 输入: - 物料 ID(文本)

变量: - ZPL 代码变量(文本)

输出: - ZPL 代码(文本)

逻辑:1. 更新数据:配置“ZPL 代码变量”——设置为——[包含 @Inputs.Material ID 的 ZPL 代码表达式]2. 返回:“ZPL 代码”数据源“ZPL 代码变量”

应避免的模式

请勿为在所有应用程序中总共仅出现 1-2 次的逻辑创建函数。

为何会导致问题

  • 管理该函数的开销超过了其带来的收益
  • 迫使应用程序开发人员为极少出现的场景学习函数接口
  • 由于需要在函数和应用之间切换,导致调试难度增加

将连接器函数嵌入到函数中

推荐方法

使用连接器函数时,请将连接器函数的输入传递给调用该连接器函数的函数。这样,该函数就能以更简便、更集中化的方式处理超时重试和错误处理,从而简化整个解决方案中的应用逻辑。

将连接器函数嵌入到函数中,还能通过减少对各个应用程序所需的修改量,从而最大限度地降低未来可能进行的 ERP 迁移工作量。

示例

函数:更新生产订单输入: - 订单 ID(文本) - 状态(文本)

输出: - 错误消息(文本)

变量: - HTTP 状态码(整数) - 超时重试次数(整数) - 错误消息(文本)

逻辑:1. 运行连接器函数 2. 如果 HTTP 代码表示成功,则结束函数 3. 如果 HTTP 状态码表示超时,且“超时重试次数”小于或等于指定值,则将“超时重试次数”递增,并返回“运行连接器函数”步骤4. 如果 HTTP 状态码是函数逻辑无法解析的代码,则在“错误消息”输出中返回一条有用的提示信息

传递记录 ID,而非单个表记录字段

推荐方法

当函数需要表记录中的数据时,应传递记录 ID,并在函数内部加载该记录。

示例

虽然以下示例在逻辑上是正确的(其中“订单 ID”是来自 Orders 表的 ID,其他字段是该表中的列),但还有一种更简单的配置方法。

函数:处理订单 输入: - 订单 ID(文本) - 客户名称(文本) - 产品 ID(文本) - 数量(数字) - 到期日期(日期时间) - 优先级(文本)

逻辑:1. [使用输入字段执行逻辑]

下面的示例使用最少的输入字段就实现了相同的结果:

函数:处理订单输入: - 订单 ID(文本)

逻辑:1. 获取表记录:Orders 表中 ID = '订单 ID' 的记录2. [使用表记录字段执行逻辑]

为什么第二个示例是更好的方法:

  • 输入项更少(仅需1个,而非6个以上)
  • 若表结构发生变化,函数可轻松适应
  • 应用程序中的函数调用更简洁
  • 降低了将错误字段映射到错误输入的概率

以统一的方式命名并描述函数和输入

推荐做法

在工作区中的所有函数中使用统一的命名约定。

函数名称

  • 使用动词 + 名词:创建样本、更新作业状态、验证序列号
  • 不要仅使用名词:样本、作业、序列号

函数描述

  • 编写直观的描述,说明该函数的功能。例如,对于名为“Create Defect”的函数,应编写如下描述:“在 Defects 表中创建一条状态为 OPEN 的新记录”。

输入名称

  • 使用统一术语:始终使用“工单 ID”(不要有时用“订单 ID”或“Work_id”)
  • 尽可能与表字段名称保持一致

逻辑块名称

  • 表述要明确:“获取工单记录”,而非“获取表记录”
  • 为未来的读者提供帮助:“验证样本类型”,而非“检查值”

为何这很重要

  • 应用程序开发人员能快速理解函数的用途
  • 在使用多个函数时减轻认知负荷
  • 使“使用位置”分析更轻松
  • 改善文档和培训

无缝处理输入验证和用户错误提示

推荐做法

始终将函数输入标记为必填字段,并在适当情况下使用输入验证规则。请勿在函数内部进行输入验证。

为何这很重要

  • 应用用户在输入值时能获得清晰的反馈
  • 通过让应用程序处理输入验证,并确保函数仅在接收已知有效输入时运行,从而简化函数逻辑
  • 防止因错误输入导致数据损坏

应避免的模式

切勿在函数内部进行输入验证。

为何这会引发问题

  • 这与应用编辑器中已有的输入验证功能存在重复
  • 在函数内部重新检查输入有效性会造成额外的、不必要的延迟
NOTE

App builders can bypass the system by passing blank static values in function inputs. For functions where validated data is critical, it may be best practice to validate inputs in the function itself (in addition to marking required fields in the app).

尽量减少循环内的表查询

如果函数需要遍历数组,请避免在每次迭代时查询表。相反,应在循环开始前查询一次,并引用该结果。

将函数用于逻辑处理,而非简单的数据引用

请勿创建仅用于检索单条表记录的函数——这正是record placeholders 的作用。请将函数保留给用于转换数据的逻辑处理。

限制输出大小

如果函数返回大型对象或数组,请考虑仅返回应用程序所需的字段,而非整个对象数组。


其他资源