japicmp-gradle-plugin - JApicmp Gradle插件提供Java库二进制兼容性分析

= JApicmp Gradle 插件 :japicmp-url: https://github.com/siom79/japicmp :issues: https://github.com/melix/japicmp-gradle-plugin/issues :gradle-url: http://gradle.org/ :plugin-version: 0.4.1

image:https://github.com/melix/japicmp-gradle-plugin/actions/workflows/gradle-build.yml/badge.svg?branch=master&event=push["构建状态", link="https://github.com/melix/japicmp-gradle-plugin/actions/workflows/gradle-build.yml?query=branch:master+event:push"] image:https://img.shields.io/github/license/melix/japicmp-gradle-plugin["许可证", link="LICENSE.txt"] image:https://img.shields.io/gradle-plugin-portal/v/me.champeau.gradle.japicmp.svg["下载", link="https://plugins.gradle.org/plugin/me.champeau.gradle.japicmp"]

japicmp-gradle-plugin 通过 {japicmp-url}[JApicmp] 使用 {gradle-url}[Gradle] 提供二进制兼容性报告。

== 安装

此插件需要 Gradle 6+。在 Gradle 构建文件中使用以下代码片段：

[source,groovy] [subs="attributes"]

plugins { id 'me.champeau.gradle.japicmp' version '{plugin-version}' }

或者（不推荐）：

[source,groovy] [subs="attributes"] .build.gradle

buildscript { repositories { mavenCentral() }

dependencies {
    classpath 'me.champeau.gradle:japicmp-gradle-plugin:{plugin-version}'
}

} apply plugin: 'me.champeau.gradle.japicmp'

== 配置

该插件提供了一个新的任务类型：me.champeau.gradle.japicmp.JapicmpTask，你可以用它来比较两个 jar 包。这个任务暴露了以下属性作为其配置的一部分：

[horizontal] oldClasspath:: 用于比较的基准库的类路径。类型：FileCollection newClasspath:: 当前版本库的类路径，您想要检查其二进制兼容性。类型：FileCollection oldArchives:: 将用作比较基准的 jar 文件。类型：FileCollection。 newArchives:: 我们想要分析的 jar 文件。类型：FileCollection。 onlyModified:: 仅输出修改过的类/方法。如果不设置为 true，则打印所有类和方法。类型：boolean。默认值：false onlyBinaryIncompatibleModified:: 仅输出导致二进制不兼容的修改的类/方法。类型：boolean。默认值：false packageIncludes:: 要包含的包名列表，* 可用作通配符。类型：List packageExcludes:: 要排除的包名列表，* 可用作通配符。类型：List classIncludes:: 要包含的类列表。类型：List classExcludes:: 要排除的类列表。类型：List methodIncludes:: 要包含的方法列表。类型：List methodExcludes:: 要排除的方法列表。类型：List fieldIncludes:: 要包含的字段列表。类型：List fieldExcludes:: 要排除的字段列表。类型：List annotationIncludes:: 要包含的注解列表。字符串必须以'@'开头。类型：List annotationExcludes:: 要排除的注解列表。字符串必须以'@'开头。类型：List compatibilityChangeExcludes:: 要排除的兼容性更改列表，将它们标记为源代码和二进制兼容。字符串必须匹配 japicmp.model.JApiCompatibilityChange 枚举的值。类型：List accessModifier:: 设置访问修饰符级别（public、package、protected、private）。类型：String。默认值：public failOnSourceIncompatibility:: 如果更改导致源代码级别不兼容，则失败。将此设置为 true 也会隐式启用 failOnModification。类型：boolean。默认值：false failOnModification:: 设置为 true 时，如果检测到修改，构建将失败。类型：boolean。默认值：false xmlOutputFile:: 生成的 XML 报告的路径。类型：File。默认值：null htmlOutputFile:: 生成的 HTML 报告的路径。类型：File。默认值：null txtOutputFile:: 生成的 TXT 报告的路径。类型：File。默认值：null semverOutputFile:: 生成的语义版本报告的路径。类型：File。默认值：null includeSynthetic:: 默认情况下不跟踪合成类和类成员（如桥接方法）。这个新选项启用了此类类和类成员的跟踪 ignoreMissingClasses:: 忽略类路径上缺失的所有超类或接口。默认值：false

