Java项目搭建与结构规范详解

最近发现不少小伙伴都对文章很感兴趣，所以今天继续给大家介绍文章相关的知识，本文《Java项目初始化与结构规范解析》主要内容涉及到等等知识点，希望能帮到你！当然如果阅读本文时存在不同想法，可以在评论中表达，但是请勿使用过激的措辞~

Maven 通过 archetype 自动生成标准 Java 项目结构，含 src/main/java、src/test/java、pom.xml 等；需确保 packaging 为 jar，资源目录分离（main/resources 用于运行时，test/resources 仅测试用），源码路径必须严格匹配 package 声明，.gitignore 和 Maven Wrapper 应纳入版本控制。

用 Maven 创建符合标准结构的 Java 项目

标准 Java 项目结构不是靠手动建文件夹凑出来的，而是由构建工具（主要是 Maven）约定并生成的。直接执行命令就能得到带 src/main/java、src/test/java、pom.xml 等目录的干净骨架。

• 推荐使用官方 Archetype：mvn archetype:generate -DgroupId=com.example -DartifactId=myapp -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
• 生成后务必检查 pom.xml 中的 jar 是否存在——缺了它，IDE 可能不识别为可运行 Java 项目
• IntelliJ 或 Eclipse 导入时选 “Import project from external model → Maven”，别选 “Create project from existing sources”，否则目录不会被正确标记为 Sources/Test Sources

src/main/resources 和 src/test/resources 的作用不能颠倒

这两个目录在编译期会被分别复制到 target/classes 和 target/test-classes 下，类路径（classpath）加载资源时依赖这个分离机制。常见错误是把测试专用配置（如 application-test.yml）放在 src/main/resources 里，导致打包后污染生产环境。

• src/main/resources：所有运行时需要的配置、SQL 文件、静态模板等
• src/test/resources：仅测试阶段生效的 mock 配置、临时数据库脚本、测试用 JSON 样例
• Spring Boot 项目中，若用 @TestConfiguration + @ImportResource 加载 XML，确保 XML 在 src/test/resources 下，否则测试会误读主配置

Java 源码目录层级必须匹配 package 声明

Java 编译器和绝大多数 IDE（包括 javac 命令行）都强制要求物理路径与 package 语句严格一致。比如类声明为 package com.example.service;，那么它必须放在 src/main/java/com/example/service/ 下，多一级或少一级都会报 error: class X is public, should be declared in a file named X.java 或运行时报 NoClassDefFoundError。

• 不要手动在 IDE 里“新建包”再拖文件进去——先建好目录，再建类；或者用 IDE 的 “New → Java Class” 功能，它会自动同步创建路径
• 模块化项目（module-info.java）中，requires 和 exports 的包名也必须与实际路径一致，否则编译失败
• Gradle 用户注意：sourceSets.main.java.srcDirs 默认指向 src/main/java，改路径不如守规范

忽略文件和 IDE 配置要纳入版本控制

标准结构不止是目录，还包括协作必需的元配置。没它们，不同人拉下代码后可能因 IDE 设置不一致导致编译失败或单元测试跳过。

• 根目录放 .gitignore，至少包含：target/、**/*.class、.idea/、.vscode/、out/
• Maven 项目建议提交 mvnw 和 mvnw.cmd（Maven Wrapper），避免团队成员本地 Maven 版本不一致引发构建差异
• 如果用了 Lombok，pom.xml 中的 lombok 依赖必须设 provided，且 IDE 要安装对应插件——否则 @Data 等注解不会触发 getter/setter 生成，编译报错

├── pom.xml
├── mvnw
├── mvnw.cmd
├── .gitignore
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/myapp/
│   │   │       ├── MyApplication.java
│   │   │       └── domain/
│   │   ├── resources/
│   │       └── application.yml
│   └── test/
│       ├── java/
│       │   └── com/example/myapp/
│       │       └── MyApplicationTest.java
│       └── resources/
│           └── application-test.yml
└── target/ (not committed)

Java 项目结构看着简单，但真正卡住人的往往不是“怎么建”，而是“为什么这个路径下类找不到”“为什么测试配置没生效”“为什么 CI 构建成功本地却跑不了”——这些问题几乎都源于对目录语义和构建流程的模糊处理。

以上就是《Java项目搭建与结构规范详解》的详细内容，更多关于的资料请关注golang学习网公众号！