Gradle 8.7 發行說明 - Gradle 繁體中文

新功能和可用性改進

支援使用 Java 22 建置專案

Gradle 現在支援使用 Java 22 來編譯、測試和啟動其他 Java 程式。使用工具鏈來選擇語言版本。

您無法使用 Java 22 執行 Gradle 8.7 本身，因為 Groovy 仍需要支援 JDK 22。不過，預計未來版本將提供此支援。

由於建置快取支援，避免 Groovy 建置指令碼編譯

Gradle 建置快取是一種機制，旨在透過重複使用先前建置的本機或遠端輸出，來節省時間。

在此版本中，Groovy 建置指令碼編譯可以受益於遠端建置快取，啟用時，可透過完全避免此步驟，來減少開發人員的初始建置時間。

雖然此功能自 Gradle 5.0 中引入 Kotlin DSL 以來，就已經可用於 Kotlin 建置指令碼編譯，但 Groovy DSL 缺乏此功能同等性。

建置撰寫改進

隨著建置的複雜性增加，要確定何時何地設定特定值可能會很困難。Gradle 提供一種有效的方式來使用延遲設定管理此複雜性。

更新集合屬性的更好 API

此版本改進了延遲集合屬性的 API，這是 Gradle 延遲設定的關鍵元素。在此版本之前，傳統集合方法的互動、慣例的概念和圍繞空提供者的規則，在某些情況下會導致使用者的行為令人驚訝。根據社群回饋，此版本 Gradle 引入了具有更明確合約的更新集合的替代 API

HasMultipleValues.append*(...)，旨在作為 HasMultipleValues.add*(...) 的更方便替換。
MapProperty.insert*(...)，旨在作為 MapProperty.put*(...) 的更方便替換。

新的 API 提供以下好處

尊重慣例

一個常見的抱怨是，在慣例值之上新增值（在 ListProperty.add(...)、SetProperty.add(...) 或 MapProperty.put(...) 上），將導致失去慣例中的值。

例如，在已套用的外掛中，清單屬性 ListProperty<String> 已設定慣例

listProp.convention(listOf("one"))

在建置檔案中，建置作者將元素新增到該清單屬性中

listProp.add("two")
// listProp now only contains "two", that’s confusing

然而，正如程式片段中所說明的，行為令人驚訝。新引進的方法（例如 ListProperty.append(...)、SetProperty.append(...) 和 MapProperty.insert(...)）允許使用者表達應保留慣例

listProp.append("two")
// listProp now contains ["one", "two"], as expected

忽略空的提供者值

另一個常見的混淆來源是集合屬性中如何處理空的提供者。例如，使用 add(...) 將空的提供者新增至集合屬性，將導致整個屬性也變成沒有任何值。

listProp.add("one")
listProp.add(providers.environmentVariable("myEnvVar"))
// listProp will be empty if `myEnvVar` is not defined

為了避免這種行為，您可以改用此版本中引入的新更新 API（例如 ListProperty.append(...)、SetProperty.append(...) 和 MapProperty.insert(...)）

listProp.append("one")
listProp.append(providers.environmentVariable("myEnvVar"))
// listProp will still contain "one" if myEnvVar is not defined

錯誤和警告報告改進

Gradle 提供豐富的錯誤和警告訊息，以協助您了解並解決建置中的問題。

改進的套件應用程式錯誤回報

當套用需要較高版本 Gradle 的套件應用程式（透過指定 org.gradle.plugin.api-version 屬性）時，相依性解析失敗時的錯誤訊息現在會清楚說明問題

FAILURE: Build failed with an exception.

* What went wrong:
A problem occurred configuring root project 'example'.
> Could not resolve all files for configuration ':classpath'.
   > Could not resolve com.example:plugin:1.0.
     Required by:
         project : > com.example.greeting:com.example.greeting.gradle.plugin:1.0
      > Plugin com.example:plugin:1.0 requires at least Gradle 8.0. This build uses Gradle 7.6.

* Try:
> Upgrade to at least Gradle 8.0. See the instructions at https://gradle-docs.dev.org.tw/8.7/userguide/upgrading_version_8.html#sub:updating-gradle.
> Downgrade plugin com.example:plugin:1.0 to an older version compatible with Gradle 7.6.

失敗的建議解決方案將包括升級您的 Gradle 版本或降級套件應用程式的版本。這取代了之前的低階不相容訊息，其中包含套件應用程式要求中涉及的所有屬性的詳細資料。

改進的複製任務錯誤回報

當在Copy任務中包含壓縮檔案導致重複檔案，且DuplicatesStrategy.Fail已使用時，錯誤訊息現在會清楚說明問題

Cannot copy file <SOURCE_FILE> to <DESTINATION_DIR> because file <OTHER_SOURCE_FILE> has already been copied there.

可抑制的「沒有版本的相依性」驗證錯誤

當產生 Gradle 模組元資料檔案時，Gradle 會透過尋找常見的組態錯誤，防止您的專案發佈中斷的元資料。

