@flow-scanner/lightning-flow-scanner-core

检测不安全的上下文、循环中的查询、硬码的ID,以及更多优化销售力流程

目录

• 默认规则
  • 问题
  • 建议
  • 版式
• 配置
  • 配置规则
  • 定义例外
  • 不包括流量
  • 扫描选项
• 安装
  • 分发量
  • CID 模板
• 快速启动
• 发展

默认规则

📌提示 : 要直接链接到特定规则,请使用完整的 GitHub 锚定链接格式. 示例

https://flow-scanner.github.io/lightning-flow-scanner/#不安全运行-context

想帮助改进这个项目吗? 看我们的 贡献准则

问题

这些规则检测到您的流中的反标和不安全做法,它们可能破坏功能,损害安全,或导致部署失败.

循环中的 DML 语句

在一个循环中执行DML操作(插入,更新,删除)是一种高风险的反模式,经常导致州长限制例外. 所有数据库操作都应在循环之外收集和执行一次.

规则ID: dml-in-loop
类名称 : DML 声明内环
严重性 : 🔴 错误

硬码 Id

避免硬编码记录ID,因为它们是特定类人独有的,在其他环境中不会起作用. 相反,将ID存储在变量中——例如合并域 URL 参数或一个 获取记录 元素——使流动具有便携式、可维护性和灵活性.

规则ID: hardcoded-id
类名称 : 硬码
严重性 : 🔴 错误

硬码保密

避免硬编码密钥,API密钥,令牌,或Flows中的证书. 这些应当安全地存储在命名的证书、自定义设置、自定义元数据或外部秘密管理系统中.

规则ID: hardcoded-secret
类名称 : 硬码加密
严重性 : 🔴 错误

硬码 Url

避免硬编码 URL, 因为它们可能在环境之间或随着时间的推移而变化 。 相反,在变量或自定义设置中存储URL,使"流"具有适应性,可维护性和环境独立性.

规则ID: hardcoded-url
类名称 : 硬码Url
严重性 : 🔴 错误

进程构建器

进程构建器已退役 。 继续使用它会增加维修费,并有未来兼容性问题的风险. 将自动化迁移到流动可减少风险并改进可维护性.

规则ID: process-builder-usage
类名称 : 进程构建器
严重性 : 🔴 错误

SOQL 循环查询

在循环中运行 SOQL 查询可以快速地超过查询限制并严重地降低性能. 查询应执行一次,结果在整个循环中重复使用.

规则ID: soql-in-loop
类名称 : SOQL 查询内部
严重性 : 🔴 错误

不安全运行上下文

配置为在系统模式下运行而无需共享允许访问所有数据的流程,绕过用户权限. 避免这种设置,以防止安全风险并保护敏感数据.

规则ID: unsafe-running-context
类名称 : 不安全运行背景
严重性 : 🔴 错误

复制 DML 操作

当一个"流"通过多屏幕执行数据库操作时,用户向后导航会导致相同的动作多次运行. 为了防止意外变化,要么限制后向导航,要么重新设计流程,从而在单一的向前移动步骤中执行数据库操作.

规则ID: duplicate-dml
类名称 : 复制DML操作
严重性 : 🟡 3⁄4 ̄ ̧漯B

缺少错误路径

可能失败的元素应包括优雅处理错误的故障路径 。 没有它,失败会给用户显示一般错误. 故障路径改善可靠性和用户体验.

规则ID: missing-fault-path
类名称 : 缺少错误
严重性 : 🟡 3⁄4 ̄ ̧漯B

缺少 Null 处理器

在找不到数据时, 获取记录操作返回无效 。 如果不处理这些无效值,流动就可能失败或产生出意料的结果。 添加无效检查可以提高可靠性,并确保流程如预期的那样表现.

规则ID: missing-null-handler
类名称 : 失踪的纽尔·汉德勒
严重性 : 🟡 3⁄4 ̄ ̧漯B

更新后递归

保存后流更新同记录会引发再起,引起出乎意料的行为或性能问题. 避免更新保存后流中的触发记录;取而代之的是使用保存后流防止再起.

规则ID: recursive-record-update
类名称 : 更新后递归
严重性 : 🟡 3⁄4 ̄ ̧漯B

建议

这些规则突出了可以改进流量的领域。 其后可提高可靠性和长期可维护性.

循环中的动作呼叫

反复在循环中援引Apex行为,可以用尽州长的限制并导致业绩问题. 在可能的情况下,通过将动作调用移出循环并传递一个收藏变量来放大你的逻辑.

规则ID: action-call-in-loop
类名称 : 动作呼叫内环
严重性 : 🟡 3⁄4 ̄ ̧漯B

获取全部记录字段

避免使用 Get Record 来取回所有字段, 除非有必要 。 这可以提高性能,减少处理时间,并限制不必要的数据的曝光.

