Spring Boot从零搭建指南：从环境配置到第一个接口运行-北京尧图网络

我从2015年前后开始接触Java后端开发那时候写一个Web项目光配置文件就能把人整懵。后来Spring Boot出现整个圈子像是换了一种活法不用再面对动辄几百行的XML不用再纠结Tomcat怎么部署一个main方法点下去服务就跑起来了。这篇是从零开始的Spring Boot学习系列第一篇我把搭建配置初步运行整个过程完整捋一遍包含JDK选型、Maven镜像配置、IDEA初始化项目、配置文件解读、第一个接口的编写以及新手最容易踩的坑。适合刚学完Java基础、准备切入Web开发的同学也适合之前一直用传统SSM框架、想快速上手Spring Boot的老开发。看完之后你能在自己的电脑上把一个Spring Boot项目从无到有跑起来并且清楚每一步到底在做什么、为什么要这么做。1. 为什么是Spring Boot先搞清楚它解决了什么问题1.1 传统Java Web开发的繁琐之处很多同学学完Java SE之后第一次接触Web开发时会被一套东西劝退Servlet、JSP、过滤器、拦截器、web.xml、Spring容器、SpringMVC配置、MyBatis配置、数据源配置……这就是早期Java Web开发的常态。以前用传统Spring搭一个最简单的Web项目要写很多配置文件。我印象最深的是第一次给一个SSM项目加一个拦截器需要在spring-mvc.xml里注册拦截器、写拦截器类、再配拦截规则前前后后改了三个文件。后来接手一个老项目光一个spring-config.xml就有几百行里面是各种bean的声明。配置和代码几乎一样多而这些配置本身不是业务需求只是为了让框架跑起来不得不做的事情。Spring Boot的核心价值就是把这一堆不得不做的基础装修变成了自动化的拎包入住。它内置了大量约定好的配置只要遵循它的目录结构和依赖规则大部分常用功能都不用自己写配置就能直接使用。比如你想做Web接口引入一个spring-boot-starter-web依赖框架就会自动配置好内嵌的Tomcat、SpringMVC、JSON序列化等组件你就直接写Controller就够了。1.2 约定优于配置是什么意思Spring Boot的设计哲学核心是约定优于配置Convention over Configuration。通俗地讲就是框架先帮你把标准答案设定好你只需要在偏离标准的场景下才去额外配置。拿出租房来类比传统Spring就像一个毛坯房水、电、墙、门、窗都要你自己找人来做每一项都要单独对接。Spring Boot则是一个精装修公寓基础家具都配齐了你直接搬进来住就行如果觉得某个家具不喜欢再单独替换。大多数情况下你不用管它怎么搭配先用起来再说。这种设计最大的好处是把团队里开发者的心智负担降低了一大截。大家只需要遵循同样的项目结构约定就能快速理解任何基于Spring Boot的工程。这对新人的友好程度是很明显的。1.3 什么人适合学Spring Boot我不建议完全零基础的人一上来就直接学Spring Boot。你得先知道Java的基础语法、面向对象、集合、IO这些概念否则遇到lambda表达式、泛型、注解这些内容时会比较吃力。比较好的路径是先学完Java SE基础再简单了解一下HTTP、JSON、数据库这些Web开发常识然后就可以进入Spring Boot的世界。Spring Boot适合以下学习场景想进入Java后端开发岗位的人、学校课程需要完成Web项目的在校生、想要快速搭建一个原型系统的个人开发者、以及以前用过传统Spring框架想提升开发效率的人。它的生态非常庞大从Web接口到消息队列、定时任务、微服务治理都有对应的组件学完基础之后还有很多方向可以继续深入。2. 搭建前准备工作JDK、Maven、IDE的选型与安装2.1 JDK版本怎么选别盲目追新动手搭建Spring Boot项目之前第一件事是搞清楚JDK版本。等你把所有东西安装好、项目也能启动之后我发现很多老机器上的同学最容易在这一步翻车JDK版本和Spring Boot版本不匹配项目根本起不来。Spring Boot 2.x系列最低要求是JDK 8兼容到JDK 11、甚至JDK 17也能跑。Spring Boot 3.x系列最低要求是JDK 17。我当前的建议是如果你完全是从零开始且没有历史项目的包袱直接装JDK 17或JDK 21就行。JDK 8虽然经典但毕竟是十几年前的技术了很多新特性用不上而且Spring Boot 3.x系列生态已经完全转向JDK 17。安装JDK的时候不同操作系统各有各的方式。Windows上要自己去官网下载对应安装包安装之后配置JAVA_HOME环境变量。macOS上可以用homebrew安装。设置好环境变量之后打开命令行执行java -version能看到类似openjdk version 17.0.x这样的输出就说明安装成功了。还有一个容易被忽略的点安装JDK之后IDE里也要检查自己的编译级别。比如你系统里装了JDK 21但IDEA的项目结构里Project SDK还指向JDK 1.8那项目编译出来就可能因为语法或API问题报错。2.2 Maven的安装与镜像配置这一步能省很多时间Maven是Spring Boot项目里最常用的构建工具。它做了什么简单说它负责帮你下载第三方依赖jar包、管理依赖版本、打包编译项目。你可以把Maven理解成一个快递站你告诉它需要什么依赖它就从中央仓库把jar包拉取下来放到本地仓库里以后再用就从这个本地仓库里取。IDEA自带一个Maven如果不装独立的Maven也可以用内置版本。但我一直建议自己安装一个独立的Maven原因有三点一是版本可控可以指定Maven 3.8等版本二是可以在settings.xml里明确配置本地仓库路径和镜像地址三是从命令行操作时能直接用mvn命令不用在IDE里去手动触发。Maven下载地址可以从官网获取解压到某个本地目录然后配置环境变量。配置完成后命令行输入mvn -v会输出Maven版本号同时能看到它使用的Java版本这个信息对排查问题很有用。重点来了国内网络环境下直接访问Maven中央仓库下载依赖有时会比较慢或者干脆超时。这时候就需要配置镜像。打开Maven安装目录下的conf/settings.xml在mirrors节点中添加一个阿里云镜像配置mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror配置完成后Maven拉取依赖就会优先走这个镜像地址速度明显变快。注意mirrorOf的值为central表示对中央仓库的访问都会被镜像接管。2.3 IDE选型与必备插件目前绝大多数Java开发者的选择是IDEA社区版Community Edition是免费的对学习Spring Boot来说完全够用。如果你后面要做Spring Cloud微服务开发可能旗舰版会更顺手但学习阶段不需要那个。IDEA里我建议至少要装两个插件Lombok插件和Spring Assistant现在新版IDEA部分功能已经内置。Lombok用来消除Java Bean里的getter/setter模板代码Spring Assistant用来提供Spring配置文件的智能提示。在创建第一个项目之前先花几分钟把IDEA的Maven配置指到你自己安装的Maven进入SettingsMac上是PreferencesBuild Tools Maven把Maven home path改成自己的Maven目录User settings file改成settings.xml的路径。这样后续项目的依赖下载、编译用的都是同一个Maven实例避免IDEA自带Maven和配置好的settings.xml错位导致加载不到镜像配置。3. 项目搭建实操从零生成一个Spring Boot骨架3.1 用Spring Initializr生成项目快且不容易出错搭建Spring Boot项目最省事的方式就是通过Spring Initializr这个网站来生成骨架。你只需要在网页上填好项目元数据、选好依赖网站会打包生成一个可导入的工程压缩包。流程是打开start.spring.io左侧的Project选择MavenLanguage选择JavaSpring Boot版本选择当前稳定的3.x版本页面默认会给出推荐版本然后在Project Metadata区域填上Group和Artifact。Group通常填类似com.example这样的公司域名倒写形式Artifact就是项目名比如demo。右侧依赖区域先点Dependencies输入框搜索Web然后选中Spring Web。这一步会引入spring-boot-starter-web它是后面写接口的基础。生成之后点击Generate就会下载一个zip压缩包解压之后用IDEA直接打开这个文件夹。用IDEA打开项目时注意选择打开方式要么选择pom.xml文件打开要么直接打开整个目录。首次打开后IDEA会开始下载项目所需的依赖右下角有进度条。这个下载过程第一次会比较慢如果你前面配置好了阿里云镜像这里会顺利很多。3.2 生成的目录结构长什么样项目下载完成后你会看到这样一个工程结构demo/ ├── src/main/java/com/example/demo/ │ ├── DemoApplication.java │ └── ... ├── src/main/resources/ │ ├── application.properties │ └── ... ├── src/test/java/com/example/demo/ │ └── DemoApplicationTests.java ├── pom.xml └── ...如果你用start.spring.io生成时勾选了Web依赖还会多一个spring-boot-starter-test测试依赖和对应的测试类。DemoApplication.java是程序的主类它包含了main方法运行这个类就能把整个Spring Boot应用启动起来。application.properties是默认的配置文件项目端口、数据库地址、日志级别等配置都写在这里。pom.xml是Maven的配置文件定义了项目的依赖和构建插件。3.3 手写pom.xml到底在写什么用Spring Initializr自动生成的项目pom.xml已经帮你写好了。但很多同学想知道这些内容是什么含义我拆开讲一下。一个最简的Spring Boot项目pom.xml核心部分如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /buildspring-boot-starter-parent是Spring Boot的父工程它统一管理了一大堆第三方依赖的版本号。这意味着你在项目的dependencies里声明一个Spring相关依赖时不用写version标签因为父工程已经锁定了版本。这种依赖版本统一管理的方式可以有效避免项目里各jar包版本互相冲突。spring-boot-starter-web是起步依赖它帮我们引入SpringMVC、内嵌Tomcat、Jackson序列化组件等Web开发所需的一整套库。所谓起步依赖就是把某个功能领域常见的基础依赖打包整合你只需要引入一个starter相关的jar包就都被带进来了。spring-boot-maven-plugin是构建插件它的主要作用有两个一是支持把项目打成可执行的jar包里面包含内嵌Tomcat可以直接java -jar运行二是在执行某些命令时提供Spring Boot特有的帮助功能。这个插件在你使用IDEA启动项目时不是必须的但是当你将来要打包部署时它就是核心了。4. 配置与核心概念从application.properties说起4.1 配置文件选properties还是ymlSpring Boot支持两种主流的配置文件格式application.properties和application.yml。它们的作用完全一样区别只是书写方式不同。properties是传统的键值对形式yml则用缩进表示层级结构。两种格式放在一起对比# application.properties server.port8081 spring.application.namedemo spring.datasource.urljdbc:mysql://localhost:3306/test spring.datasource.usernameroot spring.datasource.password123456# application.yml server: port: 8081 spring: application: name: demo datasource: url: jdbc:mysql://localhost:3306/test username: root password: 123456我个人的习惯是用yml格式因为配置多了之后层级关系一目了然也不需要重复写前缀。但是yml对缩进极其敏感新手常因为多一个空格或少一个空格导致解析失败。如果你不熟悉缩进语法先用properties也行这两种格式Spring Boot都原生支持。关于配置文件里的常用配置项我列几个最常见的server.port服务端口号默认8080如果你本地的8080被占用可以改成8081或者其他端口。spring.application.name应用名称注册到注册中心时会显示这个名字。spring.profiles.active指定当前激活的profile用来加载不同环境的配置文件。server.servlet.context-path应用的上下文路径配置后访问接口需要带上这个前缀。4.2 多环境配置怎么组织实际开发中一个项目通常要部署到多个环境本地开发环境、测试环境、生产环境。不同环境下的配置是不一样的比如数据库地址、日志级别、加密密钥等。Spring Boot提供了profile机制来处理这种情况。常见做法是维护多个配置文件application-dev.yml开发环境、application-test.yml测试环境、application-prod.yml生产环境然后在主配置文件application.yml里通过spring.profiles.active这一行指定当前用哪套配置spring: profiles: active: dev运行的时候如果启动参数里指定了--spring.profiles.activeprod可以覆盖配置文件里的默认值。这种方式的好处很明显环境配置和代码分离部署到不同环境时不需要改代码只需要指定不同的参数就行。特别是生产环境的一些敏感信息不应该写死在代码里而是通过环境变量或配置中心传入。4.3 主类上的SpringBootApplication是什么打开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); } }SpringBootApplication是一个组合注解它相当于SpringBootConfiguration、EnableAutoConfiguration、ComponentScan三个注解的集合。简单理解SpringBootConfiguration标明这是一个Spring Boot配置类。EnableAutoConfiguration开启自动配置让Spring Boot根据引入的依赖自动装配相关组件。比如你引入了web starter它就自动配置Tomcat和SpringMVC。ComponentScan让Spring去扫描当前包及其子包下面的组件被Controller、Service、Repository等注解标注的类把它们注册到容器中。这三个注解的工作可以类比为一个装修公司进场后发现你是精装房于是把基础家具按标准摆放好然后在房间里自动寻找你新添置的物件把它们登记到家具清单里。这就是为什么Spring Boot项目里主类所在包一定要放在最外层因为扫描范围默认是从主类所在包开始的。如果你的Controller写在了主类的兄弟包之外扫描不到访问就404。5. 初步运行与验证把人生第一个Spring Boot接口跑起来5.1 启动过程全记录项目导入IDEA、依赖下载完成后直接在IDEA里右键DemoApplication.java选择Run就会看到控制台开始输出日志。第一次启动Spring Boot项目时日志量会比想象的多因为自动配置打印了很多条件评估信息debug模式才会有详细列表默认日志其实还算简洁。关注日志里几个关键行第一是显示Spring Boot的Logo和版本信息第二是Tomcat started on port(s): 8080这行日志它说明内嵌Tomcat已经在8080端口上启动成功第三是Started DemoApplication in x.xxx seconds这行出现后说明整个应用初始化完成。这时打开浏览器输入http://localhost:8080如果看到的是Whitelabel Error Page或者404页面这其实是正常的。因为项目里目前还没有任何Controller没有可以响应的路径。Whitelabel页面是Spring Boot默认的错误页面说明Tomcat在工作只是没有资源返回。这个时候我们马上写一个接口来打破这个404。5.2 第一个接口写一个HelloController在com.example.demo包下新建一个类命名为HelloController内容如下package com.example.demo; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; RestController public class HelloController { GetMapping(/hello) public String hello() { return Hello Spring Boot!; } }代码写好后不用重启服务不此时如果你项目已经启动Spring Boot默认是不会自动加载新类的。你需要手动重新运行一次如果后面配置了热部署则可以自动重载。重启后浏览器访问http://localhost:8080/hello就能看到Hello Spring Boot!这段文字了。这里有个知识点为什么类上用RestController而不是Controller简单说RestController是Controller和ResponseBody的结合体它表示当前控制器类中的方法返回值会直接作为HTTP响应体返回也就是以JSON或纯文本的形式写回浏览器而不经过视图解析器渲染成页面。在前后端分离的项目中RestController是最高频使用的注解。接着我们再把接口扩展一下接收前端传入的参数。Spring Boot提供了几种常见的参数接收方式比如RequestParam接收查询参数RestController public class HelloController { GetMapping(/hello) public String hello(RequestParam(name name, defaultValue World) String name) { return Hello name !; } }重启项目后访问http://localhost:8080/hello?nameSpring返回结果就变成了Hello Spring!。RequestParam注解里name属性指定了前端传来的参数名defaultValue指定了参数缺省时的值。另一种常见的是PathVariable用来接收URL路径参数GetMapping(/users/{id}) public String getUser(PathVariable Long id) { return user id: id; }访问http://localhost:8080/users/123返回值是user id: 123。这两者在开发中一个对应RESTful风格的路径参数一个对应传统的查询字符串参数用起来要区分场景。5.3 用命令行curl验证接口浏览器验证很方便但作为一个后端开发者习惯用命令行验证接口也很重要。打开终端执行curl http://localhost:8080/hello返回结果是Hello Spring Boot!。如果在Windows的CMD里curl命令也是自带的使用方式一样。还可以加上参数进行POST请求测试这个后面的系列文章会用到。5.4 热部署改完代码不用手动重启每次改代码都要手动重启服务这样开发效率太低。Spring Boot提供了spring-boot-devtools热部署组件引入后可以在代码变更时自动重启应用。在pom.xml里添加依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId optionaltrue/optional /dependency然后需要在IDEA中开启自动编译否则改了代码也不会触发重启进入Settings Build, Execution, Deployment Compiler勾选Build project automatically再用快捷键打开Advanced Settings勾选Allow auto-make to start even if developed application is currently running。配置完成后每次保存Java文件IDEA会触发增量编译devtools检测到变化后自动重启应用。devtools的原理并不是把整个JVM重启而是加载了新的类加载器去重新加载项目类所以重启速度比手动重启要快。不过这里要强调一个注意点生产环境部署时千万不要带上devtools依赖因为自动重启在正式运行环境里是一件很危险的事。一般通过Maven的profiles或者打包排除机制把它隔离在开发阶段。6. 常见问题与排查技巧实录6.1 端口被占用启动时报错Port 8080 was already in use说明8080端口被其他程序占用了。最直接的解决方案是换一个端口号在application.properties里设置server.port8081如果你想知道是哪个进程占用了端口Windows上可以使用netstat -ano | findstr 8080找到对应的PID然后在任务管理器里结束进程。macOS或Linux上可以使用lsof -i :8080查看占用进程。我个人更推荐换端口而不是去杀进程因为本地机器上跑很多服务其他服务可能也有用杀掉容易误伤。6.2 依赖下载失败或速度极慢这是新手最常见的问题。表现是IDEA的Maven窗口里依赖列表一直加载失败或者控制台报错Cannot resolve ...。这种情况九成以上是网络问题。先去确认Maven的settings.xml的镜像配置有没有生效注意检查你用的是不是IDEA自带的Maven因为IDEA默认配置不会读你手动安装的Maven的设置。另一个问题是本地仓库里残留了下载失败的.lastUpdated文件。有时候网络闪断导致jar包没有完整下载Maven可能不会自动重新拉取。解决办法是进入本地仓库目录默认在用户目录下的.m2/repository搜索并删除所有.lastUpdated结尾的文件然后重新刷新Maven项目。Maven重新加载后就会尝试重新下载。6.3 JDK版本不匹配导致的启动失败Spring Boot 3.x项目如果你用JDK 8去跑控制台会直接抛出类似UnsupportedClassVersionError的异常。这个错误信息里的数字很有线索价值比如class file version 61.0表示编译该代码的JDK版本是1761对应JDK 17而你运行的JVM版本太低。解决方法是统一JDK版本。检查IDEA的Project Structure中Project SDK设为JDK 17或以上再检查File Settings Build Tools Maven Running里的JRE是否为同一版本最后检查pom.xml里有没有配置java.version属性项目的编译目标也要同步调整。6.4 中文乱码问题项目中出现中文乱码为预防这类情况最根本的做法是从创建项目开始就统一编码。IDEA里默认编码一般就是UTF-8但你导入老项目时可能会出现问题。建议把IDE的File Encodings选项全部设为UTF-8并在properties文件里写中文时格外注意。另外有些版本IDEA对properties文件默认使用ISO-8859-1编码如果你在application.properties里直接写中文注释或中文配置值容易乱码。最稳妥的方案是中文配置尽量放在yml文件里或者保持properties里的内容全部为ASCII字符。6.5 访问接口一直404接口404首先要确认Controller是否被Spring扫描到。检查主类的包路径SpringBootApplication所在的主类必须在Controller的同级或上级包下。然后检查Controller类上有没有RestController注解方法上有没有写GetMapping路径。如果这些都正确再检查请求的URL包括端口号、context-path前缀是否拼写正确。7. 写在最后的经验与建议我从零开始学Spring Boot时犯过一个挺小的错误但当时很困惑我以为改了application.properties里端口号以后会自动生效结果没有。后来发现Spring Boot的配置读取是有时机的改完配置必须重新启动应用才能生效。类似这样的不对齐在开发里太常见了。我的建议是这一篇的学习目标不需要定得太高先把能跑变成肌肉记忆会从零搭一个项目会写一个接口会改端口号会看懂启动日志。至于Spring Boot背后自动配置的完整原理、条件装配的细节在后面写实际业务项目的过程中再慢慢深入。第一课如果纠缠在原理里反而容易被劝退。这个小项目跑起来之后下一步可以做这些扩展给项目加上一个数据库比如MySQL或内置的H2写一个实体类和Repository接口配合前面写的Controller完成简单的增删改查也可以把工程拆分成controller、service、mapper三层模拟真实项目的结构。每往前走一步Spring Boot的拼图就会多完整一块。这篇系列的第一讲就到这里。下一篇我会从分层架构入手带着大家写第一个具备真实业务意义的CRUD接口把service层、数据访问层、统一异常处理这些东西一次讲透。咱们下期见。

