Automatisch 内置 Filter 应用指南基于条件分流自动化流程的完整实现与原理【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch导读Filter 是 Automatisch 内置的一个零连接应用它不需要连接任何外部服务即可作为流程中的 Action 使用其核心作用是根据设定的条件判断当前流程是否继续向下执行从而实现数据分流、条件校验与流程熔断。本文将围绕 Automatisch 中 Filter 应用的条件体系、AND/OR 组合逻辑、底层早退Early Exit机制展开并结合仓库源码与端到端测试用例帮助你彻底掌握如何用它搭建带条件分支的自动化流程。一、Filter随 Automatisch 内置、无需任何配置的应用在 Automatisch 的 Filter 应用官方文档 中第一句就点明了它的本质Filter is a built-in app shipped with Automatisch, and it doesnt need to talk with any other external service to run. So there are no additional steps to use the Filter app.这意味着Filter 是 Automatisch 出厂自带的内置应用无需像 GitHub、Slack 那样进行 OAuth 授权它不依赖任何外部服务运行时不发起任何网络请求没有额外的接入步骤——在流程编辑器里选中 Filter 应用即可直接使用。这一点在源码中得到了直接印证。查看 Filter 的应用定义 packages/backend/src/apps/filter/index.jsimport defineApp from ../../helpers/define-app.js; import actions from ./actions/index.js; export default defineApp({ name: Filter, key: filter, iconUrl: {BASE_URL}/apps/filter/assets/favicon.svg, authDocUrl: {DOCS_URL}/apps/filter/connection, supportsConnections: false, baseUrl: , apiBaseUrl: , primaryColor: #001F52, actions, });关键配置一目了然配置项值含义keyfilter应用唯一标识在步骤数据与测试中被引用supportsConnectionsfalse不支持连接即无需任何凭据/授权即可使用baseUrl/apiBaseUrl空字符串不调用任何外部 APIauthDocUrl{DOCS_URL}/apps/filter/connection指向本文所依据的官方说明文档其中supportsConnections: false正是零配置可用这一特性的实现根源Automatisch 在构建流程上下文时会对内置应用走特殊路径Filter 因此可以无缝出现在任意流程中。二、Filter 的定位作为 Action 使用只做继续或终止的判断Filter 只有一个 Action即Continue if conditions match条件匹配则继续。这一点在 packages/backend/src/apps/filter/actions/index.js 中可以看到import continueIfMatches from ./continue/index.js; export default [continueIfMatches];而该 Action 的定义与实现位于 packages/backend/src/apps/filter/actions/continue/index.jsexport default defineAction({ name: Continue if conditions match, key: continueIfMatches, description: Let the execution continue if the conditions match, arguments: [], async run($) { const orGroups $.step.parameters.or; // ...条件判定逻辑 if (!shouldContinue(orGroups)) { $.execution.exit(); } $.setActionItem({ raw: { or: matchingGroups }, }); }, });两个核心信息arguments: []——该 Action 没有预声明的参数所有条件完全由用户在流程编辑器中动态配置对应前端的动态条件表单运行时逻辑——条件不匹配时调用$.execution.exit()终止流程匹配时则通过$.setActionItem输出命中的条件数据。也就是说Filter 在流程中扮演的角色是条件闸门放在两个步骤之间前一步的结果是否符合预期、后续步骤是否值得继续执行都由它把关。三、八大条件运算符从源码看精确语义官方文档列出 Filter 支持的 8 种可用条件conditionsis equal等于is not equal不等于is greater than大于is less than小于is greater than or equal大于等于is less than or equal小于等于contains包含does not contain不包含对应到源码 packages/backend/src/apps/filter/actions/continue/index.js 中每一个运算符都有精确的底层实现const isEqual (a, b) a b; const isNotEqual (a, b) !isEqual(a, b); const isGreaterThan (a, b) Number(a) Number(b); const isLessThan (a, b) Number(a) Number(b); const isGreaterThanOrEqual (a, b) Number(a) Number(b); const isLessThanOrEqual (a, b) Number(a) Number(b); const contains (a, b) a.includes(b); const doesNotContain (a, b) !contains(a, b); const operators { equal: isEqual, not_equal: isNotEqual, greater_than: isGreaterThan, less_than: isLessThan, greater_than_or_equal: isGreaterThanOrEqual, less_than_or_equal: isLessThanOrEqual, contains: contains, not_contains: doesNotContain, };这里有几个值得注意的实现细节直接决定了你在配置条件时的行为预期比较大小类运算符大于/小于/大于等于/小于等于底层通过Number(a)与Number(b)做数值转换后比较。因此它们更适合作用于数值型字段若字段值无法被转换为数值例如非数字字符串Number()会得到NaN所有大小比较都会返回false。等于/不等于使用严格相等比较类型不同如字符串1与数字1视为不相等。包含/不包含基于 JavaScript 字符串的includes实现属于子串匹配substring match而非单词边界或正则匹配。例如Automatisch包含auto忽略大小写之外的含义请自行注意匹配本身区分大小写。运算符的内部标识equal、not_equal、greater_than等与前端下拉框选项的value一一对应这也是条件配置数据从 UI 到引擎的契约。四、条件组合逻辑AND 组与 OR 组单一条件显然不够用Filter 支持多条件任意组合。它的数据模型是parameters.or [ { and: [条件1, 条件2, ...] }, // OR 组 A { and: [条件3, 条件4, ...] }, // OR 组 B ... ]即多个OR 组之间是或的关系每个 OR 组内部的多个条件是AND且的关系。判定流程见源码中的shouldContinueconst shouldContinue (orGroups) { let atLeastOneGroupMatches false; for (const group of orGroups) { let groupMatches true; for (const condition of group.and) { const conditionMatches operate( condition.operator, condition.key, condition.value ); if (!conditionMatches) { groupMatches false; break; } } if (groupMatches) { atLeastOneGroupMatches true; break; } } return atLeastOneGroupMatches; };翻译成白话任一 OR 组内的全部条件都满足 → 该组命中只要有任意一个 OR 组命中→ 整个 Filter 判定通过流程继续所有 OR 组都未命中 → 流程终止。这套组合逻辑在前端表单 packages/web/src/components/FlowSubstep/FilterConditions/index.jsx 中有着直观的对应第一组条件标题显示为Only continue if…仅当满足以下条件时继续新增的分组则显示OR continue if…或满足以下条件时继续文案定义在 packages/web/src/locales/en.jsonfilterConditions.onlyContinueIf: Only continue if…, filterConditions.orContinueIf: OR continue if…,同时 UI 为每个条件提供三要素Choose field选择字段——要判断的数据来源通常填写上一步输出的变量引用如{{step.1234567890.query.key}}Choose condition选择条件——从上述 8 种运算符下拉选择Enter text输入值——用于比较的目标值。每行条件右侧有删除按钮底部有And和Or两个添加按钮分别用于在当前组内追加 AND 条件、新增一个 OR 组。五、条件不匹配时到底发生了什么——早退Early Exit机制解析这是 Filter 最值得深入理解的部分。当条件不匹配时源码调用的是$.execution.exit();而$.execution.exit()的实现位于 packages/backend/src/engine/global-variable.jsexecution: { id: execution?.id, testRun, exit: () { throw new EarlyExitError(); }, },它会抛出一个EarlyExitError该错误类型定义于 packages/backend/src/errors/early-exit.jsimport BaseError from /errors/base.js; export default class EarlyExitError extends BaseError {}关键点在于早退不是执行失败。在 Action 处理管线 packages/backend/src/engine/action/process.js 中EarlyExitError被显式地从错误中豁免try { await command.run($); } catch (error) { const shouldEarlyExit error instanceof EarlyExitError; const shouldNotProcess error instanceof AlreadyProcessedError; const shouldNotConsiderAsError shouldEarlyExit || shouldNotProcess; if (!shouldNotConsiderAsError) { // 只有真正的错误才会写入 $.actionOutput.error } } const executionStep await execution .$relatedQuery(executionSteps) .insertAndFetch({ stepId: $.step.id, status: $.actionOutput.error ? failure : success, dataIn: computedParameters, dataOut: $.actionOutput.error ? null : $.actionOutput.data?.raw, errorDetails: $.actionOutput.error ? $.actionOutput.error : null, });由此可以得到两个重要事实Filter 步骤本身仍记录为success即使条件不匹配不会触发失败告警条件不匹配时dataOut为null因为setActionItem没有被执行后续步骤不会收到该 Action 的输出并且整个流程在这一步之后被短路——EarlyExitError向上抛出让引擎停止继续迭代后续步骤。这也解释了为什么在流程执行详情页中条件未命中的 Filter 步骤会显示为绿色成功状态但后续步骤完全缺失——这正是设计上期望的分流行为。六、端到端验证测试用例里的 Filter 真实行为仓库中内置了 Filter 的完整端到端测试最典型的位于 packages/backend/src/engine/tests/built-in-webhook-sync/execution-with-filter.test.js另有一个异步 webhook 版本 packages/backend/src/engine/tests/built-in-webhook-async/execution-with-filter.test.js。测试流程构造了一个四步流水线webhook 触发器同步模式Filter 步骤key: continueIfMatches条件是{{step.xxx.query.key}}取请求 query 中的key参数equal值为Aformatter 步骤将query.name做首字母大写转换webhook respondWith 步骤返回指定状态码与响应体。其验证结论非常直观条件命中时请求?nameautomatischkeyA生成 4 个执行步骤Filter 的dataIn显示比较双方key: A与value: A后续 formatter 正常输出Automatischwebhook 正常返回 422 与定制响应体条件未命中时请求?nameautomatischkeyB只生成 2 个执行步骤触发器 FilterFilter 的dataOut为nullformatter 与 respondWith均未执行。这段测试代码从执行结果层面完整复现了本文第四节、第五节描述的行为Filter 作为闸门命中放行、未命中短路。如果你在实现类似流程时怀疑自己的条件配置是否正确可以参考该测试中parameters.or的 JSON 结构来对照你自己的步骤参数。七、实战建议Filter 的典型应用场景基于以上机制Filter 在 Automatisch 流程中的典型用法包括数据合法性校验在收到 webhook 后先用 Filter 校验query、body中的关键字段是否符合预期如状态值、类型标记不合法则直接短路避免后续步骤处理脏数据。关键值分流例如当订单金额 ≥ 1000 时走 VIP 处理流程——用greater_than_or_equal判断金额字段配合 AND/OR 组合处理多条件场景。内容筛选用contains/does not contain判断文本字段是否包含特定关键词常用于邮件主题、评论内容的初步过滤。避免重复或无效处理将 Filter 放在耗时或会产生副作用的 Action如发邮件、调外部 API之前从源头减少无效调用。需要提醒的几点限制源自源码行为大小比较运算符基于Number()转换请确保比较字段与目标值可被数值化contains是区分大小写的子串匹配Filter 属于全有或全无式闸门它只有continue一个 Action不支持不匹配时走另一个分支。如果需要真·多分支需要组合多个 Filter 步骤或改用其他内置应用来构造等价逻辑每个 OR 组内的多个 AND 条件为严格且关系任何一个不满足即整组失效。结语Filter 虽然是一个轻量级内置应用但它在 Automatisch 流程编排中承担着举足轻重的条件闸门角色。通过本文你不仅掌握了官方文档列出的 8 种条件运算符还从 应用定义、Action 实现、早退错误类型 与 引擎处理管线 等源码层面理解了条件匹配才继续、不匹配即短路的完整闭环更有 端到端测试 作为行为背书。无论是做数据校验、关键值分流还是内容筛选Filter 都能以最低的成本为你的自动化流程加上一重可靠的判断力。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考