企业官网建设流程全解析

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

规则集（Ruleset）是 SQL Assessment API 评估 SQL Server 配置的核心载体，它以单个 JSON 文本文件的形式承载全部最佳实践检查项（Rules）与数据采集探针（Probes）的定义。本文以 RulesetFileStructure.md 为主体，结合本仓库中 SQL Assessment API 的完整文档体系与示例 JSON 文件，系统讲解规则集文件的顶层结构、规则与探针的组织方式、目标匹配与版本区间语法，并给出可直接复制改造的自定义规则集实战样例，帮助读者从零构建属于自己的 SQL Server 最佳实践检查清单。

规则集文件：一个 JSON 对象承载一份评估策略

在 SQL Assessment API 中，规则集存储在一个文本文件里，文件内容是一个 JSON 对象。该 JSON 对象定义了"针对哪些 SQL Server 目标、按哪些最佳实践规则、通过哪些探针采集数据"的完整评估策略。引擎可以同时加载多个规则集，并按照添加顺序依次应用其中的规则。

三个必填顶层属性

规则集对象包含三个简单且必须存在的顶层属性：

| 属性 | 类型 | 说明 | | - | - | - | |name| string | 规则集名称，用于标识该规则集 | |version| string | 规则集版本号 | |schemaVersion| string | 文件格式版本号，用于声明 JSON 结构所遵循的格式版本 |

其中schemaVersion决定了文件格式的解析方式。截至本文编写时，文件格式版本为1.0。而name与version共同构成规则集的身份标识（identity）——引擎据此区分不同规则集及其迭代版本。

两个可选顶层属性：rules 与 probes

除了必填属性之外，规则集还有两个可选的核心属性：

• rules：一个由 SQL Assessment API 规则组成的数组。规则用于构建检查清单（checklist），每条规则要么定义一个新的检查项，要么修改一个或多个已有的检查项。
• probes：探针定义集合。探针用于从目标 SQL Server 实例、宿主机及其他数据源获取真实数据（如动态管理视图、注册表、WMI、Azure 元数据等）。每个探针定义是一个 JSON 数组，数组中包含一个或多个实现（implementation），以便针对不同版本的 SQL Server 选用最合适的实现。

rules与probes之所以都是可选的，是因为一个规则集里的规则可以引用另一个规则集中的探针——这为规则的复用与分层管理提供了极大的灵活性。例如，你可以维护一份"公共探针规则集"，再在多个"业务规则集"中共享其中的探针。

官方文档 RulesetFileStructure.md 给出了规则集文件的整体结构示意图：

规则集文件的完整骨架示例

{ "name": "Ruleset name", "version": "Ruleset version", "schemaVersion": "Schema version", "rules":[ { … rule A … }, { … rule B … }, … ], "probes":{ "probe1": [ { … implementation 1 … }, { … implementation 2 … }, … ], "probe2": [ … ], … } }

规则（Rules）：如何构建评估检查清单

规则是 SQL Assessment API 评估流程的核心。理解规则，首先要理解评估引擎的两步工作流程（详见 RulesandProbes.md）：

1. 为给定目标构建检查清单：清单中包含针对该目标（服务器或数据库）的完整检查项集合；
2. 逐项验证并报告违规：引擎遍历清单，检查目标是否满足每一条最佳实践，对不满足的项生成消息报告。

之所以需要"规则"这种抽象，是因为最佳实践并非放之四海而皆准：准则取决于 SQL Server 版本、版本类型（Edition）、宿主平台、甚至使用模式。例如，某些最佳实践只适用于云环境，另一些则针对物理机上的实例；msdb数据库的最佳实践集合也与用户数据库不同。规则通过target模式精准界定适用范围，从而让同一套评估机制适配千差万别的环境。

规则的 itemType：definition 与 override

每条规则都是一个 JSON 对象，其itemType属性决定规则的行为（详见 Rule.md）：

• definition：定义一条新的检查项；
• override：修改一个或多个已有的检查项。

一个检查项可以被多条规则影响。第一条规则（definition）必须定义检查项并赋予其唯一的字符串 ID。检查项可以带有tags标签，从而支持按组管理。此后的 override 规则可以通过 ID 或标签引用检查项，一次修改多个检查项。

例如，下面的 definition 规则使 ID 为MaxMemory的检查项出现在所有 SQL Server 2012 及以上实例的清单中，并将其limit参数设置为 2147483647：