规则ID: get-record-all-fields
类名称 : 获取所有字段
严重性 : 🟡 3⁄4 ̄ ̧漯B

非活动流量

非活性流动应予删除或存档以减少风险。 即使在不活动时,它们也可能在测试中引起出乎意料的记录变化,或者作为分流被激活. 只保持活性,相干流能提高安全性和可维护性.

规则ID: inactive-flow
类名称 : 不活动花
严重性 : 🟡 3⁄4 ̄ ̧漯B

无效的 API 版本

在已过时的API版本上运行的流程在使用更新的平台特性或组件时可能表现不一. 从API版本50.0向上,API版本属性明确控制了流程运行时的行为. 使流量与支持的API版本保持一致有助于防止相容性问题并确保可预测的执行.

规则ID: invalid-api-version
类名称 : APVERSION 计划
严重性 : 🟡 3⁄4 ̄ ̧漯B

缺少过滤记录触发

在已更改的字段上没有过滤器的被记录触发的流程,或者在每个记录更改上执行输入条件. 添加过滤器可确保只在必要时运行,从而提高性能.

规则ID: missing-record-trigger-filter
类名称 : 缺少文件记录
严重性 : 🟡 3⁄4 ̄ ̧漯B

相同的记录字段更新

保存前流能通过$Record直接安全地更新触发记录,高效地应用更改而无需额外的DML操作. 使用保存前更新可提高性能

规则ID: same-record-field-updates
类名称 : 同为记录的字段更新日期
严重性 : 🟡 3⁄4 ̄ ̧漯B

认知复杂性

环绕着深层的循环流动,决策也难以理解. 与计算路径的环形复杂性不同,认知复杂性会惩罚筑巢深度. 考虑将嵌入的逻辑提取出分流.

规则ID: cognitive-complexity
类名称 : 认知复杂性
严重性 : 🔵 说明

过于复杂

大量循环和决定元素增加了"流"的环形复杂性. 为了保持简便和可读性,考虑使用分流或将分流分出为更小的有序流.

规则ID: excessive-cyclomatic-complexity
类名称 : 杂交
严重性 : 🔵 说明

缺少触发顺序

没有指定触发命令的记录触发流可能以不可预测的顺序执行. 设置触发命令可确保您的流量按预定顺序运行 .

规则ID: unspecified-trigger-order
类名称 : 触发命令
严重性 : 🔵 说明

将ID记录为字符串

使用字符串变量进行记录ID而不是接收完整记录的流程会引入不必要的复杂性并增加Get Records查询. 使用完整记录简化了"流"并改进了性能.

规则ID: record-id-as-string
类名称 : 记录
严重性 : 🔵 说明

转换而不是循环

对每个项目进行直接分配的循环元素可以减缓流量. 使用"变形"元素,可以对收藏进行批量操作,提高性能并降低复杂性.

规则ID: transform-instead-of-loop
类名称 : 变换代替循环
严重性 : 🔵 说明

版式

这些规则侧重于命名、文件和组织,确保流程保持清晰、易于理解并随着自动化的发展得以维持.

流程命名公约

使用清晰而一致的流程名称可以提高可读性、可发现性和维护性。 良好的命名会帮助团队成员迅速理解"流"的目的——例如包括一个域和像"Service OrderFulflement"这样的简短描述. 采用符合贵组织标准的命名模式.

规则ID: invalid-naming-convention
类名称 : 流程Name
严重性 : 🔴 错误

缺少流量描述

流程描述对文件编制和可维护性至关重要。 包括每个流量的描述,解释其目的和使用地点.

规则ID: missing-flow-description
类名称 : 流程描述
严重性 : 🔴 错误

缺少元数据描述

没有说明的要素和元数据降低了清晰度和可维护性。 添加描述可以提高可读性,使你的自动化更容易被理解.

规则ID: missing-metadata-description
类名称 : 缺少元数据Description
严重性 : 🟡 3⁄4 ̄ ̧漯B

未知的 API 名称

API 名称不明确或重复的元素, 如 Copy Of Element, 降低可读性 。 复制元素时确保更新 API 名称以保持您的流程组织 .

规则ID: unclear-api-naming
类名称 : 复制APIName
严重性 : 🟡 3⁄4 ̄ ̧漯B

无法获取元素

未连接的元素从不执行并添加不必要的拼接. 删除或连接未使用的流程元素,使流程保持清洁高效.

规则ID: unreachable-element
类名称 : 未连接元素
严重性 : 🟡 3⁄4 ̄ ̧漯B

未使用的变量

未使用的变量永远不会被引用,并添加不必要的拼接. 删除它们,以保持流量的效率和易于维护.

规则ID: unused-variable
类名称 : 无用可变
严重性 : 🟡 3⁄4 ̄ ̧漯B

缺少自动布局

