必须用java-library插件：当代码被其他模块通过implementation project(':xxx')或api project(':xxx')依赖、需发布到Maven仓库、使用maven-publish生成pom.xml，或构建多项目且子模块间存在依赖时。

选 java-library，除非你明确知道自己在做一个不被其他模块依赖的纯工具脚本或单体应用启动器。

什么时候必须用 java-library

只要你写的 Java 代码会被别的模块（哪怕是同一项目的另一个子项目）通过 implementation project(':xxx') 或 api project(':xxx') 引入，就必须用 java-library。它提供的 api 和 implementation 配置是控制依赖传递性的唯一可靠手段。

• 多项目构建中，子模块之间有依赖关系 → 必须用 java-library
• 你要发布一个 jar 到 Maven 仓库，供外部项目 implementation 'com.example:mylib:1.0' 使用 → 必须用 java-library
• 你用了 maven-publish 插件生成 pom.xml → java 插件无法正确区分 compile/runtime 作用域，会把所有依赖塞进 <scope>compile</scope>

java 插件只剩一种合理用途：快速验证或教学 Demo

java 插件（即 apply plugin: 'java' 或 plugins { id 'java' }）在 Gradle 7.0+ 中已实质弃用：它没有 api/implementation 分离能力，compile 配置早已被移除，且默认行为会让所有依赖无差别传递。

Java 接口排错助手

在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。

下载

• 新建项目时用 gradle init --type java-library，不是 java
• application 插件自动包含 java-library，所以连可执行应用也默认支持 API 分离
• 如果你看到老项目还在用 compile，说明它卡在 Gradle 3.3 或更早，升级时第一件事就是切到 java-library + api/implementation

误选 java 插件的真实代价

表面看编译能过，但问题藏在下游：

立即学习“Java免费学习笔记（深入）”；

• 消费者项目莫名其妙出现类冲突（比如两个不同版本的 guava 因为你的 java 插件全透传进来）
• 改了一个内部工具类，结果整个依赖树上 20 个模块全部触发 compileJava —— 因为没有 implementation 隔离，Gradle 认为“任何改动都可能影响别人”
• 发布的 pom.xml 里 org.slf4j:slf4j-api 被标成 runtime 范围，导致消费者编译失败：找不到 LoggerFactory
• IDE（如 IntelliJ）无法正确推导类路径，频繁提示 “Cannot resolve symbol”

真正容易被忽略的是：一旦你在多项目里混用 java 和 java-library，Gradle 的依赖解析会退化为保守模式——宁可多传、绝不少传。这种隐性耦合比编译错误更难调试。