报告问题

插件可以通过 Gradle 的问题报告 API 报告问题。这些 API 报告关于构建过程中发生的富结构化信息的问题。这些信息可以被不同的用户界面使用，例如 Gradle 的控制台输出、Build Scan 或 IDE，以最合适的方式向用户传达问题。

以下示例展示了从插件报告的问题

ProblemReportingPlugin.java
public class ProblemReportingPlugin implements Plugin<Project> {

    public static final ProblemGroup PROBLEM_GROUP = ProblemGroup.create("sample-group", "Sample Group");

    private final ProblemReporter problemReporter;

    @Inject
    public ProblemReportingPlugin(Problems problems) { (1)
        this.problemReporter = problems.getReporter(); (2)
    }

    public void apply(Project project) {
        ProblemId problemId = ProblemId.create("adhoc-deprecation", "Plugin 'x' is deprecated", PROBLEM_GROUP);
        this.problemReporter.report(problemId, builder -> builder (3)
            .details("The plugin 'x' is deprecated since version 2.5")
            .solution("Please use plugin 'y'")
            .severity(Severity.WARNING)
        );
    }
}
1 Problem 服务被注入到插件中。
2 为插件创建了一个问题报告器。虽然命名空间由插件作者决定，但建议使用插件 ID。
3 报告了一个问题。这个问题是可恢复的，因此构建将继续。

有关完整示例，请参阅我们的端到端示例。

构建问题

在报告问题时，可以提供各种各样的信息。ProblemSpec 描述了可以提供的所有信息。

报告问题

在报告问题时，我们支持两种不同的模式

  • 报告问题用于报告可恢复的问题，构建应继续。

  • 抛出问题用于报告不可恢复的问题，构建应失败。

有关更多详细信息，请参阅 ProblemReporter 文档。

问题汇总

在报告问题时，Gradle 确保报告简洁且没有不必要的冗余。具体来说，它会阻止在达到特定阈值后重复报告相同的问题。

  • 在构建期间，问题的前几个实例被报告为 Problem，提供该问题的所有可用信息。

  • 在构建结束时，同一问题的后续出现将被分组并汇总为 ProblemSummary。此摘要通过 ProblemSummariesEvent 传递，其中提供了出现总数。

构建失败

指示构建失败的标准方法是抛出异常。ProblemReporter 通过允许抛出带有相关问题报告的异常，为此提供了增强的支持。

FailingTask.java
ProblemId id = ProblemId.create("sample-error", "Sample Error", StandardPlugin.PROBLEM_GROUP);
throw getProblems().getReporter().throwing((new RuntimeException("Message from runtime exception")), id, problemSpec -> {
    problemSpec.contextualLabel("This happened because ProblemReporter.throwing() was called");
    problemSpec.details("This is a demonstration of how to add\ndetailed information to a build failure");
    problemSpec.documentedAt("https://example.com/docs");
    problemSpec.solution("Remove the Problems.throwing() method call from the task action");
});

这确保了构建失败与底层问题清晰地联系起来，并且这些问题被正确地传达给各种客户端。当使用 Problems API 报告构建失败时，所有客户端（Tooling API、CLI、Build Scan 等）都将有权访问该关联。

命令行界面

CLI 构建失败输出将包含有关问题的详细信息。错误消息和描述直接来自问题报告。如果问题报告包含解决方案或建议的操作，则将显示这些内容以代替通用解决方案。

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':sample-project:myFailingTask'.
> Message from runtime exception
    This happened because ProblemReporter.throwing() was called
      This is a demonstration of how to add
      detailed information to a build failure

* Try:
> Remove the Problems.throwing() method call from the task action
> Run with --scan to get full insights.

BUILD FAILED in 0ms

Tooling API 客户端

Tooling API 客户端可以通过根构建操作上的 Failure 对象访问与构建失败相关的详细问题报告。要接收这些报告，客户端必须为 OperationType.ROOT 操作类型注册进度监听器。然后，进度监听器回调应检查操作结果是否为 FailureResult 类型，然后可以通过 Failure.getProblems() 访问关联的问题。

此外，还有一种更方便的方法来访问失败详细信息。如果客户端使用 LongRunningOperation.withFailureDetails() 配置项目连接，则 Tooling API 隐式订阅 ROOT 操作类型，并通过 GradleConnectionException.getFailures() 方法提供失败详细信息。

生成的 HTML 报告

Problems API 生成的问题的输出也以 HTML 报告的形式提供，该报告在构建结束时生成。此报告充当用户查看构建期间发生的问题的中心位置。

插件作者可以使用 Problems API 记录特定于其插件的事件，添加到 Gradle 生成的事件中。

如果没有报告任何问题，则不会生成报告。此外，如果您不想生成此报告，可以使用 --no-problems-report 标志禁用它。控制台输出提供了指向此报告的链接，如下所示

[Incubating] Problem report is available at: <project-dir>/build/reports/problems/problems-report.html

BUILD SUCCESSFUL in 1s

渲染的报告链接将您定向到问题的详细 HTML 视图

problems report html