第 2 章 创建 YAML 规则
每个分析器规则是一组用于分析源代码并检测迁移问题的指令。
分析器解析用户提供的规则,将它们应用到应用程序的源代码,并为匹配规则生成问题。一个或多个规则的集合形成规则集。创建规则集提供了一种组织实现常见目标的多个规则的方法。分析器 CLI 将 rulesets 用作输入参数。
2.1. YAML 规则结构和语法
MTA 规则使用 YAML 编写。每个规则由元数据、条件和操作组成,它指示分析器在给定条件匹配时执行指定的操作。
MTA 中的 YAML 规则文件包含一个或多个 YAML 规则。
2.1.1. 规则元数据
规则元数据包含有关规则的一般信息。元数据的结构如下:
ruleId: "unique_id" 1 labels: 2 # key=value pair - "label1=val1" # valid label with value omitted - "label2" # valid label with empty value - "label3=" # subdomain prefixed key - "konveyor.io/label1=val1" effort: 1 3 category: mandatory 4
2.1.1.1. 规则标签
标签是为规则或规则集以及依赖项指定的 key=val
对。对于依赖项,供应商会在检索依赖项时添加标签。规则集上的标签由属于它的所有规则自动继承。
标签格式
标签在 labels
字段中指定为 key=val
格式的字符串列表,如下所示:
labels: - "key1=val1" - "key2=val2"
标签的键可以是子域前缀:
labels: - "konveyor.io/key1=val1"
标签的值可以为空:
labels: - "konveyor.io/key="
标签的值可以省略。在这种情况下,它将被视为空值:
labels: - "konveyor.io/key"
保留标签
分析器定义了一些具有特殊含义的标签,如下所示:
-
konveyor.io/source
:标识应用规则或规则集的源技术 -
konveyor.io/target
: 标识应用规则或规则集的目标技术
标签选择器
分析器 CLI 将 --label-selector
字段用作选项。这是一个字符串表达式,支持逻辑 AND、OR 和 NOT 操作。您可以使用它来根据其标签过滤或过滤出规则。
示例:
要过滤所有带有键
konveyor.io/source
且值为eap6
的规则:--label-selector="konveyor.io/source=eap6"
要过滤所有带有键
konveyor.io/source
和任何值标签的规则:--label-selector="konveyor.io/source"
使用
&
amp;& operator 对多个规则都匹配逻辑 AND 操作:--label-selector="key1=val1 && key2"
使用
||
运算符对多个规则执行逻辑 OR 操作:--label-selector="key1=val1 || key2"
要执行 NOT 操作来过滤使用
!
operator 设置key1=val1
标签的规则:--label-selector="!key1=val1"
使用 AND 对子表达式进行分组和控制优先级:
--label-selector="(key1=val1 || key2=val2) && !val3"
依赖项标签
分析器引擎为依赖项添加标签。这些标签提供有关依赖项的额外信息,如其编程语言以及依赖项是否为开源还是内部。
目前,分析器会将以下标签添加到依赖项中:
labels: - konveyor.io/dep-source=internal - konveyor.io/language=java
依赖项标签选择器
分析器 CLI 接受 --dep-label-selector
选项,该选项允许根据标签从依赖项生成的 filtering-in 或 filtering-out 事件。
例如,分析器将 konveyor.io/dep-source
标签添加到依赖项中,其值表示依赖项是否为已知的开源依赖项。
要排除所有此类开源依赖项的事件,您可以使用 -dep-label-selector
,如下所示:
konveyor-analyzer … --dep-label-selector !konveyor.io/dep-source=open-source
分析器中的 Java 供应商也可以向软件包列表添加一个 exclude 标签。要排除所有这样的软件包,您可以使用 --dep-label-selector
和 !
operator,如下所示:
konveyor-analyzer … --dep-label-selector !konveyor.io/exclude
2.1.1.2. 规则类别
必需
- 您必须解决成功迁移的问题,否则生成的应用程序不会成功构建或运行。此类问题的一个示例是目标平台上不支持的专有 API。
optional
- 如果您没有解决这个问题,应用程序应该可以正常工作,但结果可能不是最佳。如果您没有在迁移时进行更改,则需要在迁移完成后尽快按计划设置。例如,EJB 2.x 代码没有升级到 EJB 3。
potential
- 您需要在迁移过程中检查问题,但没有足够的信息来确定解决问题是否强制迁移成功。例如,当目标平台上没有直接兼容类型时,迁移第三方专有类型。
2.1.1.3. 规则操作
规则可以包含两类操作: message 和 tag。每个规则包括其中一个或两个。
消息操作
当规则匹配时,message 操作会创建一条消息的问题。供应商导出的自定义数据也可以在消息中使用。
Message: "helpful message about the issue"
Example:
- ruleID: test-rule when: <CONDITION> message: Test rule matched. Please resolve this migration issue.
(可选)消息可以包含超链接到外部 URL,它们提供有关问题或快速修复相关信息。
links: - url: "konveyor.io" title: "Short title for the link"
消息也可以是模板,其中包含有关通过规则上的自定义变量插入的匹配项的信息。
标签操作
tag 操作指示分析器在找到匹配项时为应用程序生成一个或多个标签。tag
字段中的每一字符串可以是以逗号分隔的标签列表。另外,您可以为标签分配类别。
tag: - "tag1,tag2,tag3" - "Category=tag4,tag5"
Example
- ruleID: test-rule when: <CONDITION> tag: - Language=Golang - Env=production - Source Code
标签可以是字符串或 key=val
对,其中密钥被视为 MTA 中的标签类别。具有标签操作的任何规则都被称为本文档中的"标记规则"。
请注意,不会为仅包含标签操作的规则创建问题。
2.1.1.4. 规则条件
每个规则都有 when
block,它指定了对 MTA 执行某个操作需要满足的条件。
when
块包含一个条件,但该条件可以在它下嵌套多个条件。
when: <condition> <nested-condition>
MTA 支持三种类型的条件: provider
、和
或
。
2.1.1.4.1. 供应商条件
应用程序分析器检测到用于构建应用程序的编程语言、框架和工具,并相应地使用语言服务器协议(LSP)为每个支持的供应商生成默认规则集。每个支持的供应商都默认定义了一个规则集,并在单独的容器中运行。
MTA 支持多语言源代码分析。使用 供应商
条件启用源代码中的特定语言。此条件定义了特定语言提供程序的搜索查询。供应商
条件还指定用于分析代码的提供程序的"功能"的"功能"。
供应商
条件格式为 < provider_name>.<capability>
:
when: <provider_name>.<capability> <input_fields>
分析器目前支持以下供应商 条件
:
-
builtin
-
java
-
go
-
dotnet
在 CLI 上分析多个应用程序时,支持提供单个报告只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议(SLA)支持,且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。
有关红帽技术预览功能支持范围的更多信息,请参阅技术预览功能支持范围。
供应商规则条件 | 供应商名称 |
---|---|
完全支持并包含在产品中的供应商 | Java |
在产品中已定义了规则的供应商 | .NET |
需要自定义规则集进行分析的供应商 |
|
2.1.1.4.1.1. 内置
供应商
内置
是一个内部供应商,它可以分析引擎生成的各种文件和内部元数据。
这个供应商有以下功能:
-
file
-
FileContent
-
xml
-
json
-
hasTags
file
文件
功能可让供应商搜索与给定模式匹配的源代码中的文件。
when: builtin.file: pattern: "<regex_to_match_filenames>"
FileContent
filecontent
功能使供应商能够搜索与给定模式匹配的内容。
when: builtin.filecontent: filePattern: "<regex_to_match_filenames_to_scope_search>" pattern: "<regex_to_match_content_in_the_matching_files>"
xml
xml
功能可让供应商查询提供的 XML 文件列表中的 XPath 表达式。此功能采用 2 个输入参数 xpath
和 文件路径
。
when: builtin.xml: xpath: "<xpath_expressions>" 1 filepaths: 2 - "/src/file1.xml" - "/src/file2.xml"
json
json
功能可让供应商在提供的 JSON 文件列表中查询 XPath 表达式。目前,json
仅采用 XPath 作为输入,并对代码库中的所有 JSON 文件执行搜索。
when:
builtin.json:
xpath: "<xpath_expressions>" 1
- 1
XPath
必须是有效的 XPath 表达式。
hasTags
hasTags
功能使供应商能够查询应用程序标签。它查询内部数据结构,以检查应用是否有给定的标签。
when:
# when more than one tag is given, a logical AND is implied
hasTags: 1
- "tag1"
- "tag2"
- 1
- 当有多个标签时,意味着一个逻辑 AND。
2.1.1.4.1.2. Java
供应商
java
供应商分析 Java 源代码。
这个供应商有以下功能:
-
引用
-
依赖项
引用
引用
的功能可让供应商在源代码中查找引用。此功能采用三种输入参数: 模式
、位置
和 注释
。
when: java.referenced: pattern: "<pattern>" 1 location: "<location>" 2 annotated: "<annotated>" 3
支持的位置如下:
-
CONSTRUCTOR_CALL
-
TYPE
-
继承
-
METHOD_CALL
-
注解
-
IMPLEMENTS_TYPE
-
ENUM_CONSTANT
-
RETURN_TYPE
-
IMPORT
-
VARIABLE_DECLARATION
-
字段
-
方法
依赖项
依赖项
功能可让供应商查找给定应用程序的依赖项。MTA 生成应用程序的依赖项列表,您可以使用此功能查询列表,并检查是否在依赖项版本范围内的应用程序中存在特定的依赖项。
when: java.dependency: name: "<dependency_name>" 1 upperbound: "<version_string>" 2 lowerbound: "<version_string>" 3
2.1.1.4.1.3. Go
供应商
Go
供应商分析 Go 源代码。此提供程序的功能 被引用
,依赖项
为。
引用
引用
的功能可让供应商在源代码中查找引用。
when: go.referenced: "<regex_to_find_reference>"
依赖项
依赖项
功能可让供应商查找应用程序的依赖项。
when: go.dependency: name: "<dependency_name>" 1 upperbound: "<version_string>" 2 lowerbound: "<version_string>" 3
2.1.1.4.1.4. dotnet
供应商
dotnet
是一个外部供应商,用于分析 .NET 和 C# 源代码。目前,供应商支持 引用
的功能。
引用
引用
的功能可让供应商在源代码中查找引用。
when: dotnet.referenced: pattern: "<pattern>" 1 namespace: "<namespace>" 2
2.1.1.4.2. 自定义变量
供应商条件可以关联有自定义变量。您可以使用自定义变量从源代码中的匹配行捕获相关信息。这些变量的值与源代码中匹配的数据进行干预。这些值可用于在规则的操作中生成详细的模板消息(请参阅 消息操作)。它们可以添加到 customVariables
字段中的规则中:
- ruleID: lang-ref-004 customVariables: - pattern: '([A-z]+)\.get\(\)' 1 name: VariableName 2 message: "Found generic call - {{ VariableName }}" 3 when: java.referenced: location: METHOD_CALL pattern: com.example.apps.GenericClass.get
2.1.1.5. 逻辑条件
分析器提供两个基本逻辑条件,和
或
,供您聚合其他条件的结果并创建更复杂的查询。
2.1.1.5.1. 和
条件
and
条件对条件数组的结果执行逻辑 AND 操作。当 所有子
条件都匹配时,和 条件都匹配。
when: and: - <condition1> - <condition2>
Example
when: and: - java.dependency: name: junit.junit upperbound: 4.12.2 lowerbound: 4.4.0 - java.referenced: location: IMPORT pattern: junit.junit
条件也可以嵌套在其他条件内。
Example
when: and: - and: - go.referenced: "*CustomResourceDefinition*" - java.referenced: pattern: "*CustomResourceDefinition*" - go.referenced: "*CustomResourceDefinition*"
2.1.1.5.2. 或
条件
or
条件对条件数组的结果执行逻辑 OR 操作。当任何子条件都匹配时,或
条件会匹配。
when: or: - <condition1> - <condition2>
Example
when: or: - java.dependency: name: junit.junit upperbound: 4.12.2 lowerbound: 4.4.0 - java.referenced: location: IMPORT pattern: junit.junit
2.1.2. Rulesets(规则集)
组规则形成规则集。MTA 不需要每个规则文件属于规则集,但您可以使用规则集来对实现常见目标的多个规则进行分组,并将规则传递给规则引擎。
您可以通过将一个或多个 YAML 规则放在目录中,并在目录 root 中创建 ruleset.yaml
文件来创建规则集。当您使用- rules
选项将该目录作为输入传递给 MTA CLI 时,此目录中的所有规则都将被视为 ruleset.yaml
文件定义的规则集的一部分。
ruleset.yaml
文件存储规则集的元数据。
name: "Name of the ruleset" 1 description: "Description of the ruleset" labels: 2 - key=val
要执行任何应用程序分析,请运行以下命令:将 <application_to_analyze> 替换为您的应用程序,<output_dir> 替换为您选择的目录,<custom_rule_dir> 替换为自定义规则集文件。
$ mta-cli analyze --input=<application_to_analyze> --output=<output_dir> --rules=<custom_rule_dir> --enable-default-rulesets=false
在启动时,mta-cli 工具决定了应用程序的类型以及分析所需的相应供应商。然后,它会在具有所需依赖项和工具的容器中启动提供程序。最后,提供商使用分析器来执行一系列规则集来分析源代码。