后端程序流脚本节点

后端程序流脚本节点运行在服务器端，用于在程序流中调用 .action.ts 或 hooks.action.ts 中的自定义脚本函数。它适合处理内置节点不方便表达的服务端业务逻辑，例如复杂校验、访问数据库、调用服务端 API、读写文件，或把一段可复用逻辑封装成程序流节点。

如果脚本只处理浏览器页面内的组件状态、用户事件或页面上下文，优先使用前端程序流脚本节点。

写在哪里

按复用范围选择脚本位置：只给一个资源使用，写在资源同目录的同名 .action.ts；应用或项目内多个资源复用，写到对应层级的 hooks.action.ts；多个项目复用时，再考虑系统级脚本。具体路径和作用范围见脚本文件组织。

编写脚本函数

后端程序流脚本函数使用 action_ 作为函数名前缀。系统会从脚本中识别 action_ 开头的函数，并在程序流执行后端脚本节点的函数选择项中列出。

export function action_buildAuditMessage(
  args: { orderNo: string; amount: number },
  ctx: any
): string {
  if (!args.orderNo) {
    throw new Error('订单号不能为空');
  }

  const level = args.amount >= 100000 ? '大额订单' : '普通订单';
  return `${level}：${args.orderNo}`;
}

写法要求：

1. 函数名以 action_ 开头。
2. 建议使用 export 导出函数，便于设计器解析函数并在节点配置中选择。
3. 第一个参数使用对象接收节点参数，属性名和节点上配置的参数名一致。
4. 第二个参数是程序流节点运行上下文。需要使用上下文能力时，先查看当前版本的类型声明。
5. 函数返回值会作为当前脚本节点的执行结果，可在后续节点中通过该节点的 $result 输出变量继续使用。

配置节点

在程序流设计器中添加执行后端脚本节点后，按下面方式配置：

1. 选择脚本文件，例如页面同名 .action.ts、应用级 hooks.action.ts 或项目级 hooks.action.ts。
2. 选择执行函数。节点会从脚本文件中列出 action_ 开头的函数。
3. 设置参数。参数值可以写常量，也可以写表达式引用程序流参数、模型字段或前序节点结果。
4. 设置输出变量。需要给后续节点使用返回值时，在节点输出变量中保存 $result。

如果直接编辑元数据，executeActionScript.method 按后端脚本导出的函数名填写，例如 action_buildAuditMessage。

例如节点参数配置为：

参数名	参数值
orderNo	params.orderNo
amount	[订单].[金额]

脚本函数会收到：

{
  orderNo: 'SO-20260628-001',
  amount: 128000
}

参数名应保持稳定。已经被程序流节点引用的参数，不要随意改名；确需调整时，同步修改节点参数配置和后续引用。

返回值和异常

脚本函数可以返回字符串、数值、布尔值、对象或数组。返回值会进入当前脚本节点的 $result，后续节点可以用表达式读取。

export function action_createResult(args: { success: boolean; message: string }, ctx: any) {
  return {
    success: args.success,
    message: args.message,
    time: new Date()
  };
}

如果函数没有返回值，$result 为空。需要让后续分支根据执行结果判断时，建议显式返回状态对象，而不是只依赖异常。

export function action_validateAmount(args: { amount: number }, ctx: any) {
  if (args.amount == null || args.amount <= 0) {
    return { success: false, message: '金额必须大于 0' };
  }
  return { success: true };
}

脚本函数中抛出的异常会导致脚本节点执行失败。需要给用户明确提示时，在错误信息中写清可处理原因，例如缺少参数、权限不足、外部接口不可用等。

事务和权限

后端脚本节点在服务器端执行，适合处理需要可信执行的业务逻辑。读取或修改数据时，应优先使用后端脚本 API，并让程序流统一控制权限、错误分支和提交结果。

如果脚本通过程序流上下文取得连接对象，不要在脚本中自行提交事务；程序流会在流程结束时统一处理提交或回滚。确实需要脱离程序流事务时，应使用独立连接并自行控制提交、关闭和异常处理。

相关类型

需要核对字段或运行环境时，可查看以下类型声明：

• 程序流执行脚本概念：types/internal/succ.concepts.d.ts
• 执行后端脚本节点元数据：types/meta/actionComponent/executeActionScript.d.ts
• 后端程序流脚本类型：svr-api/types/actionflow.types.d.ts

更多程序流节点结构见 .afl 程序流元数据。