如果你没有设置 oldArchives 和 newArchives，插件将从 oldClasspath 和 newClasspath 属性中推断它们：

如果你将类路径设置为一个配置，要比较的归档文件将是该配置的一级依赖项
如果你将类路径设置为一个简单的文件集合，所有归档文件都将被比较

== 使用方法

在你的构建文件中添加以下内容：

[source,groovy]

tasks.register("japicmp", me.champeau.gradle.japicmp.JapicmpTask) { oldClasspath.from(files('path/to/reference.jar')) newClasspath.from(tasks.named('jar')) onlyModified = true failOnModification = true txtOutputFile = layout.buildDirectory.file("reports/japi.txt") }

== JApiCompatibilityChange 过滤

该插件支持对已识别的兼容性更改进行简单的排除，在 API 比较期间将这些更改视为二进制和源代码兼容：

[source,groovy]

tasks.register("japicmp", me.champeau.gradle.japicmp.JapicmpTask) { ... compatibilityChangeExcludes = [ "METHOD_NEW_DEFAULT" ] }

来自 japicmp 的 JApiCompatibilityChange 枚举表示可以排除的已识别兼容性更改列表。为简单起见，插件使用 List 进行配置。

== 自定义过滤

该插件支持在考虑 API 比较之前为字节码成员添加过滤器：

[source,groovy]

tasks.register("japicmp", me.champeau.gradle.japicmp.JapicmpTask) { ... addIncludeFilter(MyCustomFilter) addExcludeFilter(MyOtherFilter) }

其中 MyIncludeFilter 和 MyExcludeFilter 是实现继承自 japicmp.filter.Filter 类型的类。

例如，添加以下过滤器作为排除过滤器将从 API 比较中隐藏带有 @Custom 注解或名称包含 Custom 的字段：

[source,groovy]

class MyOtherFilter implements FieldFilter { @Override boolean matches(CtField field) { return field.hasAnnotation("Custom") || field.name.contains("Custom") } }

== 自定义报告和失败条件

该插件支持一个 DSL 来基于 API 比较结果生成自定义报告。这有几个优点：

你可以生成一个只关注公共 API 的报告，将内部 API 排除在外
你可以实现自定义规则来决定构建是否应该失败
报告可以呈现给用户，并为从一个版本迁移到另一个版本提供指导

=== 配置

可以使用 richReport 块配置报告：

[source,groovy]

tasks.register("japicmp", me.champeau.gradle.japicmp.JapicmpTask) { ... richReport { ... } }

富报告的选项包括：

[horizontal] renderer:: 用于生成报告的渲染器。默认使用 GroovyReportRenderer includedClasses:: 表示包含模式的字符串列表（解释为正则表达式）。只有匹配此模式的类才会被包括。 excludedClasses:: 表示排除模式的字符串列表。如果一个类的完全限定名匹配这些模式中的任何一个，它将不会被包括。 destinationDir:: 存储报告的目录 reportName:: 生成的报告的文件名（默认为 rich-report.html） title:: 报告的标题 description:: 报告的描述 addDefaultRules:: 一个布尔值，表示是否应添加默认规则。

如果没有明确定义规则，将应用默认规则。如果添加了任何规则，默认规则将不会被应用，除非 addDefaultRules 设置为 true。

=== 自定义规则

规则用于向报告添加违规。"违规"一词应该以简单的意义理解，因为它代表要在报告中显示的数据，无论是严重违规还是仅仅是信息。

违规由三元组（成员、严重程度、解释）组成，将在报告中显示。例如，如果发现二进制不兼容，你可以使用以下方式创建违规：

Violation.notBinaryCompatible(member)

这将自动将其分配为 error 严重程度，导致构建失败。然而，可以创建任何类型的违规，甚至接受二进制不兼容的更改。

规则可以应用于 3 个不同的级别：

