第 2 章创建 YAML 规则

每个分析器规则是一组用来分析源代码并检测迁移问题的指令。

分析器解析用户提供的规则，将它们应用到应用程序的源代码，并为匹配的规则生成问题。由一个或多个规则的集合组成一个规则集。创建规则集提供了一种方法来组织多个实现常见目标的规则。分析器 CLI 使用规则集作为输入参数。

2.1. YAML 规则结构和语法
复制链接

MTA 规则使用 YAML 编写。每个规则由元数据、条件和操作组成，指示分析器在给定条件匹配时采取指定操作。

MTA 中的 YAML 规则文件包含一个或多个 YAML 规则。

2.1.1. 规则元数据
复制链接

规则元数据包含有关规则的常规信息。元数据结构如下：

ruleId: "unique_id" 
labels: 
  # 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 
category: mandatory

ruleId: "unique_id"


labels:


  # 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


category: mandatory

Copy to Clipboard

Toggle word wrap

1: 该 ID 在规则所属的规则集中必须是唯一的。
2: 有关标签格式的描述信息，请参见以下。
3: effort 是一个整数值，指示解决这个问题所需的工作量程度。
4: category 描述了迁移问题的严重性。该值可以是 强制的、可选 或 潜在的。有关这些类别的描述，请参阅规则类别。

2.1.1.1. 规则标签
复制链接

标签是为规则或规则集以及依赖项指定的 key=val 对。对于依赖项，供应商在检索它们时向依赖项添加标签。规则集上的标签由属于它的所有规则自动继承。

标签格式

标签在 labels 字段中指定，作为 key=val 格式的字符串列表，如下所示：

labels:
- "key1=val1"
- "key2=val2"

labels:
- "key1=val1"
- "key2=val2"

Copy to Clipboard

Toggle word wrap

标签的密钥可以是 subdomain-prefix：

labels:
- "konveyor.io/key1=val1"

labels:
- "konveyor.io/key1=val1"

Copy to Clipboard

Toggle word wrap

标签值可以为空：

labels:
- "konveyor.io/key="

labels:
- "konveyor.io/key="

Copy to Clipboard

Toggle word wrap

标签值可以省略。在这种情况下，它被视为空值：

labels:
- "konveyor.io/key"

labels:
- "konveyor.io/key"

Copy to Clipboard

Toggle word wrap

保留标签

分析器定义一些具有特殊含义的标签，如下所示：

konveyor.io/source: 标识规则或规则集应用到的源技术
konveyor.io/target: 标识规则或规则集的目标技术

标签选择器

分析器 CLI 将 --label-selector 字段用作选项。它是支持逻辑 AND, OR 和 NOT 操作的字符串表达式。您可以使用它根据标签过滤或过滤出规则。

示例：

要过滤所有具有键 konveyor.io/source 和 value eap6 的标签的规则：
--label-selector="konveyor.io/source=eap6"
要过滤所有具有键 konveyor.io/source 和 any 值的标签的规则：
--label-selector="konveyor.io/source"
使用 & amp;& operator 对多个规则执行逻辑 AND 操作：
--label-selector="key1=val1 && key2"
使用 || 运算符对多个规则执行逻辑 OR 操作：
--label-selector="key1=val1 || key2"
要执行 NOT 操作，以过滤掉使用 ! 运算符设置的 key1=val1 标签的规则：
--label-selector="!key1=val1"
使用 AND 对子表达式和控制优先级进行分组：
--label-selector="(key1=val1 || key2=val2) && !val3"

依赖项标签

分析器引擎向依赖项添加标签。这些标签提供有关依赖项的额外信息，如其编程语言以及依赖项是开源还是内部。

目前，分析器将以下标签添加到依赖项中：

labels:
- konveyor.io/dep-source=internal
- konveyor.io/language=java

labels:
- konveyor.io/dep-source=internal
- konveyor.io/language=java

Copy to Clipboard

Toggle word wrap

依赖项标签选择器

分析器 CLI 接受 --dep-label-selector 选项，该选项允许根据标签从依赖项生成的过滤或过滤出事件。

例如，分析器会将 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。
潜在
- 您需要在迁移过程中检查问题，但没有足够的信息来确定解决问题是否必须成功。当目标平台上没有直接兼容类型时，会迁移第三方专有类型。

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.

- ruleID: test-rule
  when:
    <CONDITION>
  message: Test rule matched. Please resolve this migration issue.

Copy to Clipboard

Toggle word wrap

另外，消息可以包含到外部 URL 的超链接，以提供有关此问题或快速修复的相关信息。

links:
  - url: "konveyor.io"
    title: "Short title for the link"

links:
  - url: "konveyor.io"
    title: "Short title for the link"

Copy to Clipboard

Toggle word wrap

