問題回報

外掛程式可以透過 Gradle 的問題回報 API 來回報問題。這些 API 會回報關於建置期間發生的問題的豐富結構化資訊。這些資訊可以被不同的使用者介面使用，例如 Gradle 的主控台輸出、建置掃描或 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、建置掃描等）都將可以存取此關聯。

命令列介面

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