Spring Boot从零搭建指南：从环境配置到第一个接口运行

相关推荐

【异常】codex 超时报错（Timeout waiting for child process to exit）已验证解决流程：把 Codex auth.json 改到 TaoToken

BQL队列控制：用类SQL规则语言治理消息积压与雪崩

HexView实战：ECU刷写文件转换、裁剪与CRC校验避坑指南

更多资讯

Claude Code安全稳定使用指南：上下文管理、权限边界与实战避坑

基于YOLOv9的车辆行人识别计数系统：从检测到跟踪的完整工程实践

Python深度强化学习多智能体电梯调度：目的楼层预约算法实战

dash.js 开发者贡献指南：Issue 优先级体系、代码提交十步流程与质量门槛

软件工程常见过程模型全解析：从瀑布模型到迭代模型，用 TaoToken 统一 API 通道做一次横向对比

信贷风控实战：贷款违约预测的端到端Python建模与避坑指南

今日更新

Susi AI API实战指南：susi_alexa_skill如何用Node.js调用chat.json获取智能回答

换新电脑了？KeyStats 恢复码数据找回完全指南，端到端加密统计一键重建

重建二叉树：由前序与中序遍历序列还原二叉树的原理与 Java 实现（YCBlogs 剑指 Offer 精讲）

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？