{ "id": "MaxMemory", "itemType": "definition", "target": { "type": "Server", "version": "[11.0,)" }, "limit": 2147483647 }

下面的 override 规则修改上述检查项的limit参数：

{ "id": "MaxMemory", "itemType": "override", "limit": 2000000000 }

override 规则还可以借助targetFilter只修改特定目标上的检查项。例如，针对不同版本类型（engineEdition）为MaxMemory设置不同的内存上限：

{ "id": "MaxMemory", "itemType": "override", "targetFilter": { "engineEdition": "Standard" }, "limit": 131072 }, { "id": "MaxMemory", "itemType": "override", "targetFilter": { "engineEdition": "Express" }, "limit": 1410 }

enabled 属性：清单中的检查项不一定都会执行

检查项出现在清单中，并不代表它一定会被评估引擎执行。每个检查项都有enabled属性，默认值为true；如果所有规则应用完毕后该属性变为false，引擎将跳过该检查项。

例如，下面的 override 规则通过targetFilter针对所有运行在 Linux 上的实例，一次性禁用MaxMemory检查项以及所有带Performance标签的性能相关检查项：

{ "id": [ "MaxMemory", "Performance" ], "itemType": "override", "targetFilter": { "platform": "Linux" }, "enabled": false }

规则的完整属性清单

依据 Rule.md 与 RulesandProbes.md，一条规则支持以下属性：

| 属性 | 取值/类型 | 说明 | | - | - | - | |itemType|definition/override| 定义新检查项或修改已有检查项 | |tags| string 数组 | 用于分类检查项的短标签，如"Memory"表示内存相关最佳实践；单词标签效果最佳 | |id| string 或 string 数组 | 被定义/修改的检查项 ID；数组形式可同时按多个 ID 或标签选择检查项（命中任一标签即生效） | |target| Target pattern | 目标模式，规则仅应用于匹配该模式的对象 | |targetFilter| Target pattern | 与target语法相同，但专用于 override 规则| |displayName| string | 显示在清单中的短名称，说明该检查项在查什么 | |message| string | 消息模板，当检查项发现不符合最佳实践时展示给用户（支持变量插值） | |description| string | 长描述，解释为何检查该问题及其影响 | |helpLink| string | 指向最佳实践说明与修复建议的超链接 | |level|Information/Low/Medium/High| 问题严重级别 | |probes| array | 本检查项所需探针的引用列表 | |condition| 表达式对象 | 条件表达式：返回true表示最佳实践已落实；返回false则向用户展示message| |parameters| 任意属性 | 随探针数据一起传给条件、消息模板、探针参数及 transform 的任意参数 |

条件表达式的求值语义

每个检查项都需要数据来支撑分析。检查项本身不从目标服务器或数据库检索任何数据，而是引用探针（probes）来获取数据。每个探针返回零行或多行包含命名项（named items）的数据；如果检查项从多个探针取数，结果数据集按所有行的组合（类似 T-SQL 的CROSS JOIN）构建。

条件的求值是逐行进行的：例如某数据库用 3 块磁盘存放文件，那么"磁盘剩余空间"类最佳实践会分别作用于每块磁盘；若一个检查项使用两个探针，一个产生 2 行数据、另一个产生 3 行，则条件将被求值 2×3=6 次；若其中 2 次结果为false，该检查项将产生 2 条消息。

探针（Probes）：检查项的数据来源

探针解决了"数据从哪来"的问题。SQL Assessment API 的探针类型十分丰富，不仅限于 T-SQL 查询，还支持从操作系统与云平台取数。完整类型列表见 Probes 参考文档：

| 类型 | 说明 | | - | - | | AzGraph | 针对 Azure Resource Graph 的 Kusto 查询 | | AzMetadata | 针对 Azure Instance Metadata Service 返回对象的 JSONPath | | CMD | 在目标机器上运行的命令外壳脚本 | | External | 任意 .NET 代码（实现IProbeImplementation接口的类） | | PowerShell | PowerShell 脚本 | | Registry | 从注册表读取数据 | | SQL | T-SQL 查询 | | WMI | WMI 查询 |

探针定义结构

在规则集 JSON 中，探针以属性形式存在：属性名即探针 ID（供规则引用），属性值是一个探针实现数组（详见 Probe.md）：

"probes":{ "Custom_DatabaseConfiguration": [ { … implementation 1 … }, { … implementation 2 … } ] }

评估引擎会按数组顺序选择第一个 target 模式匹配的实现，因此实现顺序很重要。一个探针可以由 CLR 与 SQL 实现混合组成，其他规则集也可以在此列表之上追加实现。

