author-governance-ruleset

API 治理规则集编写指南

使用治理 CLI 工具发现模型、验证规则集并简化输出，以编写有效的 Anypoint API Governance 规则集（Validation Profile 1.0 YAML）。

概述

治理规则集是一个 YAML 文件，以 #%Validation Profile 1.0 开头，并针对某个域模型（API 规范、API 实例、MCP 服务等）声明验证规则。每条规则都针对一个类，约束其属性，并设置严重级别（violation、warning、info）。

此技能使用 anypoint-cli-v4 governance:ruleset CLI 命令来发现模型、验证规则集并简化输出。切勿猜测类名、属性名或约束兼容性——务必查询 CLI。

---

前提条件：确保治理插件版本符合要求

运行任何治理 CLI 命令之前，请强制安装最新的治理插件，以确保模型、约束和验证逻辑与此技能匹配。所需版本为 1.0.20 或更高版本：

anypoint-cli-v4 plugins:install mulesoft-anypoint-cli-governance-plugin@latest

每次启动此技能时都要运行此命令，即使插件似乎已经安装也不例外——@latest 可确保安装兼容版本（1.0.20 或更高版本）。只有在此命令成功完成后，才能继续以下步骤。

步骤 1：理解意图

解析用户请求。确定：

• 目标类/节点（例如 Operation、WebAPI、APIInstance、MCPServer）
• 受约束的属性（例如 description、version、policies）
• 必须满足的条件（例如必须存在、必须匹配某个模式、必须至少有一个）

如果用户使用领域术语（例如 “consumerUrl”、“endpointUrl”、“rate-limit policy”），请解析它们：

anypoint-cli-v4 governance:ruleset:resolve <term>

别名仅用于编写时辅助，绝不能出现在规则集 YAML 中。请使用 resolve 命令返回的规范 targetClass + path。

步骤 2：选择域

列出可用域，并根据用户意图进行匹配：

anypoint-cli-v4 governance:ruleset:domains

重要规则： 一个规则集只能针对一个 specKind。切勿在同一规则集中组合 api-spec 和 mcp 目标。不带 specKind 的域可以自由组合。

步骤 3：发现模型

列出所选域中可作为目标的类：

anypoint-cli-v4 governance:ruleset:classes --domain <domain-name>

然后列出特定类的属性及其类型：

anypoint-cli-v4 governance:ruleset:properties <prefix.ClassName>

属性类型（scalar、node、scalarArray、nodeArray）决定了哪些约束有效。

步骤 4：选择约束

查询适用于该属性类型的有效约束：

anypoint-cli-v4 governance:ruleset:constraints --type <propertyType>

其中 <propertyType> 可为：scalar、node、scalarArray、nodeArray。

需避免的常见错误：

• 切勿对 nodeArray 或 node 属性使用 pattern 或 in
• 在 nodeArray 上使用 atLeast/atMost，检查“至少有一项匹配 X”
• 在 scalarArray 上使用 containsSome，检查“至少有一个值为 X”
• 在 scalarArray 上使用 in，将所有值限制在允许的集合内
• 使用 / 的属性路径会遍历嵌套节点；最后一个属性决定了有效约束

步骤 5：编写规则集

将有效的 Validation Profile 1.0 YAML 写入文件：

#%Validation Profile 1.0
profile: <profile-name>
prefixes:                    # Only needed for non-default namespaces
  management: http://anypoint.com/vocabs/management#
validations:
  <rule-name>:
    targetClass: <prefix.ClassName>
    message: <human-readable error message>
    propertyConstraints:
      <prefix.propertyName>:
        <constraint>: <value>
violation:                   # MUST assign every rule to a severity
  - <rule-name>
warning:
  - <other-rule>
info:
  - <another-rule>

默认前缀（切勿重新声明）：

• apiContract、core、shacl、shapes、raml-shapes、doc、meta、security、data、xsd、rdfs、rdf、sourcemaps

非默认前缀（必须在 prefixes: 块中声明）：

• management: http://anypoint.com/vocabs/management#
• mulesoft: http://anypoint.com/vocabs/management#mulesoft.com/
• gcl: http://anypoint.com/vocabs/gcl#
• api: http://anypoint.com/vocabs/api#
• catalog: http://anypoint.com/vocabs/digital-repository#
• mcp: http://anypoint.com/vocabs/mcp#
• apiExt: http://a.ml/vocabularies/api-extension#

第 6 步：验证规则集

编写或修改规则集后，使用 CLI 进行验证：

anypoint-cli-v4 governance:ruleset:validate-authoring <path-to-ruleset.yaml>

此命令会检查：YAML 语法、JSON schema 一致性、targetClass 有效性、属性路径正确性、约束类型兼容性和严重级别分配。

如果验证返回错误，请修复后重新验证。规则集通过验证且错误数为零之前，切勿向用户展示。

第 7 步：简化

验证通过后，简化规则集：

anypoint-cli-v4 governance:ruleset:simplify <path-to-ruleset.yaml>

此命令会展平嵌套属性路径并移除冗余的逻辑包装。如果进行了更改，请将简化后的输出写回文件并重新验证。

第 8 步：展示结果

向用户展示最终经过验证和简化的规则集。简要说明：

• 检查内容
• 选择了哪些约束及其原因
• 严重级别分配

---

规则

• 始终以 #%Validation Profile 1.0 作为第 1 行
• 始终为每项验证分配一个严重级别（violation、warning 或 info）
• 规则集 YAML 中绝不使用别名——始终使用规范的 targetClass + 属性路径
• 绝不在同一个规则集中混用 api-spec 和 mcp 目标
• 绝不猜测属性名称——始终运行 governance:ruleset:properties <class> 进行查询
• 绝不猜测约束兼容性——始终运行 governance:ruleset:constraints --type <type>
• 每次写入或修改后，始终使用 governance:ruleset:validate-authoring 进行验证
• 验证通过后，始终使用 governance:ruleset:simplify 进行简化
• 属性路径使用 /（空格-斜杠-空格）分隔各段
• 备用路径使用 |（空格-竖线-空格）分隔，并用 ( ) 括起来
• 对于条件规则，在验证级别使用 if: / then:
• 对于逻辑组合，在验证级别使用 and:、or:、not: 或 xone:
• Rego（rego:）是跨资源检查的最后手段——优先使用声明式约束
• 消息模板可以引用属性值："{{ prefix.property }}"
• 修改现有规则集时，应用更改后重新验证
• 如果用户询问支持的领域，运行 governance:ruleset:domains——未经查询，绝不声称某项功能不受支持