企业官网建设流程全解析

• 示例工程
• 数据库
• 教程
• 后端

SQL Assessment API 通过"规则（Rule）→ 检查（Check）→ 探针（Probe）"的层次化模型完成最佳实践评估，而探针引用（Probe Reference）正是将"检查需要什么数据"与"探针如何取数"衔接起来的核心桥梁。本文以 ProbeReference.md 为骨架，结合同目录下的 RulesandProbes.md、Probe.md、DataTransformation.md 等配套文档，完整讲解探针引用的四种属性（alias、id、params、transform）、同探针多次调用、探针间数据传递两大核心编排场景，以及表达式与数据变换的底层规则。读完本文，你将能够独立编写自定义规则集中的探针引用，实现多探针联动评估。

背景：检查的数据从何而来

在深入探针引用之前，先明确它在整个评估流程中的位置。SQL Assessment API 使用"最佳实践建议集"检查 SQL Server 环境是否可优化，其实现是两步过程（详见 RulesandProbes.md）：

1. 为给定目标构建检查清单（checklist）：清单包含完整的一组检查，取决于目标（目标可以是服务器、数据库等，通过目标模式target/targetFilter匹配 SQL Server 版本、版本类型、平台等）；
2. 逐项遍历清单并报告最佳实践违规项：引擎检查目标是否满足每一条最佳实践，不满足时按消息模板输出建议。

每个检查（Check）本身不直接向目标服务器或数据库取数，而是引用探针（Probe）。探针是负责取数的独立单元，大多数探针使用 T-SQL 查询，但 SQL Assessment API 也支持 WMI、Windows 注册表、Azure Instance Metadata Service，以及以 .NET 类实现的自定义探针（Probe.md 中的类型表列出了 AzGraph、AzMetadata、CMD、External、PowerShell、Registry、SQL、WMI 共八种）。从源码结构看，默认规则集中的探针只读取元数据（如更新日志、服务器属性），不读取用户表数据，也不向数据库或实例写入任何内容。

探针引用正是"检查 → 探针"这一跳转的载体：检查通过probes数组声明它需要哪些探针的数据，数组中的每个元素就是一条探针引用。

探针引用的两种形态

探针引用本质上是描述检查所需探针的JSON 对象。文档给出了一个关键简化规则：

当探针被引用且无需任何附加选项或参数时，探针引用可以缩写为仅含探针 ID 的字符串。

也就是说，"probes": ["SysDmOsSysInfo"]是合法的——它等价于一个只有id的完整对象。这种简写形式在 LocalVariables.md 的示例中可以看到实际应用：

{ "probes": ["SysDmOsSysInfo"], "locals": { "workers": {"sub": [ "@max_workers_count", 1 ] } }, "message": "Workers = @{workers}.", "condition": { "lt": [ 0, "@workers" ], "lt": [ "@workers", 4 ] } }

而完整的探针引用对象通常出现在需要传参、起别名或做数据变换的场景，由以下属性构成。

探针引用属性详解

id：引用探针的标识

id是探针引用的核心标识。探针本身在规则集文件中以 JSON 对象定义，属性名即探针 ID，属性值是探针实现数组；引擎会选取第一个与目标模式匹配的实现，因此实现数组的顺序很重要（Probe.md）。探针引用通过id精确指定要使用哪个已定义探针。

alias：表达式中使用的别名

alias为该探针起一个替代名称，供本检查中的表达式使用。它的价值体现在文档强调的两个场景中：

• 同一探针多次调用（calling probe multiple times）：同一检查需要用不同参数多次调用同一探针时，用别名区分各次调用返回的结果；
• 探针间数据传递（using data from another probe）：一个探针的输出要作为另一个探针的输入时，用别名（或探针 ID）作为前缀引用前一个探针的输出变量。

params：传给探针的参数

params是传给该探针的参数集合。参数以 JSON 对象属性的形式给出，属性名是参数名，属性值可以是任意表达式。表达式可以包含常量、全局变量、局部变量，以及由其他探针返回的数据（通过alias引用）。参数的具体含义取决于探针类型：例如 T-SQL 探针的主要参数是取数查询；而引用文档中的DiskInfo探针的参数是DiskName。

表达式支持的操作符体系见 Operators.md，涵盖逻辑（and/or/not）、字符串（indexof、startswith、endswith及不区分大小写的i前缀变体）、数学（add、sub、mul、div、mod、ceiling、floor、max、min、位运算等）、集合（intersect、in、iin）与比较（lt/less、gt/greater、eq、ge、le、ne、match正则匹配、interval区间取值等）五类，是编写params值与condition的基础语言。

transform：进入条件计算前的数据变换