消息也可以是模板，以包含有关通过规则上的自定义变量进行匹配的信息。

标签操作

标签操作指示在找到匹配项时为应用程序生成一个或多个标签。tag 字段中的每一字符串可以是以逗号分隔的标签列表。另外，您可以为标签分配类别。

tag:
  - "tag1,tag2,tag3"
  - "Category=tag4,tag5"

tag:
  - "tag1,tag2,tag3"
  - "Category=tag4,tag5"

Copy to Clipboard

Toggle word wrap

Example

- ruleID: test-rule
  when:
    <CONDITION>
  tag:
  - Language=Golang
  - Env=production
  - Source Code

- ruleID: test-rule
  when:
    <CONDITION>
  tag:
  - Language=Golang
  - Env=production
  - Source Code

Copy to Clipboard

Toggle word wrap

标签可以是字符串或 key=val 对，其中键被视为 MTA 中的标签类别。任何具有标签操作的规则都被称为本文档中的"标记规则"。

请注意，不会为仅包含标签操作的规则创建问题。

2.1.1.4. 规则条件
复制链接

每个规则都有一个 when 块，它指定了一个需要满足 MTA 执行特定操作的条件。

when 块包含一个条件，但该条件可以在它下嵌套多个条件。

when:
  <condition>
    <nested-condition>

when:
  <condition>
    <nested-condition>

Copy to Clipboard

Toggle word wrap

MTA 支持三种类型的条件： 提供程序、和 或。

2.1.1.4.1. 供应商条件
复制链接

MTA 支持多语言源代码分析。使用 供应商 条件启用源代码中的特定语言。此条件定义特定语言供应商的搜索查询。供应商 条件还指定提供程序的"功能"用于分析代码。

供应商 条件格式为 < provider_name>.<capability&gt; :

when:
  <provider_name>.<capability>
    <input_fields>

when:
  <provider_name>.<capability>
    <input_fields>

Copy to Clipboard

Toggle word wrap

分析器目前支持以下供应商 条件 ：

builtin
java
Go

2.1.1.4.1.1. 内置供应商
复制链接

builtin 是一种内部提供程序，可以分析引擎生成的各种文件和内部元数据。

此供应商具有以下功能：

file
FileContent
xml
json
hasTags

file

文件 功能使提供程序能够搜索与给定模式匹配的源代码中的文件。

when:
  builtin.file:
    pattern: "<regex_to_match_filenames>"

when:
  builtin.file:
    pattern: "<regex_to_match_filenames>"

Copy to Clipboard

Toggle word wrap

FileContent

filecontent 功能可让提供程序搜索与给定模式匹配的内容。

when:
  builtin.filecontent:
    filePattern: "<regex_to_match_filenames_to_scope_search>"
    pattern: "<regex_to_match_content_in_the_matching_files>"

when:
  builtin.filecontent:
    filePattern: "<regex_to_match_filenames_to_scope_search>"
    pattern: "<regex_to_match_content_in_the_matching_files>"

Copy to Clipboard

Toggle word wrap

xml

xml 功能可让供应商在提供的 XML 文件列表上查询 XPath 表达式。该功能采用 2 个输入参数 xpath 和 文件路径。

when:
  builtin.xml:
    xpath: "<xpath_expressions>" 
    filepaths: 
      - "/src/file1.xml"
      - "/src/file2.xml"

when:
  builtin.xml:
    xpath: "<xpath_expressions>"


    filepaths:


      - "/src/file1.xml"
      - "/src/file2.xml"

Copy to Clipboard

Toggle word wrap

1: XPath 必须是有效的 XPath 表达式。
2: filepaths 是要应用 XPath 查询的文件列表。

json

json 功能可让供应商在提供的 JSON 文件列表中查询 XPath 表达式。目前，json 仅使用 XPath 作为输入，并对代码库中的所有 JSON 文件执行搜索。

when:
  builtin.json:
    xpath: "<xpath_expressions>"

when:
  builtin.json:
    xpath: "<xpath_expressions>"

Copy to Clipboard

Toggle word wrap

1: XPath 必须是有效的 XPath 表达式。

hasTags

hasTags 功能使提供程序能够查询应用标签。它查询内部数据结构，以检查应用是否具有给定的标签。

when:
  # when more than one tags are given, a logical AND is implied
  hasTags: 
    - "tag1"
    - "tag2"

when:
  # when more than one tags are given, a logical AND is implied
  hasTags:


    - "tag1"
    - "tag2"

Copy to Clipboard

Toggle word wrap

1: 指定了多个标签时，代表逻辑 AND。

2.1.1.4.1.2. Java 供应商
复制链接

java 提供程序分析 Java 源代码。

此供应商具有以下功能：

referenced
依赖项.

referenced