其中一個錯誤是發佈元資料，其中包含沒有版本的相依性。此驗證錯誤現在可以被抑制，因為在某些情況下此類元資料是有效的

tasks.withType(GenerateModuleMetadata).configureEach {
    suppressedValidationErrors.add('dependencies-without-versions')
}

組態快取改進

透過快取組態階段的結果並在後續建置中重複使用，組態快取改善了建置時間。此功能可以顯著改善建置效能。

配置快取報告中更簡潔的堆疊追蹤

在配置快取報告中顯示的禁止 API 呼叫的堆疊追蹤可能很長，而且包含不總是對解決問題有幫助的內部 Gradle 框架。在此版本中，內部堆疊框架預設會摺疊，以突顯觸發錯誤的建置邏輯

Collapsed stack frames in the configuration cache report

必要時，仍可以展開並檢查摺疊的框架。

支援標準串流作為工作屬性值

標準串流 (System.in、System.out 和 System.err) 現在可以用作 Exec 和 JavaExec 工作的 standardInput、standardOutput 和 errorOutput，而不會中斷配置快取。

具有 java.io.InputStream 和 java.io.OutputStream 類型屬性的使用者建立的工作也可以使用標準串流作為屬性值。不支援使用 System.setIn、System.setOut 和 System.setErr 設定自訂標準串流。

Kotlin DSL 改進

內嵌 Kotlin 升級至 1.9.22

內嵌 Kotlin 已從 1.9.10 更新至 Kotlin 1.9.22。

Kotlin DSL 參考更新

從 Java 程式碼產生的 Javadoc 現在支援「since」區段，表示功能導入的 Gradle 版本。

資訊來自 Javadoc 中的 @since 標籤，到目前為止尚未顯示。可以在 JavaToolchainSpec 找到範例。

其他改進

使用 Gradle init 產生簡潔專案

使用新的 --no-comments 選項讓 Gradle init 產生不含註解程式碼的新專案。產生的建置檔案和原始檔較小且較不冗長。

gradle init --use-defaults --type kotlin-library --no-comments

可以在 Gradle 屬性中將 org.gradle.buildinit.comments 屬性設定為 false，以永久設定此偏好設定。

不帶參數的共用建置服務註冊

Gradle 讓工作透過建置服務共用狀態或資源，例如預先計算的值或外部服務，建置服務是包含狀態供工作使用的物件。建置服務可以選擇性地接受參數，Gradle 在建立服務實例時會將這些參數注入服務實例。

現在可以使用更新的 registerIfAbsent() 方法註冊不需要額外設定的共用建置服務，而不需要提供空的設定動作

gradle.sharedServices.registerIfAbsent("counter", CountingService, voidAction) 	// Old method
gradle.sharedServices.registerIfAbsent("counter", CountingService)		// New method

支援 TestNG 的 threadPoolFactoryClass 參數

TestNG 是一個在 Gradle 中支援的測試架構。在 TestNG 中，threadPoolFactoryClass 屬性用於指定自訂執行緒池工廠類別，詳細說明 TestNG 如何管理執行緒以進行平行測試執行。

threadPoolFactoryClass 參數現在可以在 TestNGOptions 上針對支援它的 TestNG 版本進行設定（例如 TestNG 7.0.0 及以上版本）

testing {
    suites {
        test {
            useTestNG("7.5")
            targets {
                all {
                    testTask.configure {
                        options.threadPoolFactoryClass = "com.example.MyThreadPoolFactory"
                    }
                }
            }
        }
    }     
}

如果針對不支援此參數的 TestNG 版本設定此參數，將會發生錯誤。

一致排序元資料驗證檔案中被忽略的鍵

為了減輕安全性風險並避免在專案中整合受危害的依賴項，Gradle 支援依賴項驗證。依賴項驗證通常使用檢查總和或數位簽章來完成。Gradle 會驗證已下載的成品是否與預期的檢查總和相符，或是否已使用受信任的鍵簽署。

在此版本之前，元資料驗證檔案中的被忽略的鍵清單未由 Gradle 正確排序，因此順序會根據執行順序而改變，進而影響檔案的建置和檢查總和的可重複性。在此版本中，無論執行順序為何，都保證順序會被保留。

透過檔案系統監控，對符號連結提供更好的支援

Gradle 會維護一個虛擬檔案系統 (VFS) 來計算在重複建置專案時需要重新建置的內容。透過監控檔案系統，Gradle 會在建置之間保持 VFS 的最新狀態，減少所需的 I/O 作業。

此版本修正了透過符號連結間接參照的內容變更偵測問題，進而改善建置的正確性。

支援 JVM 測試套件依賴項區塊中的約束

Gradle 7.6 中引入的強類型依賴項區塊不支援依賴項約束。

在此版本中，現在可以新增依賴項約束

testing {
    suites {
        getByName<JvmTestSuite>("test") {
            dependencies {
                implementation(constraint("foo:bar:1.0"))
            }
        }
    }
}

目前不支援針對每個部分提供個別字串或使用命名參數。

Gradle 發行說明

目錄

升級說明