★ FEATURED ARTICLE 前后端分离的 Spring Boot Vue 项目被卡在第一步的人远比你想象的多。很多人不是不会写代码而是项目根本跑不起来版本对不上、目录乱成一团、前端到后端的请求跨域、端口冲突随便一个都能让人怀疑人生。这篇是系列1只讲新建项目这一件事。我会带你从后端初始化、前端创建、到两边服务在本地真正跑通把“第一步”这个地基打牢。如果后面你很顺利大概二十分钟能搞定如果中间踩坑这篇文章也会帮你把常见的坑都填平。之所以要把“新建项目”单独拿出来讲一篇原因是很多人后面部署出问题、联调出问题往回追往往都是这一步留下的隐患项目名乱取、依赖版本乱选、目录结构随手建、端口规划没概念。这些都是可以在一开始就避免的。所以这篇不是敷衍的“打开 IDE 点下一步”而是把一个合格从业者在这一步真正会做的规划、选择和配置讲透。适合刚接触这套技术栈的新手也适合以前照老教程搭过、但想理清版本和结构的老手。这篇会先讲版本选型和目录规划然后分别搭建后端和前端最后把前后端在本地打通。等到下一篇我们再进入业务代码和数据库再往后才是真正的部署上线。现在开始。1. 开工之前先把版本和目录规划好新建项目这件事最怕的就是“打开工具直接干”。工具默认给的版本、模板不一定适合你手头的情况等你代码写了一半发现问题再回头改版本基本等于重建项目。所以我习惯在任何代码落盘之前先花五分钟把版本、目录、端口这三件事定死。1.1 版本选型不是越新越好是越稳越好先说后端。目前 Spring Boot 已经到 3.x它跟 2.x 最大的区别是强制要求 JDK 17 及以上很多老教程还在用 JDK 8 Spring Boot 2.x 的组合。你要是照着老教程硬套大概率会在依赖下载或者编译的时候出问题然后在百度上搜一圈才发现是版本不兼容。我选型的建议很简单工具推荐版本选型理由JDK17LTSSpring Boot 3.x 的硬性要求长期支持版稳Spring Boot3.x 最新稳定版官方推荐安全更新和社区资料都齐全Maven3.6.3 及以上支持 JDK 17 的编译默认配置无需额外处理Node.js20 LTSVite 5 以上要求 1820 是长期支持版生态兼容最好Vue3.x当前主流组件语法和生态最成熟Vite5.xVue 官方推荐的构建工具启动速度比旧版 Webpack 快太多你机器上如果已经装了好几个 JDK 版本那要注意 IDEA 或者 IDE 里要单独确认一下项目用的到底是哪个 JDK这个后面编译的时候很容易踩坑。Node 版本管理推荐用 nvm装错了随时切版本比卸载重装省事太多。1.2 目录结构规划一个总目录两个子项目前后端分离的项目最忌讳的是后端一个目录、前端一个目录放得到处都是过两个月你自己都找不着。我比较推荐在一个总项目目录下划分两个子目录后面部署的时候也方便统一上传和打包。比如你的项目叫某业务管理系统那就建一个总目录business-system/里面再建business-system/ ├── backend/ # Spring Boot 后端 ├── frontend/ # Vue 前端 └── docs/ # 接口文档、部署说明等这个结构的优点是路径清晰后面打jar包、构建dist静态文件的时候所有产物都在同一个大目录下部署脚本也好写。我个人还会在docs里建一个deploy.md专门记录服务器上的部署步骤省得每次上线都靠脑子回忆。1.3 开发工具和网络环境先把坑填平后端开发我建议直接用 IDEA社区版就够用前端开发用 VS Code 顺手一些。两者可以同时开改前端代码和改后端代码互不干扰。另外有一个很现实的问题依赖下载速度。国内拉 Maven 和 npm 的依赖经常慢到怀疑人生这不是项目的问题是网络环境的问题。解决办法很简单先配置国内镜像。Maven 镜像在settings.xml里加一段mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirrornpm 镜像在命令行执行npm config set registry https://registry.npmmirror.com这两步看起来不起眼但能让你后面少等至少一半的下载时间。很多新手卡在“依赖一直下载不动”这个环节其实不是电脑坏了就是镜像没配。2. 后端 Spring Boot 项目搭建三分钟跑通第一个接口规划做完了下面开始真正动手。我先从后端开始因为前端联调必须要有一个能响应请求的后端服务在跑否则前端只能看一个空页面。2.1 用 Spring Initializr 创建后端项目打开浏览器访问 Spring Initializr这个网站是 Spring 官方的项目生成器省得自己在 IDE 里一步步点。需要填的几个关键项Group 填你的包名倒序比如com.example如果是公司项目就填公司域名倒序Artifact 填项目名比如backend生成的项目名就是backendJava 版本选 17Spring Boot 版本选当前 3.x 稳定版依赖这一栏这一篇建议只选三个Spring Web提供 REST 接口能力必选Lombok简化实体类的 getter/setter 代码必选Validation后面做参数校验要用提前选上不亏数据库相关的依赖比如 MyBatis、JPA、MySQL Driver这款先不加。原因是数据库驱动的依赖在启动时如果没有对应的配置会直接报错这一篇的目标是先把骨架跑通数据库等下一篇讲业务的时候再加这样每一篇的起点都是“可运行”的。生成之后会下载一个 zip 包解压到你刚才建好的backend目录然后用 IDEA 打开。第一次打开 Maven 会自动下载依赖这个过程不要中断等右下角的进度条走完。这里有一个新手最容易看懵的事情IDEA 里怎么确认 Maven 用的是你本地的 settings.xml看 IDEA 的Settings - Build, Execution, Deployment - Build Tools - MavenUser settings file 那一栏要指向你的 Maven 配置文件否则镜像配置不生效下载依旧慢。2.2 配置文件应用 yml 格式并规划端口Spring Initializr 默认生成的是application.properties文件我习惯把它改成application.yml因为 YAML 的层级结构在配置多的时候更清晰。在src/main/resources下新建application.yml写入server: port: 8080 spring: application: name: backend3.x 的 Spring Boot 会把默认端口定在 8080这没问题但是你要记住了后端 8080前端 5173这两个端口后面联调要用。如果你的 8080 已经被占用了java.net.BindException: Address already in use就会找上门这时候两条路一是杀掉占用 8080 的进程二是在 yml 里改成别的端口。我建议统一用 8080因为后面 Nginx 反代配置的时候会少一些端口映射的心智负担。2.3 第一个 REST 接口与启动验证后端项目刚生成是没有接口的我们写一个最简单的接口来验证服务能跑通。在com.example.backend主包下新建一个controller包然后在里面创建package com.example.backend.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/api) public class HelloController { GetMapping(/hello) public String hello() { return Hello from Spring Boot; } }不要小看这个/api前缀。我见过很多项目接口直接写/hello、/login后面部署到 Nginx 的时候前端请求要转发到后端如果接口路径不带统一前缀Nginx 的location规则会写得很绕。带/api前缀以后所有前后端交互的请求都是/api/xxx规则统一代理配置省心很多。然后启动项目右键BackendApplication选 Run。控制台看到类似这样的日志就说明后端跑通了Tomcat started on port(s): 8080 (http) with context path 这时候打开浏览器访问http://localhost:8080/api/hello应该能看到一段纯文本。其实第一次搭后端的项目我建议在验证接口之前先看一眼控制台有没有报错。最经典的一个报错就是 Lombok 相关的编译异常这是因为 IDE 里没安装 Lombok 插件或者编译器没有开启注解处理。新版 IDEA 基本是内置的但如果你用的插件版比较旧装一下 Lombok 插件并且在Settings - Compiler - Annotation Processors里勾选Enable annotation processing就稳了。3. 前端 Vue 项目搭建从脚手架到能调通后端后端跑通了接下来创建前端项目。这里我会用 Vite 而不是旧版的 Vue CLI因为 Vite 启动快、配置简单官方现在也推荐这条路。3.1 用 create-vue 还是 create-viteVue 官方提供的脚手架有两个入口npm create vuelatest用于创建带官方推荐工程结构的 Vue 3 Vite 项目会问你需不需要 Router、Pinia、ESLint 等npm create vitelatest是 Vite 官方的通用脚手架选 Vue 模板后只给你最精简的空框架我给的建议是直接用npm create vuelatest。原因很简单后面写页面基本都会用到路由和状态管理与其之后手动集成不如一开始就选上。它在交互式问答里会问你要不要 TypeScript、Vue Router、Pinia你按需选就行。在business-system目录下执行npm create vuelatest frontend创建过程会问一系列问题建议的选项是TypeScript 可以先不选这一篇为了减少心智负担用 JS 就行Vue Router 选 Yes因为后面页面跳转几乎必用Pinia 按需选现在要是不用可以先 NoESLint / Prettier 选 Yes代码风格统一一下。进入项目并启动cd frontend npm install npm run dev看到Local: http://localhost:5173/就说明前端也跑起来了。浏览器打开这个地址你会看到 Vue 官方的欢迎页。3.2 前端目录结构设计与基础依赖安装脚手架生成的目录已经有一些基础结构但还不够应付真实项目。我自己的习惯是在src下再规划出这么几个目录src/ ├── api/ # 所有接口请求封装 ├── assets/ # 静态资源图片、样式 ├── components/ # 公共组件 ├── router/ # 路由配置 ├── stores/ # 全局状态管理如果选了 Pinia ├── views/ # 页面组件 └── utils/ # 工具函数这一步在手把手的新建项目阶段就能做好不要等代码写多了再来返工。然后安装 axios这是每个前后端分离项目都绕不开的 HTTP 库npm install axios如果你想用现成的 UI 组件库推荐 Element Plus 装一个npm install element-plus这套组合Vue 3 Vite Element Plus在业务管理系统里非常常见接下来的整个系列都会基于这套技术栈展开。3.3 Vite 代理配置解决跨域让 /api 直达后端现在前端和后端都在跑但如果你直接在浏览器里从http://localhost:5173请求http://localhost:8080/api/hello会碰到跨域问题浏览器会拦截响应控制台报错。解决这个的业内标准做法是利用 Vite 开发服务器的代理功能让浏览器认为请求发往的是同一台服务器实际由 Vite 在服务端转发给后端。这样开发环境完全不需要后端开启 CORS。在frontend/根目录下找到vite.config.js改成这样import { fileURLToPath, URL } from node:url import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ plugins: [vue()], resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) } }, server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })关键就是server.proxy这一段。它表示所有以/api开头的请求都会被 Vite 开发服务器转发到http://localhost:8080。这里我多说一句changeOrigin的作用。有些后端服务会校验请求头里的 Host不设置changeOrigin: true的话后端看到的 Host 还是localhost:5173有些严格的服务会拒绝设为true后代理转发时会改成目标地址的 Host。在本地开发环境里基本不会出问题但加上这个配置总归是更稳妥的。修改完配置文件Vite 会自动重启无需手动重启。这个特性很舒服。4. 前后端联调与地基整理把准备工作做到位骨架都有了、代理也配好了接下来最重要的就是“让两边真的能对话”。只要这一次对话成功了整个开发环境的地基就稳了大半。4.1 联调验证看到一个字符串出现在页面上先确认后端还在 8080 跑着前端 dev server 还在 5173 跑着。然后打开前端项目里主要的页面组件在onMounted里用 axios 请求后端的接口。以脚手架生成项目为例在src/views/下新建一个HomeView.vue内容写成template div h1{{ msg }}/h1 /div /template script setup import { ref, onMounted } from vue import axios from axios const msg ref(正在请求后端...) onMounted(async () { const res await axios.get(/api/hello) msg.value res.data }) /script然后把路由的默认指向改到HomeView浏览器访问http://localhost:5173页面应该从“正在请求后端...”变成Hello from Spring Boot。这一步的意义怎么强调都不为过。它验证了四件事后端 Spring Boot 项目能正常运行前端 Vue 项目能正常运行axios 请求发出去了Vite 代理把/api请求正确转发给后端四件事只要有一件不行这里就过不去。联调不成功的话优先打开浏览器的开发者工具看 Network 面板如果请求状态是 404看路径前缀是不是写错了如果是 502看代理目标地址的端口是不是和后端对不上如果是 CORS 报错说明代理配置没生效检查 Vite 配置后重启。4.2 统一响应结构减少后面返工的第一件事我在新建项目阶段就会把前后端的“接口约定”定下来而不是等写了三五个接口再回头统一。推荐做一个统一的响应体后端所有接口都返回这个结构package com.example.backend.common; import lombok.Data; Data public class Result { private Integer code; private String message; private Object data; public static Result success(Object data) { Result result new Result(); result.setCode(200); result.setMessage(success); result.setData(data); return result; } public static Result error(String message) { Result result new Result(); result.setCode(500); result.setMessage(message); return result; } }这样前端 axios 请求里就可以统一做拦截处理先看code是不是 200不是的话弹个提示。好处是接口越多前后端沟通成本越低。前端也可以对应建一个src/utils/request.js封装 axios 实例统一处理响应码。这个环节现在做只需要几分钟等业务接口写多了再改就是几十个接口的大工程。4.3 本地常见问题速查表我非常确定你新建项目的时候会碰到下面一些问题先列出来遇到直接对照着排查问题可能原因解决方法后端启动报Address already in use8080 端口被占用用netstat -ano找到占用进程杀掉或改 yml 端口前端npm install卡住npm 源访问慢配置镜像后重装前端启动报 Node 版本错误Node 版本低于 18用 nvm 切换到 20 LTS页面请求/api/hello404后端接口路径不对确认后端 Controller 的 RequestMapping 和 GetMapping页面请求/api/helloCORS 报错Vite 代理没生效检查 vite.config.js改后重启 dev serverMaven 依赖下载报错镜像未配置或 Maven 版本过低配置阿里云镜像升级 Maven 到 3.6.3后端编译报 Lombok 相关错误IDE 注解处理未开启安装 Lombok 插件开启 Annotation Processing我自己这些年带过的项目里最坑的一个问题不是技术而是“两个项目同时开着前端调用时才发现后端没启动”。这种情况浏览器报的是 ECONNREFUSED容易让人误以为代码有问题。所以联调之前永远先确认后端控制台有没有日志后端页面能不能直接访问。先把这条养成本能反应能省很多瞎排查的时间。4.4 为下一步部署做的准备提交一次干净的初始版本新建项目完成、联调通过之后我建议你做一次完整的 git 提交把这个“可运行的初始状态”固定下来。为什么因为接下来写业务代码、接数据库的过程中你可能随时改出问题有了这个干净的基准确认心里就不慌随时能退回来。提交的时候注意一个点在项目根目录建一个.gitignore文件把node_modules/、target/、dist/这些目录全部排除掉。一开始不建的话很容易把几十万个前端依赖打进仓库后面每次提交都痛苦。前后端分离的新建项目到这一步就完成了。地基是最无聊也最不能省的部分我把这一篇的内容都踩实之后下一篇就能放心地进入数据库设计和业务接口开发而不必担心还在结构问题上绕圈。我个人在实际项目里的一个习惯是新建项目后不是马上写业务代码而是花半天把基础结构完整跑通一遍甚至把部署脚本的雏形都写出来。原因很简单基础的每一点混乱都会在后面的联调和部署阶段被放大。把这里做扎实后面整个项目周期都会省心得多。
阅读完成 · 觉得有帮助？