引用 的功能可让供应商在源代码中查找引用。该功能采用两个输入参数，即 模式 和位置。

when:
  java.referenced:
    pattern: "<pattern>" 
    location: "<location>"

when:
  java.referenced:
    pattern: "<pattern>"


    location: "<location>"

Copy to Clipboard

Toggle word wrap

1: 要匹配的 RegEx 模式，例如 org.kubernetes memcached
2: 指定需要匹配模式的确切位置，如 IMPORT

支持的位置如下：

CONSTRUCTOR_CALL
TYPE
继承
METHOD_CALL
注解
IMPLEMENTS_TYPE
ENUM_CONSTANT
RETURN_TYPE
IMPORT
变量_DECLARATION

依赖项

依赖项 功能使供应商能够查找给定应用程序的依赖项。MTA 生成应用程序依赖项列表，您可以使用此功能查询列表，并检查应用程序是否在指定范围内的依赖项存在。

when:
  java.dependency:
    name: "<dependency_name>" 
    upperbound: "<version_string>" 
    lowerbound: "<version_string>"

when:
  java.dependency:
    name: "<dependency_name>"


    upperbound: "<version_string>"


    lowerbound: "<version_string>"

Copy to Clipboard

Toggle word wrap

1: 要搜索的依赖项名称
2: 依赖于依赖项版本的上限
3: 降低依赖项版本绑定

2.1.1.4.1.3. Go 供应商
复制链接

Go 供应商分析 Go 源代码。此提供程序的功能 被引用 和依赖项。

referenced

引用 的功能可让供应商在源代码中查找引用。

when:
  go.referenced: "<regex_to_find_reference>"

when:
  go.referenced: "<regex_to_find_reference>"

Copy to Clipboard

Toggle word wrap

依赖项

依赖项 功能可让供应商查找应用程序的依赖项。

when:
  go.dependency:
    name: "<dependency_name>" 
    upperbound: "<version_string>" 
    lowerbound: "<version_string>"

when:
  go.dependency:
    name: "<dependency_name>"


    upperbound: "<version_string>"


    lowerbound: "<version_string>"

Copy to Clipboard

Toggle word wrap

1: 要搜索的依赖项名称
2: 依赖于依赖项版本的上限
3: 降低依赖项版本绑定

2.1.1.4.2. 自定义变量
复制链接

供应商条件可以关联自定义变量。您可以使用自定义变量从源代码中匹配行捕获相关信息。这些变量的值与源代码中匹配的数据进行干预。这些值可用于在规则的操作中生成详细的模板消息（请参阅消息操作）。它们可以添加到 customVariables 字段中的规则中：

- ruleID: lang-ref-004
   customVariables:
   - pattern: '([A-z]+)\.get\(\)' 
      name: VariableName 
    message: "Found generic call - {{ VariableName }}" 
  when:
      java.referenced:
          location: METHOD_CALL
          pattern: com.example.apps.GenericClass.get

- ruleID: lang-ref-004
   customVariables:
   - pattern: '([A-z]+)\.get\(\)'


      name: VariableName


    message: "Found generic call - {{ VariableName }}"


  when:
      java.referenced:
          location: METHOD_CALL
          pattern: com.example.apps.GenericClass.get

Copy to Clipboard

Toggle word wrap

1: Pattern ：找到匹配项时，源代码行中匹配的 RegEx 模式
2: 名称 ：可以在模板中使用的变量名称
3: Message : 使用自定义变量消息的模板

2.1.1.5. 逻辑条件
复制链接

分析器提供了两个基本逻辑条件，和 或，它们可让您聚合其他条件的结果并创建更复杂的查询。

2.1.1.5.1. 和条件
复制链接

和 条件对一组条件的结果执行逻辑 AND 操作。当其 所有子 条件都匹配时，和条件都匹配。

when:
  and:
    - <condition1>
    - <condition2>

when:
  and:
    - <condition1>
    - <condition2>

Copy to Clipboard

Toggle word wrap

Example

when:
  and:
    - java.dependency:
        name: junit.junit
        upperbound: 4.12.2
        lowerbound: 4.4.0
    - java.referenced:
        location: IMPORT
        pattern: junit.junit

when:
  and:
    - java.dependency:
        name: junit.junit
        upperbound: 4.12.2
        lowerbound: 4.4.0
    - java.referenced:
        location: IMPORT
        pattern: junit.junit

Copy to Clipboard

Toggle word wrap

条件也可以嵌套在其他条件内。

Example

when:
  and:
  - and:
    - go.referenced: "*CustomResourceDefinition*"
    - java.referenced:
        pattern: "*CustomResourceDefinition*"
  - go.referenced: "*CustomResourceDefinition*"

