我刚学Spring Boot那会儿最难的不是语法而是我明明照着教程敲了代码怎么启动就报错启动成功了访问页面又404。网上教程铺天盖地但要么默认你懂Maven要么默认你懂Tomcat对纯小白极其不友好。这篇内容就是写给刚学完Java基础、没碰过Web开发、想快速看到第一个能跑起来的网页程序的读者的。我会从环境准备开始带你创建一个真实的Spring Boot项目拆解每个文件的作用写第一个接口最后把项目打成jar包在命令行里运行。全程用大白话解释不涉及底层源码争取让你在一个下午之内亲手搭出一个可运行的Web应用。1. 先搞清楚Spring Boot到底解决了什么问题——别急着写代码很多新手上来就搜Spring Boot教程结果搜到一堆SSM整合XML配置的历史帖子直接被劝退。我想先花点篇幅讲清楚Spring Boot的存在意义搞清楚这个后面写代码你才知道自己在干嘛。1.1 从没有Boot的Spring说起配置地狱是什么体验Spring框架本身很强大但它早期是出了名的配置繁琐。想象一下你买了一套毛坯房水电、墙面、地板全要自己弄你得在web.xml里配置DispatcherServlet在spring-mvc.xml里配置视图解析器、静态资源映射、注解驱动在applicationContext.xml里配数据源、事务管理器、扫描包路径……一个最小的Web项目光配置文件就要写上百行而且版本之间还不兼容。我刚入门时最崩溃的就是配置文件明明是照着抄的为什么别人的能跑我的报错。Spring Boot的出现相当于从毛坯房变成了精装交付房子已经帮你装好水电、铺好地板你只需要拎包入住往里摆家具就行。Boot把那些惯常的配置做成了自动配置Auto Configuration你只要引入对应的起步依赖Starter框架自己会根据classpath里的jar包推断你应该需要什么配置并自动装配好。比如你引入了spring-boot-starter-webBoot就自动配置好内嵌的Tomcat、DispatcherServlet、默认错误处理页面等一整套Web运行环境。1.2 Spring、Spring Boot、Spring Cloud微服务这三个到底啥关系这是新手最容易混淆的问题。我用一个简单类比Spring是整个家族的名字它提供最基础的容器和工具比如依赖注入、AOP相当于零件和地基。Spring Boot是Spring家族里的一个快速搭积木工具它把Spring那些零件预先组装成了手感顺滑的积木包让你不用关心零件怎么拧在一起。Spring Cloud则是管理多台机器上微服务之间通信、注册、配置更新的协作平台——在一台机器上写应用用Boot就够了要拆成多个服务协同工作才需要Cloud。现阶段你只需要明白**Spring Boot不是新的编程语言它只是让Spring用起来更简单的一套启动框架。**你写的代码还是Java底层还是Spring那一套只不过省掉了大量手工配置。至于微服务那是后话等你能独立用Boot写出完整应用之后再去了解也不迟。1.3 小白最该记住的一句话Boot 自动配置 起步依赖 内嵌服务器整个Spring Boot的核心浓缩成一句话就够它帮你在引入依赖时自动把能配的全配好还自带一个能跑Web应用的服务器你只需要专注写自己的业务代码。起步依赖解决的是依赖版本打架问题——传统开发里你要自己找Spring各个模块的兼容版本选了A的4.3又发现跟B的4.5不兼容直接崩。Boot通过spring-boot-starter-parent这个父工程把所有官方认可的组合版本都锁定了你只要写starter的名字不用写版本号也不容易冲突。内嵌服务器是另一个巨大的体验提升。以前我们写完 Spring 应用得手动下载Tomcat把项目打成war包丢进webapps目录再启动外部服务器才能访问。Boot的spring-boot-starter-web里自带一个内嵌Tomcat你在main方法里点一下运行它自己就把服务器拉起来业务代码直接就能通过localhost访问。2. 开发环境准备与第一个项目的诞生环境这块我不讲太多理论直接给清单。按照这个配置来大概率不会在起步阶段卡太久。2.1 工具清单IDEA社区版 JDK 17就够了JDK建议安装JDK 17。Spring Boot 3.x全系列要求JDK 17起步Boot 2.x用JDK 8/11也能跑但3.x是当前主流新项目方向官网新教程也基本都是3.x。如果你电脑上已经有JDK 8建议还是装一个17两个版本共存没问题IDEA里可以分别指定。开发工具IntelliJ IDEA社区版完全够用不用非得专业版我们这篇内容用不到Spring Initializr专业版专属功能社区版照样可以创建Spring Boot项目。MavenIDEA社区版自带Maven不需要单独安装。只是想让你知道底层项目构建是靠Maven去拉取依赖的。浏览器Chrome/Edge都行用来访问你启动后的页面。装好JDK之后在命令行输入java -version能正确输出版本号就算成功。如果你已经装了多个JDKIDEA里在项目结构Project Structure里指定Project SDK为17即可。2.2 三种创建项目的方式最推荐哪种创建Spring Boot项目常见有三种方式IDEA内置的Spring Initializr在IDEA新建项目时选择Spring Initializr勾选依赖就能生成项目社区版也支持。官网start.spring.io浏览器打开 start.spring.io 在线填好信息下载一个zip包再解压导入IDE。Spring CLI命令行用spring命令在终端敲命令生成对小白来说不推荐多一步安装CLI的环节。我最推荐前两种两者本质一样都是通过Spring Initializr生成项目骨架区别只是IDEA里操作还是浏览器里操作。我自己经常用官网生成原因是它的可视化界面更直观能直接看到你勾选了哪些依赖还能预览项目结构。在IDEA里操作则省去了解压导入的步骤页面直接打开。2.3 start.spring.io上的关键选项到底怎么选在start.spring.io页面上一堆下拉框新手容易懵。逐个说Project选Maven。Gradle虽然也很主流但Maven在中文社区教程最多、资料最好找你这个阶段先用Maven。LanguageJava。Spring Boot选最新的稳定版比如3.2.x或3.3.x尽量别选带SNAPSHOT后缀的版本那是快照版不稳定。Project MetadataGroup填com.exampleArtifact填demo。这两项决定了你代码里的包名具体叫什么不重要先跑起来再说。Dependencies这是一个核心操作。先只勾选一个Spring Web它是最基础的Web起步依赖包含内嵌Tomcat、SpringMVC等全套Web开发能力。其余的TDD、DevTools等先不勾够用就行。等以后用到数据库再单独加。生成完项目后用IDEA打开等右下角Maven依赖下载完第一次会比较久视网络情况几分钟到二十分钟不等。下载完成后你会看到项目目录里有一个pom.xml文件和一个带SpringBootApplication注解的class文件。3. 项目结构逐层拆解别再被那一堆文件夹吓到项目生成之后很多小白面对一堆文件夹会感到恐惧这么多目录我到底该把代码放哪里这里给你逐层讲明白看完之后你会觉得其实很简单。3.1 src/main/java下面到底该放什么在这个目录下你会看到类似com.example.demo这样的包路径结构如果你前文按我的建议填了Group和Artifact的话里面有一个DemoApplication.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); } }这个类极其重要但你现在没必要深入理解它的原理。你只需要知道它代表Spring Boot的启动按钮。SpringBootApplication是组合注解包含了自动配置、组件扫描等能力。你把类写在它所在的包或者子包里就会被自动扫描写在别的地方则扫描不到这是一个经典踩坑点后面讲。当你以后往项目里添加Controller、Service等类时统统放在com.example.demo下新建子包即可比如com.example.demo.controller、com.example.demo.service。3.2 resources目录里的秘密static、templates、application.propertiessrc/main/resources这是一个非Java代码的存放区同样很重要static放静态资源比如CSS、JavaScript、图片。Spring Boot默认把这个目录映射为网站的根路径你放一个a.css浏览器就能通过/a.css访问到。templates放模板引擎的页面文件Thymeleaf、FreeMarker等。如果写前后端分离这个目录基本用不上统一用static或交给前端打包工具。application.properties也可能是application.yml这是Spring Boot的配置文件所有你想调整的东西端口号、数据库连接信息、日志级别等都在这里改。我给新手一个直观理解src/main/java里写的是程序逻辑和规则resources里放的是程序需要的素材和设置。学习初期你用不到static和templates也没关系只要你的Controller返回字符串或JSON根本不需要这两个目录存在。3.3 那个带SpringBootApplication的类真的不只是一个入口而已很多教程都会说main方法里点运行就能启动但是很少有人跟你说清楚SpringBootApplication内部到底干了啥。我简单拆一下组合注解里的三个核心注解SpringBootConfiguration标记这个类是个配置类。EnableAutoConfiguration启用Spring Boot的自动配置。它就像一个大管家看你引入哪些依赖自动帮你把相关的Bean配置好。ComponentScan扫描当前类所在包及子包下的组件如Controller、Service、Repository等把它注册成Spring容器里的Bean。这就是为什么你的类必须放在主类所在包或子包下。如果你把HelloController放在com.example.demo.controller这个子包下没问题但你要是一顺手放到了com.other.controllerSpring根本扫描不到它访问接口必然404。我后来排查过不少类似问题基本都是包路径放错了。4. 写第一个接口从跑通到理解请求处理的完整链路项目结构看懂了接下来就可以动手写第一个能跑通的接口了。这一步做完你就拥有第一个自建Web应用。4.1 RestController GetMapping 的组合拳在com.example.demo.controller包下新建一个Java类命名为HelloController放入以下代码package com.example.demo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; RestController public class HelloController { GetMapping(/hello) public String sayHello() { return 你好Spring Boot; } }这里有两个关键注解RestController告诉Spring这是一个控制器类并且类里每个方法的返回值会直接写入HTTP响应体而不是走视图渲染。你浏览器访问对应路径时看到的就是方法返回的那段纯文本或JSON。GetMapping(/hello)将HTTP的GET请求映射到/hello路径上。浏览器地址栏输入http://localhost:8080/hello时就会调用sayHello()方法并把返回值显示在页面上。你可以试一下在RestController之外再写一个Controller注解的对比或者改一下返回一个Java对象看看返回结果变成JSON——总之掌握这两个注解你的第一个接口就跑通了。4.2 启动流程与启动日志怎么读现在回到DemoApplication类右键点击运行main方法。你会看到控制台疯狂输出日志第一次跑起来这些日志长得吓人但新手只需要看两个关键点日志中会有类似Tomcat started on port 8080 (http)的行这说明内嵌服务器已启动成功。日志末尾会看到Started DemoApplication in 2.3 seconds之类的字样说明完整启动成功。然后在浏览器地址栏输入http://localhost:8080/hello看到页面显示你好Spring Boot的一瞬间恭喜你你刚刚亲手完成了一个Web应用的从零到一。日志里还有一个细节值得注意启动时的默认端口是8080。如果你的8080端口被别的程序占了启动会报Port 8080 was already in use。这个问题处理起来很简单修改配置文件里server.port即可后面会讲到。4.3 让接口支持传参RequestParam与PathVariable的差别跑通第一个接口后下一步很自然就是让接口接受参数。怎么让接口更灵活两个最常用的方式方式一查询参数路径长这样/hello?name张三GetMapping(/hello) public String sayHello(RequestParam(value name, defaultValue 世界) String name) { return 你好 name ; }RequestParam把URL里的?name张三提取出来赋给name变量。defaultValue是可选的加了它之后你没传参数也能正常访问。方式二路径参数路径长这样/hello/张三GetMapping(/hello/{name}) public String sayHello(PathVariable String name) { return 你好 name ; }PathVariable把路径里{}括住的那一段提取为参数。访问/hello/张三时name就是张三。两者的区别可以理解为RequestParam是在URL问号后面拿数据PathVariable是从URL路径里拿数据。日常开发中两者都很常用看着接口文档要求来选择即可。至于POST、PUT等其它请求方式以及RequestBody接收JSON等你做实际项目时再加不迟先掌握GET请求这条链路最重要。5. 配置管理application.properties还是application.yml怎么选跑起来之后下一步你要学会配置。Spring Boot最方便的是把启动相关的设置统一放在配置文件里改起来不用重新编码只需要重启应用就好。但是新手在配置文件这里很容易被两个问题卡住选.properties还是.yml以及YAML那套缩进规则到底怎么算对。5.1 两种格式的对比与选择application.properties与application.yml的根本区别是书写格式不同功能基本等价。举个例子把端口改成8081、上下文路径改成/apiproperties格式server.port8081 server.servlet.context-path/apiyml格式server: port: 8081 servlet: context-path: /api如果你是一个完全没接触过配置文件的新手我建议直接用application.properties因为它是键值对一对一是最容易理解的key是配置项名称右边是值。YAML虽然更简洁、层次感更强但缩进必须一致用Tab键或空格混用会导致解析直接失败报错提示还不那么直观小白容易在这里消耗大量耐心。等你熟了一点再反过来用YAML也不迟两者都支持但项目里同时存在两个同名配置时会以application.properties优先级更高实际项目一般只保留一个格式避免混乱。5.2 最常用的几个配置项端口、上下文路径、日志与编码我把入门阶段最常用的配置项整理成表格方便你直接套用配置项作用典型示例server.port修改服务器端口server.port8081server.servlet.context-path给所有接口统一加前缀server.servlet.context-path/apispring.application.name设置应用名微服务/日志里会用到spring.application.namedemo-appspring.jackson.date-format格式化JSON里的日期spring.jackson.date-formatyyyy-MM-dd HH:mm:ssserver.servlet.encoding.charset设置HTTP请求响应编码server.servlet.encoding.charsetUTF-8你修改完配置文件后需要重启应用才能生效。新手最容易犯的错误是改完端口后发现访问还是8080——那是因为你改的端口只对修改之后启动的那次进程生效得先停掉正在运行的程序再启动不是刷新就能解决的。5.3 自定义配置项Value与ConfigurationProperties初体验有时候你只是想在配置里放一些自己的业务参数比如某个文件的上传路径、某个业务开关。Spring Boot提供了多种读自定义配置的方式最简单的就是用Value注解。比如在application.properties里写app.custom-namefinal-demo app.custom-version1.0.0在代码里读取时Component public class AppInfoReader { Value(${app.custom-name}) private String customName; Value(${app.custom-version}) private String customVersion; }等以后你接触更多项目会遇到ConfigurationProperties这种批量读取配置类的方式它能将同一前缀的配置映射成一个Java对象比Value一条条读取更有组织性。但入门阶段直接用Value就够了关键是理解配置文件 - 注入到代码变量这条链路。5.4 profile切换开发环境和生产环境配置怎么切一个应用往往要应对多套环境本地开发环境、测试环境、线上生产环境——它们的数据库地址、日志级别、调试开关都不一样。Spring Boot提供了profile机制专门来管理多套配置。实现方式很简单配置文件命名时加一个后缀比如默认用application.properties不指定环境时的公共配置、application-dev.properties开发环境、application-prod.properties生产环境。然后在你启动的时候告诉Spring Boot用哪个环境两个方式在application.properties里写spring.profiles.activedev命令行里加参数java -jar demo-0.0.1-SNAPSHOT.jar --spring.profiles.activeprod等你以后真的部署上线时会发现这个机制很救命本地调试时用一个开发库发布时切到生产库重启一条命令搞定不会出现写错数据库地址把数据搞坏这种低级事故。入门要先知道这个存在不用花太多精力在这上面等有需要再深入研究即可。6. 小白最容易踩的坑版本配对、依赖冲突和打包部署在这篇文章的最后部分我来总结几个我见过以及自己踩过的典型坑帮你提前绕开。6.1 JDK与Spring Boot版本配对为什么你明明照做了还是报错Spring Boot 3.x要求JDK 17起步而Spring Boot 2.x支持JDK 8/11。如果你电脑上默认环境是JDK 8创建一个Boot 3.x项目一启动就会看到UnsupportedClassVersionError之类的报错。同理你在pom.xml里写了一个兼容老版本的Boot比如2.7.x却用JDK 17编译部分场景也有兼容问题。解决思路是对照检查先看你的pom.xml里spring-boot-starter-parent的版本号再确认Project Structure中的Project SDK和模块SDK是同一个版本。比较稳妥的组合有三组——JDK 8 Boot 2.7.x、JDK 11 Boot 2.7.x、JDK 17 Boot 3.x。新手统一推荐最后一组因为现在是3.x的时代学新不学旧。这里有一个进阶的注意点我最近还在关注一个信息Spring Boot 3.5及后续版本在Java 21上有更好的虚拟线程支持通过spring.threads.virtual.enabledtrue即可开启使大量并发请求处理有更佳的吞吐表现。如果后续你有条件切换JDK 21可以留意一下但对于刚入门阶段JDK 17够了。6.2 依赖冲突的直观感受与排查思路Boot虽然帮你锁定了官方组合版本但只要你引入第三方依赖比如为了连数据库引入MyBatis或者为了缓存引入Caffeine还是可能遇到依赖打架的问题。典型场景是两个jar包里包含了同一个class文件运行时就会报NoSuchMethodError或ClassNotFound这些看起来莫名其妙的错。我的排查思路一般这样走先完整看一遍控制台报错找第一行异常类型和关键信息。在IDEA右侧Maven面板执行mvn dependency:tree它能打印出所有依赖的版本树搜一下冲突的相关包名看是谁引入了不同版本。在pom.xml里用exclusion排除掉出问题的传递性依赖或者直接在你自己声明的依赖上指定明确版本覆盖旧的。这项工作现在对小白来说做起来比较费劲不用刻意学。关键是要意识到报错不一定是你代码的问题先查依赖再看代码不慌就好。6.3 打包成jar扔服务器上跑本地能跑只是第一步。更接近真实开发的是把应用打成可执行的jar包在命令行里用java -jar启动而不是依赖IDEA运行。Spring Boot的maven插件已经帮你封装好了流程在IDEA右侧Maven面板里找到demo - Lifecycle - clean - package依次双击执行。也可以在项目根目录命令行下执行mvn clean package执行完成后在target目录下能看到一个demo-0.0.1-SNAPSHOT.jar文件。然后直接命令行运行java -jar target/demo-0.0.1-SNAPSHOT.jar启动成功后用浏览器访问同一个地址效果和IDEA里一模一样。这就是生产环境部署的最小模型——以后服务器上只要装了JDK把你的jar传上去一个java -jar就完成了部署极其轻量。这也是Boot相比传统Servlet容器部署的最大优势之一。打包时我遇到过一个小坑如果在pom.xml里加了maven-surefire-plugin的配置或项目里有测试类执行package时可能会因为跑测试不通过而出包失败。临时跳过测试可以加-DskipTests参数完整命令mvn clean package -DskipTests新手第一次打jar包时建议先用这个命令跳过测试等懂了测试逻辑再取消。写在最后先跑起来再去抠原理回看我自己的学习过程最值得分享的经验是别一开始就想搞懂所有底层原理让应用跑起来是第一优先级。只要你能创建项目、启动、写一个Controller、访问通一个页面Spring Boot这座大山的山脚就踩实了。之后的数据库操作、模板引擎、Spring Security都是在这个基础上不断加柱子的过程。很多你现在觉得这啥东西的注解和配置等用过一个完整项目回过头再看自然会融会贯通。如果非要给一条建议我会建议你接下来不要急着学Spring Cloud而是先做一个带列表、新增、删除功能的小案例比如一个简单的地址簿把Controller、Service、数据处理这几层串起来比看多少教程都管用。到时候你迎面撞上的问题正是成长最快的地方。