Spring Boot 3.x项目初始化：Spring Initializr从选型到首个接口实践

1. 为什么 Spring Initializr 依然是启动项目的首选我接触 Spring Boot 已经有几年时间从最早的 1.x 版本一路用到现在。说实话每次看到新人纠结“要不要用 Initializr”、“是不是自己手写 pom.xml 更显功底”这类问题时我都很想拉他们坐下聊聊。Spring Initializr 不是“新手玩具”它本身就是 Spring 官方团队维护的核心生产力工具。Spring Boot 3.x 时代项目的初始化复杂度其实是上升了而不是下降了——JDK 版本选型、依赖版本兼容性、Starter 的传递依赖管理、构建插件配置这些如果全部手工操作光是把一个空项目跑起来就可能消耗半天时间而且极易踩到版本冲突的坑。Initializr 的价值在于它把“正确性”内置到了生成流程里。你只需要选好项目类型、语言、构建工具和依赖组合它生成的项目天然遵循当前 Spring Boot 版本的推荐实践所有 Starter 的版本号都有 BOMBill of Materials统一管理Maven 或 Gradle 的插件也预先配置妥当。这意味着你拿到项目的第一个瞬间就可以直接写业务代码而不是先跟环境配置缠斗。这条工作流从我个人的经验来看适用于几乎所有场景个人学习、公司内部项目、开源项目脚手架搭建、甚至微服务架构下的多模块工程拆分。无论你处在哪个阶段Spring Initializr 都能帮你把前 10% 的重复劳动压缩掉让你把精力放在真正有价值的事情上。2. Initializr 前先搞懂 Spring Boot 3.x 的选型要求在打开 start.spring.io 之前有四个关键选项需要先想清楚。这些决策会在很大程度上影响后续的开发体验而且一旦项目创建后再想反悔改造成本就高了。2.1 构建工具选 Maven 还是 GradleSpring Boot 3.x 官方对 Maven 和 Gradle 都提供了完整支持但从社区生态和大多数企业的实际选择来看Maven 依然占据主导地位。原因其实很现实Maven 的成熟度更高插件生态更稳定绝大多数开发者的学习曲线更平缓而且在国内的网络环境下Maven 中央仓库的镜像源配置非常成熟下载依赖的体验很顺畅。Gradle 的优势在于构建速度快、脚本灵活如果你所在团队已经全面转向 Gradle或者项目有复杂的自定义构建需求选 Gradle 肯定是合理的。但如果你是刚接触 Spring Boot 3.x或者不太确定该怎么选我倾向于建议直接用 Maven。没必要在这个环节给自己增加额外的认知负担。2.2 语言选 Java 还是 KotlinSpring Boot 3.x 对 Java 17 以及更高版本有了硬性要求这一点必须明确——如果你的本机 JDK 还停留在 8 或者 11直接用 3.x 会立刻遇到编译错误。所以项目初始化前先确认 JDK 版本是第一优先级的事项。Java 我基本不犹豫因为资料多、团队熟悉度高出了问题排查成本低。Kotlin 在 Spring 生态里的支持度也很好Spring 官方甚至提供了 Kotlin 相关的专门文档但如果你的主要目标是把业务跑起来用 Java 会稳妥很多。2.3 JDK 版本选 17 还是 21Spring Boot 3.0 时代JDK 17 是基线版本这也是当时绝大多数项目的选择。到了 Spring Boot 3.2 以及后续版本JDK 21 的支持已经很成熟了如果你是从零开始的新项目直接选 21 是合理的选择。JDK 21 带来了虚拟线程等新特性配合 Spring Boot 3.2 以上的版本在高并发 I/O 密集型场景下能获得明显的性能收益而且默认的 G1 垃圾回收器在 21 上的表现也更成熟。完全没必要在起跑线上选一个已经处于维护末期的版本。2.4 项目类型选 Jar 还是 War除非你有明确的部署需求比如必须部署到外部 Servlet 容器否则直接选 Jar 就好。Spring Boot 内置的 Tomcat 在绝大多数场景下已经足够Jar 包的部署、迁移、水平扩展都比 War 包简单得多。Spring Boot 3.x 时代War 包基本只出现在老旧系统的改造项目中。3. 实操Spring Initializr 页面逐项配置详解打开 start.spring.io你会看到一个分区域的配置界面。很多人喜欢直接中间选几个依赖就点生成但我建议你花两分钟时间每一栏都过一遍。3.1 项目基础信息填写Project 栏选择 MavenLanguage 选择 JavaSpring Boot 版本选择当前最新的稳定版。这里要注意不要选带有 SNAPSHOT 或者 M1、M2 字样的版本这些是里程碑预览版或者开发版虽然功能上没有什么大问题但依赖的稳定性没有保障。我在生产环境只使用 GA 版本这条原则也建议你遵守。Group 一栏填写组织标识一般用公司域名倒写比如 com.example。如果项目没有明确的域名归属用 com.yourname 也行后续可以全局替换。Artifact 一栏是项目标识比如 order-service、user-center这一项会直接成为 Jar 包名的一部分注意使用小写字母和短横线分隔。Name 是项目显示名称通常和 Artifact 保持一致。Package Name 是 Java 根包名默认会拼接 Group 和 Artifact可以自己微调但要保证后续所有代码都落在这个包路径下。Packaging 选 JarJava 版本选 21。这部分配置看起来简单但我遇到过不少同事把包名起得随意比如 com.demo.test 混着另一个包名结果 Controller 扫描不到 Service排查半天才发现是根包不统一的问题。建议初始就规划好省得后面返工。3.2 Dependencies 依赖选择策略点击右侧 Add Dependencies 按钮会弹出依赖搜索框。这里不要一上来就猛加一堆我的原则是“只选当前确定要用的”不需要的以后随时可以手动加。对于构建一个标准的 REST API 服务最基础的依赖是 Spring Web。如果你要操作数据库Spring Data JPA 或者 MyBatisSpring Boot 3.x 下用 mybatis-spring-boot-starter可以按需添加。这里我提醒一下不要一上来就把一堆中间件依赖全勾上。我用 Spring Initializr 创建项目时除了 Spring Web通常一个都不勾后续在写代码的过程中按需引入这样每次新增依赖时都能明确知道是干什么用的遇到问题也好定位。3.3 一键生成与项目导入确认所有配置项无误后点击 Generate 按钮浏览器会下载一个 zip 压缩包。解压后用 IntelliJ IDEA 打开项目目录选择信任项目即可。Maven 会自动开始下载依赖首次下载的时间取决于你的网络状况。这里有一个国内开发者必须做的事修改 Maven 仓库镜像地址。Spring Boot 3.x 的依赖数量不少如果直接走 Maven Central下载速度会很感人。建议在 maven 安装目录下的 conf/settings.xml 或者用户目录下的 .m2/settings.xml 中配置阿里云镜像或其他国内镜像源。配置完成后再重新加载项目依赖下载速度会明显提升。mirror idaliyun/id mirrorOfcentral/mirrorOf namealiyun/name urlhttps://maven.aliyun.com/repository/central/url /mirror这段配置是我在多个项目中验证过稳定可用的方案直接用即可。3.4 项目结构一图看懂Spring Initializr 生成的项目雏形在 IDEA 中打开后你会看到统一的层级结构。根目录下有个 pom.xml这是整个项目的核心配置声明了 Spring Boot 版本、所有依赖和构建插件。src/main/java 下是你的 Java 源码目录默认包含一个以项目名命名的启动类且带 SpringBootApplication 注解。资源目录 src/main/resources 下默认只有一个 application.properties这是全局配置文件。测试目录 src/test/java 下有一个空的上下文加载测试类用来验证 Spring 容器能否正常启动。启动类是整个项目的入口SpringBootApplication 是一个组合注解集成了 SpringBootConfiguration、EnableAutoConfiguration 和 ComponentScanSpring 启动时会自动扫描启动类所在包及其子包下的所有组件。有一点要特别留意你新写的 Controller 和 Service 必须放在启动类所在包的子包里否则扫描不到。4. 第一个接口写完后验证项目是否真的跑通了项目结构看明白之后动手写第一个接口是最直接的验证方式。这一步跑通后续的所有业务开发流程就理顺了。4.1 Controller 编写细节在启动类同级的 controller 子包下新建一个 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 hello() { return Hello, Spring Boot 3.x!; } }RestController 注解会将类的返回值直接写入 HTTP 响应体省去了 Controller 加 ResponseBody 的组合。这个方法很短但它验证了一整条链路——组件扫描、依赖注入、请求映射、响应序列化。如果你在浏览器访问 http://localhost:8080/hello 看到返回字符串说明项目已经跑通了。4.2 启动时常见异常速查很多人在启动过程遇到报错就慌实际上这些报错只要拆开看原因都比较直接。端口被占用是最常见的场景会出现 Web server failed to start 的提示确认 8080 端口具体是被哪个进程占用了用下面的命令就能定位。lsof -i :8080如果是 JDK 版本不匹配会提示 UnsupportedClassVersionError这说明你本地 Java 版本低于项目要求。Spring Boot 3.x 必须使用 Java 17 及以上版本这个在环境准备阶段就要确认好。还有一个高频问题是在依赖下载阶段出现的比如某个依赖的 jar 包下载不完整或者部分仓库无法访问Maven 会给出红色报错。这种问题最有效的解药是切换镜像源或者直接删除本地仓库中对应的目录后重新加载项目。4.3 配置文件按环境拆分规划项目刚刚创建时application.properties 里什么都没有很多初学者会直接在里面写业务配置。实际在团队开发中我更推荐按环境去拆分配置文件。把公共配置放在 application.yml开发、测试、生产环境的差异化配置分别放到 application-dev.yml、application-test.yml、application-prod.yml 中。启动时指定环境切换成本很低。Spring Initializr 生成的应用默认只读取 application.properties后面你如果改成了 yaml 格式注意把原文件删掉不要让它在目录里掺和否则加载顺序搞混了会浪费大量排查时间。5. 从 Initializr 到业务开发的衔接思考很多创建完项目就卡在第一步的人不是代码能力不行而是不知道从哪下手。在正式开始写业务代码之前你可以先做几件非常基础但对后续开发很受益的事。第一件事是完善项目的基础包结构。Spring Initializr 只帮你生成了启动类和支持类但实际开发需要 form、service、mapper、entity、common、config 这样的子包。建议在开始写需求之前就把这些包目录建好后续代码放置的位置从第一天就清晰有序而不是写着写着就开始在包里乱丢导致代码腐化极快。第二件事是配置数据库连接信息。如果项目涉及数据持久化在写第一个业务接口前就把数据源配置好。Spring Boot 3.x 使用默认的 HikariCP 连接池配置项非常简洁spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver注意 driver-class-name 在 Spring Boot 3.x 下必须是 com.mysql.cj.jdbc.Driver老的 com.mysql.jdbc.Driver 已经不支持新版本驱动了。第三件事是统一接口响应结构。在 controller 直接返回实体对象短期看着方便但一旦接口数量多起来统一响应体的好处就会显现出来。推荐一开始就定义一个 Result 类包含 code、message、data 三个字段所有接口返回这个对象后面做全局异常处理时才能无缝配合。这三件事做完项目才算真正进入了可开发的良性状态。Spring Initializr 只是帮你打开了门走进去之后的路还是需要自己一步一步铺。后面的系列文章我会依次展开 Spring Boot 3.x 的自动配置原理、常用 Starter 的精细使用、数据库访问层的最佳实践、以及接口设计的坑与解。如果你在实际创建项目过程中遇到了什么奇怪的问题欢迎在评论区留言我会尽量给出基于实操经验的排查思路。