1. 从“Hello World”到项目骨架为什么Spring Boot是Java新手的首选如果你刚接触Java后端开发或者被Spring框架复杂的XML配置劝退过那么Spring Boot就是你一直在等的那个“救星”。我第一次接触它的时候感觉就像从手动挡换到了自动挡——以前要花半天时间搭建的Web项目环境现在几分钟就能跑起来一个可用的服务。Spring Boot的核心价值就是“约定大于配置”。它预设了一套最佳实践帮你把Spring生态里那些繁琐的依赖管理、应用配置、服务器部署都打包好了你只需要专注于写业务代码。对于小白来说这意味着学习门槛被极大地降低了。你不用再纠结于该引入哪个版本的spring-core也不用在几十行的XML里配置一个Bean。Spring Boot通过一个spring-boot-starter-web依赖就帮你把Web MVC、内嵌Tomcat服务器、JSON序列化等全套东西都准备好了。它的自动配置机制会根据你引入的依赖和类路径下的文件智能地帮你完成绝大部分配置。你写的第一个控制器Controller可能只需要一个类和一个注解。所以这篇教程的目标很明确带你从零开始用最直观的方式亲手搭建一个Spring Boot项目并理解其背后的运行逻辑。我们不会上来就讲深奥的原理而是通过“做中学”让你在动手的过程中自然而然地掌握那些核心概念。当你看到浏览器里显示出“Hello, Spring Boot!”时你就已经跨过了最重要的一步。2. 环境准备与第一个项目避开初始化工具的“隐形坑”万事开头难但Spring Boot让开头变得异常简单。官方提供了多种创建项目的方式对于新手我强烈推荐使用Spring Initializr这是一个在线的项目生成器。不过这里有几个新手容易忽略的细节直接关系到你第一步能否成功。2.1 开发环境清单与版本选择策略在访问Initializr之前请确保你的本地环境已经就绪JDKSpring Boot 3.x 需要JDK 17或更高版本。这是硬性要求用JDK 8或11是无法启动的。建议直接安装OpenJDK 17或Oracle JDK 17并配置好JAVA_HOME环境变量。在命令行输入java -version验证。构建工具Maven或Gradle任选其一。对于国内网络环境Maven的生态和镜像配置更成熟遇到问题也更容易搜索到解决方案因此我建议新手从Maven开始。你需要安装Maven并配置其settings.xml文件使用阿里云等国内镜像仓库这能极大提升依赖下载速度。IDE集成开发环境IntelliJ IDEA Ultimate付费或 Community免费版是首选它对Spring Boot的支持是“开箱即用”级的。Eclipse with STS插件也可以但IDEA的体验和智能提示更友好。现在打开浏览器访问start.spring.io这就是Spring Initializr。页面上的选项很多我们一步步来填Project选择Maven Project。Gradle很强大但Maven的XML配置更直观便于理解依赖关系。LanguageJava。Spring Boot不要选择最新的快照SNAPSHOT版本。对于新手选择一个稳定的、文档丰富的版本至关重要。我推荐选择当前显示的稳定版比如3.2.x。太旧的版本如2.x和太新的快照版都可能遇到未知问题。Project MetadataGroup通常使用公司域名的倒写例如com.example。Artifact你的项目名例如my-first-boot-app。这里就用英文小写和横杠。Name、Description可以保持默认或简单填写。Package name会自动根据Group和Artifact生成例如com.example.myfirstbootapp。Packaging选择Jar。这是Spring Boot的推荐方式它会把应用打包成一个包含内嵌服务器的可执行JAR文件部署极其方便。Java选择你安装的JDK版本例如17。2.2 依赖选择理解“Starter”是什么这是最关键的一步。Initializr提供了大量“Starter”依赖每个Starter都是一组预打包好的依赖集合。我们第一个项目只需要最基础的Web功能。在Dependencies搜索框中输入web然后选择Spring Web。这个spring-boot-starter-webStarter会自动引入Spring MVC框架用于处理Web请求内嵌的Tomcat服务器默认Web容器Jackson库用于JSON序列化/反序列化一系列相关的、版本兼容的Spring核心库千万不要在这里勾选一大堆你暂时用不上的依赖比如Security安全、JPA数据库等。保持项目纯净有助于你理解核心流程。其他选项保持默认点击页面底部的GENERATE按钮下载一个ZIP压缩包。2.3 项目导入与目录结构解析解压ZIP包用IntelliJ IDEA打开这个文件夹。IDEA会自动识别为Maven项目并开始下载依赖观察右下角进度条。依赖下载完成后我们来看一下生成的项目结构my-first-boot-app/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/example/myfirstbootapp/ │ │ │ └── MyFirstBootAppApplication.java // 核心启动类 │ │ └── resources/ │ │ ├── static/ // 存放静态资源CSS, JS, 图片 │ │ ├── templates/ // 存放模板文件如Thymeleaf │ │ └── application.properties // 主配置文件 │ └── test/ // 测试代码目录 └── pom.xml // Maven项目对象模型管理依赖和构建重点文件解读MyFirstBootAppApplication.java这是Spring Boot应用的主启动类。它包含一个标准的main方法和一个SpringBootApplication注解。运行这个main方法就启动了整个Spring Boot应用。pom.xmlMaven的核心配置文件。打开它你会看到Spring Boot的父工程依赖spring-boot-starter-parent它统一管理了所有子依赖的版本这就是为什么我们不需要手动指定版本号。在dependencies里可以看到我们刚才选的spring-boot-starter-web。application.properties应用的配置文件。所有自定义的配置比如服务器端口、数据库连接等都可以在这里以keyvalue的形式进行设置。现在你可以直接右键点击MyFirstBootAppApplication.java选择Run ‘MyFirstBootAppApplication.main()‘。如果控制台没有报错并看到类似Tomcat started on port(s): 8080的日志恭喜你你的第一个Spring Boot应用已经启动成功了虽然它现在什么也做不了但服务器已经在8080端口监听了。3. 编写第一个REST接口搞懂注解背后的请求生命周期服务器跑起来了接下来我们要让它“说话”即响应HTTP请求。在Spring Boot中这通过编写Controller控制器来实现。Controller就像餐厅的服务员它接收客人的点单HTTP请求然后通知后厨Service层处理最后把做好的菜HTTP响应端给客人。3.1 创建Controller类与核心注解剖析在src/main/java/com/example/myfirstbootapp/目录下新建一个包例如controller。然后在这个包里新建一个Java类命名为HelloController。package com.example.myfirstbootapp.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController // 关键注解1表明这是一个REST风格的控制器 RequestMapping(/api) // 关键注解2为这个控制器下所有方法设置统一的请求路径前缀 public class HelloController { GetMapping(/hello) // 关键注解3处理HTTP GET请求映射到路径 /api/hello public String sayHello() { return Hello, Spring Boot!; } }我们来拆解这几个注解RestController这是一个组合注解它包含了Controller和ResponseBody。Controller标明这是一个Spring MVC的控制器BeanResponseBody告诉Spring这个控制器方法的返回值应该直接写入HTTP响应体Response Body而不是跳转到一个视图页面。对于返回JSON或纯文本的REST API必须用它。RequestMapping(“/api”)类级别的注解。它定义了这类中所有方法映射的URL的根路径。这样设计的好处是API路径清晰便于管理。例如用户相关的接口可以放在UserController里并统一前缀/api/user。GetMapping(“/hello”)方法级别的注解。它非常具体地声明了这个sayHello方法只处理发送到/api/hello的HTTP GET请求。类似的还有PostMapping,PutMapping,DeleteMapping分别对应POST、PUT、DELETE请求。这是一种“语义化”的映射比老式的RequestMapping(method RequestMethod.GET)更简洁直观。3.2 重启应用与接口测试代码写完后Spring Boot的DevTools如果引入了这个依赖支持热重启但为了确保万无一失我们第一次可以先停止应用然后重新运行MyFirstBootAppApplication。应用启动后打开你的浏览器访问http://localhost:8080/api/hello。你应该会在页面上看到纯文本Hello, Spring Boot!。这就是你的方法返回的字符串通过RestController和ResponseBody的魔力直接变成了HTTP响应。实操心得理解“约定大于配置”的体现到这里你可能会有疑问我并没有在任何地方配置这个URL路径/api/hello和HelloController的映射关系啊这就是Spring Boot“约定大于配置”的威力。当你给一个类加上RestController或Controller注解时Spring在启动过程中会自动扫描Component Scan这些类并将它们注册为Bean。同时它会解析类上和方法上的RequestMapping系列注解在内存中建立一张“URL路径 - 处理方法”的映射表。当内嵌Tomcat收到一个请求时Spring MVC的DispatcherServlet前端控制器就会查这张表找到对应的方法来执行。这一切都是自动完成的。3.3 进阶让接口返回JSON数据现代Web应用前后端分离后端接口主要返回JSON格式的数据。在Spring Boot中这简单到不可思议。我们修改一下sayHello方法让它返回一个对象。首先新建一个简单的Java类通常称为DTO或VO来承载数据。在controller同级目录下建一个dto包创建User.javapackage com.example.myfirstbootapp.dto; public class User { private String name; private Integer age; // 必须有无参构造函数默认就有 // 必须为每个字段提供getter和setter方法可以用Lombok注解简化这里先手写 public String getName() { return name; } public void setName(String name) { this.name name; } public Integer getAge() { return age; } public void setAge(Integer age) { this.age age; } }然后修改HelloController增加一个新接口package com.example.myfirstbootapp.controller; import com.example.myfirstbootapp.dto.User; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/api) public class HelloController { GetMapping(/hello) public String sayHello() { return Hello, Spring Boot!; } GetMapping(/user) public User getUser() { User user new User(); user.setName(张三); user.setAge(25); return user; // 直接返回对象 } }重启应用访问http://localhost:8080/api/user。你会发现浏览器或使用Postman等工具收到的不再是文本而是一个JSON对象{“name”: “张三”, “age”: 25}。核心原理这是因为spring-boot-starter-web默认引入了Jackson库。当方法返回一个对象时RestController下的ResponseBody会触发消息转换器HttpMessageConverterJackson会自动将这个Java对象序列化成JSON字符串并设置响应的Content-Type为application/json。整个过程对开发者完全透明。4. 配置文件详解区分“.properties”与“.yml”的适用场景Spring Boot的配置系统非常强大且灵活其核心是application.properties或application.yml文件。所有对框架默认行为的定制几乎都在这里完成。4.1 基础配置修改服务器端口与上下文路径默认情况下应用运行在8080端口没有上下文路径。我们可以在src/main/resources/application.properties中修改# 修改服务器端口为 9090 server.port9090 # 设置应用的上下文路径Context Path为 /boot server.servlet.context-path/boot修改后重启应用此时你的应用根地址变成了http://localhost:9090/boot。所以/api/hello接口的完整访问地址就变成了http://localhost:9090/boot/api/hello。为什么需要改端口一台机器上可能运行多个Spring Boot应用或者8080端口已被其他程序如Tomcat、Nginx占用修改端口可以避免冲突。4.2 YAML格式更清晰的结构化配置除了.properties文件Spring Boot也支持使用YAML.yml格式的配置文件它采用缩进来表示层级关系对于复杂的、有多层结构的配置可读性更强。将application.properties重命名为application.yml然后将内容转换为YAML格式server: port: 9090 servlet: context-path: /boot # 例如配置数据库连接假设使用H2内存数据库 spring: datasource: url: jdbc:h2:mem:testdb driver-class-name: org.h2.Driver username: sa password: h2: console: enabled: true # 启用H2数据库的Web控制台YAML的层级关系一目了然。spring.datasource.url在properties里是一行在YAML里通过缩进清晰地表达了它是datasource下的一个属性。注意YAML对缩进非常敏感必须使用空格通常2个不能使用Tab键。选.properties还是.yml简单配置如果配置项很少且没有复杂的嵌套.properties更直接。复杂配置当需要配置数据源、Redis集群、多环境配置等具有层次结构的属性时.yml的优势巨大结构清晰不易出错。个人习惯很多团队和开源项目默认使用.yml建议新手从.yml开始适应。4.3 多环境配置开发、测试、生产环境隔离在实际项目中开发、测试、生产环境的配置如数据库地址、日志级别通常是不同的。Spring Boot通过Profile机制来支持多环境配置。你可以创建多个配置文件命名规则为application-{profile}.yml。application-dev.yml开发环境配置application-test.yml测试环境配置application-prod.yml生产环境配置在application.yml中你可以设置默认激活哪个Profile# application.yml (主配置) spring: profiles: active: dev # 默认激活dev环境配置当你运行应用时Spring Boot会先加载application.yml然后加载application-dev.yml后者会覆盖前者的同名配置。这样公共配置写在application.yml环境特有配置写在对应的-dev.yml或-prod.yml中。启动时指定Profile你也可以在启动JAR包时通过命令行参数来指定激活的Profile这在生产环境部署时非常有用java -jar myapp.jar --spring.profiles.activeprod5. 自动配置与起步依赖理解Spring Boot的“魔法”内核前面我们一直在享受Spring Boot带来的便利现在是时候揭开部分“魔法”的面纱理解其核心原理自动配置Auto-Configuration和起步依赖Starter。5.1 起步依赖一站式的依赖打包回顾我们的pom.xml只引入了一个spring-boot-starter-web。但如果你查看Maven的依赖树在IDEA中右键项目 - Maven - Show Dependencies你会发现它引入了数十个传递依赖包括Spring MVC、Tomcat、Jackson等等。起步依赖的本质是一个Maven项目对象模型POM它定义了某个功能领域如Web、安全、数据访问所需的一组版本兼容的依赖库。例如spring-boot-starter-web的POM文件里就声明了对spring-boot-starter-tomcat、spring-webmvc、spring-boot-starter-json等的依赖。这样做的好处是依赖管理简化你无需记忆和查找几十个库及其兼容版本只需引入一个Starter。避免版本冲突Spring Boot团队已经帮你测试好了所有子依赖的兼容性组合。功能模块化需要什么功能就引入什么Starter清晰明了。5.2 自动配置条件化装配Bean这是Spring Boot最精妙的部分。Spring Boot在启动时会扫描类路径Classpath下的所有jar包寻找META-INF/spring.factories文件Spring Boot 2.7后逐渐改为META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。这个文件中列出了大量的自动配置类XXXAutoConfiguration。这些自动配置类上通常带有ConditionalOnXxx注解例如ConditionalOnClass当类路径下存在某个类时才生效。ConditionalOnMissingBean当Spring容器中不存在某个Bean时才生效。ConditionalOnProperty当配置文件中某个属性为特定值时才生效。举个例子当我们引入了spring-boot-starter-web类路径下就有了Spring MVC的相关类和内嵌Tomcat的类。WebMvcAutoConfiguration这个自动配置类上的ConditionalOnClass条件得到满足它就会生效。这个类内部通过Bean方法向Spring容器中注册了DispatcherServlet、视图解析器、消息转换器如MappingJackson2HttpMessageConverter用于JSON转换等一系列运行Web应用所必需的组件。而当你自己通过Bean显式地定义了一个同类型的Bean时ConditionalOnMissingBean条件就会让自动配置类中对应的Bean方法失效从而使用你自定义的Bean。这实现了“开箱即用”和“按需定制”的完美平衡。5.3 查看自动配置报告如果你想了解Spring Boot在本次启动中应用和未应用了哪些自动配置有一个非常实用的调试技巧。在application.yml中开启调试模式debug: true重启应用你会在启动日志中看到两大块内容Positive matches生效的自动配置类及原因。Negative matches未生效的自动配置类及原因例如因为缺少某个类。这份报告是理解自动配置机制的最佳学习材料。通过它你可以清楚地知道因为你引入了某个StarterSpring Boot为你自动配置了哪些东西。6. 常用Starter与项目结构规范构建可维护的工程掌握了核心机制后我们来了解几个最常用的Starter并规划一个标准、清晰的项目结构这对于任何规模的Spring Boot项目都至关重要。6.1 必知必会的核心Starter除了spring-boot-starter-web以下Starter出场率极高spring-boot-starter-data-jpa用于简化数据库操作整合Hibernate/JPA。它会自动配置数据源、实体管理器、事务管理等。spring-boot-starter-data-redis用于集成Redis提供RedisTemplate等便捷的操作模板。spring-boot-starter-security提供全面的安全控制认证和授权。spring-boot-starter-test单元测试Starter包含JUnit、Spring Test、AssertJ、Mockito等。spring-boot-starter-aop面向切面编程支持用于日志、事务、权限等横切关注点。spring-boot-starter-validation数据校验支持配合Valid注解使用。spring-boot-devtools开发工具支持应用热重启、静态资源热加载等提升开发效率。6.2 推荐的项目目录结构一个结构清晰的项目是团队协作和长期维护的基础。以下是一种广泛采用的MVC分层结构src/main/java/com/example/yourapp/ ├── YourappApplication.java // 主启动类放在根包下 ├── config/ // 配置类目录 │ ├── WebConfig.java // Web相关配置如拦截器 │ └── RedisConfig.java // Redis自定义配置 ├── controller/ // 控制器层处理HTTP请求 │ ├── UserController.java │ └── OrderController.java ├── service/ // 业务逻辑层 │ ├── UserService.java │ ├── impl/ │ │ └── UserServiceImpl.java // 接口实现类 │ └── OrderService.java ├── repository/ (或 dao/) // 数据访问层JPA中常叫repository │ ├── UserRepository.java // JPA Repository接口 │ └── OrderRepository.java ├── entity/ (或 model/domain/) // 实体类与数据库表对应 │ ├── User.java │ └── Order.java ├── dto/ // 数据传输对象用于接口入参/出参 │ ├── UserDTO.java │ └── OrderQueryDTO.java ├── vo/ // 视图对象用于返回给前端的数据封装 │ └── UserVO.java ├── util/ // 工具类 │ └── DateUtil.java └── exception/ // 自定义异常类 └── BusinessException.java分层职责解读Controller薄薄的一层只负责接收请求、调用Service、返回响应。不应包含复杂的业务逻辑。Service业务逻辑的核心所在地。处理具体的业务规则、流程编排、事务管理等。Repository/Dao负责与数据库或其他数据源直接交互执行CRUD操作。Entity纯粹的领域模型/数据模型通常使用JPA注解与数据库表映射。DTO/VO用于在不同层之间传输数据避免直接暴露Entity。DTO常用于接收前端参数VO用于封装返回给前端的复杂数据。Config存放各种Configuration配置类用于自定义Bean的装配。Exception定义项目统一的业务异常体系。遵循这样的结构能让你的代码职责清晰便于测试和维护。当项目规模增长时你还可以考虑按业务模块如user,order进行进一步的垂直拆分。7. 开发、调试与打包部署从编码到上线的完整链路最后我们把一个Spring Boot应用从编码、调试到最终打包部署的完整流程走通。7.1 热部署与日志调试热部署在开发过程中每次修改代码都要重启应用非常低效。引入spring-boot-devtools依赖可以实现应用的热重启注意不是热加载是快速重启。在pom.xml的dependencies中添加dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId scoperuntime/scope optionaltrue/optional /dependency添加后修改Java代码或配置文件IDEA会自动编译然后DevTools会触发应用重启。这个过程比冷启动快很多因为它使用了两个类加载器基础类库不变只重启你的业务代码。日志调试Spring Boot默认使用Logback作为日志框架。你可以在application.yml中轻松配置日志级别这对于排查问题至关重要。logging: level: # 将根日志级别设置为WARN减少无关信息 root: WARN # 将我们自己的应用包下的日志级别设置为DEBUG便于调试 com.example.myfirstbootapp: DEBUG # 将Spring框架SQL相关的日志级别设置为DEBUG可以查看执行的SQL语句 org.springframework.jdbc.core.JdbcTemplate: DEBUG org.springframework.jdbc.core.StatementCreatorUtils: TRACE在代码中使用日志通常通过Lombok的Slf4j注解需引入Lombok依赖或直接创建Logger对象import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.RestController; Slf4j RestController public class HelloController { GetMapping(/test) public String test() { log.debug(这是一个debug级别日志); log.info(处理了一个/test请求); log.error(模拟一个错误日志, new RuntimeException(测试异常)); return test; } }7.2 单元测试入门一个健壮的项目离不开测试。Spring Boot Test Starter提供了强大的测试支持。在src/test/java下你会找到一个与主类同名的测试类。一个基础的Web接口测试示例如下package com.example.myfirstbootapp; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.test.web.servlet.MockMvc; import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; SpringBootTest // 启动完整的Spring应用上下文 AutoConfigureMockMvc // 自动配置MockMvc用于模拟HTTP请求 class MyFirstBootAppApplicationTests { Autowired private MockMvc mockMvc; // 注入MockMvc对象 Test void testHelloApi() throws Exception { // 模拟发送GET请求到 /api/hello并验证状态码为200响应内容为Hello, Spring Boot! mockMvc.perform(get(/api/hello)) .andExpect(status().isOk()) .andExpect(content().string(Hello, Spring Boot!)); } }运行这个测试方法它会启动一个轻量级的应用环境不会启动内嵌Tomcat然后模拟请求并验证结果。这是保证代码质量的重要手段。7.3 打包与部署生成可执行JARSpring Boot应用最方便的部署方式就是打包成可执行的“Fat JAR”。这个JAR包内嵌了Web服务器如Tomcat和所有依赖库只需要有JRE环境就能运行。使用Maven打包非常简单。在项目根目录下打开终端执行mvn clean package如果使用IDEA可以点击右侧Maven工具栏中的Lifecycle-clean然后package。命令执行成功后在target/目录下会生成两个文件my-first-boot-app-0.0.1-SNAPSHOT.jar可执行JAR和my-first-boot-app-0.0.1-SNAPSHOT.jar.original不包含依赖的原始JAR。运行JAR包java -jar target/my-first-boot-app-0.0.1-SNAPSHOT.jar应用就会以和生产环境完全相同的方式启动。你可以通过--spring.profiles.activeprod参数指定生产环境配置或者使用-D设置JVM参数。部署到服务器只需将这个JAR包上传到Linux服务器使用nohup或systemd等工具在后台运行即可。例如nohup java -jar myapp.jar --spring.profiles.activeprod app.log 21 这就完成了从开发到上线的闭环。Spring Boot通过极简的配置和强大的约定让Java后端开发的入门和部署变得前所未有的简单。理解并熟练运用这些基础你就已经具备了用Spring Boot构建现代Web服务的能力。