gradle java项目必须严格遵循约定目录结构，src/main/java和src/test/java是java插件识别源码与测试的硬性起点，包路径须与类声明完全匹配，resources须独立置于src/main/resources等目录，多模块需在settings.gradle.kts中显式声明且模块名与文件夹名一致。

Gradle Java项目必须按约定目录结构组织，否则java插件无法自动识别源码、资源和测试代码——这不是可选项，是插件行为的前提。

src/main/java 和 src/test/java 是硬性起点

Gradle 的 java 插件默认只扫描这两个路径。哪怕你把 Java 文件放在 src/main/com/example/App.java 之外的任何位置（比如 src/main/src/ 或根目录下），编译时都会报 package does not exist 或直接跳过编译。

• src/main/java 下的包路径必须与类声明的 package 完全匹配，例如 com.example.App 对应 src/main/java/com/example/App.java
• src/test/java 同理，且测试类名通常以 Test 结尾（JUnit 5 默认扫描规则）
• 不要手动在 build.gradle.kts 里用 sourceSets.main.java.srcDirs 覆盖默认路径，除非你明确要打破约定并承担后续所有任务（编译、测试、打包）的手动适配成本

resources 目录不能和 java 混放

src/main/resources 和 src/test/resources 是独立于 Java 源码的资源加载路径。JVM 运行时通过 ClassLoader.getResource() 查找它们，而 IDE 和 Gradle 都依赖这个分离结构来正确处理打包和测试类路径。

JavaStoryDevelop

你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在

下载

• application.properties 放在 src/main/resources，测试专用的 test-application.yml 必须放 src/test/resources，否则测试会读到生产配置
• 如果把资源文件误放进 src/main/java，Gradle 不会报错，但打包后这些文件不会出现在 JAR 的根路径下，而是嵌套在 java/ 子目录里，导致 getResource("config.json") 返回 null
• Spring Boot 的 @PropertySource 或 spring.config.location 也依赖此结构，混放会导致配置不生效

多模块项目中 settings.gradle 是结构入口

单模块项目可以没有 settings.gradle，但只要涉及子模块，它就是整个项目树的唯一定义点——Gradle 不会自动扫描子目录，一切模块都必须显式声明。

• settings.gradle.kts 中必须写 include("api", "service", "common")，漏掉任何一个，该模块的 build.gradle.kts 就不会被加载
• 模块名必须和文件夹名完全一致（区分大小写），比如 include("core") 对应 ./core/，而不是 ./Core/ 或 ./core-module/
• 根项目的 build.gradle.kts 通常只做统一配置（如 allprojects { repositories { mavenCentral() } }），具体构建逻辑应下沉到各模块自己的 build.gradle.kts 中

最常被忽略的一点：Gradle 不校验目录是否存在。你删掉 src/main/java，gradle build 仍会成功（只是产出空 JAR）；你把测试类放到 src/main/java，gradle test 会静默跳过——问题往往在运行时暴露，而不是构建阶段。

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南