所有成员（无条件应用的通用规则）
针对特定变更类型（NEW、REMOVED、UNCHANGED、MODIFIED），参见 JApiChangeStatus
针对特定兼容性变更描述符（参见 JApiCompatibilityChange）

规则按以下顺序执行：

首先是状态变更
特定兼容性变更
通用规则

例如，假设我们想检查所有新方法是否都使用 @Incubating 注解（这是 Gradle 项目中的一条规则）。那么，你需要创建一个实现该检查的规则类：

[source,groovy]

class IncubatingMissingRule implements ViolationRule { @Override Violation maybeViolation(final JApiCompatibility member) { if (member instanceof JApiMethod) { if (!member.annotations.find { it.fullyQualifiedName == 'org.gradle.api.Incubating' }) { if (!member.jApiClass.annotations.find { it.fullyQualifiedName == 'org.gradle.api.Incubating' }) { Violation.error(member, "新方法未使用 @Incubating 注解") } } } } }

然后你需要配置报告以使用该规则：

[source,groovy]

richReport { addRule(JApiChangeStatus.NEW, IncubatingMissingRule) }

规则可以接受参数，但仅限于 Map<String, String> 类型。例如，以下规则会将二进制破坏性变更标记为错误，除非它被审核并接受。接受列表作为参数传递给规则：

[source,groovy]

class AcceptedRegressionRule implements ViolationRule { private final Map<String, String> acceptedViolations

public AcceptedRegressionRule(Map<String, String> params) {
    acceptedViolations = params
}

@Override
Violation maybeViolation(final JApiCompatibility member) {
    if (!member.binaryCompatible) {
        def acceptation = acceptedViolations[Violation.describe(member)]
        if (acceptation) {
            Violation.accept(member, acceptation)
        } else {
            Violation.notBinaryCompatible(member)
        }
    }
}

}

以下是如何应用该规则：

[source,groovy]

richReport { addRule(AcceptedRegressionRule, acceptedViolations) }

=== 设置和后处理规则

从 0.2.2 版本开始，插件还支持设置和后处理规则。设置规则允许设置一些全局上下文，可以被扩展 AbstractContextAwareViolationRule 的规则访问。当你需要在规则之间共享数据，并在后处理规则中执行最终检查时，这会很有用。

设置规则需要实现 SetupRule：

[source,groovy]

class MySetupRule implements SetupRule {

@Override
void execute(final ViolationCheckContext violationCheckContext) {
    // 这将在执行任何其他规则之前执行
    violationCheckContext.userData.executed = false
}

}

并使用 addSetupRule 声明：

[source,groovy]

richReport { addSetupRule(MySetupRule) }

然后可以在实现 AbstractContextAwareViolationRule 的规则中访问上下文：

[source,groovy]

class ContextAwareRule extends AbstractContextAwareViolationRule {

@Override
Violation maybeViolation(final JApiCompatibility member) {
    // 此规则访问全局上下文并可以修改用户数据
    context.userData.executed = true

    return null
}

}

最后，后处理规则可以访问用户数据，并且可以在生成报告之前修改每个类的实际违规列表：

[source,groovy]

class MyTearDownRule implements PostProcessViolationsRule {

@Override
void execute(final ViolationCheckContextWithViolations violationCheckContextWithViolations) {
    // 这个规则在所有检查完成后执行，就在生成报告之前
    // 它提供了添加额外违规、过滤违规或使用自定义错误失败的机会
    assert violationCheckContextWithViolations.userData.executed == true
    assert !violationCheckContextWithViolations.violations.isEmpty()
}

}

需要使用 addPostProcessRule 钩子进行连接：

[source,groovy]

richReport { addPostProcessRule(MySetupRule) }

== 避免同一类出现多个违规

从 0.2.5 版本开始，现在可以跟踪哪些成员已经导致了违规。由于规则按顺序执行，并且可能对同一成员同时应用状态变更规则和通用规则，因此一个成员可能触发多个违规。为了避免这种情况，你可以让你的规则继承 AbstractRecordingSeenMembers。这个规则要求应用 RecordSeenMembersSetup，它只会在之前没有为同一成员添加违规时才添加违规。