我最初接触 Spring Boot 时最直观的感受就是懒人福音。这是 Spring 生态里少数能让我这种被 XML 配置折磨过的人第一次体会到开箱即用的框架。如果你之前用传统 Spring 搭过项目一定记得那些繁琐的配置数据源、事务管理器、视图解析器、包扫描路径…… 而 Spring Boot 的核心价值就是把这些重复劳动变成几个 Starter 依赖和一段配置说明。这篇文章聊的是 Spring Boot 的基础入门我会带你从零开始创建一个 Spring Boot 项目然后逐行拆解配置文件里的关键项。这不是官方案例的复读更多是我把这几年的实际踩坑经验揉进去让新手能少走弯路也让有基础的开发者能搞清楚配置背后的原理。1. Spring Boot 到底解决了什么问题1.1 从传统 Spring 的痛点说起在讲 Spring Boot 之前我建议你先理解一个问题它并不是一个功能上的新框架而是一种约定优于配置的实践产物。传统 Spring 搭一个 Web 项目我需要手动引入 Spring MVC、Tomcat、Jackson 等一堆依赖然后逐个写 XML 配置文件web.xml 里要注册 DispatcherServletapplicationContext.xml 里要配组件扫描、数据源、事务管理器还有一堆第三方库的配置文件要导入刚开始光搭环境就能花掉一整天。等你终于跑起来一个空壳项目又会发现另一个问题版本兼容。Spring 4.x 搭配什么版本的 MyBatis、什么版本的 Jackson全靠自己试错。网上搜到的教程经常版本对不上编译报错一堆这里缺 jar 包那里类名找不到非常消耗耐心。Spring Boot 的解决方案简单粗暴它内置了版本管理机制你只需要引入一个spring-boot-starter-web它就会自动带上配套版本的 Tomcat、Jackson、Spring MVC 等依赖而且这些版本已经经过官方测试不会出现明显的兼容问题。再用一个SpringBootApplication注解加上 main 方法就能把整个应用跑起来不再需要任何 XML 配置。1.2 自动配置的原理约定优于配置上面说到的不需要配置就能跑背后依赖的是自动配置Auto Configuration机制。简单理解Spring Boot 在启动时会扫描classpath下的依赖然后根据依赖推断该做什么配置。举个例子你的pom.xml里加了spring-boot-starter-web启动容器时 Spring Boot 的自动配置类ServletWebServerFactoryAutoConfiguration就会生效它会去检测当前项目是否已有嵌入式的 Tomcat/Jetty/Undertow帮你自动生成一个 Web 容器接着再通过DispatcherServletAutoConfiguration完成前端控制器的注册。这些配置类都放在spring-boot-autoconfigure这个 jar 包里对应的配置文件是spring.factories。实际使用过程中你不需要去记哪些自动配置类生效了想查看当前项目生效了哪些自动配置只需要在启动类上加一个启动参数--debug控制台就会输出一个CONDITIONS EVALUATION REPORT把你项目里所有启用和未启用的自动配置类都列出来这个后续调试特别有用。一句话理解这个过程框架做事前先看你的依赖里有什么然后按默认经验替你安排好。如果你想覆盖默认配置就用配置文件或自定义Bean来覆盖优先级是:用户自定义配置 自动配置。2. 环境准备与第一个 Spring Boot 工程2.1 基础工具链选择我不打算太机械地罗列所有工具只把影响后续使用舒适度的关键选择说清楚。JDK推荐 JDK 8 或 JDK 11。如果你刚开始学直接装 JDK 8 也行大部分企业项目还是用 8。想体验新特性可以用 11 或 17Spring Boot 2.x 完全兼容 JDK 83.x 要求 JDK 17。新手先装 8后面需要换再换成本不高。IDE我主要用 IntelliJ IDEA社区版也够用Spring Boot 支持在社区版创建项目只是没有 Spring 官方插件的一些可视化快捷键。嫌 IDEA 社区版创建不了的可以直接去官网的 Spring Initializr 生成项目压缩包再用 IDEA 以 Maven 项目方式导入。Maven我用 Maven 3.6 就够了版本不用太高3.8 系列稳定。安装完后记得配置本地仓库路径和国内镜像否则拉依赖能让你等到怀疑人生。提示Maven 的镜像源我建议用阿里云仓库。具体配置是在settings.xml的mirrors标签里添加一个镜像配置方法网上到处都是我就不复制粘贴了。这一步不做的话首次创建项目拉取依赖会非常慢。2.2 通过 IDEA 快速创建一个 Spring Boot 项目如果你用的是 IDEA 2019.3 之后的版本创建方式分两种一种是直接在 IDEA 里 New Project - Spring Initializr另一种是去 start.spring.io 上生成 zip 再导入。我习惯用第二种原因是官网上生成时能直接看到最终的目录结构和依赖版本能避免 IDEA 缓存的模板版本过老。不管用哪种有几个关键配置项要说明下Group一般填公司域名倒写比如com.example。Artifact项目的模块名比如demo最终 jar 包名会是demo-0.0.1-SNAPSHOT.jar。Dependencies刚开始只需选一个Spring Web即 starer-web。不要一上来全勾上很多依赖一旦引入但没用到反而会影响自动配置判断增加理解难度。后面需要什么再慢慢加。项目生成后默认的目录结构非常固定你务必记住每个目录的职责demo ├── pom.xml // Maven 构建描述文件 ├── src │ ├── main │ │ ├── java │ │ │ └── com.example.demo │ │ │ └── DemoApplication.java // 启动类 │ │ └── resources │ │ ├── application.properties // 配置文件也可以叫 yml │ │ ├── static/ // 静态资源目录js/css/html │ │ └── templates/ // 模板目录Thymeleaf 等 │ └── test │ └── java │ └── com.example.demo │ └── DemoApplicationTests.javaDemoApplication.java内容如下package com.example.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }这里SpringBootApplication其实是一个组合注解它包含三个核心注解SpringBootConfiguration标记这是一个 Spring Boot 配置类、EnableAutoConfiguration开启自动配置和ComponentScan自动扫描启动类所在的包及其子包。基于这个设计你后面的 Controller、Service、Mapper 都要放在com.example.demo包或其子包下否则扫描不到容器不会加载。运行main方法后看到类似下面的日志就说明项目启动成功Tomcat started on port(s): 8080 (http) with context path Started DemoApplication in 2.31 seconds (JVM running for 2.87)2.3 顺便提一句工具包常见依赖第一次创建完项目pom.xml里只有 starter-web、starter-test 和 spring-boot-maven-plugin。这时你可能连 JSON 拼接、字符串判断这种基础工具都还没引入。我建议直接引入 Hutool 或 Apache Commons Lang3能省很多事。不过这些是后话等用到再往pom.xml里加依赖即可不要一开始就贪多。3. 配置文件application.properties 与 application.yml3.1 properties 和 yml选哪个Spring Boot 支持两种配置文件格式我两种都用过最终稳定在 yml 上。它不是简单的格式偏好而是涉及层级表达和字符串转义的差异会影响你写配置的效率。application.properties的经典写法是扁平键值对server.port8080 spring.datasource.urljdbc:mysql://localhost:3306/test spring.datasource.usernameroot spring.datasource.password123456application.yml的写法是层级 缩进的 YAMLserver: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/test username: root password: 123456YAML 的缩进可以少敲不少重复前缀多层级配置一眼就能看出归属关系但它对缩进敏感稍一不留神空格数量不对就会解析失败。我给你的建议是如果只是临时测试properties 更快如果是长期维护的项目用 yml层级关系更清晰我后面讲自定义配置项时也会用 yml 演示。提示两者同时存在时application.properties优先级高于application.yml。为了避免配置为什么没生效这种诡异问题项目里最好只保留一种配置文件格式。3.2 核心配置项的逐个拆解下面以我常用的 yml 配置为例把它当成一个可以持续完善的基础模板带着你一条条分析。server: port: 8080 servlet: context-path: /demo spring: application: name: demo datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/test?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8 mybatis: mapper-locations: classpath:mappers/*.xml configuration: map-underscore-to-camel-case: true logging: level: com.example.demo: debugserver.port / server.servlet.context-path端口默认 8080如果你本地起了多个服务端口冲突是常态直接改端口即可。context-path是所有接口的统一前缀设置为/demo后访问地址就变成http://localhost:8080/demo/xxx。要不要设置看你是不是有网关或前端固定路径的调用要求前期调试可以不加。spring.application.name这个必须要习惯性设置好虽然本地开发看不出什么作用但一旦接入 Nacos、Consul 等注册中心服务名就是注册中心的实例 ID也就是别人调用你的唯一标识。不设置的话默认是 unknown排查微服务链路时你会很痛苦。spring.datasource数据源四件套。驱动类名要根据数据库版本确定MySQL 8.x 用com.mysql.cj.jdbc.DriverMySQL 5.x 用com.mysql.jdbc.Driver。URL 里的characterEncodingutf8是为了防中文乱码serverTimezoneAsia/Shanghai是为了设置数据库连接时区。之前我吃过这个亏数据库连接不指定时区Java 应用用本地时间插数据跟库里差 8 小时排查到后来才发现是时区问题。spring.jackson如果接口返回的 JSON 里包含时间字段建议在这里统一设置格式避免每个时间字段都手动加JsonFormat注解。date-format指定序列化格式time-zone指定时区防止给前端返回的时间少了 8 小时。注意这两个配置配合JsonFormat混用时注解上的优先级更高容易覆盖全局配置后续要注意。mybatis.mapper-locations如果你用了 MyBatis 且 XML 文件和实体类分开存放必须设置这个路径才能让 Mapper 接口找到对应的 XML 文件。map-underscore-to-camel-case这个配置建议直接打开因为你数据库字段大多是user_name这种下划线风格实体类大多是userName这种驼峰风格它能自动映射省去大量冗余的 ResultMap。logging.level设置日志级别。com.example.demo改成自己的包名开发时可以用 debug 级别看 SQL 日志MyBatis 的 SQL 打印就靠这个上线时改为 info避免日志量过大。3.3 自定义配置项与 ConfigurationProperties 绑定配置文件不只给框架用你自己的业务参数也可以放在里面。最典型的是上传文件路径、第三方接口地址、超时时间、开关项等。有两种方式读取自定义配置第一种用Value注解适合少量配置Component public class FileStorage { Value(${file.upload-path}) private String uploadPath; }第二种用ConfigurationProperties前缀批量绑定适合多字段配置file: upload-path: /data/upload max-size: 10MB allowed-types: - jpg - png - pdf对应的配置类Component ConfigurationProperties(prefix file) public class FileStorageProperties { private String uploadPath; private String maxSize; private ListString allowedTypes new ArrayList(); // getter/setter 必须提供否则绑定不进去 }ConfigurationProperties是编译期绑定比Value少了$占位符和字符串拼接的麻烦也方便复用。这里有个细节属性类必须提供 getter 和 setter其实这是 JavaBean 的标准要求但新手写的时候经常只写了字段绑定成功后拿到 null查半天找不到原因。4. 多环境配置dev、test、prod 的分而治之4.1 profile 文件的作用几乎每个项目都会面临环境问题本地开发、测试环境、生产环境的配置都不一样。数据库地址、日志级别、缓存开关这些内容放一套配置文件里来回改既不安全也容易漏。Spring Boot 天然支持多 profile 配置最简单的方式是文件名后缀区分application.yml application-dev.yml application-test.yml application-prod.yml主配置文件application.yml里指定当前激活的环境spring: profiles: active: devapplication-dev.yml放本地数据库、本地 Redis、debug 级别日志application-test.yml放测试服务器配置application-prod.yml里就绝对不能出现 test 库的密码要用生产库及生产环境的参数。用 jar 包启动时也可以动态指定环境不用改代码java -jar demo.jar --spring.profiles.activeprod这条命令是外部化配置覆盖优先级高于主配置文件里的spring.profiles.active。我在公司经常线上需要切环境就用这种方式非常迅速。4.2 多环境下的配置优先级Spring Boot 配置的来源不只是 yml 文件还包括启动参数、环境变量、当前目录的 config 目录等。它们的优先级顺序从高到低大致是命令行参数Java System 属性System.getProperties()操作系统环境变量application-{profile}.ymlapplication.yml其他位置的配置文件这套优先级规则你在排查为什么配置改了没生效时会非常有用。我有一次在application.yml里把端口改成了 8081但启动日志还是显示 8080排查到最后发现是 IDEA 的 Run Configuration 里加了虚拟机参数-Dserver.port8080命令行参数优先级高于配置文件所以它赢了。新手阶段你只要记住一个结论命令行参数的优先级最高覆盖力最强。以后遇到类似问题优先检查是不是有外部参数或环境变量覆盖了你的配置。4.3 配置文件里隐藏的坑中文编码问题application.yml里写了中文注释或中文配置值启动时报编码错误。解决办法是 IDEA 右下角把文件编码改为 UTF-8同时确认Settings - Editor - File Encodings里的Properties Files默认编码也是 UTF-8。yml 的非法字符密码里如果包含*、、%这类特殊字符直接写在 yml 里可能会解析失败。处理方法是给值加上双引号比如password: abc123。更省心的做法是密码等敏感信息用环境变量注入或放在配置中心不要硬编码在 yml 中。配置覆盖顺序混乱如果你在多个地方配置了同一个属性以优先级高的为准不要试图通过调整文件位置来改变优先级。记住命令行 环境变量 application-{profile}.ymlapplication.yml这个顺序就够了。4.4 第三方组件的配置入口Spring Boot 的配置项虽然多但不用死记硬背。几乎所有体系化的配置前缀都有规律可循官方文档里你能查到完整列表。我这里说几个常用前缀你可以去扩展查询spring.datasource.*数据源相关spring.redis.*Redis 连接配置spring.kafka.*Kafka 相关配置spring.mail.*邮件服务配置mybatis.*MyBatis 相关配置logging.*日志相关配置需要什么组件直接搜spring boot {组件名} properties就能快速定位配置项。这个搜索习惯建议早点养成因为你不可能把每个组件的配置项都背下来。5. 几个容易踩的学习误区与实测心得5.1 启动类位置绝不能随便放前面提过SpringBootApplication的包扫描机制。我知道很多人一开始贪方便把 Controller 放在启动类同级的包外结果一启动就 404所有接口都访问不到。要保证扫描生效最稳妥的做法是启动类放在根包下其他所有业务代码都放在它的子包里。不要为了图目录清爽把某些类翻到外层否则只能手动加scanBasePackages等于给自己挖坑。5.2 创建项目后的第一次运行很慢新项目首次 runMaven 要下载大量插件和依赖很多教程里默认你已经配好了本地仓库。我的建议是第一次创建完项目后先执行一遍mvn clean compile让依赖全部下载完成再运行 main 方法。不然 IDEA 里一边提示下载依赖一边启动容易超时或者异常新手会以为项目有问题其实是依赖还没拉完。5.3 自动配置失效了先怀疑这几点我总结了自动配置注入失败最常见的三种情况某个依赖没引入。比如你写了数据源配置但pom.xml里压根没加spring-boot-starter-jdbc或 MyBatis 的 starterSpring Boot 自然不会去加载DataSourceAutoConfiguration。自定义Bean和自动配置冲突。你手动定义了DataSource框架检测到已有DataSource类型的 Bean它的自动配置就会退出。被exclude掉了。有时候你为了排除某个自动配置用了SpringBootApplication(exclude xxxAutoConfiguration.class)如果排除错了后续相关配置就不生效。排查时可以看看CONDITIONS EVALUATION REPORT里对应的自动配置显示的是matched还是did not match。5.4 静态资源和模板目录的作用我把resources/static和resources/templates也提一下。Spring Boot 默认把static目录当作静态资源根目录放一个hello.html进去启动后可以直接http://localhost:8080/hello.html访问到。templates目录和后端模板引擎Thymeleaf配合使用通过 Controller 返回视图名时框架会自动去这个目录找对应的模板文件。如果你是纯前后端分离开发后端只写接口这两个目录基本用不上但要知道它们的存在因为很多老项目还是用这套机制做页面渲染的。6. 把项目跑起来之后建议你再做这几件事项目能启动、接口能访问只是第一步我建议你按下面这个清单一步步加深理解在pom.xml里找到spring-boot-starter-web展开它的依赖树看看它到底自动引入了哪些 jar 包这是理解自动配置的起点。修改一下server.port然后观察日志里端口的变化感受一下配置文件直接触发底层行为的过程。在 Controller 里写一个 GET 和 POST 接口分别用浏览器和 Postman 请求一遍熟悉请求参数绑定和 JSON 返回。把启动类加上--debug参数跑一遍阅读CONDITIONS EVALUATION REPORT看看你的项目里哪些自动配置类是匹配的哪些没匹配并尝试推断原因。尝试拆出一个自定义配置类用ConfigurationProperties绑定几个业务参数然后在接口里读取展示出来。这几件事做完你对 Spring Boot 的配置运转机制就建立了一个初步的完整图景。后续再深入时不管是 Web 开发还是微服务都能建立在同一个正确的底层认知上。我在最初学习这类框架时最大的体会是不要被自动两个字迷惑自动背后是一套我们可以控制的规则。当你遇到问题第一件事不是搜索为什么报错而是先回顾配置的优先级、依赖的引入情况、Bean 的扫描路径。搞明白这三件事大部分问题都能自己定位出方向。