SpringBoot+Vue3博客系统实战：半小时搭建前后端分离项目

如果你正在寻找一个能快速上手、结构清晰、功能完整的JavaWeb项目来丰富你的简历或完成毕业设计那么这篇文章就是为你准备的。SpringBoot Vue3 前后端分离的博客管理系统听起来技术栈很“潮”但很多教程要么过于复杂要么只给源码不讲原理导致你下载后根本跑不起来。这篇文章要解决的核心问题很简单如何在半小时内真正搭建并运行一个可用的博客管理系统而不是仅仅下载一堆看不懂的代码。我们不仅要跑通还要理解每一步为什么这么做以及在实际开发中如何避免那些常见的“坑”。这个项目麻雀虽小五脏俱全涵盖了用户认证、文章管理、分类标签、评论等核心功能是理解现代Web开发流程的绝佳样本。我将带你从零开始手把手完成环境搭建、项目启动、功能测试并重点讲解前后端分离架构下接口联调、跨域处理、数据库配置等最容易出错的环节。无论你是JavaWeb的初学者还是想用Vue3SpringBoot做一个拿得出手的项目这篇文章都能提供一条清晰的路径。1. 为什么选择“博客系统”作为你的第一个全栈项目在众多JavaWeb项目中博客管理系统是一个经典且实用的选择。它不像电商或OA系统那样业务复杂但又足够覆盖一个Web应用的核心技术点。对于学习者而言它的优势在于技术栈全面且主流SpringBoot后端API、Vue3前端SPA、MySQL数据存储、MyBatis-Plus数据操作这些都是当前企业开发中的热门技术组合写在简历上很有分量。业务逻辑清晰围绕“文章”的增删改查CRUD展开衍生出用户、分类、标签、评论等模块逻辑自洽易于理解和实现。前后端分离架构实践这是现代Web开发的标配。通过这个项目你能深刻体会前端如何通过Ajax调用后端RESTful API以及如何解决跨域、权限认证等关键问题。极高的可扩展性基础功能完成后你可以轻松地为其添加富文本编辑器、文章统计、全文检索、缓存优化等进阶功能让项目不断“生长”。很多人失败在第一步环境配置和项目启动。网上的源码包往往缺少关键的配置说明或者依赖版本冲突。本文将聚焦于“可运行”确保你跟着步骤走一定能看到登录界面和文章列表。2. 核心概念与项目架构解读在动手之前我们先花几分钟理解这个项目的骨架。这能帮你后续排查问题时知道该去哪里找。2.1 前后端分离Frontend-Backend Separation这是本项目的核心架构思想。简单说就是前端Vue3应用和后端SpringBoot应用是两个独立的工程分别开发、分别部署。前端负责页面渲染、用户交互。它通过HTTP请求使用Axios等库调用后端提供的API接口来获取或提交数据。它不直接操作数据库。后端负责业务逻辑、数据处理、数据库操作。它提供一系列标准的API接口如/api/article/list接收前端的请求处理后将数据以JSON格式返回。优势前后端可以并行开发技术选型更灵活更利于团队协作和后期维护。2.2 技术栈详解后端 (SpringBoot):SpringBoot: 快速构建Spring应用的框架省去了大量繁琐的XML配置。MyBatis-Plus: MyBatis的增强工具提供了通用的CRUD方法让你不用写简单的SQL极大提升开发效率。Spring Security 或 JWT: 用于用户认证和授权。本项目很可能采用基于Token如JWT的无状态认证。MySQL: 关系型数据库存储所有业务数据。前端 (Vue3):Vue 3: 当前主流的前端框架采用组合式API代码组织更灵活。Vite: 新一代前端构建工具启动和热更新速度极快。Element Plus 或 Ant Design Vue: UI组件库提供现成的按钮、表格、表单等组件快速搭建界面。Axios: 用于发送HTTP请求到后端API。Vue Router: 管理前端页面路由。Pinia: Vue 3 官方推荐的状态管理库用于管理跨组件共享的数据如用户登录状态。2.3 项目目录结构预览一个清晰的结构是成功的一半。典型的项目目录如下blog-backend/ (SpringBoot后端) ├── src/main/java/com/yourname/blog/ │ ├── controller/ # 控制器接收请求返回响应 │ ├── service/ # 业务逻辑层 │ ├── service/impl/ # 业务逻辑实现 │ ├── mapper/ # MyBatis-Plus 的 Mapper 接口 │ ├── entity/ # 实体类对应数据库表 │ └── config/ # 配置类如跨域配置、JWT配置 ├── src/main/resources/ │ ├── application.yml # 主配置文件数据库、端口等 │ └── mapper/ # XML映射文件如果使用 └── pom.xml # Maven依赖管理文件 blog-frontend/ (Vue3前端) ├── src/ │ ├── api/ # 封装所有对后端API的请求函数 │ ├── router/ # 路由配置 │ ├── stores/ # Pinia 状态管理 │ ├── views/ # 页面组件如HomeView, LoginView │ ├── components/ # 可复用的子组件 │ └── utils/ # 工具函数如请求拦截器 ├── public/ # 静态资源 └── package.json # 项目依赖和脚本理解了这个结构你就知道修改一个功能应该从哪里入手了。3. 环境准备确保你的电脑“装备齐全”这是最关键的一步环境不对一切白费。请严格按照以下清单检查。3.1 后端开发环境JDK: 版本1.8或11、17推荐。SpringBoot 3.x 需要 JDK 17但大多数教学项目基于 SpringBoot 2.x使用 JDK 8 或 11 更稳妥。检查命令java -versionMaven: 用于管理项目依赖和构建。版本 3.6 即可。检查命令mvn -vIDE:IntelliJ IDEA Ultimate 或 Community 版强烈推荐或者 Eclipse。IDEA 对 SpringBoot 支持更好。MySQL: 版本 5.7 或 8.0。安装并启动MySQL服务。你需要创建一个空的数据库例如blog_db。记住你的数据库连接信息主机localhost、端口3306、用户名、密码。3.2 前端开发环境Node.js: 版本 16 或 18推荐LTS版本。它自带了 npm 包管理工具。检查命令node -v和npm -vIDE:Visual Studio Code (VSCode)是前端开发的首选轻量且插件丰富。3.3 获取项目源码你可以从Gitee或GitHub搜索“SpringBoot Vue3 博客”找到许多开源项目。为了本文演示我们假设一个标准的项目结构。请确保你下载的源码包含完整的pom.xml和package.json文件。4. 后端项目配置与启动让我们先从后端开始让API服务先跑起来。4.1 导入项目到 IDEA打开 IntelliJ IDEA选择File-Open...找到并选择后端项目的根目录包含pom.xml的文件夹。IDEA 会自动识别为 Maven 项目并开始下载依赖。这个过程可能需要几分钟取决于你的网速。请耐心等待直到右下角的进度条消失。4.2 配置数据库连接找到src/main/resources/application.yml或application.properties文件这是SpringBoot的核心配置文件。# application.yml 示例 server: port: 8080 # 后端服务启动端口 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/blog_db?useUnicodetruecharacterEncodingutf-8serverTimezoneAsia/Shanghai username: root # 改为你的MySQL用户名 password: 123456 # 改为你的MySQL密码 # JPA 配置如果使用 jpa: hibernate: ddl-auto: update # 首次启动可设为update自动创建表。生产环境务必改为validate或none show-sql: true # 在控制台打印SQL便于调试 # MyBatis-Plus 配置 mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 打印SQL日志 global-config: db-config: logic-delete-field: deleted # 全局逻辑删除字段名如果项目有 logic-delete-value: 1 # 逻辑已删除值 logic-not-delete-value: 0 # 逻辑未删除值关键点将url、username、password修改为你本地MySQL的实际信息。ddl-auto: update很实用它会在应用启动时根据你的实体类Entity自动创建或更新数据库表结构。首次启动后建议改为validate仅校验表结构防止误操作导致数据丢失。4.3 解决依赖问题与启动如果 IDEA 提示依赖错误红色波浪线可以尝试右键点击项目 -Maven-Reload Project。在 IDEA 右侧的 Maven 工具栏点击刷新按钮。在终端中进入项目根目录执行mvn clean install -DskipTests。找到主启动类通常命名为XxxApplication.java例如BlogApplication.java其内部包含SpringBootApplication注解和main方法。右键点击这个类选择Run ‘BlogApplication‘。观察控制台日志。如果看到类似以下的输出说明启动成功Started BlogApplication in 5.632 seconds (JVM running for 6.215) Tomcat started on port(s): 8080 (http)5. 前端项目配置与启动后端服务在localhost:8080运行起来后我们再来启动前端。5.1 安装依赖用 VSCode 打开前端项目根目录。打开内置终端Terminal-New Terminal。在终端中执行以下命令安装项目所需的所有npm包npm install # 或使用淘宝镜像加速 # npm install --registryhttps://registry.npmmirror.com这个过程也会下载大量依赖请等待完成。5.2 配置API代理解决跨域问题在开发阶段前端运行在localhost:5173Vite默认端口后端在localhost:8080浏览器会因为“同源策略”阻止请求。我们通过Vite的代理功能来解决。 找到前端项目的vite.config.js或vite.config.ts文件// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue // https://vitejs.dev/config/ export default defineConfig({ plugins: [vue()], server: { port: 5173, // 前端开发服务器端口 proxy: { // 关键配置将所有以 /api 开头的请求代理到后端服务器 /api: { target: http://localhost:8080, // 你的后端地址 changeOrigin: true, // 通常不需要重写路径除非后端接口没有 /api 前缀 // rewrite: (path) path.replace(/^\/api/, ) } } } })这样前端代码中请求/api/article/list实际上会被转发到http://localhost:8080/api/article/list。5.3 启动前端开发服务器在VSCode终端中运行npm run dev如果成功你会看到类似输出VITE v4.4.9 ready in 320 ms ➜ Local: http://localhost:5173/ ➜ Network: use --host to expose现在打开浏览器访问http://localhost:5173你应该能看到博客系统的前端界面了6. 核心功能代码走读与二次开发指南项目跑起来了但如果你想把它变成自己的或者深入理解必须看懂关键代码。6.1 后端核心一个文章查询接口是如何工作的我们以“获取文章列表”这个最常用的功能为例。实体类 (Entity):Article.java定义了文章表的字段。// src/main/java/com/yourname/blog/entity/Article.java import com.baomidou.mybatisplus.annotation.*; import lombok.Data; import java.time.LocalDateTime; Data TableName(blog_article) // 对应数据库表名 public class Article { TableId(type IdType.AUTO) // 主键自增 private Long id; private String title; private String content; private Long categoryId; private String tags; private Integer viewCount; TableField(fill FieldFill.INSERT) // 插入时自动填充 private LocalDateTime createTime; TableField(fill FieldFill.INSERT_UPDATE) // 插入和更新时自动填充 private LocalDateTime updateTime; }Mapper 接口:ArticleMapper.java继承MyBatis-Plus的基类立刻拥有基础CRUD方法。// src/main/java/com/yourname/blog/mapper/ArticleMapper.java import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.yourname.blog.entity.Article; public interface ArticleMapper extends BaseMapperArticle { // 如果需要复杂查询可以在这里定义方法并在对应的XML中写SQL }Service 层:ArticleService.java和ArticleServiceImpl.java编写业务逻辑。// src/main/java/com/yourname/blog/service/ArticleService.java import com.baomidou.mybatisplus.extension.service.IService; import com.yourname.blog.entity.Article; import java.util.List; public interface ArticleService extends IServiceArticle { // 定义业务方法例如带条件分页查询 ListArticle getArticlesByCondition(String keyword, Long categoryId); } // src/main/java/com/yourname/blog/service/impl/ArticleServiceImpl.java import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl; import com.yourname.blog.entity.Article; import com.yourname.blog.mapper.ArticleMapper; import com.yourname.blog.service.ArticleService; import org.springframework.stereotype.Service; import java.util.List; Service public class ArticleServiceImpl extends ServiceImplArticleMapper, Article implements ArticleService { Override public ListArticle getArticlesByCondition(String keyword, Long categoryId) { LambdaQueryWrapperArticle wrapper new LambdaQueryWrapper(); if (keyword ! null !keyword.trim().isEmpty()) { wrapper.like(Article::getTitle, keyword); // 标题模糊查询 } if (categoryId ! null) { wrapper.eq(Article::getCategoryId, categoryId); // 分类精确查询 } wrapper.orderByDesc(Article::getCreateTime); // 按创建时间倒序 return this.list(wrapper); } }Controller 层:ArticleController.java接收HTTP请求调用Service返回JSON。// src/main/java/com/yourname/blog/controller/ArticleController.java import com.yourname.blog.common.Result; import com.yourname.blog.entity.Article; import com.yourname.blog.service.ArticleService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import java.util.List; RestController RequestMapping(/api/article) // 所有接口以 /api/article 开头 public class ArticleController { Autowired private ArticleService articleService; GetMapping(/list) public Result listArticles(RequestParam(required false) String keyword, RequestParam(required false) Long categoryId) { ListArticle articles articleService.getArticlesByCondition(keyword, categoryId); return Result.success(articles); // 统一封装返回结果 } PostMapping(/save) public Result saveArticle(RequestBody Article article) { // RequestBody 注解表示从请求体中接收JSON数据并转换为Article对象 boolean saved articleService.saveOrUpdate(article); return saved ? Result.success(保存成功) : Result.error(保存失败); } // 其他接口删除、详情查询等... }Result是一个自定义的通用返回类用于统一API响应格式。// src/main/java/com/yourname/blog/common/Result.java import lombok.Data; Data public class ResultT { private Integer code; // 状态码如 200成功500失败 private String msg; // 提示信息 private T data; // 返回的数据 public static T ResultT success(T data) { ResultT result new Result(); result.setCode(200); result.setMsg(操作成功); result.setData(data); return result; } public static T ResultT error(String msg) { ResultT result new Result(); result.setCode(500); result.setMsg(msg); return result; } }6.2 前端核心如何调用后端API并渲染数据在前端Vue3项目中我们通常在src/api/目录下封装请求。封装请求工具 (Axios)// src/utils/request.js import axios from axios; // 创建axios实例 const service axios.create({ baseURL: import.meta.env.VITE_APP_BASE_API, // 从环境变量读取基础URL开发环境通常是 /api timeout: 5000 // 请求超时时间 }); // 请求拦截器例如添加Token service.interceptors.request.use( config { const token localStorage.getItem(token); // 从本地存储获取token if (token) { config.headers[Authorization] Bearer ${token}; } return config; }, error { return Promise.reject(error); } ); // 响应拦截器例如统一处理错误 service.interceptors.response.use( response { const res response.data; if (res.code ! 200) { // 业务逻辑错误 console.error(请求错误:, res.msg); return Promise.reject(new Error(res.msg || Error)); } else { return res; // 直接返回后端Result对象中的data } }, error { // HTTP状态码错误 console.error(网络错误:, error); return Promise.reject(error); } ); export default service;定义文章相关的API函数// src/api/article.js import request from /utils/request; // 获取文章列表 export function getArticleList(params) { return request({ url: /api/article/list, method: get, params // 对应 RequestParam }); } // 新增或更新文章 export function saveArticle(data) { return request({ url: /api/article/save, method: post, data // 对应 RequestBody }); } // 删除文章 export function deleteArticle(id) { return request({ url: /api/article/delete/${id}, method: delete }); }在Vue组件中使用!-- src/views/ArticleListView.vue -- template div el-table :dataarticleList stylewidth: 100% el-table-column proptitle label标题/el-table-column el-table-column propcategoryName label分类/el-table-column el-table-column propcreateTime label创建时间/el-table-column el-table-column label操作 template #defaultscope el-button sizesmall clickhandleEdit(scope.row)编辑/el-button el-button sizesmall typedanger clickhandleDelete(scope.row.id)删除/el-button /template /el-table-column /el-table /div /template script setup import { ref, onMounted } from vue; import { getArticleList, deleteArticle } from /api/article; import { ElMessage, ElMessageBox } from element-plus; const articleList ref([]); // 加载文章列表 const loadData async () { try { const res await getArticleList({}); // 传递查询参数 articleList.value res.data; // res.data 对应后端 Result 里的 data 字段 } catch (error) { ElMessage.error(获取文章列表失败); } }; // 删除文章 const handleDelete (id) { ElMessageBox.confirm(确定删除这篇文章吗, 提示, { confirmButtonText: 确定, cancelButtonText: 取消, type: warning }).then(async () { await deleteArticle(id); ElMessage.success(删除成功); loadData(); // 刷新列表 }).catch(() {}); }; onMounted(() { loadData(); }); /script通过以上代码一个完整的前后端数据流就清晰了前端组件触发 - 调用API函数 - Axios发送请求 - 后端Controller接收 - Service处理业务 - Mapper操作数据库 - 原路返回数据 - 前端渲染。7. 数据库初始化与数据验证项目启动后数据库可能是空的。你需要初始化表结构和基础数据。7.1 使用SQL脚本初始化推荐在项目资源文件夹src/main/resources或源码包中通常会有sql/目录里面存放了blog_schema.sql建表语句和blog_data.sql初始数据如管理员账号。打开你的MySQL客户端如命令行、Navicat、MySQL Workbench。执行blog_schema.sql创建所有表。执行blog_data.sql插入初始数据如默认管理员用户admin/123456。7.2 验证数据与接口验证数据库登录MySQL查看blog_db数据库中是否生成了blog_article,blog_user,blog_category等表。验证后端API启动后端后打开浏览器或使用 Postman/ApiFox 等工具访问http://localhost:8080/api/article/list。你应该能收到一个JSON格式的响应可能是空数组或者初始化的文章数据。验证前端登录访问http://localhost:5173尝试使用初始化的管理员账号登录。登录成功后应能跳转到后台管理页面。8. 常见问题与排查思路必看这是你能否成功运行项目的关键。90%的问题都出在这里。问题现象可能原因排查方式解决方案后端启动失败端口冲突8080端口被其他程序占用控制台日志会明确报错Port 8080 was already in use1. 在application.yml中修改server.port为其他端口如 8081。2. 在命令行执行netstat -ano | findstr :8080找到占用进程并结束。后端启动失败数据库连接错误1. MySQL服务未启动。2. 数据库连接信息URL、用户名、密码错误。3. 数据库blog_db不存在。查看控制台日志通常会有Communications link failure或Access denied等错误信息。1. 确保MySQL服务已启动。2. 仔细检查application.yml中的配置。3. 登录MySQL执行CREATE DATABASE blog_db;创建数据库。前端npm install失败1. 网络问题。2. Node.js 版本不兼容。3. 项目依赖包有冲突。观察错误信息常见有ETIMEDOUT网络超时或peer dependencies冲突。1. 使用淘宝镜像npm config set registry https://registry.npmmirror.com再重试。2. 检查package.json中要求的Node版本。3. 删除node_modules文件夹和package-lock.json文件重新执行npm install。前端能访问但列表为空/接口报4041. 后端服务未启动。2. 前端代理配置错误。3. 后端接口路径与前端的请求路径不匹配。1. 确认后端控制台是否运行正常。2. 打开浏览器开发者工具F12的“网络(Network)”标签查看请求的URL是否正确代理到了localhost:8080。3. 直接访问http://localhost:8080/api/article/list看后端是否正常响应。1. 确保后端已启动。2. 检查vite.config.js中的proxy配置target必须是正确的后端地址。3. 核对前端API函数中的url和后端Controller的RequestMapping是否一致。前端报跨域 (CORS) 错误后端没有配置允许前端源进行跨域访问。浏览器控制台报错包含CORS policy字样。在后端添加一个全局跨域配置类登录失败提示“用户名或密码错误”1. 数据库中没有对应的用户数据。2. 密码加密方式不匹配。1. 检查数据库blog_user表是否有数据。2. 查看后端登录逻辑的密码比对代码通常是BCrypt加密。1. 运行提供的SQL初始化脚本或手动插入一个测试用户注意密码需要是加密后的字符串。2. 如果是自己注册确保后端注册逻辑正确加密了密码。页面样式错乱Element Plus 等UI库未正确引入或版本冲突。检查浏览器控制台是否有关于CSS或组件未找到的警告。1. 确认main.js或main.ts中正确引入了UI库及其CSS。2. 检查package.json中UI库的版本是否与项目兼容。后端跨域配置示例// src/main/java/com/yourname/blog/config/CorsConfig.java import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.cors.CorsConfiguration; import org.springframework.web.cors.UrlBasedCorsConfigurationSource; import org.springframework.web.filter.CorsFilter; Configuration public class CorsConfig { Bean public CorsFilter corsFilter() { CorsConfiguration config new CorsConfiguration(); config.addAllowedOrigin(http://localhost:5173); // 允许前端地址 config.addAllowedHeader(*); // 允许任何头 config.addAllowedMethod(*); // 允许任何方法POST, GET等 config.setAllowCredentials(true); // 允许发送Cookie UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration(/**, config); // 对所有接口生效 return new CorsFilter(source); } }9. 项目优化与进阶开发建议当项目能稳定运行后你可以考虑以下优化这会让你的项目在简历中更加出彩。9.1 代码层面统一响应封装确保所有Controller都返回Result对象便于前端统一处理。全局异常处理使用ControllerAdvice或RestControllerAdvice创建一个全局异常处理器捕获并处理RuntimeException、SQLException等返回友好的错误信息而不是一堆栈轨迹。参数校验在Controller的方法参数或实体类字段上使用Validated和NotBlank、Size等注解进行数据校验。日志记录使用SLF4J Logback在关键业务节点如登录、增删改记录操作日志。9.2 功能层面文章详情页实现一个面向公众的博客首页和文章详情页。文章分类与标签完善分类和标签的管理支持多对多关系。文章搜索集成Elasticsearch实现全文检索或使用MySQL的LIKE进行简单搜索。评论与回复实现嵌套评论功能。文件上传支持文章封面图片上传可使用本地存储或OSS如阿里云OSS、七牛云。权限细化基于Spring Security实现更细粒度的角色权限控制如管理员、编辑、普通用户。9.3 部署层面前端打包运行npm run build将Vue项目打包成静态文件在dist目录。后端打包使用mvn clean package生成可执行的JAR包。部署方式传统部署将前端dist目录下的文件放入后端src/main/resources/static/目录然后打包成一个JAR使用java -jar blog.jar运行。前后端分离部署前端使用Nginx托管静态文件并配置反向代理到后端API后端JAR包在服务器上运行。这是生产环境的标准做法。容器化部署为前后端分别编写Dockerfile使用Docker Compose一键部署更利于运维。通过这个SpringBootVue3博客管理系统的实践你不仅得到了一个可运行、可展示的项目更重要的是走通了一个现代JavaWeb应用从环境搭建、编码、联调到部署的完整流程。理解这个流程远比死记硬背面试题更有价值。接下来你可以尝试修改UI、增加新功能或者将其作为模板快速开发其他管理系统。