SQL Server 评估 API（SQL Assessment API）规则引擎局部变量（Local Variables）完全指南：用表达式在条件和消息模板中复用探针数据

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

导读

本文围绕微软官方 SQL Server 样例仓库中 SQL Assessment API 的 Local Variables 参考文档 展开，系统讲解评估规则中locals局部变量机制的语法、求值规则与实战用法。你将掌握：如何在自定义检查规则中把探针返回的原始数据加工成可复用的中间变量，如何在condition条件表达式与message消息模板中引用这些变量，以及如何借助仓库内置规则集（ruleset.json）中的真实案例落地自己的合规检查。

一、局部变量在评估规则体系中的位置

SQL Assessment API 用「规则（Rule）」构建检查清单（Checklist），每条规则要么定义一个新检查（check），要么覆盖修改一个或多个现有检查。检查本身不直接采集数据，而是引用「探针（Probe）」——大多数探针执行 T-SQL 查询（也支持 WMI、注册表、PowerShell、Azure 元数据等，见 Probe 文档）。探针返回的数据行会以类似CROSS JOIN的方式组合成检查的输入数据集（参见 Rules and Probes）。

一个检查（check）的 JSON 定义中通常包含四个相互协作的部分：

• probes：列出本检查需要引用的探针；
• locals：定义本检查可用的局部变量（即本文主题）；
• condition：以表达式树描述「最佳实践已被满足」的条件，求值为false时输出推荐消息；
• message：消息模板，用于向用户展示检查发现的问题与建议。

规则的全部属性（id、itemType、target、targetFilter、displayName、level、probes、condition、parameters、locals等）可参见 Rule 文档。

二、Local Variables 的核心定义

参考文档给出了权威定义：

A rule can define local variables available for conditions and message templates. Local variables are any expressions involving literals, probe data, and transformation results.

即：局部变量是可供条件表达式（condition）与消息模板（message）使用的中间变量，其值可以是任意表达式，表达式可组合字面量（literals）、探针数据（probe data）与转换结果（transformation results）。

局部变量以 JSON 对象locals的形式挂在检查定义上，每个属性名即变量名，属性值即变量的取值表达式。文档给出的最小完整示例：

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

这个示例虽然简短，却完整展示了局部变量机制的三个关键用法：

1. 探针SysDmOsSysInfo返回了名为@max_workers_count的原始数据；
2. 局部变量workers通过算术减法sub将其加工为「max_workers_count - 1」；
3. 加工后的workers同时被message（以@{workers}插值）和condition（以"@workers"引用）使用。

三、表达式与变量引用的语法基础

要正确书写locals，必须先理解评估引擎的表达式语法（详见 JSON 配置格式参考）：

• 布尔与数字字面量：JSON 的true/false与数字直接作为常量使用；
• 字符串字面量：普通字符串表示字符串常量；以@开头的字符串表示变量引用，变量名即@之后的名称；
• 表达式对象：只有单个属性的 JSON 对象即一个操作表达式，属性名是操作符，属性值是该操作符的参数数组；
• 简写形式：属性名以@开头时，是「变量等于值」的简写（等价于equal操作）；多属性对象是 AND 操作的简写；condition 中的数组是 OR 操作的简写。

因此，在locals中，"workers": {"sub": [ "@max_workers_count", 1 ] }的含义是：把探针变量@max_workers_count与字面量1作为sub（减法）操作符的参数，计算结果赋给局部变量workers。

变量可见性与作用域

• 全局/检查级数据：探针返回的字段、检查parameters中定义的任意属性，以@变量名形式在整个检查内可见（parameters 可引用变量或其他参数，见 JSONConfiguration.md）；
• 局部变量：locals中定义的名称在同一检查的 condition、message、probe params 与转换中可用；
• 跨探针数据：一个探针的输出可以作为另一个探针的参数（用alias::variable语法），详见 Probe Reference 文档。

四、可在 locals 中使用的操作符全集

局部变量的值本质是表达式树，因此可以调用评估引擎的全部操作符（完整参考见 Operators 文档）。按类别归纳如下：

