Gradle项目中CopySpec的DuplicatesStrategy文档问题解析

概述

在Gradle构建工具中，CopySpec接口的setDuplicatesStrategy方法文档存在与实际行为不符的情况。这个问题自Gradle 7.x版本以来就存在，但文档至今仍未更新，可能导致开发者在使用文件复制任务时遇到困惑。

问题背景

CopySpec是Gradle中用于定义文件复制规范的接口，其中的setDuplicatesStrategy方法用于设置当多个文件被复制到同一目标位置时的处理策略。根据官方文档描述，默认策略是DuplicatesStrategy.INHERIT，即继承父复制规范的策略，如果没有父规范则使用DuplicatesStrategy.INCLUDE。

然而，实际上从Gradle 7.0开始，当遇到重复文件时，构建会直接失败（对应issue #15594）。这与文档中描述的默认行为不符，可能导致开发者在不了解这一变更的情况下遇到意外的构建失败。

技术细节

DuplicatesStrategy枚举

Gradle提供了几种重复文件处理策略：

1. INCLUDE：包含所有重复文件
2. EXCLUDE：排除重复文件
3. WARN：包含但发出警告
4. FAIL：构建失败（默认行为）
5. INHERIT：继承父策略

实际行为变更

从Gradle 7.0开始，默认行为实际上已变为FAIL，即遇到重复文件时构建失败。这一变更可能是为了增强构建的严格性和一致性，防止意外覆盖文件的情况发生。

影响范围

这一文档问题会影响：

1. 从Gradle 6.x升级到7.x的项目
2. 依赖文件复制任务且可能产生重复文件的构建脚本
3. 期望默认行为是包含重复文件的开发者

解决方案

开发者可以采取以下措施：

1. 显式设置所需的重复策略，而不是依赖默认行为
2. 对于需要保留旧行为的项目，可以明确设置duplicatesStrategy = DuplicatesStrategy.INCLUDE
3. 检查构建脚本，确保不会意外产生重复文件

最佳实践

为避免因文档不准确导致的问题，建议：

1. 在文件复制任务中始终显式设置重复策略
2. 在升级Gradle版本时，特别关注文件处理相关的变更
3. 使用--warning-mode all运行构建，以获取可能的重复文件警告

总结

Gradle 7.x中CopySpec的默认重复文件策略已变更为构建失败，但文档尚未更新。开发者应当了解这一变更，并在构建脚本中采取相应的措施，以确保构建行为的可预测性和稳定性。这也提醒我们在依赖工具文档时，需要结合实际版本行为进行验证。