★ FEATURED ARTICLE 1. 为什么我强烈建议你用多种方式创建Spring Boot项目接触Spring Boot这几年我见过太多人只会用IDEA里那个默认的Spring Initializr按钮点下一步。这不是不好但你想想——如果某天断网了、如果公司内网没有外网权限、如果你需要完全离线的开发环境你的项目还建不建如果团队统一规范要求从某个固定仓库拉基础工程你还在官网手动选依赖效率反而最低。所以这次我把IDEA里创建Spring Boot项目的五种主流方式全部趟了一遍从最常用的图形界面方式到最不常用的纯命令方式每一招都附上我的实测体会和踩坑记录。这五种方式分别是——IDEA自带Initializr图形向导、官网Spring Initializr生成zip导入、start.spring.io网页定义项目后命令行构建、Maven archetype方式创建、从零手写一个Spring Boot工程。用一篇文章说清楚每个方式的适用场景、核心步骤、容易翻车的细节以及我个人的优先级建议。这套内容适合刚接触Spring Boot的初学者也适合团队里负责搭工程骨架、统一开发规范的开发者。新手可以找到最顺手的入口老人可以看到一些平时忽略的边角细节比如跳过依赖下载、-Dmaven参数这些操作。2. 五种创建方式的整体对比和选型思路2.1 先搞明白创建一个Spring Boot项目到底是在“创建”什么在正式开跑之前先把底层逻辑捋清楚。不管用哪种方式创建Spring Boot项目最终落到磁盘上你得到的都是一堆文件和目录——一个Maven或Gradle构建文件、一个启动类、一个配置文件、一份测试代码以及按规范铺好的目录结构。换句话说我们所谓的“创建项目”本质上是把Spring Boot项目骨架从外部装进IDEA的工作区IDEA本身不承担任何生成逻辑它只负责识别和集成构建系统。知道这一点之后你对下面五种方式的差异就会理解得快很多有的方式是让托管服务帮你生成这一堆文件有的是让本地的Maven帮你生成有的干脆是你自己手写出来。骨架生成之后剩下的工作是一样的——导入依赖、写启动类、调整配置、运行。理解了“创建项目生成骨架接入构建系统”这两件事你在选法的时候就不会纠结只看哪个方式在当前条件下最省力、最可靠。2.2 一张表看懂五种方式的定位差异我用过所有方式之后习惯把它们的核心差异浓缩成下面这张表方便你选型的时候快速对照。创建方式核心依赖是否需要联网上手难度适用场景IDEA自带Initializr向导IDEA 本机Maven需要(首次)很低日常开发、新手入门spring官网Initializr生成zip浏览器 本机Maven需要低离线保存、版本精确控制start.spring.io网页化命令行构建浏览器 Maven命令需要中自动化脚本、批量生成Maven Archetype生成本机Maven 本地模板可选中离线环境、统一架构约束纯手写工程文本编辑器 本机Maven否较高学习原理、极端环境从这张表能看出来没有哪个方式是绝对最好的。IDEA自带的Initializr向导日常用得最顺手但不适合转交给别人复现场景官网生成zip比较直观但游离在IDE之外Maven Archetype一旦配好团队模板效率极高。它们不是竞争关系而是互补关系。2.3 我平时选方式的思考路径我自己在实际项目中基本遵循这个判断逻辑——先在电脑上测试一下Maven能否正常解析依赖能解析就用IDEA自带向导顺手快速如果不能联网我会评估是否需要本地已有的依赖仓库如果仓库里已经有常用的starter依赖我直接用Archetype或手写方式把工程建起来后面构建时让它走离线模式。如果项目对Spring Boot版本有非常苛刻的要求比如参考某篇博客里的版本组合我会先去官网生成一个精确版本的zip包作为底子再导入IDEA换掉自动生成的版本号。这条路径走下来效率最高几乎没有浪费时间的环节。别小看这些细节我曾经见过有同事每次建项目都要花半个小时手动整理目录结构原因就是他只会用IDEA向导却从来没研究过怎么自定义模板工程这些问题在下面几种方式中都能解决。3. 方式一IDEA自带Spring Initializr图形向导3.1 这个方式为什么是“默认首选”IDEA自带Spring Initializr本质上还是调用了start.spring.io的服务只不过把这些操作封装在图形界面里了。你在界面上填完项目信息、勾选依赖、点完成IDEA会替你向官网发起一个生成请求拿到返回的zip包之后在本地解压并重新识别为Maven工程。这个过程非常顺滑尤其适合刚开始接触Spring Boot的开发者——不需要接触命令行也不需要懂Spring Boot底层结构跟着窗口一步一步走就行。它的优势不只是操作省事还在于IDEA会同步做好接下来的一堆事情识别Maven坐标、建立模块索引、下载依赖到本地仓库、配置运行方式。比如你勾选spring-boot-starter-web之后再勾选spring-boot-starter-testIDEA会在生成的pom.xml里自动帮你写好这些starter以spring-boot-maven-plugin的方式打包还帮你规范了src/main/java和src/test/java目录。3.2 图形向导每一步的细节操作打开IDEA以后在欢迎页选择New Project或者菜单栏选择File - New - Project都能进到同一个面板。特别注意左边项目类型这里有很多人习惯直接选Spring Initializr但新版IDEA里更稳妥的做法是先选“New Project”下的“Spring Boot”然后IDEA会自动帮你关联Spring Initializr服务。接下来配置项目基本信息重点看这几个字段——Name填项目名称会影响最后生成的包路径Location选在哪个目录创建Artifact和Package Name默认跟项目名联动如果你不想用默认值一定要在生成之前改好否则后面改名还要同步改启动类所在包路径很麻烦。Type这里我建议默认选Maven因为Spring Boot的官方示例和多数公司构建仓库都是以Maven为主。到选择依赖的页面常用的组合是——Spring Web支持HTTP接口、Validation做参数校验、DevTools做热部署、Lombok简化实体类。新手经常犯的错误是依赖勾选太多一堆用不到的starter全塞进去启动变慢不说还会增加无意义的依赖冲突排查成本。我的建议是先最小化勾选后面抽到哪个功能再加哪个。JDK版本这个位置必须和本机实际安装的版本匹配否则IDEA会用默认的JDK进行编译版本不匹配时会直接编译报错。提交完成之后IDEA右下角会显示一个进度条这个进度条在拉取Spring Boot的元数据不是卡住了。等进度条结束IDEA会自动打开这个新项目并且会提示“Loading Maven project”紧接着开始解析依赖。如果你这里网络不好会卡在解析依赖很久——这时候可以先检查一下本机Maven的镜像仓库是否配置了国内镜像这是第一个容易踩的坑。3.3 实测中一定注意的初始化细节项目创建完成后不要着急写代码先检查三处。第一检查根目录下的.mvn目录是否存在如果IDEA帮你创建了Maven Wrapper那么后续你可以在命令行直接用./mvnw命令构建不用单独配系统Maven。注意看mvnw文件有没有可执行权限Windows不受影响但Mac和Linux系统如果少了执行权限会直接报Permission denied。第二打开pom.xml确认parent是否引用了spring-boot-starter-parent这是整个Spring Boot项目依赖管理的核心。这个parent帮你锁定了大量jar包的默认版本比如spring-boot-starter-web底层引入的Tomcat版本、Jackson版本不需要你自己写version属性。第三找到主启动类确认SpringBootApplication注解是否已经加上。有一个非常容易忽略的细节启动类所在的包必须是所有子包的最顶层否则Spring Boot默认的包扫描会扫描不到Controller、Service这些组件。比如启动类在com.example.demo而Controller写在com.example.controller那启动时就找不到这个Controller接口直接404。4. 方式二Spring官网Initializr生成zip再导入4.1 什么时候该放弃IDEA向导改用官网IDEA自带向导有个隐性约束——它用到的是IDEA内置的Spring Boot版本元数据有时这个元数据并不是最新的或者说不是你想要的那个版本。比如你手上有个老项目必须在Spring Boot 2.x版本上维护而IDEA里的默认版本已经切到3.x这时如果你用IDEA向导去创建就得手动改版本号改完之后还可能因为依赖版本不匹配出现一堆问题。另一个场景更典型你需要把项目的生成参数分享给别人比如让团队里另一个同事创建完全相同的骨架。官网方式直接把所有参数固化在一个链接里把链接发过去就能生成一样的工程。这比隔着屏幕指挥对方“先选这个再勾那个”靠谱得多。4.2 官网生成的完整流程打开浏览器进入start.spring.io这个页面只做一件事——收集项目参数。页面上有ProjectMaven还是Gradle、LanguageJava还是Kotlin等、Spring Boot版本、Group、Artifact、Dependencies这些字段。填好之后点击Generate就能下载一个zip压缩包把这个压缩包解压出来之后就是一个完整的、没有绑定任何IDE的Spring Boot工程目录。然后回到IDEA选择File - Open直接定位到刚才解压出来的目录IDEA会识别出pom.xml以Maven工程的形式导入。导入过程中IDEA可能弹出一个提示让你选择信任这个Maven项目选Trust即可。接下来就是等依赖下载完去Application启动类检查一下包路径然后再跑起来。4.3 除了常规步骤还应该做哪些动手调整使用官网方式有一个隐藏的操作习惯我可以分享——下载下来的工程解压后先别急着导入IDEA。先用文本编辑器打开pom.xml确认一下依赖列表里是不是所有你勾选的starter都已经正确了进去。因为有的版本组合不会有编译错误但会因为缺少某段依赖导致实际业务代码用不了。比如你勾选了Spring Web但忘记确认spring-boot-starter-web具体在哪个依赖分组——这种问题在官网生成时不太常见但我在离线修改产物的流程里踩过。导入完成后建议把.idea目录自动生成的配置看一眼尤其是compiler.xml里的字节码版本。官网生成的项目默认使用的java.version可能和你本机IDEA全局配置不一样造成“Build success但运行时抛UnsupportedClassVersionError”的问题。解决方法是直接在pom.xml中调整java.version保证和本机一致。另外官网生成的项目带了一个.gitignore文件里面默认忽略了target目录。如果你准备把工程放进远程仓库这个文件别删。很多人在IDEA里手忙脚乱的时候会顺手删掉这些隐藏文件后续就会出现把构建产物提交到仓库的低级事故。5. 方式三start.spring.io自定义组合后走命令行构建5.1 为什么我把它单独列成一种“方式”严格来说这种方式和方式二同源都会用到start.spring.io生成项目。但区别在于——方式二停留在“下载zip包然后手工导入IDE”而这种方式更进一步把“导入IDE”也省了直接通过命令行构建和编译甚至可以把整个流程写成一个脚本在CI流水线里自动执行。这在做自动化测试环境、快速搭建微服务项目集群时非常有用。例如你批量创建好几个不同模块的工程每个模块的包名、端口、依赖都不一样。用图形界面一个个点创建三个就要花将近半小时。用脚本命令行的组合一条命令可以循环执行把所有工程批量拉出来然后统一mvn clean package效率高一个量级。5.2 一条curl命令解决项目骨架生成start.spring.io其实不止可以网页操作它本身就暴露了HTTP接口直接以Get请求加参数就能生成zip。我经常用的是这样一条命令curl https://start.spring.io/starter.zip \ -d typemaven-project \ -d languagejava \ -d bootVersion2.7.18 \ -d groupIdcom.example \ -d artifactIddemo-cli \ -d namedemo-cli \ -d packageNamecom.example.demo \ -d packagingjar \ -d javaVersion8 \ -d dependenciesweb,validation \ -o demo-cli.zip这里最关键的几个参数解释一下typemaven-project指定工程类型是Maven工程bootVersion在这里可以指定到具体的版本号这在后面统一管控多个工程时非常有用dependencies参数用逗号分隔多个依赖标识比如web,validation,actuator也可以写全称如spring-boot-starter-web。执行完这条curl以后当前目录会出现一个demo-cli.zip然后继续执行unzip demo-cli.zip -d demo-cli cd demo-cli mvn clean package如果mvn命令提示找不到说明本机Maven没有配置到环境变量要么去配置PATH要么直接用下载包里自带的mvnw脚本。这一步对初次接触命令行构建的人挑战稍大但一旦跑通过你会觉得比图形界面还要利索。5.3 命令行方式的实用脚本组合为了让这个方式更有实操价值我提供一个批量创建多个工程的参考脚本结构。假设你要创建user-service、order-service、product-service三个模块在bash中写一个简单的循环for artifact in user-service order-service product-service; do curl https://start.spring.io/starter.zip \ -d typemaven-project \ -d languagejava \ -d bootVersion3.2.0 \ -d groupIdcom.example.micro \ -d artifactId$artifact \ -d name$artifact \ -d packageNamecom.example.micro \ -d packagingjar \ -d javaVersion17 \ -d dependenciesweb,actuator \ -o $artifact.zip unzip $artifact.zip -d $artifact rm $artifact.zip done跑完之后三个独立工程就都生成好了。注意循环体中每次生成的zip包要用rm清理掉不然会在目录里堆积很多压缩包。这个脚本看似简单但它把人工从重复劳动里解放了出来后续你还可以继续扩展比如在工程生成后自动执行mvn -DskipTests install。5.4 这个方式最容易忽略的问题用命令行方式建工程有些人会直接把curl https://start.spring.io/starter.zip后面串一堆参数我建议artifactId、name、packageName这三个尽量保持一致或者至少保证packageName是你期望的最终包路径因为Spring Boot启动类的SpringBootApplication注解默认就是按照packageName生成的。如果你随便填后面搬迁代码时要改的地方会非常多。另外在内网开发环境中如果无法访问start.spring.io这个方式就完全失效。我的经验是提前把常用参数的zip包下载保存下来存到本地某个共享目录后续直接从本地分发。这样既保留脚本化生成的便利又绕开了网络限制。6. 方式四使用Maven Archetype创建Spring Boot工程6.1 Archetype方式到底是什么Maven Archetype是Maven提供的一个项目模板机制它对Spring Boot的适配思路很简单——Maven官方或者第三方把标准的Spring Boot项目结构打包成一个模板你执行一个命令Maven就按照模板把文件批量生成出来。这和start.spring.io在原理上有相似之处但它是纯本地机制可以事先把模板文件全部缓存到本地仓库中从而完全脱离外网工作。Spring Boot本身在Maven中央仓库里维护了一个spring-boot-archetype这不是真正的官方主推方式所以很多人不知道。它生成的标准结构和用官网Initializr生成的基本一致包括src/main/java、src/main/resources、pom.xml。另外社区里也有一些开源的Spring Boot Archetype模板使用方式大同小异。6.2 实际执行的Archetype命令以我手头使用的spring-boot-archetype为例执行方式和传统Maven项目类似mvn archetype:generate \ -DgroupIdcom.example \ -DartifactIdsample-archetype \ -DpackageNamecom.example.sample \ -Dversion1.0.0 \ -DarchetypeGroupIdorg.apache.maven.archetypes \ -DarchetypeArtifactIdmaven-archetype-quickstart \ -DinteractiveModefalse注意这里的maven-archetype-quickstart是最基础的Maven模板并不会给你带Spring Boot依赖。如果你要生成一个Spring Boot的Archetype模板需要把archetypeArtifactId换成带spring boot支持的模板。Maven中央仓库中能找到类似spring-boot-archetype的构件你可以先查一下可用的版本再替换上面的坐标。第一次执行时Maven会去中央仓库下载Archetype插件所以严格说Archetype方式在首次使用的时候也需要联网。但之后的创建不再依赖在线因为模板已经被缓存到本地.m2目录了。团队内部如果长期用同一个模板完全可以把settings.xml里的镜像配置到内网私服保证团队生成的项目结构和初始依赖完全统一。6.3 离线使用Archetype的完整准备想要真正实现完全离线创建需要把两样东西提前预备好——Archetype插件本身和模板内容。Maven插件一般存放在~/.m2/repository/org/apache/maven/plugins/maven-archetype-plugin目录模板则存放在相应的Archetype坐标目录下。只要这些文件都存在于本地离线时执行同样的命令就没问题。在内网环境验证时可以通过mvn archetype:generate -DarchetypeCataloglocal指定只扫描本地仓库的模板避免Maven因访问远程目录超时而卡住。这个参数非常实用不加上去的话离线状态下Maven会尝试连接远程仓库等待超时的过程能让你怀疑人生。生成完成之后项目里已经带了一个最简单的启动类要用Spring Boot跑起来你还需要在pom.xml里自行加上spring-boot-starter-parent和Web依赖。如果模板已经内置了这些依赖那拿到手直接运行即可。设置模板是团队负责人值得投入的一件事——把统一的基础依赖、包结构、编码风格模板化新人上手直接用比每次口头交代“记住要加这几个依赖”靠谱一百倍。7. 方式五完全手写一个Spring Boot工程7.1 手写不是“闲得慌”是理解Spring Boot的最快路径你可能会说——这年头谁还手写工程骨架又不是十年前。但我在指导新人或者排查一些诡异构建问题的时候反而会鼓励对方手写一遍。原因很简单——当你手写过一次Spring Boot工程你才会真正理解项目里每个文件存在的原因遇到构建报错时你才能凭借经验判断是哪个部分出了问题而不是看着一屏报错日志发呆。而且手写的方式对环境没有任何依赖。你只要在本机装好JDK能用任意文本编辑器编辑文件就能搭出一个可运行的Spring Boot应用。在完全没有外网、没有IDE辅助、没有Maven中央仓库的情况下只要你本地仓库里有依赖这套方式依然能跑通。可以说手写是兜底方案也是最能体现基本功的方案。7.2 手写工程最小文件清单一个能跑起来的Spring Boot Web工程最少需要以下四个东西pom.xml——声明Spring Boot依赖与构建插件。启动类——带SpringBootApplication注解的主类。application.properties或application.yml配置——至少包含应用端口等基础配置。一个示例Controller——用来验证HTTP访问是否正常。先看核心的pom.xml?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.0/version relativePath/ /parent groupIdcom.example/groupId artifactIdhandwritten/artifactId version0.0.1-SNAPSHOT/version properties java.version17/java.version /properties 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 /build /projectpom.xml中有几处容易写错的地方——relativePath这个标签如果你的父工程指向的是本地工程的某个位置才会用到如果指向的是中央仓库的spring-boot-starter-parent就保持空值或者加一行relativePath/它会在当前目录向上查找父pom这个细节如果你用IDEA图形方式从没注意过手写时就会踩到坑。接下来是启动类创建一个名为HandwrittenApplication.java的文件放在src/main/java/com/example目录下package com.example; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class HandwrittenApplication { public static void main(String[] args) { SpringApplication.run(HandwrittenApplication.class, args); } }这个类的关键就是SpringBootApplication它把Configuration、EnableAutoConfiguration、ComponentScan三个核心能力组合到了一起。少一个都没法正常工作。例如你只用SpringBootApplicationSpring才能完成自动扫描如果你不小心把它误删了只留下了Configuration那Controller就全都注册不到容器里。7.3 手写工程后如何验证它真的能跑配置文件我建议先最小化只要把端口写明白即可server.port8080 spring.application.namehandwritten-app然后在src/main/java/com/example下额外创建一个Controllerpackage com.example; 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 Handwritten!; } }这个时候打开命令行进入工程根目录执行mvn spring-boot:run看到日志里出现Tomcat started on port 8080就说明这个手写工程已经能正常工作了。然后浏览器访问http://localhost:8080/hello能看到返回的字符串即验证通过。整个过程听起来简单但实际手写时非常容易在目录结构上出错——比如src/main/java下面少建了main这一层或者启动类根包名和Controller包名不一致导致扫描不到。把这些问题自查完你对项目结构的理解会比用向导点十次更深。8. 几个建完项目后真正影响工作效率的细节8.1 同一套依赖配置在不同方式下的差异创建方式不同最后得到的pom.xml在结构上会有些微差异。IDEA向导和官网生成的pom.xml通常带着完整注释依赖也比较规整Archetype方式生成的pom.xml可能是极简模板很多依赖需要自己补而完全手写的pom.xml只要骨架完整就算成功。这些差异在日常开发中也许看不出什么但当你用公司统一的代码检查工具或者依赖锁定工具去解析时差异会被放大——比如有的工具默认要求声明每个依赖的版本号而Spring Boot的parent已经管了版本如果你在dependency里强行加version反而可能引发冲突。所以我的经验是pom.xml里有spring-boot-starter-parent引用的依赖一律不写version没有parent引用的必须写version。8.2 创建后必须做的统一检查清单不管用哪种方式创建的工程一定要做一遍下面这套检查基本能规避90%的刚导入报错问题。检查项检查内容常见问题Maven配置settings.xml是否正确配置了私服/镜像首次构建超时、下载失败JDK版本项目java.version与本机编译级别一致UnsupportedClassVersionError启动类位置启动类在包路径的最顶层扫描不到Controller依赖完整性所有用到的starter是否已引入缺依赖时编译期才发现配置文件编码application.yml/properties是UTF-8中文乱码、启动异常Maven Wrapper是否有mvnw权限是否正常无法在命令行构建这个清单我自己每次创建完工程都会过一遍尤其对团队协作项目这能省掉很多“你机器上能跑为什么我这边不行”的沟通成本。8.3 为什么我建议团队沉淀一套内部创建规范创建Spring Boot项目的方式看似小事但在团队里其实应该统一。因为每个人用不同的方式创建出来的工程目录组织、依赖管理、格式风格都会慢慢出现差异。过半年再看有的人项目里多了.mvn目录有的人没有有的人pom里多了一条spring-boot-maven-plugin有的人没有——这些差异在日常开发中未必致命但在统一构建和问题排查时就是隐性成本。比较好的做法是把上面五种方式里的Archetype或脚本方式固化下来做成团队的标准脚手架。一旦标准化新人入职创建项目不再需要各自摸索生成出的骨架结构统一、依赖统一后续CI构建和部署流水线也会更好维护。9. 汇总我的个人体验和最终建议五种方式全部跑完我个人在日常开发中最常用的是IDEA自带的Initializr向导因为它和IDE集成最紧密省去了导入项目、配置识别的时间。在批量创建工程和自动化流程中我更倾向于用start.spring.io的HTTP接口配合命令行构建因为人工参与度降到最低出错概率也最小。而在离线开发或教学讲解场景下Maven Archetype和手写方式则完全发挥了兜底作用。给新手一个明确的路径建议先用IDEA向导建一个项目找到感觉再用官网生成一个zip解压导入理解项目文件然后用curl命令自动创建一个体验自动化的爽快再体验一把Maven Archetype最后抽时间手写一遍。走完这个流程你对Spring Boot项目的理解会非常通透以后再遇到任何“创建项目”相关的疑难杂症都能自己独立判断。最后分享一个小细节——不管用哪种方式创建完项目第一件事不是赶紧写业务代码而是先跑一次完整的mvn clean package -DskipTests确认整个构建链路是通的。这个习惯帮我提前发现了多次因为JDK版本不匹配、依赖仓库配置错误导致的坑。先把地基夯结实后面的一百层楼才盖得稳。
阅读完成 · 觉得有帮助？