| 类别 | 操作符 | 说明 | | - | - | - | | 逻辑 |not/and/or| 逻辑非 / 与 / 或（and无参返回false，or无参返回true） | | 字符串 |indexof/iindexof| 查找子串索引（区分/不区分大小写） | | 字符串 |startswith/istartswith/endswith/iendswith| 前缀 / 后缀判断（区分/不区分大小写） | | 数学 |ceiling/floor| 向上 / 向下取整 | | 数学 |max/min| 最大值 / 最小值 | | 数学 |mul/div/mod| 乘法 / 除法 / 取余 | | 数学 |add/sub| 加法 / 减法 | | 数学 |bitand/bitor/bitxor| 按位与 / 或 / 异或 | | 集合 |intersect/in/iin| 集合交集 / 成员判断（区分/不区分大小写） | | 比较 |lt/less、gt/greater、eq/equal、ieq| 小于 / 大于 / 等于（含大小写不敏感变体） | | 比较 |ge/greaterequal、le/lessequal、ne/notequal、ine| 大于等于 / 小于等于 / 不等于（含大小写不敏感变体） | | 比较 |match/imatch| 正则匹配（第二参数为正则表达式，区分/不区分大小写） | | 比较 |interval| 区间查值：(*a*, *v₁*, *t₁*, ..., *vₙ*, *tₙ*, *d*)，返回第一个 ≥a的tᵢ对应的vᵢ，全部小于a时返回默认值d|

注意：文档示例中condition使用了"lt": [ 0, "@workers" ]与"lt": [ "@workers", 4 ]两个并列属性——多属性对象是 AND 简写，因此该条件等价于「0 < workers < 4」。

五、示例探针 SysDmOsSysInfo 的源码级佐证

@max_workers_count来自哪里？在仓库内置规则集 ruleset.json 中可找到SysDmOsSysInfo探针的定义，它依据目标引擎版本选择不同实现：

"SysDmOsSysInfo": [ { "type": "SQL", "target": { "engineEdition": "SqlServer, ManagedInstance", "platform": ["Windows", "Linux"], "version": ["[11.0.7001,12.0)", "[12.0.6024,13.0)", "[13.0.4001,)"] }, "implementation": { "query": "SELECT max_workers_count, virtual_machine_type, sql_memory_model FROM sys.dm_os_sys_info (NOLOCK)" } }, { "type": "SQL", "target": { "engineEdition": "SqlServer, ManagedInstance", "platform": ["Windows", "Linux"], "version": "[11.0,)" }, "implementation": { "query": "SELECT max_workers_count, virtual_machine_type, 0 AS sql_memory_model FROM sys.dm_os_sys_info (NOLOCK)" } } ]

从源码结构可以推断：该探针针对 SQL Server 2012（11.0）及以上版本（含 Managed Instance）设计，查询sys.dm_os_sys_info视图取max_workers_count（当前配置的最大工作线程数）、virtual_machine_type与sql_memory_model；较老版本没有sql_memory_model列，因此用0 AS sql_memory_model补齐。这也印证了参考文档的说明——探针的返回值就是局部变量表达式可以引用的「probe data」。

该变量在默认规则集中同样被直接使用，例如ThreadExhaustionCPUBound检查（见 DefaultRuleset.csv 中的对应条目与 ruleset.json 中的定义）在消息模板里输出Configured workers is '@{max_workers_count}'。这说明探针原始变量与局部变量可以共存于同一模板。

六、在消息模板中引用局部变量

局部变量与探针变量一样，可以直接嵌入message模板，语法为@{变量名}（详见 MessageTemplate 文档）：

• 模板风格类似 C# 字符串插值，@{workers}会被替换为局部变量workers的字符串形式；
• 支持格式说明符：@{变量名:格式}，例如@{recommended:N0}（千位分隔、无小数）、@{fragmentation:P2}（百分比、两位小数）；
• 字符串值的格式化有扩展行为：当值非空时，格式字符串中的#会被替换为实际值，可用于按需拼接句子片段。

因此文档示例的"message": "Workers = @{workers}."输出形如Workers = 511.（若max_workers_count为 512）。

七、仓库内置规则集中的真实 locals 案例

locals并非纸上谈兵，仓库的默认规则集 ruleset.json 中就有多处实战用法，是学习局部变量设计模式的最佳教材。

案例 1：MaxMemory 检查的内存推荐值（多级嵌套表达式）

MaxMemorySystem检查（ruleset.json）定义了两个局部变量recommended与sysmem，其中recommended是典型的复杂嵌套表达式：

"locals": { "recommended": { "floor": { "min": [ "@limit", { "sub": [ { "div": [ "@total_physical_memory_kb", 1024 ] }, { "mul": [ "@max_workers_count", { "interval": [ "@host_architecture", 0.5, 32, 2, 64, 4 ] } ] } ] } ] } }, "sysmem": { "div": [ "@total_physical_memory_kb", 1024 ] } }

可以解读为：先把物理内存 KB 换算成 MB（div1024），按@host_architecture（32 位/64 位）通过interval区间查表得到每个工作线程的内存开销，再乘以@max_workers_count得到线程开销总量，两者相减得到推荐内存上限，最后与检查参数@limit取min并用floor向下取整。消息模板中则以@{recommended:N0}、@{sysmem:N0}格式化输出。这个案例充分说明局部变量如何把复杂的多步计算「拆解为可读、可复用、可调试的命名中间量」。

案例 2：索引填充因子检查（sub 的另一种用法）

