尧图网页设计 
Spring Boot 这东西说实话我一开始是有点抵触的。那时候还在用 SSM 拼 XML一个web.xml能写上百行数据源配错一个单词Tomcat 启动直接红一片。后来切到 Spring Boot第一次感受到什么叫“约定优于配置”项目从创建到跑起来前后不到五分钟。陆陆续续用了好几年也带过不少新人发现大部分人的问题其实都集中在一个点上不是 Spring Boot 本身难学而是第一步“项目创建”就没走顺后面越走越别扭。这篇文章算是系列的第二篇默认你已经知道 Spring Boot 是干嘛用的、解决了什么问题但还没真正动手建过一个项目。咱们这次不聊虚的直接从基础概念往下挖然后带着你用 IDEA 把项目从零建起来再把项目结构、启动过程、核心注解、配置文件的细节全部过一遍。你跟着操作完不仅能跑通一个 Web 项目还能搞清楚每个文件、每个注解为什么存在。考虑到现在 IDEA 版本更新快、Spring Boot 版本也一年比一年激进我会把版本选型、初始化超时、配置加密这些实操里容易踩的坑一并讲清楚。1. Spring Boot 到底解决了什么问题1.1 从 SSM 到 Spring Boot少写了多少配置我经常会问新人一个问题你没用 Spring Boot 之前搭一个 Web 项目需要做哪些事很多人答不上来因为他们的第一个项目就是用 Spring Boot 建的压根没经历过那个年代。我简单回忆一下最原始的 Spring MVC 项目要干的事先创建一个 Maven Web 项目在pom.xml里手动引入 Spring 核心、Spring MVC、Jackson、Servlet API 等一堆依赖还要操心版本兼容问题。然后写web.xml在里面配置DispatcherServlet、ContextLoaderListener、字符编码过滤器。接着写一个spring-mvc.xml配置注解驱动、组件扫描、视图解析器。数据源、事务、MyBatis 的配置也全部是 XML 文件动不动就是几百行。最让人崩溃的是项目跑不起来报错还不直观你根本不知道是包没引全还是 Bean 没扫到。Spring Boot 做的事情说白了就是把这些繁琐的配置收敛了。它通过“自动配置”机制在你引入spring-boot-starter-web之后默认帮你装配好 Spring MVC、内嵌 Tomcat、Jackson 这些组件。你不需要写web.xml不需要手动注册DispatcherServlet项目里一个main方法直接启动内嵌容器。这种体验上的转变对于刚接触 Java Web 开发的人来说几乎是一种解放。1.2 “约定优于配置”到底是什么Spring Boot 的核心哲学是“约定优于配置”翻译成人话就是框架先按最常见的场景把默认值设置好你只要不提出特殊需求就按默认的规则走。举几个最直观的例子项目结构上代码放在src/main/java资源放在src/main/resources这是 Maven 的标准目录Spring Boot 沿用这套约定你不需要额外配置源码路径。Web 项目默认端口是8080默认上下文路径是/。你要改端口只需要在配置文件里写一行server.port8081。配置文件名默认是application.properties或application.yml只要你放在classpath下Spring Boot 会自动读取。组件扫描默认从启动类所在的包开始往下扫所以启动类一般都放在根包下。这些约定看起来简单但背后省掉的是大量的决策成本。你不用去想“我这个配置文件该叫什么名字”直接按约定来就行。新人学 Spring Boot 最容易犯的一个错误就是不看默认值一上来就到处加配置结果反而把项目搞乱了。记住一点先按默认方式跑通再想着去定制。1.3 自动配置背后的核心逻辑自动配置是 Spring Boot 最让人省心、也最容易让人困惑的机制。省心是因为你不用手动写配置类困惑是因为一旦出现诡异问题你根本不知道是谁给你配的。核心逻辑其实不复杂Spring Boot 在启动时会自动加载META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件里声明的所有自动配置类。注意这里的“加载”不是真的全部生效而是带有条件判断的。每个自动配置类上都会标一堆条件注解比如ConditionalOnClass类路径下存在某个类才生效、ConditionalOnMissingBean容器中不存在某个 Bean 才生效、ConditionalOnProperty配置文件中存在指定属性才生效。举个例子你引入了spring-boot-starter-web类路径下有Servlet和Spring MVC相关类那么WebMvcAutoConfiguration就会生效帮你把 DispatcherServlet、默认的静态资源映射、消息转换器都配好。如果你自己又定义了一个WebMvcConfigurer的 BeanSpring Boot 会和你自己定义的配置合并不会暴力覆盖。理解这一点对排查问题帮助很大项目里如果多了一个你没写过的 Bean八成就是自动配置在起作用。你想看生效了哪些条件可以在配置里加一行debugtrue启动时控制台会输出一份自动配置报告详细列出哪些配置类生效、哪些未生效以及原因。排查配置问题时这个文档能省你大量时间。2. 动手之前的环境准备与版本选型2.1 JDK、Maven、IDEA 怎么搭配创建项目之前先把环境理顺。我见过太多新手卡在环境上JDK 装了 1.8 和 17 两个版本IDEA 里项目 SDK 选错了Maven 用的还是 IDEA 自带的结果依赖下载奇慢无比还经常报错。目前 Spring Boot 3.x 要求 JDK 17 起步Spring Boot 2.7 是 2.x 最后的版本支持 JDK 8。如果你机器上同时装了多个 JDK建议给不同项目做显式指定IDEA 的Project Structure - SDK和Settings - Build Tools - Maven - Importer里的 JDK 设置都要保持一致。Maven 我不是很推荐用 IDEA 自带的因为自带版本通常偏老而且它的本地仓库默认在 C 盘用户目录下时间长了能把系统盘撑爆。建议去 Maven 官网下载一个稳定版比如 3.8.8 或 3.9.x然后修改conf/settings.xml把本地仓库地址改到其他盘顺便把镜像改成国内源。具体怎么改下面配置章节会详细讲。IDEA 的话社区版免费版也能建 Spring Boot 项目只是在创建向导里少了 Spring Initializr 的图形化选项需要手动去官网拉模板。如果你用的是 2024 版本我更推荐直接用 IDEA 自带的 Spring Initializr体验已经很成熟了。Ultimate 版用户直接在 New Project 里选 Spring Initializr 就行。2.2 Spring Boot 版本号怎么看Spring Boot 的版本号有一套自己的规则比如3.2.5格式是“主版本.次版本.增量版本”。主版本是重大里程碑比如 2.x 到 3.x这意味着底层有很多不兼容的变更。次版本是功能迭代比如 3.1 到 3.2会增加新特性但整体兼容。增量版本是补丁修 bug、安全漏洞直接升级就行。选版本的原则我个人的建议是新项目不要追求最新但也不要选太老的。比如现在是 3.x 时代你如果还在用 2.7 确实有点跟不上节奏因为官方维护期已经过了。但如果你刚出 3.5 你就无脑升 3.5可能遇到一些刚引入的 bug而且在网上搜解决方案时资料还不够多。比较稳妥的做法是选当前主版本线里最新的稳定版的前一到两个版本或者直接看 Spring Initializr 默认给你的版本因为 Spring 官方会把默认版本调成经过较多验证的稳定版本。2.3 版本太高导致的坑怎么规避热词里有“springboot版本太高”这个说法这确实是很多人会遇到的困惑。其实大多数情况下不是版本本身有毛病而是你的运行环境、依赖库跟不上。JDK 版本不够Spring Boot 3.x 必须 JDK 17 以上你还在用 JDK 8 就会直接启动失败。依赖不兼容比如用 Spring Boot 3.2 搭配一个旧版的 MyBatis Spring Boot Starter它内部用的 Spring 6 的 API 可能对不上启动时会抛NoSuchMethodError或者ClassNotFoundException。Maven 编译器版本不对pom.xml里没指定java.version或者 Maven 的 compiler 插件默认用 JDK 8 的级别去编译 17 的语法直接报错。规避方法其实很简单第一创建项目时确认 Spring Boot 版本和 JDK 版本匹配第二用官方的spring-boot-starter-parent做父工程大部分依赖版本都不用你操心第三三方库不要乱给版本号优先看它有没有针对该 Spring Boot 版本的 Starter。如果你在 Spring Initializr 初始化时看到版本下拉里有一些后缀是SNAPSHOT或M1、M2的选项建议别选那是快照版和里程碑版适合尝鲜不适合学习入门。正式项目要用带RELEASE或者纯数字的稳定版。3. 用 IDEA 创建 Spring Boot 项目的完整实操3.1 推荐方案一官方 start.spring.io 初始化创建一个 Spring Boot 项目最常见的方式就是去 start.spring.io 生成一个模板包然后在 IDEA 里打开。我来说一下为什么推荐这个方式它是最原生的、不受 IDEA 版本影响的方案。IDEA 里内置的 Spring Initializr 本质上也是去请求这个服务只是帮你包了一层图形界面。有时候 IDEA 内置功能出问题直接用浏览器访问官网反而更稳定。官网界面很简单你需要填几项Project选 MavenGradle 也可以但生态上 Maven 资料更多。LanguageJava。Spring Boot选稳定版。Project MetadataGroup 一般填公司域名倒序Artifact 填项目名Name 一般和 Artifact 一致。Packaging默认 Jar。Java选你本机装的 JDK 主版本。Dependencies 面板里可以搜索并添加依赖第一次创建只需要加一个Spring Web就够了其他的等用到时再手动加。生成后是一个 zip 包解压后用 IDEA 的Open打开等 Maven 把依赖下载完就能启动。这里有个细节生成的压缩包解压后目录里会有一个mvnw.cmd和mvnw这是 Maven Wrapper它可以帮助你在没有安装 Maven 的机器上使用项目自带的 Maven 版本。如果你是直接用 IDEA 跑可以忽略它如果是命令行操作用./mvnw spring-boot:run跑项目更省心。3.2 推荐方案二IDEA 内置创建向导如果你用的是 IDEA 2024 版本内置向导已经很成熟了。具体路径是File - New - Project然后左侧选择Spring Initializr。注意IDEA 的 New Project 弹窗里默认有很多选项比如Java、Maven、Gradle、Spring Boot不要选成普通 Java 项目那样是没有 Spring Boot 选项的。进入向导后界面和 start.spring.io 基本一致填 Group、Artifact、选择依赖点 Finish 等着下载即可。IDEA 内置向导的优点是不需要自己再去解压、导入直接生成一个可识别的项目结构。但我遇到过不少情况内置向导的 Server URL 指向的是https://start.spring.io如果你的网络访问这个地址很慢甚至是超时IDEA 就会卡在“Initializing”界面很久最后报错。这个问题我在 3.3 小节专门说一下怎么绕过。3.3 初始化超时的排查与替代方案创建项目时卡在下载模板这是极其常见的问题。热词“idea 创建springboot 项目超时”说的就是它。超时原因主要有两类一类是网络连接start.spring.io不稳定另一类是 Maven 依赖下载慢。第一类问题解决方式是把 Server URL 换成国内可用的镜像地址。这里我提供一个思路在 IDEA 的Settings - Languages Frameworks - Spring Boot里可以修改 Initializr URL将其指向阿里云的镜像服务地址是https://start.aliyun.com。注意阿里云镜像的 Spring Boot 版本列表会比官网滞后但胜在速度快、稳定。如果你需要拉最新的版本等初始化完成后再到pom.xml里手动改版本号即可。第二类问题解决方式是在 Maven 的settings.xml里配置国内镜像源。常见的镜像地址有阿里云、华为云仓库等。配置方式是在mirrors节点下添加一个 mirror把central仓库指向镜像地址。这一步做完依赖下载速度会有质的飞跃。另外再补充一个经验IDEA 内置向导卡住的时候不要反复点 Next 或刷新那样只会让情况更乱。直接 CtrlC 取消本次创建检查网络和镜像配置后重新来一次。提示修改完 Maven 的 settings.xml 之后IDEA 里记得File - Reload All Maven Projects否则不会生效。判断镜像是否生效可以看 Maven 工具窗口里的日志如果下载地址变成maven.aliyun.com开头就说明设置成功了。3.4 创建完成后需要调整的默认配置项目创建成功IDEA 会自动打开这个项目Maven 开始下载依赖。这个过程第一次会比较久你可以打开右侧 Maven 面板观察下载进度。等依赖下完有 3 个默认设置我建议你检查一下编码格式IDEA 的Settings - Editor - File Encodings里把 Global Encoding、Project Encoding、Default encoding for properties files 全部改成 UTF-8。不然后面写中文注释、返回中文数据时控制台和页面都会出现乱码。Maven 运行器的 JDKSettings - Build Tools - Maven - Runner里把 JRE 选成你项目对应的 JDK 版本。Lombok 插件如果你后面要用 LombokIDEA 2021 之后的版本已经内置插件支持但需要确保Annotation Processing是开启状态。在Settings - Build, Execution, Deployment - Compiler - Annotation Processors勾选启用。这些配置不调整项目也能跑但跑到一半出现编码乱码、Lombok 不生效的问题排查起来挺烦的。提前做好基础设置后面能省事很多。4. Spring Boot 项目目录结构与启动流程拆解4.1 一个标准 Spring Boot 项目的目录长什么样项目创建完成后目录结构是这样的springboot-demo ├── src │ ├── main │ │ ├── java │ │ │ └── com/example/springbootdemo │ │ │ ├── SpringbootDemoApplication.java │ │ │ ├── controller │ │ │ ├── service │ │ │ ├── mapper │ │ │ └── entity │ │ └── resources │ │ ├── static │ │ ├── templates │ │ └── application.properties │ └── test │ └── java │ └── com/example/springbootdemo │ └── SpringbootDemoApplicationTests.java ├── pom.xml ├── mvnw ├── mvnw.cmd └── .gitignore初次创建时controller、service这些包是不存在的需要你自己手动创建。static目录放静态资源比如图片、CSS、JStemplates目录放模板文件比如 Thymeleaf 的 HTMLapplication.properties是全局配置文件我会在后面章节讲怎么改成更清爽的yml格式。src/test目录下有一个空的测试类它是 Spring Boot 自动生成的用SpringBootTest注解启动一个完整的应用上下文。这个类可以用于写集成测试但如果你只是快速启动项目它不影响任何事情可以暂时忽略。4.2 启动类为什么长这样打开SpringbootDemoApplication.java你会看到package com.example.springbootdemo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class SpringbootDemoApplication { public static void main(String[] args) { SpringApplication.run(SpringbootDemoApplication.class, args); } }这个类有两个关键点。第一SpringBootApplication是一个组合注解它包含了SpringBootConfiguration、EnableAutoConfiguration和ComponentScan。EnableAutoConfiguration开启自动配置ComponentScan让 Spring 扫描当前包及其子包下的所有组件。第二main方法里调用SpringApplication.run这个静态方法会创建应用上下文、解析配置、执行自动配置、启动内嵌的 Web 服务器。有一个细节要特别留意启动类一定要放在根包下也就是所有其他包的上级。很多人习惯把启动类放在某个子包下结果项目启动后 Controller 不生效访问接口 404其实就是因为ComponentScan默认只扫描启动类所在包及其子包你放在子包下的类根本没被扫描到。4.3 第一次启动要关注哪些日志配置完成后启动项目。第一次启动时控制台会输出几段关键信息Spring Boot 的 ASCII 艺术字体 Banner。日志级别为 INFO 的启动信息包括当前版本、运行环境。Tomcat started on port 8080 (http) with context path 这说明内嵌 Tomcat 启动成功。Started SpringbootDemoApplication in 2.345 seconds说明整个应用启动完成。Tomcat started on port 8080和Started ... in x seconds这两行是最需要关注的。如果你的端口被占用你会在前一行看到端口启动失败的错误如果 Bean 装配有问题后一行可能不会出现。启动完成之后浏览器访问http://localhost:8080如果看到一个白页或者错误页这是正常的因为你还没有写任何接口。要验证项目真的没问题可以在 IDEA 的终端里执行curl http://localhost:8080/actuator/health会得到一个404。这是因为你还没引入actuator依赖所以没有这个端点。别急先写一个接口来验证即可。5. 核心注解与第一个 REST 接口5.1 高频注解逐个说明Spring Boot 项目里注解的使用频率远高于 XML 配置建议趁早把它们的含义吃透。我挑几个最常见的RestController组合注解包含Controller和ResponseBody。标注在类上表示这个类是一个处理 HTTP 请求的控制器并且返回值会直接写入 HTTP 响应体而不是走视图解析器。RequestMapping映射 HTTP 请求路径到处理方法上。可以标注在类或方法上支持指定method属性来限定请求方式。它的便捷派生注解有GetMapping、PostMapping、PutMapping、DeleteMapping推荐优先使用派生注解语义更清晰。RequestParam绑定 HTTP 请求参数到方法参数上支持设置required和defaultValue。PathVariable绑定 URL 路径上的占位符参数。RequestBody把 HTTP 请求体中的 JSON 数据绑定到 Java 对象上常用于 POST 请求。ConfigurationProperties把配置文件里的属性批量绑定到一个 Java 对象上。相比Value逐个注入这个注解维护起来更方便适合配置项较多的场景。Autowired按类型自动注入依赖。为了更好的可读性现在也推荐在构造器上注入但在实际项目中Autowired还是最常见的写法。5.2 快速写出一个带参数的 GET 接口既然要验证项目是否跑通最快的办法就是写一个简单的接口。我建议你建一个controller包然后创建HelloController.javapackage com.example.springbootdemo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class HelloController { GetMapping(/hello) public String hello(RequestParam(value name, defaultValue World) String name) { return Hello, name !; } GetMapping(/hello/{id}) public String helloWithId(PathVariable Long id) { return Hello, id id; } }这段代码里包含了两种常见的参数传递方式。/hello?nameSpring是查询参数方式RequestParam负责解析/hello/100是路径参数方式PathVariable负责解析。两者的区别记住一点查询参数适合过滤、分页等可选项路径参数适合标识资源 ID。重启项目或者启用 DevTools 热更新后在浏览器访问这些接口你会看到对应的字符串输出。如果看到返回结果说明你的项目已经从“能启动”变成了“能处理业务请求”这是一个很大的里程碑。如果你希望返回的是结构化数据而不是简单字符串通常我们会定义一个统一的返回对象比如ResultT包含code、message、data三个字段。实际工作中前后端分离项目基本都采用这种方式统一响应格式。5.3 统一响应结构的小建议定义统一响应结构不只是为了好看更是为了前后端协作时能有一套固定约定。我经常看到一些半路出家的项目有的接口直接返回字符串有的返回 JSON 对象有的错误时直接抛异常返回默认错误结构前端对接时非常崩溃。建议的做法是定义一个泛型类package com.example.springbootdemo.common; public class ResultT { private Integer code; private String message; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMessage(success); result.setData(data); return result; } public static T ResultT error(Integer code, String message) { ResultT result new Result(); result.setCode(code); result.setMessage(message); return result; } }接口里只需要返回Result.success(Hello)前端就能拿到统一的结构。这样你在业务代码里只需要关心业务逻辑返回结构由公共类统一处理。等到后面做全局异常处理时这个结构还能继续复用。6. 配置文件、多环境切换与安全细节6.1 application.yml 的常用写法Spring Boot 早期版本的默认配置文件是application.properties现在更推荐用application.yml因为 YAML 的层级关系更清晰不会出现一长串点号连接属性名的情况。把.properties改为.yml后删掉原来的.properties文件就行Spring Boot 会优先读取yml。一个常用的application.yml初始模板server: port: 8081 servlet: context-path: /demo spring: application: name: springboot-demo datasource: url: jdbc:mysql://localhost:3306/test?useUnicodetruecharacterEncodingutf8 username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: true这里有几个细节要注意。server.port改了端口后访问地址就变成http://localhost:8081。context-path如果设置为/demo那么所有接口路径前面都要加/demo前缀例如/demo/hello。这个功能在做接口环境隔离时很有用。spring.application.name在单体项目里看上去没什么用但一旦你想接入配置中心或者做微服务应用名就是身份标识建议从第一天起就规范命名。6.2 敏感配置怎么加密不裸奔热词里有“springboot yml密文”这个需求在企业项目里非常常见。我们把数据库密码、第三方密钥直接写在application.yml里等于把钥匙挂在门上。解决思路有两种我用最简单的说法讲清楚。第一种是环境变量占位。配置不直接写死而是用${DB_PASSWORD}这种占位符让 Spring Boot 从系统环境变量里取值。这样源码仓库里不会出现明文密码部署时在服务器上设置环境变量即可。第二种是使用 Jasypt 对配置做对称加密。引入jasypt-spring-boot-starter依赖然后在配置里把明文替换成加密后的密文例如spring: datasource: password: ENC(加密后的密文) jasypt: encryptor: password: 加解密密钥项目启动时Jasypt 会自动把ENC(...)包裹的内容解密。密钥可以通过环境变量传入避免出现在代码里。这里提醒一句Jasypt 的密钥本身也要保管好不要提交到 Git否则等于没加密。如果你只做学习项目这个知识点可以先了解不需要立即落地。但心里要有个概念配置里凡是和生产环境相关的敏感信息都不能以明文形式直接出现在配置文件里。6.3 多环境 profile 切换不同环境用不同配置这是项目从开发走向线上必须解决的问题。开发的数据库和线上数据库不可能是一样的端口、日志级别、缓存配置也各不相同。Spring Boot 通过 profile 机制解决这个问题。在resources目录下你可以建多个配置文件application.yml公共配置。application-dev.yml开发环境。application-prod.yml生产环境。application.yml里通过spring.profiles.active指定当前激活哪个环境比如spring: profiles: active: dev启动的时候也可以用命令参数来覆盖java -jar springboot-demo.jar --spring.profiles.activeprod这样同一个 jar 包部署在开发服务器跑dev部署在线上跑prod相当于把复杂环境隔离问题简化成“启动时加一个参数”。想保持配置整洁的还可以用spring.profiles.group做 profile 分组比如把dev和db-dev归为一组但这是进阶用法入门阶段用上面的方案就够了。实战中我踩过一个坑就是application-dev.yml没有放在resources目录下而是随手建在了项目根目录。Spring Boot 死活读不到启动时提示找不到数据源最后花了十分钟才定位到是配置文件路径的问题。记住Spring Boot 只认classpath下的application*.yml其他位置就算你放在 pom.xml 同级目录它也不会自动加载。7. 常见问题与排查技巧实录7.1 启动类包路径错误导致 404这是新手最容易踩的坑也是最容易自查的项目能正常启动但访问接口时始终 404。如果你把启动类放在com.example.springbootdemo.controller包里而 Controller 放在com.example.springbootdemo包的上级ComponentScan默认扫描不到Controller 就不会被注册。排查方法很简单看启动类所在包的级联关系保证所有组件类都在启动类包路径下或者使用SpringBootApplication(scanBasePackages com.example)显式指定扫描路径。大部分情况下把启动类挪到根包就能解决。7.2 端口被占用的一系列连锁问题启动报Port 8080 was already in use这种情况很常见。Windows 下可以通过命令行查端口占用netstat -ano | findstr 8080拿到进程 PID 后用任务管理器结束对应进程或者在命令行执行taskkill /F /PID 进程号。如果你不想杀掉进程更省事的办法是改项目端口加上一行server.port8081。端口被占用本身不是大问题但要注意它有时候是前一次启动的应用没有完全关闭导致的而不是真的有别的程序占用了。如果你在 IDEA 里频繁重启项目偶尔会遇到端口被占用的假象等几秒再启动或者直接 kill 掉 IDEA 的 Java 进程即可。7.3 依赖下载慢的终极解决方案依赖下载慢不管换什么镜像核心思路都是修改 Maven 的settings.xml。我给一个完整的镜像配置参考mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf nameAliyun Maven Mirror/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors这个配置的意思是所有对 Maven 中央仓库的下载请求全部转发到阿里云的公共镜像。如果你项目里还用到了一些 Google 或 Spring 的专属仓库比如 Spring 的里程碑版本可以再加一个 Spring 的 mirror但一般情况下上面这个配置已经够用。镜像配置完之后依赖还是下载慢那就要检查是不是本地仓库的问题了。第一次下载时本地仓库是空的需要从远程拉取大量 JAR 包这个过程确实急不得。建议第一次创建项目后让它慢慢下不要中途取消因为中断后容易出现依赖缺失的恶心问题。中途如果报错删掉本地仓库里.lastUpdated结尾的文件再重新刷新。7.4 常见报错速查表报错信息常见原因解决方法Cannot determine embedded database driver class for database type NONE数据源配置缺失或未引入数据库依赖检查application.yml是否配置了spring.datasourceInvalid bound statement (not found)MyBatis 的 Mapper XML 路径配错检查mybatis.mapper-locations是否匹配实际路径Field xxx in Xxx required a bean of type yyy that could not be found组件没有被 Spring 扫描到或依赖未注入检查包路径和注解确认是否存在循环依赖Error creating bean with name xxxBean 初始化失败通常是构造器或配置属性类型不匹配看后续异常堆栈重点看Caused byjava.lang.UnsupportedClassVersionErrorJDK 版本过低class 文件版本高于 JVM 版本升级 JDK 或降低项目编译版本Failed to bind properties under spring.datasource配置属性类型转换失败检查 YAML 缩进、属性名拼写这张表不是万能的但能覆盖新手阶段 80% 的启动失败原因。遇到报错时不要只看第一行重点看异常堆栈里Caused by后面的内容那才是根本原因。7.5 Banner 生成和图个乐这个属于进阶的趣味技巧。热词里有“springboot banner生成器”原因是 Spring Boot 启动时默认会打印一段 ASCII 艺术字。你可以用在线生成器做一段自己的 Banner替换resources目录下的banner.txt文件想用纯文本、彩色字体都可以。Banner 虽然是个小东西但在团队内部做个项目代号展示、或者给新项目加个启动仪式感效果挺好的。而且操作没有任何风险只需要在src/main/resources下新建banner.txt把生成的内容粘贴进去就行。不喜欢的话直接删掉文件就恢复默认了。8. 面试与实战延伸把知识体系补完整8.1 Spring Boot 面试题中常考的几个点热词里出现了“springboot面试题”我顺便把高频问题梳理一下这些问题在社招和校招中出现频率极高Spring Boot 与 Spring 的关系Spring Boot 本质是 Spring Framework 的封装核心依然是 IoC 和 AOPSpring Boot 做的是简化配置、自动化装配、独立运行。自动配置原理是什么回答时提起EnableAutoConfiguration和AutoConfiguration.imports条件注解ConditionalOnClass、ConditionalOnMissingBean等。为什么 Spring Boot 的 jar 能直接运行因为spring-boot-maven-plugin把项目打成了一个可执行的 fat jar内部包含所有依赖和嵌入式的 Tomcat 容器启动时通过JarLauncher执行。如何理解 starterstarter 是一组依赖的集合通过 Maven 引入后配合自动配置类就注入了对应功能模块的 Bean。SpringBootApplication注解的组成包括SpringBootConfiguration、EnableAutoConfiguration、ComponentScan。如果基础概念能答上来面试官往往还会追问“自动配置生效的条件如何控制”所以前面那一节讲的条件注解要重点掌握。8.2 项目创建之后下一步学什么项目创建成功、第一个接口跑通这只是热身。接下来往哪个方向走我给你一个清晰的路线第一把 Spring MVC 的请求处理链路搞清楚。写接口谁都会但要理解一次 HTTP 请求从进入到返回经过了哪些组件DispatcherServlet、HandlerMapping、HandlerAdapter、参数解析器、消息转换器。第二掌握数据访问方式。JdbcTemplate 是基础但实际项目里 MyBatis 和 Spring Data JPA 用得更多。无论选哪个都要理解事务的传播行为Transactional的失效场景。第三学会整合常用组件。Redis、RabbitMQ、Elasticsearch 这些中间件Spring Boot 都有对应的 starter选择项目实际需要的学不用贪多。第四深入了解部署与运维。项目打包成 jar部署到服务器上跑起来配好日志输出、健康检查。热词里出现的“heapdump 敏感信息泄露漏洞”就是一个安全问题线上项目要限制/actuator/heapdump这类端点的访问权限。这四个方向走完你基本从“会创建项目”进阶到了“能开发项目”。我在实际带项目时有个很深的体会很多人学 Spring Boot把太多精力花在用奇技淫巧上反而忽略了最基础的东西。其实把项目创建、配置、接口、日志、异常处理这五件事做扎实日常开发就已经够用了。框架本身变化很快但底层的 Spring IoC 思想、MVC 处理流程、面向约定编程的思维这些不容易变。你把这些地基打好以后不管框架怎么升级学起来都很快。最后再分享一个小技巧创建一个新项目时别急着写业务代码先把包结构、统一返回、全局异常、日志打印这些基础设施搭好。我见过很多人项目跑起来就往 Controller 里堆业务三个月后整个项目乱成一锅粥再想重构就难了。好的开始真的能省掉后面无数的返工。 Spring Boot项目创建指南：从IDEA搭建到配置实战
Spring Boot 这东西说实话我一开始是有点抵触的。那时候还在用 SSM 拼 XML一个web.xml能写上百行数据源配错一个单词Tomcat 启动直接红一片。后来切到 Spring Boot第一次感受到什么叫“约定优于配置”项目从创建到跑起来前后不到五分钟。陆陆续续用了好几年也带过不少新人发现大部分人的问题其实都集中在一个点上不是 Spring Boot 本身难学而是第一步“项目创建”就没走顺后面越走越别扭。这篇文章算是系列的第二篇默认你已经知道 Spring Boot 是干嘛用的、解决了什么问题但还没真正动手建过一个项目。咱们这次不聊虚的直接从基础概念往下挖然后带着你用 IDEA 把项目从零建起来再把项目结构、启动过程、核心注解、配置文件的细节全部过一遍。你跟着操作完不仅能跑通一个 Web 项目还能搞清楚每个文件、每个注解为什么存在。考虑到现在 IDEA 版本更新快、Spring Boot 版本也一年比一年激进我会把版本选型、初始化超时、配置加密这些实操里容易踩的坑一并讲清楚。1. Spring Boot 到底解决了什么问题1.1 从 SSM 到 Spring Boot少写了多少配置我经常会问新人一个问题你没用 Spring Boot 之前搭一个 Web 项目需要做哪些事很多人答不上来因为他们的第一个项目就是用 Spring Boot 建的压根没经历过那个年代。我简单回忆一下最原始的 Spring MVC 项目要干的事先创建一个 Maven Web 项目在pom.xml里手动引入 Spring 核心、Spring MVC、Jackson、Servlet API 等一堆依赖还要操心版本兼容问题。然后写web.xml在里面配置DispatcherServlet、ContextLoaderListener、字符编码过滤器。接着写一个spring-mvc.xml配置注解驱动、组件扫描、视图解析器。数据源、事务、MyBatis 的配置也全部是 XML 文件动不动就是几百行。最让人崩溃的是项目跑不起来报错还不直观你根本不知道是包没引全还是 Bean 没扫到。Spring Boot 做的事情说白了就是把这些繁琐的配置收敛了。它通过“自动配置”机制在你引入spring-boot-starter-web之后默认帮你装配好 Spring MVC、内嵌 Tomcat、Jackson 这些组件。你不需要写web.xml不需要手动注册DispatcherServlet项目里一个main方法直接启动内嵌容器。这种体验上的转变对于刚接触 Java Web 开发的人来说几乎是一种解放。1.2 “约定优于配置”到底是什么Spring Boot 的核心哲学是“约定优于配置”翻译成人话就是框架先按最常见的场景把默认值设置好你只要不提出特殊需求就按默认的规则走。举几个最直观的例子项目结构上代码放在src/main/java资源放在src/main/resources这是 Maven 的标准目录Spring Boot 沿用这套约定你不需要额外配置源码路径。Web 项目默认端口是8080默认上下文路径是/。你要改端口只需要在配置文件里写一行server.port8081。配置文件名默认是application.properties或application.yml只要你放在classpath下Spring Boot 会自动读取。组件扫描默认从启动类所在的包开始往下扫所以启动类一般都放在根包下。这些约定看起来简单但背后省掉的是大量的决策成本。你不用去想“我这个配置文件该叫什么名字”直接按约定来就行。新人学 Spring Boot 最容易犯的一个错误就是不看默认值一上来就到处加配置结果反而把项目搞乱了。记住一点先按默认方式跑通再想着去定制。1.3 自动配置背后的核心逻辑自动配置是 Spring Boot 最让人省心、也最容易让人困惑的机制。省心是因为你不用手动写配置类困惑是因为一旦出现诡异问题你根本不知道是谁给你配的。核心逻辑其实不复杂Spring Boot 在启动时会自动加载META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件里声明的所有自动配置类。注意这里的“加载”不是真的全部生效而是带有条件判断的。每个自动配置类上都会标一堆条件注解比如ConditionalOnClass类路径下存在某个类才生效、ConditionalOnMissingBean容器中不存在某个 Bean 才生效、ConditionalOnProperty配置文件中存在指定属性才生效。举个例子你引入了spring-boot-starter-web类路径下有Servlet和Spring MVC相关类那么WebMvcAutoConfiguration就会生效帮你把 DispatcherServlet、默认的静态资源映射、消息转换器都配好。如果你自己又定义了一个WebMvcConfigurer的 BeanSpring Boot 会和你自己定义的配置合并不会暴力覆盖。理解这一点对排查问题帮助很大项目里如果多了一个你没写过的 Bean八成就是自动配置在起作用。你想看生效了哪些条件可以在配置里加一行debugtrue启动时控制台会输出一份自动配置报告详细列出哪些配置类生效、哪些未生效以及原因。排查配置问题时这个文档能省你大量时间。2. 动手之前的环境准备与版本选型2.1 JDK、Maven、IDEA 怎么搭配创建项目之前先把环境理顺。我见过太多新手卡在环境上JDK 装了 1.8 和 17 两个版本IDEA 里项目 SDK 选错了Maven 用的还是 IDEA 自带的结果依赖下载奇慢无比还经常报错。目前 Spring Boot 3.x 要求 JDK 17 起步Spring Boot 2.7 是 2.x 最后的版本支持 JDK 8。如果你机器上同时装了多个 JDK建议给不同项目做显式指定IDEA 的Project Structure - SDK和Settings - Build Tools - Maven - Importer里的 JDK 设置都要保持一致。Maven 我不是很推荐用 IDEA 自带的因为自带版本通常偏老而且它的本地仓库默认在 C 盘用户目录下时间长了能把系统盘撑爆。建议去 Maven 官网下载一个稳定版比如 3.8.8 或 3.9.x然后修改conf/settings.xml把本地仓库地址改到其他盘顺便把镜像改成国内源。具体怎么改下面配置章节会详细讲。IDEA 的话社区版免费版也能建 Spring Boot 项目只是在创建向导里少了 Spring Initializr 的图形化选项需要手动去官网拉模板。如果你用的是 2024 版本我更推荐直接用 IDEA 自带的 Spring Initializr体验已经很成熟了。Ultimate 版用户直接在 New Project 里选 Spring Initializr 就行。2.2 Spring Boot 版本号怎么看Spring Boot 的版本号有一套自己的规则比如3.2.5格式是“主版本.次版本.增量版本”。主版本是重大里程碑比如 2.x 到 3.x这意味着底层有很多不兼容的变更。次版本是功能迭代比如 3.1 到 3.2会增加新特性但整体兼容。增量版本是补丁修 bug、安全漏洞直接升级就行。选版本的原则我个人的建议是新项目不要追求最新但也不要选太老的。比如现在是 3.x 时代你如果还在用 2.7 确实有点跟不上节奏因为官方维护期已经过了。但如果你刚出 3.5 你就无脑升 3.5可能遇到一些刚引入的 bug而且在网上搜解决方案时资料还不够多。比较稳妥的做法是选当前主版本线里最新的稳定版的前一到两个版本或者直接看 Spring Initializr 默认给你的版本因为 Spring 官方会把默认版本调成经过较多验证的稳定版本。2.3 版本太高导致的坑怎么规避热词里有“springboot版本太高”这个说法这确实是很多人会遇到的困惑。其实大多数情况下不是版本本身有毛病而是你的运行环境、依赖库跟不上。JDK 版本不够Spring Boot 3.x 必须 JDK 17 以上你还在用 JDK 8 就会直接启动失败。依赖不兼容比如用 Spring Boot 3.2 搭配一个旧版的 MyBatis Spring Boot Starter它内部用的 Spring 6 的 API 可能对不上启动时会抛NoSuchMethodError或者ClassNotFoundException。Maven 编译器版本不对pom.xml里没指定java.version或者 Maven 的 compiler 插件默认用 JDK 8 的级别去编译 17 的语法直接报错。规避方法其实很简单第一创建项目时确认 Spring Boot 版本和 JDK 版本匹配第二用官方的spring-boot-starter-parent做父工程大部分依赖版本都不用你操心第三三方库不要乱给版本号优先看它有没有针对该 Spring Boot 版本的 Starter。如果你在 Spring Initializr 初始化时看到版本下拉里有一些后缀是SNAPSHOT或M1、M2的选项建议别选那是快照版和里程碑版适合尝鲜不适合学习入门。正式项目要用带RELEASE或者纯数字的稳定版。3. 用 IDEA 创建 Spring Boot 项目的完整实操3.1 推荐方案一官方 start.spring.io 初始化创建一个 Spring Boot 项目最常见的方式就是去 start.spring.io 生成一个模板包然后在 IDEA 里打开。我来说一下为什么推荐这个方式它是最原生的、不受 IDEA 版本影响的方案。IDEA 里内置的 Spring Initializr 本质上也是去请求这个服务只是帮你包了一层图形界面。有时候 IDEA 内置功能出问题直接用浏览器访问官网反而更稳定。官网界面很简单你需要填几项Project选 MavenGradle 也可以但生态上 Maven 资料更多。LanguageJava。Spring Boot选稳定版。Project MetadataGroup 一般填公司域名倒序Artifact 填项目名Name 一般和 Artifact 一致。Packaging默认 Jar。Java选你本机装的 JDK 主版本。Dependencies 面板里可以搜索并添加依赖第一次创建只需要加一个Spring Web就够了其他的等用到时再手动加。生成后是一个 zip 包解压后用 IDEA 的Open打开等 Maven 把依赖下载完就能启动。这里有个细节生成的压缩包解压后目录里会有一个mvnw.cmd和mvnw这是 Maven Wrapper它可以帮助你在没有安装 Maven 的机器上使用项目自带的 Maven 版本。如果你是直接用 IDEA 跑可以忽略它如果是命令行操作用./mvnw spring-boot:run跑项目更省心。3.2 推荐方案二IDEA 内置创建向导如果你用的是 IDEA 2024 版本内置向导已经很成熟了。具体路径是File - New - Project然后左侧选择Spring Initializr。注意IDEA 的 New Project 弹窗里默认有很多选项比如Java、Maven、Gradle、Spring Boot不要选成普通 Java 项目那样是没有 Spring Boot 选项的。进入向导后界面和 start.spring.io 基本一致填 Group、Artifact、选择依赖点 Finish 等着下载即可。IDEA 内置向导的优点是不需要自己再去解压、导入直接生成一个可识别的项目结构。但我遇到过不少情况内置向导的 Server URL 指向的是https://start.spring.io如果你的网络访问这个地址很慢甚至是超时IDEA 就会卡在“Initializing”界面很久最后报错。这个问题我在 3.3 小节专门说一下怎么绕过。3.3 初始化超时的排查与替代方案创建项目时卡在下载模板这是极其常见的问题。热词“idea 创建springboot 项目超时”说的就是它。超时原因主要有两类一类是网络连接start.spring.io不稳定另一类是 Maven 依赖下载慢。第一类问题解决方式是把 Server URL 换成国内可用的镜像地址。这里我提供一个思路在 IDEA 的Settings - Languages Frameworks - Spring Boot里可以修改 Initializr URL将其指向阿里云的镜像服务地址是https://start.aliyun.com。注意阿里云镜像的 Spring Boot 版本列表会比官网滞后但胜在速度快、稳定。如果你需要拉最新的版本等初始化完成后再到pom.xml里手动改版本号即可。第二类问题解决方式是在 Maven 的settings.xml里配置国内镜像源。常见的镜像地址有阿里云、华为云仓库等。配置方式是在mirrors节点下添加一个 mirror把central仓库指向镜像地址。这一步做完依赖下载速度会有质的飞跃。另外再补充一个经验IDEA 内置向导卡住的时候不要反复点 Next 或刷新那样只会让情况更乱。直接 CtrlC 取消本次创建检查网络和镜像配置后重新来一次。提示修改完 Maven 的 settings.xml 之后IDEA 里记得File - Reload All Maven Projects否则不会生效。判断镜像是否生效可以看 Maven 工具窗口里的日志如果下载地址变成maven.aliyun.com开头就说明设置成功了。3.4 创建完成后需要调整的默认配置项目创建成功IDEA 会自动打开这个项目Maven 开始下载依赖。这个过程第一次会比较久你可以打开右侧 Maven 面板观察下载进度。等依赖下完有 3 个默认设置我建议你检查一下编码格式IDEA 的Settings - Editor - File Encodings里把 Global Encoding、Project Encoding、Default encoding for properties files 全部改成 UTF-8。不然后面写中文注释、返回中文数据时控制台和页面都会出现乱码。Maven 运行器的 JDKSettings - Build Tools - Maven - Runner里把 JRE 选成你项目对应的 JDK 版本。Lombok 插件如果你后面要用 LombokIDEA 2021 之后的版本已经内置插件支持但需要确保Annotation Processing是开启状态。在Settings - Build, Execution, Deployment - Compiler - Annotation Processors勾选启用。这些配置不调整项目也能跑但跑到一半出现编码乱码、Lombok 不生效的问题排查起来挺烦的。提前做好基础设置后面能省事很多。4. Spring Boot 项目目录结构与启动流程拆解4.1 一个标准 Spring Boot 项目的目录长什么样项目创建完成后目录结构是这样的springboot-demo ├── src │ ├── main │ │ ├── java │ │ │ └── com/example/springbootdemo │ │ │ ├── SpringbootDemoApplication.java │ │ │ ├── controller │ │ │ ├── service │ │ │ ├── mapper │ │ │ └── entity │ │ └── resources │ │ ├── static │ │ ├── templates │ │ └── application.properties │ └── test │ └── java │ └── com/example/springbootdemo │ └── SpringbootDemoApplicationTests.java ├── pom.xml ├── mvnw ├── mvnw.cmd └── .gitignore初次创建时controller、service这些包是不存在的需要你自己手动创建。static目录放静态资源比如图片、CSS、JStemplates目录放模板文件比如 Thymeleaf 的 HTMLapplication.properties是全局配置文件我会在后面章节讲怎么改成更清爽的yml格式。src/test目录下有一个空的测试类它是 Spring Boot 自动生成的用SpringBootTest注解启动一个完整的应用上下文。这个类可以用于写集成测试但如果你只是快速启动项目它不影响任何事情可以暂时忽略。4.2 启动类为什么长这样打开SpringbootDemoApplication.java你会看到package com.example.springbootdemo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class SpringbootDemoApplication { public static void main(String[] args) { SpringApplication.run(SpringbootDemoApplication.class, args); } }这个类有两个关键点。第一SpringBootApplication是一个组合注解它包含了SpringBootConfiguration、EnableAutoConfiguration和ComponentScan。EnableAutoConfiguration开启自动配置ComponentScan让 Spring 扫描当前包及其子包下的所有组件。第二main方法里调用SpringApplication.run这个静态方法会创建应用上下文、解析配置、执行自动配置、启动内嵌的 Web 服务器。有一个细节要特别留意启动类一定要放在根包下也就是所有其他包的上级。很多人习惯把启动类放在某个子包下结果项目启动后 Controller 不生效访问接口 404其实就是因为ComponentScan默认只扫描启动类所在包及其子包你放在子包下的类根本没被扫描到。4.3 第一次启动要关注哪些日志配置完成后启动项目。第一次启动时控制台会输出几段关键信息Spring Boot 的 ASCII 艺术字体 Banner。日志级别为 INFO 的启动信息包括当前版本、运行环境。Tomcat started on port 8080 (http) with context path 这说明内嵌 Tomcat 启动成功。Started SpringbootDemoApplication in 2.345 seconds说明整个应用启动完成。Tomcat started on port 8080和Started ... in x seconds这两行是最需要关注的。如果你的端口被占用你会在前一行看到端口启动失败的错误如果 Bean 装配有问题后一行可能不会出现。启动完成之后浏览器访问http://localhost:8080如果看到一个白页或者错误页这是正常的因为你还没有写任何接口。要验证项目真的没问题可以在 IDEA 的终端里执行curl http://localhost:8080/actuator/health会得到一个404。这是因为你还没引入actuator依赖所以没有这个端点。别急先写一个接口来验证即可。5. 核心注解与第一个 REST 接口5.1 高频注解逐个说明Spring Boot 项目里注解的使用频率远高于 XML 配置建议趁早把它们的含义吃透。我挑几个最常见的RestController组合注解包含Controller和ResponseBody。标注在类上表示这个类是一个处理 HTTP 请求的控制器并且返回值会直接写入 HTTP 响应体而不是走视图解析器。RequestMapping映射 HTTP 请求路径到处理方法上。可以标注在类或方法上支持指定method属性来限定请求方式。它的便捷派生注解有GetMapping、PostMapping、PutMapping、DeleteMapping推荐优先使用派生注解语义更清晰。RequestParam绑定 HTTP 请求参数到方法参数上支持设置required和defaultValue。PathVariable绑定 URL 路径上的占位符参数。RequestBody把 HTTP 请求体中的 JSON 数据绑定到 Java 对象上常用于 POST 请求。ConfigurationProperties把配置文件里的属性批量绑定到一个 Java 对象上。相比Value逐个注入这个注解维护起来更方便适合配置项较多的场景。Autowired按类型自动注入依赖。为了更好的可读性现在也推荐在构造器上注入但在实际项目中Autowired还是最常见的写法。5.2 快速写出一个带参数的 GET 接口既然要验证项目是否跑通最快的办法就是写一个简单的接口。我建议你建一个controller包然后创建HelloController.javapackage com.example.springbootdemo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class HelloController { GetMapping(/hello) public String hello(RequestParam(value name, defaultValue World) String name) { return Hello, name !; } GetMapping(/hello/{id}) public String helloWithId(PathVariable Long id) { return Hello, id id; } }这段代码里包含了两种常见的参数传递方式。/hello?nameSpring是查询参数方式RequestParam负责解析/hello/100是路径参数方式PathVariable负责解析。两者的区别记住一点查询参数适合过滤、分页等可选项路径参数适合标识资源 ID。重启项目或者启用 DevTools 热更新后在浏览器访问这些接口你会看到对应的字符串输出。如果看到返回结果说明你的项目已经从“能启动”变成了“能处理业务请求”这是一个很大的里程碑。如果你希望返回的是结构化数据而不是简单字符串通常我们会定义一个统一的返回对象比如ResultT包含code、message、data三个字段。实际工作中前后端分离项目基本都采用这种方式统一响应格式。5.3 统一响应结构的小建议定义统一响应结构不只是为了好看更是为了前后端协作时能有一套固定约定。我经常看到一些半路出家的项目有的接口直接返回字符串有的返回 JSON 对象有的错误时直接抛异常返回默认错误结构前端对接时非常崩溃。建议的做法是定义一个泛型类package com.example.springbootdemo.common; public class ResultT { private Integer code; private String message; private T data; public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMessage(success); result.setData(data); return result; } public static T ResultT error(Integer code, String message) { ResultT result new Result(); result.setCode(code); result.setMessage(message); return result; } }接口里只需要返回Result.success(Hello)前端就能拿到统一的结构。这样你在业务代码里只需要关心业务逻辑返回结构由公共类统一处理。等到后面做全局异常处理时这个结构还能继续复用。6. 配置文件、多环境切换与安全细节6.1 application.yml 的常用写法Spring Boot 早期版本的默认配置文件是application.properties现在更推荐用application.yml因为 YAML 的层级关系更清晰不会出现一长串点号连接属性名的情况。把.properties改为.yml后删掉原来的.properties文件就行Spring Boot 会优先读取yml。一个常用的application.yml初始模板server: port: 8081 servlet: context-path: /demo spring: application: name: springboot-demo datasource: url: jdbc:mysql://localhost:3306/test?useUnicodetruecharacterEncodingutf8 username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: true这里有几个细节要注意。server.port改了端口后访问地址就变成http://localhost:8081。context-path如果设置为/demo那么所有接口路径前面都要加/demo前缀例如/demo/hello。这个功能在做接口环境隔离时很有用。spring.application.name在单体项目里看上去没什么用但一旦你想接入配置中心或者做微服务应用名就是身份标识建议从第一天起就规范命名。6.2 敏感配置怎么加密不裸奔热词里有“springboot yml密文”这个需求在企业项目里非常常见。我们把数据库密码、第三方密钥直接写在application.yml里等于把钥匙挂在门上。解决思路有两种我用最简单的说法讲清楚。第一种是环境变量占位。配置不直接写死而是用${DB_PASSWORD}这种占位符让 Spring Boot 从系统环境变量里取值。这样源码仓库里不会出现明文密码部署时在服务器上设置环境变量即可。第二种是使用 Jasypt 对配置做对称加密。引入jasypt-spring-boot-starter依赖然后在配置里把明文替换成加密后的密文例如spring: datasource: password: ENC(加密后的密文) jasypt: encryptor: password: 加解密密钥项目启动时Jasypt 会自动把ENC(...)包裹的内容解密。密钥可以通过环境变量传入避免出现在代码里。这里提醒一句Jasypt 的密钥本身也要保管好不要提交到 Git否则等于没加密。如果你只做学习项目这个知识点可以先了解不需要立即落地。但心里要有个概念配置里凡是和生产环境相关的敏感信息都不能以明文形式直接出现在配置文件里。6.3 多环境 profile 切换不同环境用不同配置这是项目从开发走向线上必须解决的问题。开发的数据库和线上数据库不可能是一样的端口、日志级别、缓存配置也各不相同。Spring Boot 通过 profile 机制解决这个问题。在resources目录下你可以建多个配置文件application.yml公共配置。application-dev.yml开发环境。application-prod.yml生产环境。application.yml里通过spring.profiles.active指定当前激活哪个环境比如spring: profiles: active: dev启动的时候也可以用命令参数来覆盖java -jar springboot-demo.jar --spring.profiles.activeprod这样同一个 jar 包部署在开发服务器跑dev部署在线上跑prod相当于把复杂环境隔离问题简化成“启动时加一个参数”。想保持配置整洁的还可以用spring.profiles.group做 profile 分组比如把dev和db-dev归为一组但这是进阶用法入门阶段用上面的方案就够了。实战中我踩过一个坑就是application-dev.yml没有放在resources目录下而是随手建在了项目根目录。Spring Boot 死活读不到启动时提示找不到数据源最后花了十分钟才定位到是配置文件路径的问题。记住Spring Boot 只认classpath下的application*.yml其他位置就算你放在 pom.xml 同级目录它也不会自动加载。7. 常见问题与排查技巧实录7.1 启动类包路径错误导致 404这是新手最容易踩的坑也是最容易自查的项目能正常启动但访问接口时始终 404。如果你把启动类放在com.example.springbootdemo.controller包里而 Controller 放在com.example.springbootdemo包的上级ComponentScan默认扫描不到Controller 就不会被注册。排查方法很简单看启动类所在包的级联关系保证所有组件类都在启动类包路径下或者使用SpringBootApplication(scanBasePackages com.example)显式指定扫描路径。大部分情况下把启动类挪到根包就能解决。7.2 端口被占用的一系列连锁问题启动报Port 8080 was already in use这种情况很常见。Windows 下可以通过命令行查端口占用netstat -ano | findstr 8080拿到进程 PID 后用任务管理器结束对应进程或者在命令行执行taskkill /F /PID 进程号。如果你不想杀掉进程更省事的办法是改项目端口加上一行server.port8081。端口被占用本身不是大问题但要注意它有时候是前一次启动的应用没有完全关闭导致的而不是真的有别的程序占用了。如果你在 IDEA 里频繁重启项目偶尔会遇到端口被占用的假象等几秒再启动或者直接 kill 掉 IDEA 的 Java 进程即可。7.3 依赖下载慢的终极解决方案依赖下载慢不管换什么镜像核心思路都是修改 Maven 的settings.xml。我给一个完整的镜像配置参考mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf nameAliyun Maven Mirror/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors这个配置的意思是所有对 Maven 中央仓库的下载请求全部转发到阿里云的公共镜像。如果你项目里还用到了一些 Google 或 Spring 的专属仓库比如 Spring 的里程碑版本可以再加一个 Spring 的 mirror但一般情况下上面这个配置已经够用。镜像配置完之后依赖还是下载慢那就要检查是不是本地仓库的问题了。第一次下载时本地仓库是空的需要从远程拉取大量 JAR 包这个过程确实急不得。建议第一次创建项目后让它慢慢下不要中途取消因为中断后容易出现依赖缺失的恶心问题。中途如果报错删掉本地仓库里.lastUpdated结尾的文件再重新刷新。7.4 常见报错速查表报错信息常见原因解决方法Cannot determine embedded database driver class for database type NONE数据源配置缺失或未引入数据库依赖检查application.yml是否配置了spring.datasourceInvalid bound statement (not found)MyBatis 的 Mapper XML 路径配错检查mybatis.mapper-locations是否匹配实际路径Field xxx in Xxx required a bean of type yyy that could not be found组件没有被 Spring 扫描到或依赖未注入检查包路径和注解确认是否存在循环依赖Error creating bean with name xxxBean 初始化失败通常是构造器或配置属性类型不匹配看后续异常堆栈重点看Caused byjava.lang.UnsupportedClassVersionErrorJDK 版本过低class 文件版本高于 JVM 版本升级 JDK 或降低项目编译版本Failed to bind properties under spring.datasource配置属性类型转换失败检查 YAML 缩进、属性名拼写这张表不是万能的但能覆盖新手阶段 80% 的启动失败原因。遇到报错时不要只看第一行重点看异常堆栈里Caused by后面的内容那才是根本原因。7.5 Banner 生成和图个乐这个属于进阶的趣味技巧。热词里有“springboot banner生成器”原因是 Spring Boot 启动时默认会打印一段 ASCII 艺术字。你可以用在线生成器做一段自己的 Banner替换resources目录下的banner.txt文件想用纯文本、彩色字体都可以。Banner 虽然是个小东西但在团队内部做个项目代号展示、或者给新项目加个启动仪式感效果挺好的。而且操作没有任何风险只需要在src/main/resources下新建banner.txt把生成的内容粘贴进去就行。不喜欢的话直接删掉文件就恢复默认了。8. 面试与实战延伸把知识体系补完整8.1 Spring Boot 面试题中常考的几个点热词里出现了“springboot面试题”我顺便把高频问题梳理一下这些问题在社招和校招中出现频率极高Spring Boot 与 Spring 的关系Spring Boot 本质是 Spring Framework 的封装核心依然是 IoC 和 AOPSpring Boot 做的是简化配置、自动化装配、独立运行。自动配置原理是什么回答时提起EnableAutoConfiguration和AutoConfiguration.imports条件注解ConditionalOnClass、ConditionalOnMissingBean等。为什么 Spring Boot 的 jar 能直接运行因为spring-boot-maven-plugin把项目打成了一个可执行的 fat jar内部包含所有依赖和嵌入式的 Tomcat 容器启动时通过JarLauncher执行。如何理解 starterstarter 是一组依赖的集合通过 Maven 引入后配合自动配置类就注入了对应功能模块的 Bean。SpringBootApplication注解的组成包括SpringBootConfiguration、EnableAutoConfiguration、ComponentScan。如果基础概念能答上来面试官往往还会追问“自动配置生效的条件如何控制”所以前面那一节讲的条件注解要重点掌握。8.2 项目创建之后下一步学什么项目创建成功、第一个接口跑通这只是热身。接下来往哪个方向走我给你一个清晰的路线第一把 Spring MVC 的请求处理链路搞清楚。写接口谁都会但要理解一次 HTTP 请求从进入到返回经过了哪些组件DispatcherServlet、HandlerMapping、HandlerAdapter、参数解析器、消息转换器。第二掌握数据访问方式。JdbcTemplate 是基础但实际项目里 MyBatis 和 Spring Data JPA 用得更多。无论选哪个都要理解事务的传播行为Transactional的失效场景。第三学会整合常用组件。Redis、RabbitMQ、Elasticsearch 这些中间件Spring Boot 都有对应的 starter选择项目实际需要的学不用贪多。第四深入了解部署与运维。项目打包成 jar部署到服务器上跑起来配好日志输出、健康检查。热词里出现的“heapdump 敏感信息泄露漏洞”就是一个安全问题线上项目要限制/actuator/heapdump这类端点的访问权限。这四个方向走完你基本从“会创建项目”进阶到了“能开发项目”。我在实际带项目时有个很深的体会很多人学 Spring Boot把太多精力花在用奇技淫巧上反而忽略了最基础的东西。其实把项目创建、配置、接口、日志、异常处理这五件事做扎实日常开发就已经够用了。框架本身变化很快但底层的 Spring IoC 思想、MVC 处理流程、面向约定编程的思维这些不容易变。你把这些地基打好以后不管框架怎么升级学起来都很快。最后再分享一个小技巧创建一个新项目时别急着写业务代码先把包结构、统一返回、全局异常、日志打印这些基础设施搭好。我见过很多人项目跑起来就往 Controller 里堆业务三个月后整个项目乱成一锅粥再想重构就难了。好的开始真的能省掉后面无数的返工。