transform在计算条件值之前应用于探针数据。引入它的动机在 DataTransformation.md 中有清晰阐述：当数据格式不便直接使用（如sys.dm_os_host_info返回的host_release是'10.0.19044.2006'这样的字符串）时，与其在 T-SQL 中解析，不如在 JSON 中声明变换，使代码更易读、更易维护：

"implementation": { "query": "SELECT host_platform, host_release FROM sys.dm_os_host_info", "transform": { "type": "parse", "map": { "host_release": "/^(?<major>\\d+)\\.(?<minor>\\d+)" } } }

变换既可定义在探针实现中，也可定义在探针引用中——后者能显著提升探针复用：当一个检查需要某指标的均值、另一个检查需要同一指标的最大值时，两个检查可以引用同一个探针，但各自应用自己的变换。此时不仅探针代码被复用，数据也被复用，因为探针只会被实际调用一次（详见 DataTransformation.md）。可用变换类型见 DataTransformation 参考，包括aggregate、defaultValue、nameValuePairs、noData、parse、performance、rename、toString等，后文会结合示例展开其中最常用的aggregate。

场景一：同一探针多次调用（alias +::语法）

某些检查需要对同一探针以不同参数调用多次。做法是：添加多条具有相同id的探针引用，并在输出变量名前加上"探针别名 + 双冒号::"作为前缀，以区分不同参数返回的结果。

文档中的经典示例是比较 C: 与 D: 两块磁盘的剩余空间：

"probes": [ { "type": "DiskInfo", "alias": "FirstDisk", "params": { "DiskName": "C:" } }, { "type": "DiskInfo", "alias": "SecondDisk", "params": { "DiskName": "D:" } } ], "condition": { "greater": [ "@FirstDisk::FreeSpace", "@SecondDisk::FreeSpace" ] }

这里要点有三：

1. 两条探针引用type相同（均为DiskInfo），仅params.DiskName不同，实现"同一探针、不同参数"；
2. 分别为它们起别名FirstDisk、SecondDisk；
3. 在条件表达式中，用@别名::输出变量名的形式访问各自的结果：@FirstDisk::FreeSpace与@SecondDisk::FreeSpace通过greater比较操作符（greater是gt的同义词，见 Operators.md）得到"C 盘剩余空间是否大于 D 盘"的结论。

注意示例中探针引用使用了type而非id来指定探针——在 SQL Assessment API 的探针定义模型中，探针 ID 即探针 JSON 对象的属性名，二者在引用语境中指代同一概念，具体以所加载规则集中探针的定义为准。

场景二：探针间数据传递（前一个探针的输出作为下一个探针的输入）

一个探针返回的数据可以传给另一个探针作为参数：参数表达式中应包含以先前探针的 id 或别名作为前缀的输出变量名。

文档给出的示例是：DatabaseMasterFiles探针找出目标数据库使用的所有磁盘的卷 ID，AzStorage探针针对每个卷 ID 被调用，追加 Azure 相关的存储属性：

"probes": [ { "id": "DatabaseMasterFiles", "alias": "db_files", "params": { "dbId": null, "type": null }, "transform": [ { "type": "aggregate", "group": [ "volume_mount_point", "volume_id" ] }, { "type": "aggregate", "group": "volume_id", "map": { "volume_mount_point": "join" } } ] }, { "id": "AzStorage", "params": { "path": "@db_files::volume_id" } } ]

这个示例同时展示了三条关键机制：

1. 数据传递：第二条探针引用AzStorage的params.path取值为"@db_files::volume_id"，即"引用别名为db_files的探针（即DatabaseMasterFiles）输出中的volume_id变量"。引擎会先调用DatabaseMasterFiles，再把它的输出注入AzStorage的参数；
2. 多步变换串联：transform是一个数组，变换按顺序依次作用于数据。第一步aggregate按volume_mount_point与volume_id两列分组，第二步再按volume_id分组并将每组的volume_mount_point用join聚合函数拼成字符串——经过两级聚合后，数据收敛为"每个卷 ID 一行"，天然适配AzStorage逐卷取数的需求；
3. 聚合变换的细节：aggregate的group参数可接受单个字符串或字符串数组（作用类似 T-SQL 的GROUP BY），map参数将列名映射到聚合函数。join聚合函数默认以", "分隔、默认去重（distinct: true）、默认修剪首尾空白（trim: true），还支持limit参数控制最多拼接前 N 项并用省略号代替其余部分（详见 aggregate.md）。

关于多探针数据的组合方式还有一个重要语义：RulesandProbes.md 明确指出，当检查从多个探针获取数据时，结果数据集由所有行的全部组合构成，行为类似 T-SQL 的CROSS JOIN。条件会对每一行分别求值：例如一个数据库用 3 块磁盘存放文件，空闲空间最佳实践对每块磁盘独立适用；若检查使用两个探针、一个产生 2 行另一个产生 3 行，条件将被求值 2×3=6 次，其中 2 次为false时会产生 2 条消息。