探针实现的属性包括：

| 属性 | 说明 | | - | - | |type| 探针类型（上表所列之一） | |target| 目标模式，与规则的 target 语法一致，用于按版本/平台/版本类型等选择实现 | |implementation| 探针参数与数据变换（transform）；对 T-SQL 探针，核心参数是query| |requires| 显式功能需求；若需求不满足，探针不执行、依赖它的检查项全部跳过并返回警告 | |runFor| 显式逻辑需求；若需求不满足，探针实现不执行且立即返回空结果集 |

以 T-SQL 探针为例，其implementation支持以下参数（见 TSQLProbes.md）：

| 参数 | 必填 | 类型 | 默认值 | 说明 | | - | :-: | :-: | :-: | - | |query| 是 | String | - | T-SQL 查询 | |useDatabase| 否 | Bool |false| 是否在运行查询前发出USE DATABASE语句，适用于以数据库为目标的探针 | |timeout| 否 | Number | 30 | 命令执行超时时间（秒） |

探针的设计约定

从源码结构与官方文档可以总结出探针的几条关键设计约定：

• 探针应设计为无副作用（side-effect free）的函数；
• 引擎对探针的调用顺序不做保证，可能为了优化目标 SQL Server 负载而重排探针调用；
• 当没有任何检查项需要某探针的数据时，该探针不会被调用；
• 默认规则集（ruleset.json）中的探针只读取元数据（如更新日志、服务器属性），不读取表用户数据、不向数据库或实例写入任何内容，也不设置任何标志或属性。

探针实现的分版本示例

由于动态管理视图在不同 SQL Server 版本间存在差异，探针常按版本拆分多个实现。下面这个例子展示了针对 SQL Server 2016 及以上（version为[13.0,)）的探针实现——注意它通过useDatabase: true在目标数据库上下文中执行，并从sys.database_query_store_options读取 Query Store 状态：

{ "type": "SQL", "target": { "type": "Database", "version": "[13.0,)", "platform": "Windows, Linux", "engineEdition": "OnPremises, ManagedInstance" }, "implementation": { "useDatabase": true, "query": "SELECT db.is_auto_create_stats_on, db.is_auto_update_stats_on, (SELECT CAST(actual_state AS DECIMAL) FROM [sys].[database_query_store_options]) AS query_store_state, db.collation_name, (SELECT collation_name FROM master.sys.databases (NOLOCK) WHERE database_id = 1) AS master_collation, db.is_auto_close_on, db.is_auto_shrink_on, db.page_verify_option, db.is_db_chaining_on, db.is_auto_create_stats_incremental_on, db.is_trustworthy_on, db.is_parameterization_forced FROM [sys].[databases] (NOLOCK) AS db WHERE db.[name]=@TargetName" } }

目标模式（Target Pattern）与版本区间语法

无论是规则还是探针实现，都依赖目标模式来界定适用范围。目标模式是一个 JSON 对象，所有属性都是可选的，省略任何属性即表示匹配一切值（完整说明见 TargetPattern.md）。

目标模式的主要属性

| 属性 | 取值/语法 | 说明 | | - | - | - | |type|Server/Database| 匹配的 SQL Server 对象类型，支持逗号分隔列表 | |version| 版本区间列表 | 匹配的 SQL Server 版本范围 | |engineEdition|PersonalOrDesktopEngine/Standard/Enterprise/Express/AzureDatabase/DataWarehouse/StretchDatabase/ManagedInstance| 版本类型；Azure是AzureDatabase, DataWarehouse, StretchDatabase, ManagedInstance的简写，SqlServer是PersonalOrDesktopEngine, Standard, Enterprise, Express的简写 | |platform|Windows/Linux| 宿主机平台 | |machineType|Physical/AzureVm/Hypervisor/Other| 宿主机类型 | |name| 字符串模式 | 目标对象的名称（数据库名或实例名），支持正则与not否定 | |serverName| 字符串模式 | SQL Server 实例名；目标为实例时等于name，否则为目标对象所在实例名 |

字符串模式与正则

字符串模式可以是一个普通字符串（精确匹配）、以/开头和结尾的正则表达式（支持 .NET 正则及选项，如/win.*/c表示区分大小写）、JSON 数组（任一元素匹配即匹配），或仅含not属性的 JSON 对象（匹配"不是该值"的一切）。

示例：匹配除master、tempdb、model之外的任何数据库：