when:
  and:
  - and:
    - go.referenced: "*CustomResourceDefinition*"
    - java.referenced:
        pattern: "*CustomResourceDefinition*"
  - go.referenced: "*CustomResourceDefinition*"

Copy to Clipboard

Toggle word wrap

2.1.1.5.2. 或条件
复制链接

或 条件对一组条件的结果执行逻辑 OR 操作。当其 任何子 条件匹配时，或 条件匹配。

when:
  or:
    - <condition1>
    - <condition2>

when:
  or:
    - <condition1>
    - <condition2>

Copy to Clipboard

Toggle word wrap

Example

when:
  or:
  - java.dependency:
      name: junit.junit
      upperbound: 4.12.2
      lowerbound: 4.4.0
  - java.referenced:
      location: IMPORT
      pattern: junit.junit

when:
  or:
  - java.dependency:
      name: junit.junit
      upperbound: 4.12.2
      lowerbound: 4.4.0
  - java.referenced:
      location: IMPORT
      pattern: junit.junit

Copy to Clipboard

Toggle word wrap

2.1.2. Rulesets（规则集）
复制链接

组规则形成规则集。MTA 不需要每个规则文件都属于规则集，但您可以使用规则集对实现通用目标并传递规则到规则集的多个规则进行分组。

您可以通过将一个或多个 YAML 规则放在目录中并创建 ruleset.yaml 文件来创建规则集。当您使用 --rules 选项将此目录作为输入传递给 MTA CLI 时，此目录中的所有规则都将被视为 ruleset.yaml 文件定义的规则集的一部分。

ruleset.yaml 文件存储规则集的元数据。

name: "Name of the ruleset" 
description: "Description of the ruleset"
labels: 
  - key=val

name: "Name of the ruleset"


description: "Description of the ruleset"
labels:


  - key=val

Copy to Clipboard

Toggle word wrap

1: 名称在提供的规则集中必须是唯一的。
2: ruleset 标签由属于规则集的所有规则继承。

第 2 章创建 YAML 规则

2.1. YAML 规则结构和语法
复制链接

2.1.1. 规则元数据
复制链接

2.1.1.1. 规则标签
复制链接

2.1.1.2. 规则类别
复制链接

2.1.1.3. 规则操作
复制链接

2.1.1.4. 规则条件
复制链接

2.1.1.4.1. 供应商条件
复制链接

2.1.1.4.1.1. 内置供应商
复制链接

2.1.1.4.1.2. Java 供应商
复制链接

2.1.1.4.1.3. Go 供应商
复制链接

2.1.1.4.2. 自定义变量
复制链接

2.1.1.5. 逻辑条件
复制链接

2.1.1.5.1. 和条件
复制链接

2.1.1.5.2. 或条件
复制链接

2.1.2. Rulesets（规则集）
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

第 2 章 创建 YAML 规则

2.1. YAML 规则结构和语法复制链接链接已复制到粘贴板!

2.1.1. 规则元数据复制链接链接已复制到粘贴板!

2.1.1.1. 规则标签复制链接链接已复制到粘贴板!

2.1.1.2. 规则类别复制链接链接已复制到粘贴板!

2.1.1.3. 规则操作复制链接链接已复制到粘贴板!

2.1.1.4. 规则条件复制链接链接已复制到粘贴板!

2.1.1.4.1. 供应商条件复制链接链接已复制到粘贴板!

2.1.1.4.1.1. 内置 供应商复制链接链接已复制到粘贴板!

2.1.1.4.1.2. Java 供应商复制链接链接已复制到粘贴板!

2.1.1.4.1.3. Go 供应商复制链接链接已复制到粘贴板!

2.1.1.4.2. 自定义变量复制链接链接已复制到粘贴板!

2.1.1.5. 逻辑条件复制链接链接已复制到粘贴板!

2.1.1.5.1. 和 条件复制链接链接已复制到粘贴板!

2.1.1.5.2. 或 条件复制链接链接已复制到粘贴板!

2.1.2. Rulesets（规则集）复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

第 2 章创建 YAML 规则

2.1. YAML 规则结构和语法
复制链接

2.1.1. 规则元数据
复制链接

2.1.1.1. 规则标签
复制链接

2.1.1.2. 规则类别
复制链接

2.1.1.3. 规则操作
复制链接

2.1.1.4. 规则条件
复制链接

2.1.1.4.1. 供应商条件
复制链接

2.1.1.4.1.1. 内置供应商
复制链接

2.1.1.4.1.2. Java 供应商
复制链接

2.1.1.4.1.3. Go 供应商
复制链接

2.1.1.4.2. 自定义变量
复制链接

2.1.1.5. 逻辑条件
复制链接

2.1.1.5.1. 和条件
复制链接

2.1.1.5.2. 或条件
复制链接

2.1.2. Rulesets（规则集）
复制链接