Auto-Layout自动安排并校正了Flow元素,保持了帆布的排列并易于维护. 使其能够节省时间,提高可读性.

规则ID: missing-auto-layout
类名称 : 自动拉尤特
严重性 : 🔵 说明

系统(子类)

系统规则是布局规则的一个子集,它检测出通常被"流程构建器"UI所阻止的结构问题. 见 系统规则文档 完整名单.

配置

建议配置和界定:

• 违反任何具体规则的严重程度.
• 用于规则的表达式,例如REGEX模式和比较操作符.
• 在扫描时应忽略的任何已知例外.
• (可选)根据严重程度实施过滤器 阈值 或者说 规则类别。 。 。 .

大部分分布自 :

• .flow-scanner.yml
• .flow-scanner.json
• package.json → "flowScanner" 键

{
  "rules": {
    // rule customizations (severity, expression, enabled, ...)
  },
  "exceptions": {
    // flow → rule → result suppressions
  },
  "threshold": "error",                    // only consider errors
  "categories": ["problem", "layout"]  // only run rules from these categories
}

配置规则

默认情况下,所有默认规则都会被执行. 您可以自定义单个规则, 并推翻将要执行的规则, 而无需指定每个规则 。 下面是规则配置的现有属性的分解:

{
  "rules": {
    "<RuleId>": {
      "severity": "<Severity>", // Override severity level
      "expression": "<Expression>", // Override rule expression
      "message": "<Message>", // Set custom message
      "messageUrl": "<URL>", // Set custom documentation URL
      "enabled": false, // Disable this rule
    }
  }
}

配置严重性

现有严重性值为: error, (中文(简体) ), warning 财务报告和审定财务报表 note。如果没有提供严重性,则使用默认值。 配置每个规则的重度,如下所示:

{
  "rules": {
    "record-id-as-string": {
      "severity": "warning",
    },
    "unclear-api-naming": {
      "severity": "error",
    }
  }
}

自定义规则

一些规则是可配置的,允许凌驾于它们的默认表达式之上,或者设置一个阈值,如下例所示.

{
  "rules": {
    "invalid-api-version": {
      "expression": "===58" // comparison expression
    },
    "invalid-naming-convention": {
      "expression": "[A-Za-z0-9]" // regular expression
    },
    "excessive-cyclomatic-complexity": {
      "threshold": 10 // threshold
    }
  }
}

自定义规则信件

如果没有提供, message 显示标准规则摘要和 messageUrl 链接到 README; 提供任意一种可以覆盖默认行为.

{
  "rules": {
    "dml-in-loop": {
      "message": "Avoid DML inside loops. Bulkify operations instead.",
      "messageUrl": "https://internal.docs.company.com/salesforce/flow-dml-best-practices"
    }
  }
}

禁用规则

要禁用一条规则, 设置 "enabled": false 如下所示:

{
  "rules": {
    "dml-in-loop": {
      "enabled": false
    }
  }
}

定义例外

界定例外允许您将特定情形排除在规则执行之外。 例外可以在流量,规则或结果级别上指定,以提供精细的控制. 下面是例外配置的现有属性的细分:

{
  "exceptions": {
    "<FlowName>": {
      "<RuleId>": [
        "<ResultName>", // Suppress a result
        "*", // Wildcard to suppress all results
        ...
      ]
    },
    ...
  }
}

示例

{
  "exceptions": {
    "MyFlow": {
      "hardcoded-id": ["Old_Lookup_1"],
      "missing-null-handler": ["*"]
    }
  }
}

不包括流量

由文件路径排除(仅节点.js)

使用 glob 模式来排除基于文件系统位置的流量 。 这对于排除整个目录或特定名称模式有用:

{
  "ignore": [
    "**/testing/**",
    "**/*_Deprecated.flow-meta.xml"
  ]
}

环境相容性:需要Node.js(文件系统访问),在浏览器/web环境中使用Core库时不可用.

由流程 API 名称( 浏览器兼容) 排除

根据其独特的 API 名称排除特定流量,而不论其位置如何. 这对于:

• 排除特定流量而不知道其确切的文件路径
• 使用元数据 API 部署,目录结构可能有所不同
• 比路径模式更精确的控制

{
  "ignoreFlows": [
    "My_Legacy_Flow",
    "Temporary_Test_Flow",
    "Deprecated_Process_Builder"
  ]
}

环境相容性: 在 所有环境 包括Node.js和浏览器/web分布,因为它运行在解析的流数据而不是文件系统路径上.

扫描选项

临界值

仅报告所选严重程度或以上的侵犯行为:

{ "threshold": "error" }

按类别过滤

将扫描限制在规则的特定类别:

{ "categories": ["problem", "layout"] }

Beta 模式

在被添加到默认规则集之前,在Beta模式中引入了新规则. 要包含当前 Beta 规则, 请启用配置中的可选βmode 参数 :