"name": { "not": "/^(master|tempdb|model)$/" }

注意：正则默认不区分大小写，如需区分大小写请使用c选项。

版本区间（Version Range）语法

版本区间字符串遵循 NuGet 版本区间格式：一个或两个由逗号分隔的版本，外层可选用括号()（开区间）或方括号[]（闭区间）；版本至少需包含用句点分隔的主版本号和次版本号。常用写法：

| 版本区间 | 匹配内容 | | - | - | |"10.0"| 精确匹配版本 10.0 | |"[10.0, 13.0]"| 10.0 到 13.0（含两端） | |"(10.0, 13.0)"| 10.0 到 13.0（不含两端），如 10.50、11.0.345 | |"[10.0, 13.1)"| 10.0 到 13.1，不含右边界 | |"[10.0,)"| 10.0 及以上 | |"(,10.0]"| 10.0 及以下 | |"(,10.0)"| 低于 10.0 |

version属性还可以是版本区间列表（数组），匹配任一区间即通过。例如同时匹配 SQL Server 2016 SP2+、2014 SP3+ 与 2019+：

"version": ["[13.0.5026.0, 14.0)", "[12.0.6024.0, 13.0)", "[15.0)"]

仓库自带规则集样例拆解

仓库在 sql-assessment-api 目录下提供了两个可直接参考的规则集样例文件，它们正是 RulesetFileStructure.md 末尾列出的两个示例。

样例一：DisablingBuiltInChecks_sample.json —— 用 override 禁用内置检查

DisablingBuiltInChecks_sample.json 演示了如何通过 override 规则禁用内置检查，包含三种典型场景：

{ "schemaVersion": "1.0", "version": "0.2", "name": "Custom Overrides", "rules":[ { "id": "LatestCU", "itemType": "override", "enabled": false }, { "id": ["TraceFlag"], "itemType": "override", "enabled": false }, { "id": ["DefaultRuleset"], "itemType": "override", "targetFilter": { "type": "Database", "name": "/^(DBName1|DBName2)$/" }, "enabled": false } ] }

逐条解读：

1. 按 ID 禁用："id": "LatestCU"通过 ID 精确禁用"最新累积更新"检查项；
2. 按标签禁用："id": ["TraceFlag"]通过标签一次性禁用所有与 TraceFlag 相关的检查项；
3. 按目标过滤禁用："id": ["DefaultRuleset"]配合targetFilter（数据库类型且名称为DBName1或DBName2），仅对这两个数据库禁用整个默认规则集（所有带DefaultRuleset标签的检查项）。

样例二：MakingCustomChecks_sample.json —— 从零定义自定义检查

MakingCustomChecks_sample.json 是更完整的示例，同时包含rules与probes两部分，演示如何从零定义两个自定义检查项。

自定义规则一：Query Store 应处于活动状态

该规则针对 SQL Server 2016 及以上（version: "[13.0,)"）、Windows/Linux 平台、本地部署或托管实例（engineEdition: "OnPremises, ManagedInstance"）上的所有非系统数据库，检查 Query Store 的实际操作模式是否为"读写"（query_store_state等于 2）：

{ "target": { "type": "Database", "version": "[13.0,)", "platform": "Windows, Linux", "engineEdition": "OnPremises, ManagedInstance", "name": { "not": "/^(master|tempdb|model)$/" } }, "id": "QueryStoreOn", "itemType": "definition", "tags": [ "CustomRuleset", "Performance", "QueryStore", "Statistics" ], "displayName": "Query Store should be active", "description": "The Query Store feature provides you with insight on query plan choice and performance. …", "message": "Make sure Query Store actual operation mode is 'Read Write' to keep your performance analysis accurate", "helpLink": "https://docs.microsoft.com/sql/relational-databases/performance/monitoring-performance-by-using-the-query-store", "probes": [ "Custom_DatabaseConfiguration" ], "condition": { "equal": [ "@query_store_state", 2 ] } }

这里condition表达式"equal": [ "@query_store_state", 2 ]中的@query_store_state是探针返回数据中的命名项——探针与条件表达式通过@变量名完成数据对接。

自定义规则二：TF 834 大页内存分配（含 override 定制）

先定义一条针对本地部署服务器（engineEdition: "OnPremises"）的检查项，条件为全局 TraceFlag 列表（@TraceFlag）中应包含 834：