数据变换（transform）深入：以 aggregate 为例

transform是探针引用的灵魂属性之一，值得单独展开。变换的目的是让"原始取数"与"条件计算"解耦，从而最大化探针复用。DataTransformation.md 开篇即点明：当数据格式不便时，可以在探针实现中应用变换（如用parse正则提取host_release的主次版本号）；也可以在探针引用中应用变换，使不同检查复用同一探针、各取所需的数据形态。

以最常用的aggregate为例（完整参数见 aggregate.md）：

聚合函数包括：

• and/or：对布尔值计算逻辑与/或（null、DBNull、空字符串、空数组、字符串'false'视为false，非空字符串/数组及字符串'true'视为true）；
• array：将所有值收集为数组；
• count：计数，支持distinct（默认true，只计不重复值）与notNull（默认true，只计非空值）两个可选参数；
• join：将值转成字符串后拼接，默认分隔符", "，支持trim、separator、limit、distinct、comparison参数；
• max/min：仅限数值列的最大/最小值；
• sum：仅限数值列的求和。

不加group时聚合作用于全部数据行、返回一行；指定group时每个分组返回一行聚合结果。上一节示例中"map": { "volume_mount_point": "join" }正是"把每个卷的所有挂载点拼成一个字符串"的典型用法。更多变换（如parse正则解析、rename重命名、defaultValue缺省值填充等）可查阅 DataTransformation 参考目录。

探针引用与检查、规则的完整配合

探针引用不是孤立存在的，它最终服务于规则（Rule）所定义或修改的检查。在 Rule.md 中，检查的关键属性包括：

• probes：探针引用数组，即本文讨论的核心——声明检查取数所需的数据源；
• condition：JSON 对象树形式的表达式，使用检查参数与探针数据，最佳实践被实现时返回true，为false时向用户展示消息；
• locals：局部变量，是涉及字面量、探针数据与变换结果的任意表达式，供条件与消息模板使用（见 LocalVariables.md）；
• message：消息模板，支持类似 C# 字符串插值的@{变量}语法及:格式说明符（如@{fragmentation:P2}输出37.20%，字符串变量还支持#占位符的条件拼接，见 MessageTemplate.md）。

一个典型的数据流是：规则（definition/override）→ 检查（probes 数组中的探针引用）→ 探针实现（按目标模式取数，可带实现级变换）→ 引用级 transform → locals/condition/message。探针引用位于这条链的枢纽位置——它决定了取哪个探针、传什么参数、如何变换、如何被其他探针引用。

在动手编写自定义探针引用前，建议先通读 RulesandProbes.md 理解规则与检查的关系（如definition定义检查、override修改检查、enabled: false跳过检查等），并参考仓库中现成的规则集（如 DefaultRuleset.csv）观察真实探针引用的写法。

编写探针引用时的注意事项

综合文档与配套资料，编写探针引用需注意以下几点：

1. 无副作用设计：探针应设计为无副作用的函数；探针的调用顺序是不确定的，引擎可能为优化目标服务器负载而重排调用；当没有检查需要某探针的数据时，该探针根本不会被调用（Probe.md）。因此探针引用之间不应隐式依赖调用先后，跨探针传数据必须显式使用@别名::变量语法；
2. 别名冲突与覆盖：探针引用既可用id也可用type指定探针（取决于所加载规则集中探针的定义方式）；同一检查内多次引用同一探针时必须使用不同alias，否则无法区分各次调用的结果；
3. 多探针数据组合语义：多探针结果按"全组合（类 CROSS JOIN）"方式合并、条件逐行求值，编写引用与条件时要预估组合爆炸对评估结果消息数量的影响（RulesandProbes.md）；
4. 简写优先：无参数、无别名、无变换时优先使用字符串简写（如"probes": ["SysDmOsSysInfo"]），保持规则集 JSON 简洁可读；
5. 变换顺序敏感：transform数组中的变换按声明顺序依次执行（如先按两列分组、再按单列分组收敛），两级聚合的输出将直接决定下游探针参数与条件表达式的数据形态；
6. 目标匹配决定探针实现：探针可含多个实现，每个实现有自己的目标模式；引擎选取第一个匹配的实现，因此探针引用本身不控制版本差异——版本适配由探针实现层的目标模式完成（RulesandProbes.md）。

掌握以上规则后，你可以对照 ProbeReference.md 原文，结合 Customization 目录 中的 Rule.md、Probe.md 与 DataTransformation.md，并参考 CreatingCustomRules 教程 开始编写你自己的自定义规则与探针引用。

• 示例工程
• 数据库
• 教程
• 后端