详解 Spring Boot 4 项目结构：这些目录和文件到底干嘛用？（新手避坑指南）

本篇是《Spring Boot 4 学习从入门到大神》专栏第 3 篇。

很多初学者“能跑项目，但看不懂结构”。本篇把 Spring Boot 4 项目拆碎了讲，帮你建立正确的工程观。

一、一个标准 Spring Boot 4 项目长啥样？

先给你一个最标准、最推荐的项目结构：

spring-boot4-demo
├── .mvn
│ └── wrapper
│ ├── maven-wrapper.jar
│ └── maven-wrapper.properties
├── src
│ ├── main
│ │ ├── java
│ │ │ └── com
│ │ │ └── example
│ │ │ └── demo
│ │ │ ├── DemoApplication.java
│ │ │ ├── controller
│ │ │ ├── service
│ │ │ ├── repository
│ │ │ └── config
│ │ └── resources
│ │ ├── application.yml
│ │ ├── static
│ │ ├── templates
│ │ └── META-INF
│ └── test
│ └── java
│ └── com.example.demo
│ └── DemoApplicationTests.java
├── .gitignore
├── pom.xml
└── mvnw / mvnw.cmd

接下来我们从上到下、从外到内逐个拆解。

二、根目录下的“神秘文件”

1️⃣ pom.xml（项目的“身份证”）

这是 Maven 项目的核心文件。

Spring Boot 4 的 pom.xml 为什么这么简洁？

核心秘密在于：

<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.0.0</version>
</parent>

✅ 它帮你做了这些事：

• 统一依赖版本管理

• 默认插件配置（编译、打包、测试）

• 默认编码（UTF-8）

• 默认 Java 版本（17+）

👉 你只需要关心你用什么，不用关心版本号是多少。

2️⃣ mvnw / mvnw.cmd（Maven 包装器）

文件

作用

✅ 作用：“自带 Maven”

• 不用本地安装 Maven

• 保证团队使用相同 Maven 版本

📌 使用方式：

./mvnw clean install
mvnw.cmd clean install

3️⃣ .mvn 目录

.mvn
└── wrapper
├── maven-wrapper.jar
└── maven-wrapper.properties

这是 Maven Wrapper 的核心文件，用于：

• 指定 Maven 版本

• 自动下载 Maven

✅ 建议提交到 Git

4️⃣ .gitignore

Spring Boot 项目默认生成，已经帮你忽略了：

/target
!.mvn/wrapper/maven-wrapper.jar

✅ 不要乱改，否则容易把 target、IDE 配置提交上去。

三、src/main/java：写代码的地方（核心）

1️⃣ 启动类 DemoApplication.java

@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}

📌 黄金法则：

启动类必须放在根包下

原因：

• @ComponentScan 默认扫描当前包及其子包

• 放错位置会导致 Controller / Service 扫不到

2️⃣ 推荐的包结构（非常重要）

com.example.demo
├── DemoApplication.java
├── controller # 控制层（接收请求）
├── service # 业务层
│ └── impl
├── repository # 数据访问层
├── domain # 实体类（JPA / MyBatis）
├── dto # 数据传输对象
├── config # 配置类
└── exception # 自定义异常

✅ 这种结构：

• 符合分层架构

• 方便后期拆微服务

• 易维护、易扩展

四、src/main/resources：资源配置中心

1️⃣ application.yml（配置文件）

Spring Boot 4 强烈推荐 yml，而不是 properties。

server:
port: 8081

spring:
datasource:
url: jdbc:mysql://localhost:3306/test
username: root
password: root

✅ yml 优势：

• 结构清晰

• 层级关系明确

• 支持复杂配置

📌 注意缩进：空格，不是 Tab！

2️⃣ static：静态资源目录

static/
├── css
├── js
├── img
└── index.html

访问方式：

http://localhost:8080/css/style.css
http://localhost:8080/index.html

✅ 适合：

• HTML

• CSS

• JS

• 图片

3️⃣ templates：模板文件目录

用于服务端渲染（Thymeleaf / Fremarker）。

templates/
├── index.html
└── user/
└── list.html

示例（Thymeleaf）：

@GetMapping("/hello")
public String hello(Model model) {
model.addAttribute("name", "Spring Boot 4");
return "index";
}

📌 static vs templates 区别：

目录

是否经 Controller

4️⃣ META-INF 目录

常见用途：

• resources/META-INF/resources：WebJar 资源

• spring.factories（旧版）

• spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports（Spring Boot 4）

五、src/test/java：测试代码目录

@SpringBootTest
class DemoApplicationTests {

@Test
void contextLoads() {
}
}

✅ 特点：

• 包结构同 main

• 不打包到生产环境

• 用于单元测试 / 集成测试

📌 常用测试注解：

注解

作用

六、target 目录（重点：别提交！）

target/
├── classes
├── test-classes
├── demo.jar
└── maven-status

✅ 这是编译输出目录：

• 由 Maven 自动生成

• 包含编译后的 class 文件

• 包含打包后的 jar

🚫 绝对不要提交到 Git！

七、Spring Boot 4 项目结构常见坑（血泪总结）

❌ 坑1：启动类放错位置

现象：

• Controller 访问 404

• Service 注入失败

✅ 解决：

• 启动类放在根包

❌ 坑2：application.yml 缩进错误

现象：

• 配置不生效

• 启动报错

✅ 解决：

• 用空格缩进

• IDEA 开启 YAML 校验

❌ 坑3：static 和 templates 混用

现象：

• HTML 直接访问空白

• Thymeleaf 语法不生效

✅ 解决：

• 静态资源 → static

• 模板文件 → templates

❌ 坑4：把 target 提交到 Git

现象：

• 仓库巨大

• 冲突不断

✅ 解决：

• .gitignore 中加入 /target

八、Spring Boot 4 项目结构最佳实践（建议收藏）

✅ 启动类放在根包

✅ 使用 application.yml

✅ 按层分包，而不是按功能

✅ 测试代码与生产代码分离

✅ .mvn、pom.xml、src 必须提交

✅ target、*.iml 绝不提交

九、本篇总结

• Spring Boot 4 项目结构约定优于配置

• src/main/java 写代码

• src/main/resources 放配置

• static 和 templates 分工明确

• 启动类位置决定扫描范围

看懂项目结构，才算真正入门 Spring Boot。