第 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
1
该 ID 在规则所属的规则集内必须是唯一的。
2
有关标签格式的描述,请参见以下信息。
3
effort 是一个整数值,表示解决这个问题所需的工作量程度。
4
category 描述了迁移问题的严重性。该值可以是 强制的可选潜在的。有关这些类别的描述,请参阅 规则类别

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. 规则操作

规则可以包含两类操作: messagetag。每个规则包括其中一个或两个。

消息操作

当规则匹配时,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

需要自定义规则集进行分析的供应商

  • Go
  • Python
  • Node.js
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"
1
XPath 必须是有效的 XPath 表达式。
2
filepaths 是要应用 XPath 查询的文件列表。

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
1
要匹配的正则表达式模式,如 org.kubernetesoriented
2
指定需要匹配模式的确切位置,例如 IMPORT
3
使用查询检查特定注解及其元素,如 Java 代码中的名称和值。例如,以下查询与方法中的 Bean (url = "http://www.example.com”)注解匹配。
 annotated:
      pattern: org.framework.Bean
      elements:
      - name: url
        value: "http://www.example.com"

支持的位置如下:

  • 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
1
要搜索的依赖项的名称。
2
对依赖项版本进行上限。
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
1
要搜索的依赖项的名称。
2
对依赖项版本进行上限。
3
对依赖项版本的绑定较低。
2.1.1.4.1.4. dotnet 供应商

dotnet 是一个外部供应商,用于分析 .NET 和 C# 源代码。目前,供应商支持 引用 的功能。

引用

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

when:
  dotnet.referenced:
    pattern: "<pattern>" 1
    namespace: "<namespace>" 2
1
Pattern: 匹配所需参考的正则表达式模式。例如,HttpNotFound。
2
Namespace: 指定要在其中搜索的命名空间。例如: System.Web.Mvc。
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
1
Pattern : 找到匹配项时在源代码行上匹配的正则表达式模式。
2
Name :可以在模板中使用的变量名称。
3
Message: 使用自定义变量消息的模板。

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
1
该名称在提供的规则集内必须是唯一的。
2
ruleset 标签由属于规则集的所有规则继承。

要执行任何应用程序分析,请运行以下命令:将 <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 工具决定了应用程序的类型以及分析所需的相应供应商。然后,它会在具有所需依赖项和工具的容器中启动提供程序。最后,提供商使用分析器来执行一系列规则集来分析源代码。

Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

© 2024 Red Hat, Inc.