在索引维护类检查中（ruleset.json）：

"locals": { "leafPageEmptyPercent": { "sub": [ 100, "@threshold" ] } }

用100 - threshold直接算出叶页空闲百分比，供 condition 与 message 引用——局部变量使业务语义（“leaf page empty percent”）显式化，而不是在多个地方重复书写100 - @threshold。

案例 3：页压缩检查（依赖探针转换结果的局部变量）

数据压缩相关检查（ruleset.json）中：

"locals": { "UncompressedPages": { "sub": [ "@TotalPages", "@CompressedPages" ] }, "TotalSpaceMB": { ... } }

@TotalPages与@CompressedPages本身是探针数据经过转换（transform）后的输出，局部变量再对其做减法得到未压缩页数——这正是参考文档所说「local variables are any expressions involving literals, probe data, and transformation results」的直接体现。

八、局部变量与探针参数、数据转换的协同

局部变量表达式不仅可以引用探针输出，还可以作为探针调用的参数传递。结合 ProbeReference.md 的机制：

• 探针引用可以用alias起别名，params中的参数值可以是任意表达式（常量、全局变量、局部变量、其他探针的数据）；
• 当一个探针被多次调用（如分别检查 C: 与 D: 盘）时，用@alias::字段区分不同调用的输出；
• 一个探针的输出可以作为另一个探针的入参（如"path": "@db_files::volume_id"）；
• 探针实现内部还可以定义transform（如parse、aggregate、rename等，见 DataTransformation 文档），转换结果同样可以进入局部变量表达式。

因此，一条完整的数据加工链路通常是：探针查询 → 数据转换（transform）→ 局部变量（locals）→ 条件（condition）/ 消息（message）。把中间步骤命名为局部变量，比在 condition 里书写巨型嵌套表达式更易维护，也让消息模板能直接输出经过计算的业务指标。

九、自定义规则中的实操模板

若要在自己的规则集中使用局部变量，只需把带locals的检查定义写入规则集 JSON 即可。规则集文件的顶层结构（详见 RulesetFileStructure 文档）包含name、version、schemaVersion（当前为 1.0）三个必填属性，以及可选的rules数组与probes对象。仓库提供了可直接参考的完整样例 MakingCustomChecks_sample.json（自定义 Query Store、Trace Flag 834 等检查）与 DisablingBuiltInChecks_sample.json（禁用内置检查）。

一个融入局部变量的自定义检查骨架如下：

{ "schemaVersion": "1.0", "version": "0.1", "name": "My Custom Ruleset", "rules": [ { "id": "MyWorkerCheck", "itemType": "definition", "target": { "type": "Server", "platform": ["Windows", "Linux"], "engineEdition": "SqlServer", "version": "[11.0,)" }, "displayName": "Worker count sanity check", "level": "Low", "probes": ["SysDmOsSysInfo"], "locals": { "workers": { "sub": [ "@max_workers_count", 1 ] } }, "message": "Workers = @{workers}.", "condition": { "lt": [ 0, "@workers" ], "lt": [ "@workers", 4 ] } } ], "probes": {} }

注意：规则集中的probes是可选的，因为一个规则集可以使用另一个规则集定义的探针（默认规则集已提供SysDmOsSysInfo）。评估引擎按规则被加载的顺序依次应用规则构建检查清单，加载与运行方式可参考仓库根目录的 README.md、QuickStart.md 以及 CreatingCustomRules 教程。

十、最佳实践与注意事项

• 保持表达式无副作用：与探针的设计原则一致（探针被设计为无副作用的函数，调用顺序不保证，见 Probe.md），局部变量表达式也应只做纯计算，不依赖调用顺序；
• 用命名提升可读性：把100 - @threshold、floor(min(...))这类复杂计算提取为leafPageEmptyPercent、recommended等语义化名称，condition 与 message 会更接近自然语言；
• 注意类型与格式：消息模板中的数字记得配合格式说明符（如:N0、:P2）输出，避免默认字符串形式影响可读性；
• 区分变量来源：@字段来自探针/参数，@{局部变量}用于模板插值，"@局部变量"用于表达式引用；三者不要混淆；
• 对照内置规则集学习：ruleset.json 是最大、最真实的教科书，其中的 MaxMemory、填充因子、页压缩等检查覆盖了局部变量从简单减法到多层嵌套计算的全部形态。

结语

局部变量（Local Variables）是 SQL Assessment API 规则表达能力的放大器：它把「探针原始数据 → 加工计算 → 条件判定 → 消息输出」这条链路的中间态显式化，让规则既精确又易维护。掌握locals的语法、操作符与作用域规则，并对照仓库默认规则集与自定义样例（MakingCustomChecks_sample.json），即可为自己的 SQL Server 环境编写专业、可复用的合规评估规则。

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