{ "target": { "type": "Server", "platform": "Windows, Linux", "engineEdition": "OnPremises" }, "id": "Custom_TF834", "itemType": "definition", "tags": [ "CustomRuleset", "TraceFlag", "Performance", "Memory", "ColumnStore" ], "displayName": "TF 834 enables large-page allocations", "description": "Trace Flag 834 causes the server to use large-page memory (LPM) model for the buffer pool allocations. …", "message": "Enable trace flag 834 to use large-page allocations to improve analytical and data warehousing workloads.", "level": "Information", "probes": [ "Custom_EnabledGlobalTraceFlags" ], "condition": { "in": [ 834, "@TraceFlag" ] } }

随后用一条 override 规则针对更早的 SQL Server 版本（targetFilter.version: "(,11.0)"）覆盖描述、消息与帮助链接——这展示了同一规则 ID 的 definition 与 override 协同工作的模式。

配套探针：多实现 + 数据变换

该规则集的probes部分定义了Custom_DatabaseConfiguration（按 SQL Server 版本拆分为三个 T-SQL 实现，2016+ 版本使用useDatabase并在sys.database_query_store_options中取 Query Store 状态）以及Custom_EnabledGlobalTraceFlags。后者通过DBCC TRACESTATUS获取全局启用的 TraceFlag，并借助transform中的aggregate变换将TraceFlag列聚合为数组，供规则条件中的in操作符使用：

"Custom_EnabledGlobalTraceFlags": [ { "type": "SQL", "target": { "type": "Server", "engineEdition": "OnPremises, ManagedInstance" }, "implementation": { "query": "DECLARE @tracestatus TABLE (TraceFlag NVARCHAR(40), [Status] tinyint, [Global] tinyint, [Session] tinyint); INSERT INTO @tracestatus EXEC ('DBCC TRACESTATUS WITH NO_INFOMSGS'); IF NOT EXISTS(SELECT * FROM @tracestatus WHERE Global=1) SELECT 0 AS [TraceFlag], 0 AS [Status] ELSE SELECT [TraceFlag], [Status] FROM @tracestatus WHERE Global=1", "transform": { "type": "aggregate", "map": { "TraceFlag": "array" } } } } ]

组合多个规则集：引擎的应用顺序与覆盖机制

SQL Assessment API 允许用户逐个添加多个规则集到评估引擎。构建检查清单时，引擎按规则集添加的顺序依次应用其中的规则。这意味着：

• 后添加规则集中的 override 规则可以覆盖先前规则集（含默认规则集）中定义的检查项；
• 一条检查项可以被多条规则反复修改，最终状态由"定义 + 依序覆盖"共同决定；
• 一个规则集的规则可以使用另一个规则集定义的探针，规则与探针的归属关系被解耦。

默认规则集 ruleset.json 由 SQL Server 团队随 API 发布，并随版本不断扩充；仓库还提供了可读版本 DefaultRuleset.csv，方便浏览既有检查项及其全部字段。在动手编写自定义规则集之前，建议先通读默认规则集，了解内置规则 ID、标签与探针命名规律——因为自定义 override 的第一步就是精确引用内置检查项。

实践建议与后续学习路径

编写自定义规则集时，可以遵循以下流程：

1. 明确目标：用target/targetFilter精确界定要评估的服务器版本、版本类型、平台与数据库名称范围；
2. 复用探针：优先复用默认规则集中的探针（探针可从其他规则集借用），仅在数据不足时按 Probe.md 定义新探针；
3. 定义规则：用itemType: "definition"声明新检查项，通过condition表达式描述"合规状态"，并用level标明严重级别；
4. 精细覆盖：用itemType: "override"结合targetFilter针对特定环境微调默认规则，例如在 Linux 上禁用不适用检查、为不同版本类型设置不同阈值；
5. 验证结构：确保name、version、schemaVersion（当前为 1.0）三个必填属性齐全，JSON 语法合法。

如需深入了解规则与探针的细节，可继续阅读本仓库中的相关文档：

• 规则详解：Rule.md
• 探针详解：Probe.md 与 ProbeReference.md
• 目标模式与版本区间：TargetPattern.md
• 探针类型参考：Probes
• 数据变换：DataTransformation.md
• 分步教程：CreatingCustomRules.md、DisablingBuiltInRules.md、OverridingDefaultThresholds.md

掌握规则集文件结构，就等于掌握了 SQL Assessment API 的"配置语言"——无论是微调内置最佳实践，还是落地企业内部的配置基线，都可以通过一份 JSON 文件优雅地完成。

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