红帽全球峰会规则开发指南
创建自定义规则以增强迁移覆盖。
摘要
使开源包含更多
红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始：master、slave、黑名单和白名单。由于此项工作十分艰巨，这些更改将在即将推出的几个发行版本中逐步实施。有关更多详情，请参阅我们的首席技术官 Chris Wright 提供的消息。
第 1 章 简介
1.1. 关于规则开发指南
本指南适用于希望为应用程序(MTA)工具创建自定义基于 YAML 的规则的软件工程师。
详情请参阅 Migration Toolkit for Applications 简介 for a overview 和 CLI 指南。
1.1.1. 本指南使用
本指南使用 <MTA_HOME> 可替换变量来指示您的 MTA 安装的路径。
mta-7.3.2-cli<OS>.zip* 提取一个名为 mta-cli 的二进制文件。
在本指南中遇到 <MTA_HOME> 时，将其替换为 MTA 安装的实际路径。
1.2. MTA 规则
Migration Toolkit for Applications (MTA)包含基于规则的迁移工具（分析器），可用于分析您计划迁移的应用程序用户界面(API)、技术和架构。MTA 分析器规则使用以下规则模式：
when(condition) message(message) tag(tags)
when(condition)
message(message)
tag(tags)您可以在内部使用 MTA 规则来执行以下任务：
- 从存档中提取文件.
- 解译文件。
- 扫描和分类文件类型。
- 分析 XML 和其他文件内容。
- 分析应用程序代码。
- 构建报告。
MTA 根据规则执行结果构建数据模型，并将组件数据和关系存储在图形数据库中。然后，可以根据迁移规则的要求和报告目的来查询和更新此数据库。
您可以创建自己的自定义分析器规则。您可以使用自定义规则来识别提供标准迁移规则未涵盖的自定义库或其他组件。
第 2 章 创建 YAML 规则
每个分析器规则是一组用于分析源代码并检测迁移问题的指令。
分析器解析用户提供的规则，将它们应用到应用程序的源代码，并为匹配规则生成问题。
一个或多个规则的集合形成规则集。创建规则集提供了一种组织实现常见目标的多个规则的方法。
分析器 CLI 将 rulesets 用作输入参数。
2.1. YAML 规则结构和语法
规则用 YAML 编写。它们由：
- metadata
- conditions
- 操作
规则指示分析器在给定条件匹配时执行指定的操作。
MTA 中的 YAML 规则文件包含一个或多个 YAML 规则。
2.1.1. 规则元数据
规则元数据包含有关规则的一般信息。元数据的结构如下：
2.2. 规则标签
标签是为规则或规则集以及依赖项指定的 key=val 对。对于依赖项，供应商会在检索依赖项时添加标签。规则集上的标签由属于它的所有规则自动继承。
标签格式
标签在 labels 字段中指定为 key=val 格式的字符串列表，如下所示：
labels: - "key1=val1" - "key2=val2"
labels:
- "key1=val1"
- "key2=val2"标签的键可以是子域前缀：
labels: - "konveyor.io/key1=val1"
labels:
- "konveyor.io/key1=val1"标签的值可以为空：
labels: - "konveyor.io/key="
labels:
- "konveyor.io/key="标签的值可以省略。在这种情况下，它将被视为空值：
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"使用
&& 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
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.3. 创建基本 YAML 规则
本节论述了如何创建基本 MTA YAML 规则。假设您已安装了 MTA。有关安装说明，请参阅 MTA CLI 指南。
2.3.1. 创建基本 YAML 规则模板
基于 MTA YAML 的规则有以下基本结构：
when(condition) message(message) tag(tags)
when(condition)
message(message)
tag(tags)流程
在
/home/<USER>/ 目录中，创建一个文件，其中包含 YAML 规则的基本语法，如下所示：Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.3.2. 规则类别
-
必需：您必须解决这个问题才能成功进行迁移。如果不进行更改，则生成的应用不会成功构建或运行。示例包括替换目标平台不支持的专有 API。 -
可选：如果您不解决这个问题，应用程序应该可以正常工作，但结果可能不是最佳状态。如果您没有在迁移时进行更改，建议在迁移完成后马上将其包含在计划中。 -
潜在的：您需要在迁移过程中检查问题，但没有足够的详细信息来确定任务是否强制迁移成功。例如，当目标平台上没有直接兼容类型时，迁移第三方专有类型。
2.3.3. 规则操作
规则可包括以下类型的操作：
- message
- tag
每个规则包括其中一个或两个。
消息操作
当消息操作与规则匹配时，它会创建一个问题。供应商导出的自定义数据可以在消息中使用。
- 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.（可选）消息可以包含超链接到外部 URL，它们提供有关问题或快速修复相关信息。
links:
- url: "konveyor.io"
title: "Short title for the link"
links:
- url: "konveyor.io"
title: "Short title for the link"消息也可以是模板，其中包含有关通过规则上的自定义变量插入的匹配项的信息。
2.3.4. 规则条件
每个规则都有 when block，它指定了对 MTA 执行某个操作需要满足的条件。
when 块包含一个条件，但该条件可以在它下嵌套多个条件。
when:
<condition>
<nested-condition>
when:
<condition>
<nested-condition>MTA 支持以下类型条件：
-
provider -
and -
或者
2.3.5. 标签操作
tag 操作指示分析器在找到匹配项时为应用程序生成一个或多个标签。tag 字段中的每一字符串可以是以逗号分隔的标签列表。另外，您可以为标签分配类别。
tag: - "tag1,tag2,tag3" - "Category=tag4,tag5"
tag:
- "tag1,tag2,tag3"
- "Category=tag4,tag5"Example
标签可以是字符串或 key=val 对，其中密钥被视为 MTA 中的标签类别。具有标签操作的任何规则都被称为本文档中的"标记规则"。
没有为仅包含标签操作的规则创建问题。
2.3.6. 消息操作
当规则匹配时，使用消息操作来生成指定消息的问题，例如：
# When a match is found, the analyzer generates incidents with the same message. message: "helpful message about the violation"
# When a match is found, the analyzer generates incidents with the same message.
message: "helpful message about the violation"您还可以创建一个模板消息，使其包含通过规则上的自定义变量插入的匹配项的信息。
2.3.7. hyperlinks
超链接可以和 消息 或标签 操作一起提供，以提供与问题相关的信息，已发现：
2.3.8. 供应商条件
分析器引擎可使用 提供程序 启用多语言源代码分析。技术的源代码由供应商分析。
供应商发布在功能方面可以使用源代码的功能。
供应商条件指示分析器使用特定的提供程序及其其中一个功能。通常，它遵循 < provider_name>.<capability> 模式。
when:
<provider_name>.<capability>
<input_fields>
when:
<provider_name>.<capability>
<input_fields>
分析器目前支持以下供应商 条件 ：
-
builtin -
java -
go -
dotnet
在 CLI 上分析多个应用程序时，支持提供单个报告只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。
有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。
| 供应商规则条件 | 供应商名称 |
|---|---|
| 完全支持并包含在产品中的供应商 | Java |
| 在产品中已定义了规则的供应商 | .NET |
| 需要自定义规则集进行分析的供应商 |
|
根据提供程序，条件的字段，如上例中的模式和位置更改。
有些提供程序具有 dependency_ 功能。dependency_capability 表示该提供程序为给定应用程序生成依赖项列表。
您可以使用 dependency_condition 查询此列表，并检查应用程序是否存在带有版本范围的特定依赖项。
例如，要检查 Java 应用程序是否有特定依赖项，您可以创建一个 java.dependency 条件：
when:
java.dependency:
name: junit.junit
upperbound: 4.12.2
lowerbound: 4.4.0
when:
java.dependency:
name: junit.junit
upperbound: 4.12.2
lowerbound: 4.4.0分析器 目前支持以下提供程序：
-
builtin -
java -
go -
generic
下表总结了所有供应商及其功能：
| 供应商名称 | 功能 | 描述 |
|---|---|---|
|
| 引用 | 查找带有可选代码位置的模式参考，以进行详细搜索。 |
| dependency | 检查应用程序是否有给定的依赖项。 | |
|
| xml | 使用 xpath 查询搜索 XML 文件。 |
|
|
使用 | |
| FileContent | 使用正则表达式模式搜索常规文件中的内容。 | |
| file | 查找名称与给定模式匹配的文件。 | |
| hasTags | 检查是否使用标记规则为应用程序创建了标签。 | |
|
| 引用 | 查找对模式的引用。 |
| dependency | 检查应用程序是否有给定的依赖项。 |
按照上表中示例，您可以创建不包含任何条件字段的条件的第一个部分。
Example
创建使用 引用 能力的 java 供应商条件：
when:
java.referenced:
<fields>
when:
java.referenced:
<fields>
根据 供应商和 功能，条件中会出现不同的 < fields& gt;。
下表总结了可用的供应商、其功能及其所有字段：
| 供应商 | 功能 | 字段 | 必填 | 描述 |
|---|---|---|---|---|
| java | 引用 | pattern | 是 | 正则表达式模式 |
| 位置 | 否 | 源代码位置（请参阅 Java 位置） | ||
| annotated | 否 | 用于检查注解的额外查询（请参阅 注解检查）。 | ||
| dependency | name | 是 | 依赖项的名称。 | |
| nameregex | 否 | 与名称匹配的正则表达式模式。 | ||
| upperbound | 否 | 匹配低于或等于的版本 | ||
| lowerbound | 否 | 匹配大于或等于的版本 | ||
| builtin | xml | xpath | 是 | XPath 查询 |
| 命名空间 | 否 | 映射到范围向下查询到命名空间 | ||
| filepaths | 否 | 用于范围搜索的可选文件列表 | ||
| json | xpath | 是 | XPath 查询 | |
| filepaths | 否 | 用于范围搜索的可选文件列表 | ||
| FileContent | pattern | 是 | 在内容中匹配的正则表达式模式 | |
| filePattern | 否 | 仅在与此模式匹配的文件中搜索 | ||
| 文件 hasTags | pattern | 是 | 查找与此模式匹配的文件 | |
| hasTags | 这是字符串标签的内联列表。请参阅 Tag 操作 | |||
| go | 引用 | pattern | 是 | 正则表达式模式. |
| dependency | name | 是 | 依赖项的名称。 | |
| nameregex | 否 | 与名称匹配的正则表达式模式。 | ||
| upperbound | 否 | 匹配低于或等于的版本。 | ||
| lowerbound | 否 | 匹配大于或等于的版本。 |
Example
例如，要完成我们之前创建的 java 条件示例，请搜索软件包的引用：
when:
java.referenced:
location: PACKAGE
pattern: org.jboss*
when:
java.referenced:
location: PACKAGE
pattern: org.jboss*2.3.8.1. 内置供应商
内置 是一个内部供应商，它可以分析引擎生成的各种文件和内部元数据。这个供应商有以下功能：
-
file -
FileContent -
xml -
json -
hasTags
file
通过使用 文件 功能，提供程序搜索源代码中与给定模式匹配的文件。
when:
builtin.file:
pattern: "<regex_to_match_filenames>"
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>"
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 和 文件路径。
json
通过使用 json 功能，供应商在提供的 JSON 文件列表中查询 XPath 表达式。目前，json 仅采用 XPath 作为输入，并对代码库中的所有 JSON 文件执行搜索。
when:
builtin.json:
xpath: "<xpath_expressions>"
when:
builtin.json:
xpath: "<xpath_expressions>" - 1
XPath必须是有效的 XPath 表达式。
hasTags
通过使用 hasTags 功能，供应商查询应用程序标签。它查询内部数据结构，以检查应用是否有给定的标签。
when:
# when more than one tag is given, a logical AND is implied
hasTags:
- "tag1"
- "tag2"
when:
# when more than one tag is given, a logical AND is implied
hasTags:
- "tag1"
- "tag2"- 1
- 当有多个标签时，意味着一个逻辑 AND。
2.3.8.2. Java 供应商
java 供应商分析 Java 源代码。
这个供应商有以下功能：
-
引用 -
依赖项
引用
通过使用 引用 的功能，供应商会在源代码中找到引用。此功能采用三种输入参数： 模式、位置 和 注释。
when:
java.referenced:
pattern: "<pattern>"
location: "<location>"
annotated: "<annotated>"
when:
java.referenced:
pattern: "<pattern>"
location: "<location>"
annotated: "<annotated>" - 1
- 要匹配的正则表达式模式。
- 2
- 指定需要匹配模式的确切位置，例如
IMPORT。 - 3
- 使用查询在 Java 代码中检查特定注解及其元素，如名称和值。例如，以下查询与方法中的
Bean(url = "http://www.example.com”)注解匹配。annotated: pattern: org.framework.Bean elements: - name: url value: "http://www.example.com"annotated: pattern: org.framework.Bean elements: - name: url value: "http://www.example.com"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.3.8.3. Java 位置
java 提供程序允许将搜索范围到特定的源代码位置。
- 重要信息 ：IMPORT 允许搜索类导入。它可以与 FQN 或星号一起使用，以允许更宽匹配：
java.referenced: pattern: org.apache.lucene.search* location: IMPORT
java.referenced:
pattern: org.apache.lucene.search*
location: IMPORT在每个导入时匹配：
import org.apache.lucene.search.Query; import org.apache.lucene.search.Sort; import org.apache.lucene.search.SortField;
import org.apache.lucene.search.Query;
import org.apache.lucene.search.Sort;
import org.apache.lucene.search.SortField;建议直接在软件包后面放置结果范围，而不是在点后：
- PACKAGE: PACKAGE 位置与软件包使用匹配，可以是导入或用作代码中完全限定名称的一部分：
java.referenced: pattern: org.apache.lucene.search* location: PACKAGE
java.referenced:
pattern: org.apache.lucene.search*
location: PACKAGE对导入和完全限定的使用匹配：
import org.apache.lucene.search.*;
import org.apache.lucene.search.*;public class Test {
private org.apache.lucene.search.Query query;
}
public class Test {
private org.apache.lucene.search.Query query;
}
(*)在软件包-separation dot (.)之后正确，以获得更好的结果。
- CONSTRUCTOR_CALL 和 METHOD_CALL: 用于分别匹配构造器和方法。模式可能比较不同，可以匹配特定的返回类型、参数等。
例如，查找在 org.konveyor.MyClass 上声明的名为 "method" 的方法，该方法 返回扩展 java.lang.String 的类型列表并接受单个参数：
java.referenced: location: METHOD pattern: 'org.konveyor.Myclass.method(*) java.util.List<? extends java.lang.String>'
java.referenced:
location: METHOD
pattern: 'org.konveyor.Myclass.method(*) java.util.List<? extends java.lang.String>'
有关这些模式的可能性的更多信息，请参阅官方 Java 文档，其中包含在 createPattern (String, int, int, int) 部分中构建这些模式的所有信息。
目前，完全限定的静态方法匹配容易出错。
- TYPE ：与类型匹配，一般情况下都显示.
- INHERITANCE ：与从给定类型继承的类匹配。
- ANNOTATION: 匹配注释。
- IMPLEMENTS_TYPE ：与实施给定类型的任何类型匹配。
- ENUM_CONSTANT: 匹配 enum 常量。
- RETURN_TYPE ：与方法返回的类型匹配。
- VARIABLE_DECLARATION: 匹配作为变量声明的类型。
- FIELD (declaration): 与在字段声明中显示的类型匹配。它可以与注解匹配匹配，这是在字段上发生注解（请参阅 注解检查）
- METHOD ：与给定方法声明匹配。它可以与注解匹配（请参阅 注解检查）。
- CLASS （声明）：与给定的方法声明匹配。可以与注解匹配匹配（请参阅 注解检查）。
支持的位置如下：
-
CONSTRUCTOR_CALL -
TYPE -
继承 -
METHOD_CALL -
注解 -
IMPLEMENTS_TYPE -
ENUM_CONSTANT -
RETURN_TYPE -
IMPORT -
VARIABLE_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>" 2.3.8.4. 注解检查
您可以添加查询以匹配特定注解及其元素，例如：
这与以下 Java 代码中的 runApplication 方法匹配：
注解的 YAML 元素的结构为：
annotated:
pattern: a Java regex to match the fully qualified name of the annotation (optional)
elements: an array of elements to match within the annotation (optional)
- name: the exact name of the element to match against
value: a Java regex to match the value of the element
annotated:
pattern: a Java regex to match the fully qualified name of the annotation (optional)
elements: an array of elements to match within the annotation (optional)
- name: the exact name of the element to match against
value: a Java regex to match the value of the element
也可以将注解与特定元素匹配，而不必指定其注解的符号。以下示例还与上例中的 @Bean 注解匹配：
使用 模式 指定的唯一元素是注释本身。
2.3.8.5. Go 供应商
Go 供应商分析 Go 源代码。此提供程序的功能 被引用，依赖项 为。
引用
通过使用 引用 的功能，供应商会在源代码中找到引用。
when: go.referenced: "<regex_to_find_reference>"
when:
go.referenced: "<regex_to_find_reference>"依赖项
通过使用 依赖项 功能，供应商找到应用程序的依赖项。
when:
go.dependency:
name: "<dependency_name>"
upperbound: "<version_string>"
lowerbound: "<version_string>"
when:
go.dependency:
name: "<dependency_name>"
upperbound: "<version_string>"
lowerbound: "<version_string>" 2.3.8.6. dotnet 供应商
dotnet 供应商是一个外部供应商，用于分析 .NET 和 Ccephfs 源代码。目前，供应商支持 引用 的功能。
引用
通过使用 引用 的功能，供应商会在源代码中找到引用。
when:
dotnet.referenced:
pattern: "<pattern>"
namespace: "<namespace>"
when:
dotnet.referenced:
pattern: "<pattern>"
namespace: "<namespace>" 2.3.9. 条件模式
Java 提供程序使用的 Language Server 是 Eclipse 的 JDTLS。在内部，JDTLS 使用 Eclipse Java Development Toolkit，其中包括在项目中搜索代码的工具。
在 java.referenced 条件的 pattern 元素中，您可以使用这些工具搜索应用程序代码。如需了解更多详细信息，请参阅 Class SearchPattern，其中包含为 createPattern (String, int, int, int, int)构建这些模式的所有信息。
例子
在
javax.xml软件包下搜索任何类，在任何位置发生：java.referenced: pattern: javax.xml*
java.referenced: pattern: javax.xml*Copy to Clipboard Copied! Toggle word wrap Toggle overflow 警告与软件包匹配时，如上例中所示，星号不能在点后。例如：*
pattern: javax.xml*和 not: *pattern: javax.xml message搜索返回
java.lang.String的方法声明：java.referenced: location: METHOD pattern: '* java.lang.String'
java.referenced: location: METHOD pattern: '* java.lang.String'Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在
org.konveyor.MyClass上搜索名为 "method" 的方法，该方法返回扩展java.lang.String的类型列表：java.referenced: location: METHOD pattern: 'org.konveyor.Myclass.method(*) java.util.List<? extends java.lang.String>'
java.referenced: location: METHOD pattern: 'org.konveyor.Myclass.method(*) java.util.List<? extends java.lang.String>'Copy to Clipboard Copied! Toggle word wrap Toggle overflow 搜索实现
java.util.List的类：java.referenced: location: IMPLEMENTS_TYPE pattern: java.util.List
java.referenced: location: IMPLEMENTS_TYPE pattern: java.util.ListCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.3.10. 自定义变量
供应商条件可以关联有自定义变量。您可以使用自定义变量从源代码中的匹配行捕获相关信息。这些变量的值与源代码中匹配的数据进行干预。这些值可用于在规则的操作中生成详细的模板消息（请参阅 Message actions）。它们可以添加到 customVariables 字段中的规则中：
2.3.11. 逻辑条件
分析器提供两个基本逻辑条件，和 或，可用于聚合其他条件的结果并创建更复杂的查询。
2.3.11.1. AND 条件
and 条件对条件数组的结果执行逻辑 AND 操作。
当 所有子 条件都匹配时，和 条件都匹配，例如：
when:
and:
- <condition1>
- <condition2>
when:
and:
- <condition1>
- <condition2>Example
2.3.11.1.1. 嵌套条件
条件也可以嵌套在其他条件内。
- Example
2.3.11.2. OR 条件
or 条件对条件数组的结果执行逻辑 OR 操作。
当其 任何子 条件匹配时，or 条件会匹配，例如：
when:
or:
- <condition1>
- <condition2>
when:
or:
- <condition1>
- <condition2>Example
2.3.11.3. 链条件变量
您可以使用一个条件的输出作为在 和 或 条件中过滤另一个条件的输入。这称为 条件链。
Example
在上例中，builtin.file 条件的输出保存为 poms ：
+
[...]
as: poms
[...]
[...]
as: poms
[...]
然后，builtin.file 的变量可以在 builtin.xml 条件中使用，从 中写入，然后在 provider_ condition 块中使用 mustache 模板。
这是此特定条件知道如何使用变量设为名称 poms。
+
[...]
from: poms
[...]
[...]
from: poms
[...]然后，您可以通过将变量设置为 供应商 条件中的任何输入中的 mustached 模板来使用这些变量。
+
[...]
filepaths: "{{poms.filepaths}}"
[...]
[...]
filepaths: "{{poms.filepaths}}"
[...]
如果您只想将条件的值用作链，您可以设置 ignore: true。
这将告知引擎不使用此条件来确定规则是否已违反：
+
[...]
ignore: true
[...]
[...]
ignore: true
[...]2.3.11.3.1. Java 供应商中的链
在 java 供应商中，filepath s 变量必须大写。例如：
2.3.12. Rulesets（规则集）
组规则形成规则集。MTA 不需要每个规则文件属于规则集，但您可以使用规则集来对实现常见目标的多个规则进行分组，并将规则传递给规则引擎。
您可以通过将一个或多个 YAML 规则放在目录中，并在目录 root 中创建 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要执行任何应用程序分析，请输入：
mta-cli analyze --input=<application_to_analyze> --output=<output_dir> --rules=<custom_rule_dir> --enable-default-rulesets=false
$ mta-cli analyze --input=<application_to_analyze> --output=<output_dir> --rules=<custom_rule_dir> --enable-default-rulesets=false-
将
<application_to_analyze> 替换为应用程序的名称。 -
将
<output_dir> 替换为您选择的目录。 -
将
<custom_rule_dir> 替换为自定义规则集文件。
在启动时，mta-cli 工具决定了应用程序和分析所需的供应商。然后，它会在具有所需依赖项和工具的容器中启动提供程序。最后，提供商使用分析器来执行一系列规则集来分析源代码。
2.3.13. 创建基本 YAML 规则集模板
如果要对多个类似的规则进行分组，可以通过将其文件放在一个目录中并在目录 root 中创建 ruleset.yaml 文件来为它们创建一个规则集。当您使用- rules 选项将此目录作为输入传递给 MTA CLI 时，MTA 会将目录中的所有文件视为属于 ruleset.yaml 文件中定义的规则集。
流程
如果要使用-
rules选项传递整个目录，请为ruleset.yaml文件创建一个模板：name: <RULESET_NAME> description: <RULESET_DESCRIPTION> labels: - key=val
name: <RULESET_NAME>1 description: <RULESET_DESCRIPTION> labels:2 - key=valCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.3.14. 创建 YAML 规则
每个规则文件包含一个或多个 YAML 规则。每个规则都包含元数据、条件和操作。
流程
创建
when条件。YAML 规则的
when条件可以是provider、和或或。创建
供应商条件provider 条件用于定义对特定语言提供程序的搜索查询，并调用提供程序的特定功能。
条件的一般格式为 <
provider_name>.<capability>。该条件还具有 inner 字段，用于指定搜索的详细信息。创建供应商条件及其内部字段的方式取决于您使用的供应商以及您调用的功能。下表列出了可用的提供程序及其功能。选择一个供应商及其功能，以满足您要创建的规则的目的。条件的一部分还没有包含任何条件的字段。
Expand 供应商 功能 描述 java引用找到模式引用，包括注解，带有可选代码位置，用于详细搜索
依赖项检查应用程序是否有给定依赖项
builtinxml使用 XPath 查询搜索 XML 文件
json使用 JSONPath 查询搜索 JSON 文件
FileContent使用 RegEx 模式搜索常规文件中的内容
file查找名称与给定模式匹配的文件
hasTags检查是否通过标记规则为应用程序创建标签
go
引用查找模式引用
依赖项检查应用程序是否有给定依赖项
以下示例显示了使用
引用能力的java供应商条件。Example
when: java.referenced:
when: java.referenced:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
为
供应商条件添加合适的字段。下表列出了所有可用的供应商、其功能及其字段。选择属于您选择的供应商和功能的字段。请注意，一些字段是必须的。
Expand 供应商 功能 字段 必需？ 描述 java引用pattern是
RegEx pattern
位置否
源代码位置；请参阅下面所有支持的搜索位置列表
annotated否
注解及其元素（名称和值）
依赖项name是
依赖项的名称
nameregex否
与名称匹配的正则表达式模式
upperBound否
匹配小于或等于的版本号
lowerBound否
匹配大于或等于的版本号
builtinxmlXPath是
XPath 查询
命名空间否
映射到范围向下查询到命名空间
filepaths否
用于范围搜索的可选文件列表
jsonXPath是
XPath 查询
filepaths否
用于范围搜索的可选文件列表
FileContentpattern是
在内容中匹配的正则表达式模式
filePattern否
仅在与此模式匹配的文件中搜索
filepattern是
查找与此模式匹配的名称的文件
hasTags这是字符串标签的内联列表。有关标签格式的详情，请参阅 Rule Actions 中的 Tag Actions。
go引用pattern是
RegEx pattern
依赖项name是
依赖项的名称
nameregex否
与名称匹配的正则表达式模式
upperBound否
匹配小于或等于的版本号
lowerBound否
匹配大于或等于的版本号
以下搜索位置可用于范围
java搜索：- CONSTRUCTOR_CALL
- TYPE
- 继承
- METHOD_CALL
- 注解
- IMPLEMENTS_TYPE
- ENUM_CONSTANT
- RETURN_TYPE
- IMPORT
VARIABLE_DECLARATION
以下示例显示搜索软件包引用的规则的
when条件。Example
when: java.referenced: location: PACKAGE pattern: org.jboss*when: java.referenced: location: PACKAGE pattern: org.jboss*Copy to Clipboard Copied! Toggle word wrap Toggle overflow
创建
AND或OR条件当
所有子条件都匹配时，和 条件都匹配。创建和条件，如下所示：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 当任何子条件都匹配时，
或条件会匹配。创建或条件，如下所示：Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.3.15. 使用自定义 YAML 规则运行分析
要运行分析，请在 CLI 中使用-- rules 选项。
流程
要在一条规则文件
/home/<USER>/rule.yaml中使用规则，请运行以下命令：mta-cli analyze --input /home/<USER>/data/ --output /home/<USER>/output/ --rules /home/<USER>/rule.yaml
mta-cli analyze --input /home/<USER>/data/ --output /home/<USER>/output/ --rules /home/<USER>/rule.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 其中：
-
/home/<USER>/data/- 源代码或二进制的目录 -
/home/<USER>/output/- 报告的目录(HTML 和 YAML)
-
-
要使用多个规则文件，您需要将它们放在目录中并添加
ruleset.yaml文件。然后，目录被视为 规则集，您可以将其作为输入传递给规则选项。
请注意，如果您要在 CLI 中使用-- target 或-- source 选项，则引擎将仅选择与该目标标签匹配的规则。因此，请确保您在规则上添加了目标或源标签。如需了解更多详细信息，请参阅 保留标签。
2.4. 创建第一个 YAML 规则
本节介绍了创建和测试第一个基于 MTA YAML 的规则的过程。这假设您已安装了 MTA。有关安装说明 ， 请参阅 CLI 指南中的 安装和运行 CLI。
在本例中，您将创建一个规则来发现应用程序定义了包含 < class-loading> 元素的 文件，并提供描述如何迁移代码的文档的链接。
jboss- web.xml
2.4.1. 为规则创建 YAML 文件
- 为您的第一个规则创建一个 YAML 文件。
mkdir /home/<USER>/rule.yaml
$ mkdir /home/<USER>/rule.yaml2.4.2. 创建数据来测试规则
在目录中创建
jboss-web.xml和pom.xml文件：mkdir /home/<USER>/data/ touch /home/<USER>/data/jboss-web.xml touch /home/<USER>/data/pom.xml
mkdir /home/<USER>/data/ touch /home/<USER>/data/jboss-web.xml touch /home/<USER>/data/pom.xmlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 在您创建的
jboss-web.xml文件中，粘贴以下内容：Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在您创建的
pom.xml文件中，粘贴以下内容：Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.4.3. 创建规则
基于 MTA YAML 的规则使用以下规则模式：
when(condition) perform(action)
when(condition)
perform(action)流程
在您创建的
rule.yaml文件中，粘贴以下内容：Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- 规则的唯一 ID。例如，
jboss5-web-class-loading。 - 2
- 规则的文本描述。
- 3
- 完成
when块指定一个或多个条件：-
使用
内置提供程序的 XML 功能，因为此规则检查 XML 文件中的匹配项。 要在作为
jboss元素上匹配，请使用 XPath 表达式-web的子类加载jboss-web/web-loading作为 XML 查询。在这种情况下，您只需要一个条件：when: builtin.xml: xpath: jboss-web/class-loadingwhen: builtin.xml: xpath: jboss-web/class-loadingCopy to Clipboard Copied! Toggle word wrap Toggle overflow
-
使用
- 4
- 解释迁移问题的有用消息。当规则匹配时，报告中会生成该消息。例如：
message: The class-loading element is no longer valid in the jboss-web.xml file.
message: The class-loading element is no longer valid in the jboss-web.xml file.Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 5
- 规则的字符串标签列表。
- 6
- 解决这个问题的预期故事数。
- 7
- 一个或多个超链接指向您找到的迁移问题的文档。
links: - url: https://access.redhat.com/documentation/zh-CN/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6 title: Create or Modify Files That Control Class Loading in JBoss EAP 6
links: - url: https://access.redhat.com/documentation/zh-CN/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6 title: Create or Modify Files That Control Class Loading in JBoss EAP 6Copy to Clipboard Copied! Toggle word wrap Toggle overflow 该规则现已完成，并类似如下：
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.4.4. 安装规则
流程
将 CLI 指向您创建的规则文件：
–rules /home/<USER>/rules.yaml
–rules /home/<USER>/rules.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.4.5. 测试规则
流程
要测试规则，请将输入指向您创建的测试数据，并使用 MTA CLI 中的 rules 选项传递规则：
mta-cli analyze --input /home/<USER>/data/ --output /home/<USER>/output/ --rules /home/<USER>/rules.yaml
mta-cli analyze --input /home/<USER>/data/ --output /home/<USER>/output/ --rules /home/<USER>/rules.yaml2.4.6. 查看报告
查看报告以确保它提供了预期的结果。
流程
分析完成后，命令会输出 HTML 报告的路径：
INFO[0066] Static report created. Access it at this URL: URL="file:/home/<USER>/output/static-report/index.html"
INFO[0066] Static report created. Access it at this URL: URL="file:/home/<USER>/output/static-report/index.html"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在 Web 浏览器中打开
/home/<USER_NAME>/output/static-report/index.html。- 进入到左侧菜单中的 issues 选项卡。
验证规则是否已执行：
-
在 issues 表中，在搜索栏中输入
JBoss XML。 -
验证表中是否存在 title
Find class loading 元素的问题。
-
在 issues 表中，在搜索栏中输入
- 单击 jboss-web.xml 链接，以打开受影响的文件。
附录 A. 参考材料
A.1. 关于规则故事点
A.1.1. 什么是故事点？
故事点是敏捷软件开发中常用的抽象指标，用于估算实施功能或更改所需的工作量水平。
应用的 Migration Toolkit for Applications 使用故事点来代表迁移特定应用程序构造所需的工作程度，以及整个应用程序。它不一定转换为“人-小时”，但该值在不同的任务间应保持一致。
A.1.2. 故事点如何在规则中估计
估算一个规则的故事点的工作量水平可能很棘手。以下是估算规则所需工作量时，使用的一般准则 MTA。
| 努力级别 | 故事点 | 描述 |
|---|---|---|
| 信息 | 0 | 迁移过程中具有非常低或没有优先级的信息。 |
| 微小 | 1 | 迁移是一个微小的变化或一个简单的库交换，没有或有最小的 API 更改。 |
| 复杂 | 3 | 迁移任务所需的更改比较复杂，但有一个已包括在文档中的解决方案。 |
| 重新设计 | 5 | 迁移任务需要重新设计或完整的库更改，并有显著的 API 更改。 |
| 架构重组 | 7 | 迁移会需要组件或子系统的完全的架构重组。 |
| Unknown | 13 | 迁移解决方案并非已知的，可能需要进行彻底的重写。 |
A.1.3. 任务类别
除了工作程度外，您还可以对迁移任务进行分类，以指明任务的严重性。下列类别用于对问题进行分组，以帮助确定迁移的工作量。
- 必需
- 必须成功完成该任务才能成功迁移。如果没有进行任何更改，则生成的应用不会成功构建或运行。例如，替换在目标平台中不支持的专有 API。
- 选填
- 如果没有完成迁移任务，应用程序应该可以正常工作，但结果可能不是最佳。如果迁移时没有进行任何更改，建议在迁移完成后尽快按计划设置。
- Potential
- 应在迁移过程中检查该任务，但没有足够的详细信息来确定任务是否成功完成。当没有直接兼容类型时，这将迁移第三方专有类型。
- 信息
- 该任务会包括告知您存在某些文件。可能需要将它们检查或修改为现代化工作的一部分，但通常不需要进行更改。
A.2. 其他资源
A.2.1. 其他资源
- MTA Jira issue tracker: https://issues.redhat.com/projects/MTA/issues
- MTA 邮件列表： windup-eng@redhat.com
更新于 2025-09-23
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}