在 Java Gradle 项目中，用 Groovy 编写自定义构建任务应聚焦清晰、可维护与生命周期对齐：避免配置阶段耗时操作，复用 Gradle API，封装为带注解的 Task 类，并使用 logger 和 GradleException 规范日志与异常。
在 Java Gradle 项目中，用 Groovy 编写自定义构建任务并不需要追求“炫技”，关键是清晰、可维护、与 Gradle 生命周期对齐。Groovy 是 Gradle 默认的 DSL 脚本语言（虽已支持 Kotlin，但 Groovy 仍广泛用于脚本逻辑），其动态特性适合快速编写构建逻辑，但也容易因随意性导致性能或可读性问题。
明确任务边界，避免在配置阶段做耗时操作
Gradle 构建分配置阶段（configuration phase）和执行阶段（execution phase）。Groovy 脚本里写的闭包如果直接放在 task 定义体外（比如在 doFirst 或 doLast 外部执行 IO、网络请求、复杂计算），就会在每次运行 Gradle（哪怕只执行 help）时触发，严重拖慢构建速度。
- ✅ 正确做法：把耗时逻辑放进
doFirst或doLast里，确保只在任务真正执行时运行 - ❌ 错误示例：
def version = new URL("https://api.example.com/version").text写在 task 外部或task { ... }的顶层作用域 - ? 提示：用
project.afterEvaluate { ... }延迟到项目配置完成后再读取属性，避免未定义变量报错
复用 Gradle 内置 API，少写“轮子”
Groovy 脚本不是通用 Java 工具脚本，而是构建逻辑的声明式延伸。优先使用 Gradle 提供的类型和方法，比手写文件遍历、正则解析更稳定、更兼容未来版本。
- 用
project.copy { ... }替代new File(...).listFiles().each { ... } - 用
project.fileTree(dir: "src/main/resources", include: "**/*.properties")精准定位资源，而非硬编码路径拼接 - 读取属性优先走
project.findProperty("myProp") ?: "default"，而不是System.getenv()或System.getProperty()—— 更符合 Gradle 层级优先级（命令行 > gradle.properties > 环境变量）
封装逻辑为可复用的 Task 类型，而非匿名脚本块
简单的一次性任务可用闭包定义，但只要逻辑被多个模块复用、或需参数化控制（如不同环境打包不同配置），就该升级为自定义 Task 类。Groovy 写起来比 Java 更轻量，且天然支持 @Input、@OutputDirectory 等注解，让 Gradle 正确识别增量构建。
立即学习“Java免费学习笔记（深入）”；
- 新建
src/buildSrc/src/main/groovy/GenerateApiDocTask.groovy（buildSrc 下代码自动编译进构建类路径） - 继承
DefaultTask，用@Input标记输入参数（如String apiVersion），用@OutputDirectory标记输出目录 - 在
@TaskAction方法里写核心逻辑，Gradle 会自动跳过未变更输入的任务 - 在
build.gradle中注册：tasks.register("generateApiDocs", GenerateApiDocTask)
调试与日志：用 Gradle 原生方式，别 print 堆栈
Groovy 的 println 在 Gradle 里会混入标准输出，难以过滤；异常堆栈也不带任务上下文。应统一用 Gradle 的 logger。
- 写日志用
logger.info("Processing {} files", fileTree.files.size())，支持 log level 控制（gradle build --info） - 抛异常用
throw new GradleException("Failed to parse config: ${e.message}")，自动关联任务名和位置 - 调试时加断点？Groovy 脚本本身不支持 IDE 断点，但自定义 Task 类（.groovy 文件）可在 IntelliJ 中正常调试
不复杂但容易忽略：高效 ≠ 写得短，而是让 Gradle 能理解、能缓存、能复用、能诊断。Groovy 是工具，不是目的 —— 任务语义清晰、生命周期合规、API 使用规范，才是“高效”的本质。