{ "betaMode": true }

规则模式

默认情况下,闪电流扫描器运行 全部 默认规则并合并您提供的任何自定义配置。 换句话说,你想运行 仅限 您明确指定的规则, 使用 :

{ "ruleMode": "isolated" }

安装

分发量

隐私 : 收集零用户数据。 所有处理都是客户端的. → 看我们的 安全政策。 。 。 .

CID 模板

准备使用CI/CD模板.

快速启动

销售力CLI插件

使用 lightning-flow-scanner 在销售力CLI中:

sf flow:scan # Scan flows in the current directory
sf flow:scan --sarif > report.sarif # Export scan results as SARIF
sf flow scan --csv > results.csv # Export scan results as CSV
sf flow doc > flow-docs.md # Generate flow documentation (Single markdown file)
sf flow doc --output flow-docs --separate # Generate one Markdown file per flow
sf flow:fix -d src/force-app # Fix flows in a specific directory

详细情况见 CLI 读取器。 。 。 .

VS 代码扩展

用我们的边栏或 命令调色板 类型 flow scanner 以查看所有可用命令的列表.

• Configure Scanner - 设置规则在 .flow-scanner.yml
• Scan Flows - 分析目录或选定的流程文件
• Fix Flows - 自动应用可用的修正
• Generate Flow Documentation - 生成流程文件
• Open Scanner Documentation - 打开规则参考指南

详细情况见 VSX 读取器。 。 。 .

GitHub 动作

添加 GitHub 工作流程文件 .github/workflows/scan-flows.yml 在拉动请求中直接发现问题:

- name: Lightning Flow Scan
  id: flowscanner
  uses: Flow-Scanner/lightning-flow-scanner@main
  with:
    sarif-only: true  # Strict mode for PRs

- name: Upload SARIF to Code Scanning
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: ${{ steps.flowscanner.outputs.sarifPath }}

详细情况见 动作读取。 。 。 .

核心单元

使用 lightning-flow-scanner-core 作为节点/浏览器依赖:

// Basic
import { parse, scan } from "@flow-scanner/lightning-flow-scanner-core";
parse("flows/*.xml").then(scan);

// Get SARIF output (e.g. for GitHub Code Scanning)
import { parse, scan, exportSarif } from "@flow-scanner/lightning-flow-scanner-core";
parse("flows/**/*.flow-meta.xml").then(scan).then(exportSarif)
  // .then(sarif => fs.writeFile("results.sarif", sarif))

// Generate Markdown documentation with Mermaid flow diagrams
import { parse, exportDiagram } from "@flow-scanner/lightning-flow-scanner-core";
parse("flows/**/*.flow-meta.xml").then(exportDiagram)
  // .then(md => fs.writeFile("flow-docs.md", md))

// Browser Usage (Tooling API)
const { Flow, scan } = window.lightningflowscanner;
const metadataRes = await conn.tooling.query(`SELECT Id, FullName, Metadata FROM Flow`);
const results = scan(
  metadataRes.records.map((r) => ({
    uri: `/services/data/v60.0/tooling/sobjects/Flow/${r.Id}`,
    flow: new Flow(r.FullName, r.Metadata),
  })) //, optionsForScan
);

更多关于程序API、类型和高级使用 @flow-scanner/lightning-flow-scanner-core,参见 核心库。 。 。 .

发展

此项目可选择使用 沃尔塔 为每个贡献者保证完全相同的节点.js和工具版本.

MacOs/ Linux: (英语)

curl https://get.volta.sh | bash

窗口 :

winget install Volta.Volta

Volta 将自动安装和锁定定义的工具版本 package.json。 。 。 .

1. 清除仓库

   git clone https://github.com/Flow-Scanner/lightning-flow-scanner.git
   

2. 安装依赖性 :

   pnpm install
   

3. 编译 :

   pnpm run build
   

   仅仅编译核心软件包:

   pnpm build:core
   

4. 运行测试 :

   pnpm test
   

   或者测试新版本的核心:

   pnpm test:core
   

5. 连接本地核心模块( 可选) :

   要链接模块, 运行 :

   pnpm link --global @flow-scanner/lightning-flow-scanner-core
   

   您现在可以使用节点进行 Ad- Hoc 测试 :

   node -i -e "import('@flow-scanner/lightning-flow-scanner-core').then(m => { Object.assign(global, m.default ? m.default : m); console.log('✅ Core loaded! Try: await parse(...), scan(...), etc.'); })"
   

   或在附属项目中测试 npm link @flow-scanner/lightning-flow-scanner-core

6. 部署人员流动(可选):

   sf project deploy start
   

   导航到 阅读 详细情况

7. 创建独立的 UMD 模块( 可选) :

     pnpm dist
   

   创建 UMD 时 dist/lightning-flow-scanner-core.umd.js。 。 。 .