java-gradle-plugin是开发Gradle插件的必需构建插件，它负责编译插件代码、生成META-INF/gradle-plugins/{id}.properties描述文件（含implementation-class），使插件能被plugins { id '...' }识别；未使用则插件无法被正确加载和DSL扩展。
java-gradle-plugin 是用来开发 Gradle 插件的插件
它本身不参与你的业务项目构建，而是专为「写插件的人」服务：帮你把自定义插件编译、打包、发布成可被其他项目plugins { id '...' } 引用的模块。没有它，你写的 Plugin<project></project> 类只是普通 Java 类，Gradle 根本识别不了。
常见错误现象包括：
- 手动写了
MyPlugin类，但在其他项目里plugins { id 'com.example.myplugin' }报错 “Plugin with id '...' not found” - buildSrc 里加了插件类，但 sync 后 IDE 不提示扩展属性，
project.extensions.findByType()返回 null - 独立模块打出来的 jar 包里缺
META-INF/gradle-plugins/xxx.properties文件
必须声明 java-gradle-plugin 才能生成 plugin descriptor
Gradle 加载插件时，不是靠类名反射，而是读取META-INF/gradle-plugins/{plugin-id}.properties 文件，里面必须指定 implementation-class=全限定类名。这个文件由 java-gradle-plugin 自动创建。
实操要点：
- 仅在插件工程（buildSrc 或独立 module）中应用，**不要**在业务项目里加
- 必须配合
gradleApi()依赖，否则编译时找不到Plugin、Project等类型 - 使用 Groovy/Kotlin 编写插件类时，要额外添加对应语言插件（如
groovy或kotlin-dsl） - 插件 ID 建议用反向域名格式（如
com.example.myplugin），避免和官方插件冲突
不加 java-gradle-plugin 的典型后果
即使你写了正确的 apply 方法，Gradle 也只会把它当普通 Java 库处理：
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
-
gradlePlugin {}配置块被完全忽略 - 不会生成
pluginDescriptorstask，也不会触发generatePluginDescriptors - 发布的 jar 包无法被
plugins { id '...' }解析，只能退化为apply from: 'xxx.gradle'脚本方式 - IDE 不会识别插件扩展（Extension），
myplugin { ... }这类 DSL 语法直接报红
最容易被忽略的一点：插件工程的 build.gradle 里如果只写了 apply plugin: 'java'，哪怕类写得再对，也永远无法被正常引用——java-gradle-plugin 不是可选项，是硬性前提。
立即学习“Java免费学习笔记（深入）”；
