30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度1. 这个项目到底能帮你解决什么问题如果你正在找一个能串联起 SpringBoot3、Vue3 和 TypeScript 这三个主流技术的全栈实战项目这个图书管理系统就是一个非常典型的“练手简历”型案例。它不是一个简单的增删改查CRUD演示而是覆盖了从数据库设计、后端 API 开发、前端组件化到前后端数据交互的完整链路。对于想从零构建一个可运行、有业务逻辑的 Web 应用的中级开发者或者想系统学习前后端分离架构的初学者这个项目的价值在于提供了一个清晰的、可复现的工程化模板。最核心的价值是技术栈的整合与落地。很多教程会单独讲 SpringBoot 或 Vue3但如何让它们协同工作如何处理跨域、状态管理、接口联调、错误处理这些实战中的细节才是难点。这个项目把这些问题都暴露了出来并给出了一个可行的解决方案。你不用再纠结于“学完了理论下一步该做什么”直接 clone 代码按照 README 跑起来就能看到一个全栈应用是如何运转的。2. 环境准备跑通它需要哪些前置条件在动手之前先确认你的本地开发环境是否满足要求。这不是一个轻量级的 Demo它依赖一整套工具链。2.1 硬件与操作系统要求这个项目对硬件要求不高普通开发机即可。但需要确保有足够的磁盘空间来安装依赖Node.js 和 Maven 的依赖包体积不小。操作系统方面Windows、macOS 或 Linux 均可但后续的命令行操作会以通用命令为主Windows 用户可能需要稍作调整例如路径分隔符。2.2 软件环境清单以下是必须安装的软件及其建议版本。版本不一定要完全一致但大版本最好对齐以避免一些已知的兼容性问题。软件建议版本作用验证安装成功的命令Java JDK17 或 21运行 SpringBoot 后端java -versionNode.js18.x 或 20.x (LTS)运行 Vue 前端和包管理node -v和npm -vMySQL8.0项目数据库mysql --versionMaven3.8管理 Java 项目依赖和构建mvn -vGit最新版克隆项目代码git --versionIDE/编辑器IntelliJ IDEA / VS Code分别用于后端和前端开发-注意不要一上来就追求最新版本。特别是 Node.js某些最新版本可能与项目中的一些依赖如某些 Webpack 插件存在兼容性问题。使用长期支持版LTS是最稳妥的选择。2.3 数据库初始化这是最容易出错的一步。项目通常会在根目录或library-behind后端目录下提供一个library.sql文件。登录 MySQL打开终端或命令行使用 root 用户或你有权限的用户登录。mysql -u root -p创建数据库执行以下命令创建一个名为library的数据库名称以项目中的配置为准。CREATE DATABASE IF NOT EXISTS library CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE library;导入表结构找到项目中的library.sql文件在 MySQL 命令行中执行。SOURCE /你的项目路径/library.sql;Windows 用户注意路径格式例如SOURCE D:\projects\library-manage\library.sql;关键检查点导入成功后使用SHOW TABLES;命令应该能看到book,reader,lend_return等表。这一步没做好后端启动一定会报数据库连接或表不存在的错误。3. 后端启动与配置让 SpringBoot 先跑起来后端是整个系统的数据引擎先确保它能独立运行再去看前端。3.1 项目结构与依赖导入用 IDEA 或 Eclipse 打开library-behind目录。这是一个标准的 Maven 项目。核心结构如下library-behind ├── src │ ├── main │ │ ├── java │ │ │ └── com.xxx.library // 包路径里面是Controller, Service, Mapper等 │ │ └── resources │ │ ├── application.yml // 或 application.properties 核心配置文件 │ │ └── mapper // MyBatis的XML映射文件 │ └── test └── pom.xml // Maven依赖定义文件第一次打开IDE 会自动识别为 Maven 项目并开始下载依赖根据pom.xml。这个过程可能会比较慢取决于网络。观察 IDEA 右下角的进度条等待其完成。常见问题如果依赖下载失败通常是网络问题或 Maven 仓库地址不对。可以检查pom.xml中是否使用了需要特殊网络环境的仓库。尝试配置 Maven 使用阿里云镜像在settings.xml中配置。直接删除本地 Maven 仓库默认在~/.m2/repository中对应的依赖文件夹让 IDE 重新下载。3.2 核心配置文件修改找到src/main/resources/application.yml或.properties。你需要修改数据库连接信息使其指向你刚创建的数据库。spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/library?useUnicodetruecharacterEncodingutf-8useSSLfalseserverTimezoneAsia/Shanghai username: root # 改为你的MySQL用户名 password: yourpassword # 改为你的MySQL密码重要参数解释serverTimezoneAsia/Shanghai解决数据库时区问题避免插入时间时出现时差。useSSLfalse本地开发通常关闭 SSL 连接。生产环境必须设为true并配置证书。com.mysql.cj.jdbc.DriverMySQL 8.0 的驱动类名。3.3 启动与验证找到包含SpringBootApplication注解的主类通常叫LibraryApplication或Application直接运行它。成功标志控制台打印出 SpringBoot 的 Banner并最终看到类似Tomcat started on port(s): 8080 (http)的日志且没有持续的错误堆栈信息。验证接口打开浏览器或使用 Postman访问http://localhost:8080/api/books具体路径需查看项目中的 Controller 定义。如果返回 JSON 格式的数据哪怕是空数组[]或标准的错误信息如404说明后端服务已经正常启动并能处理 HTTP 请求了。如果返回的是Whitelabel Error Page可能是该接口路径不存在可以尝试访问一个已知存在的接口比如项目的健康检查端点http://localhost:8080/actuator/health如果引入了相关依赖。4. 前端启动与联调让 Vue3 界面动起来后端跑通后前端就是视图层负责展示和交互。4.1 安装依赖与启动用 VS Code 或 WebStorm 打开library-front目录。安装依赖在终端中进入该目录执行npm install或cnpm install如果你使用了淘宝镜像。这个命令会根据package.json文件下载所有前端依赖Vue3, ElementPlus, Axios, Pinia, ECharts等。注意如果网络不好npm install可能会超时或失败。可以尝试使用cnpm或配置 npm 镜像源npm config set registry https://registry.npmmirror.com启动开发服务器依赖安装成功后执行npm run dev或npm run serve具体命令看package.json中的scripts。成功标志终端会输出本地访问地址通常是http://localhost:5173或http://localhost:3000。用浏览器打开这个地址应该能看到登录页或管理系统的首页。4.2 前后端对接关键代理与跨域在开发环境下前端运行在localhost:5173后端运行在localhost:8080浏览器出于安全限制会阻止这种跨域请求。项目通常通过两种方式解决Vite 代理配置查看library-front/vite.config.ts文件。export default defineConfig({ // ... 其他配置 server: { proxy: { /api: { // 将所有以 /api 开头的请求转发到后端 target: http://localhost:8080, changeOrigin: true, // rewrite: (path) path.replace(/^\/api/, ) // 如果需要重写路径 } } } })这样前端代码中请求/api/books实际上会被 Vite 开发服务器转发到http://localhost:8080/api/books完美解决跨域。Axios 实例配置查看src/utils/request.ts或类似文件这里会创建一个配置好的 Axios 实例统一设置基础 URL、请求超时、请求/响应拦截器用于处理 token 等。const service axios.create({ baseURL: /api, // 基础路径配合代理使用 timeout: 10000 });联调验证启动前端后打开浏览器开发者工具F12的Network标签页。在前端页面进行任何操作如点击查询图书观察发出的网络请求。请求的 URL 应该是http://localhost:5173/api/...但响应数据应该来自后端。如果请求失败如 404 或 500需要根据错误信息分别排查前端代理配置或后端接口问题。5. 核心功能模块拆解与代码走读仅仅跑起来还不够理解代码结构才能举一反三。我们挑几个核心模块看看。5.1 后端三层架构以“借书”为例借书不是一个简单的插入操作它涉及多个表的联动和状态变更这正是业务逻辑的体现。Controller 层 (BookController.java或LendController.java)RestController RequestMapping(/api/lend) public class LendController { Autowired private LendService lendService; PostMapping public Result lendBook(RequestBody LendDTO lendDTO) { // 接收前端传来的借书数据 return lendService.lendBook(lendDTO); } }作用定义 API 端点 (/api/lend)接收前端 JSON 数据 (RequestBody)调用 Service 层处理并返回统一格式的结果 (Result)。注意RestController表明这个类返回的是 JSON 数据不是视图。Service 层 (LendServiceImpl.java)Service public class LendServiceImpl implements LendService { Autowired private BookMapper bookMapper; Autowired private ReaderMapper readerMapper; Autowired private LendReturnMapper lendReturnMapper; Override Transactional // 关键声明事务 public Result lendBook(LendDTO lendDTO) { // 1. 校验读者是否存在、是否可借未超限 Reader reader readerMapper.selectById(lendDTO.getReaderId()); if (reader null) { throw new BusinessException(读者不存在); } // 2. 校验图书是否存在、是否可借状态为在馆 Book book bookMapper.selectById(lendDTO.getBookId()); if (book null || !在馆.equals(book.getStatus())) { throw new BusinessException(图书不可借); } // 3. 插入借阅记录 LendReturn record new LendReturn(); // ... 设置属性 lendReturnMapper.insert(record); // 4. 更新图书状态为“出借中” book.setStatus(出借中); bookMapper.updateById(book); // 5. 更新读者已借数量如果需要 // ... return Result.success(借书成功); } }作用承载核心业务逻辑。这里是“借书”这个用例的核心。关键点Transactional确保“插入记录”和“更新图书状态”这两个数据库操作在一个事务里要么都成功要么都失败防止数据不一致例如记录了借书但书的状态没改。业务校验在操作数据库前进行校验这是保证数据完整性的关键。异常处理抛出自定义的BusinessException会被全局异常处理器捕获并返回给前端友好的错误信息。Mapper 层 (LendReturnMapper.java及LendReturnMapper.xml)LendReturnMapper.java(接口):Mapper public interface LendReturnMapper extends BaseMapperLendReturn { // 可以使用MyBatis-Plus提供的通用方法如insert, selectById // 复杂查询可以在这里定义方法并在XML中实现 ListLendReturnVO selectLendList(Param(query) LendQuery query); }LendReturnMapper.xml:select idselectLendList resultTypecom.xxx.library.pojo.vo.LendReturnVO SELECT lr.*, r.name as reader_name, b.name as book_name FROM lend_return lr LEFT JOIN reader r ON lr.reader_id r.id LEFT JOIN book b ON lr.book_id b.id where if testquery.readerName ! null and query.readerName ! AND r.name LIKE CONCAT(%, #{query.readerName}, %) /if !-- 更多动态查询条件 -- /where ORDER BY lr.lend_date DESC /select作用负责与数据库直接交互。简单 CRUD 用 MyBatis-Plus 的通用方法复杂联表查询在 XML 中写原生 SQL。5.2 前端组件与状态管理以“图书列表”为例前端使用 Vue3 的script setup语法和 Composition API配合 Pinia 进行状态管理。页面组件 (BookList.vue)template div el-table :databookList border !-- 列定义 -- /el-table el-pagination current-changehandlePageChange :current-pagequeryParams.pageNum :page-sizequeryParams.pageSize :totaltotal layouttotal, prev, pager, next /el-pagination /div /template script setup langts import { ref, onMounted } from vue; import { getBookList } from /api/book; // 导入API函数 import type { BookQuery, BookVO } from /types/book; // 响应式数据 const bookList refBookVO[]([]); const total ref(0); const queryParams refBookQuery({ pageNum: 1, pageSize: 10, name: , author: }); // 方法获取数据 const fetchData async () { const res await getBookList(queryParams.value); bookList.value res.data.list; total.value res.data.total; }; // 生命周期钩子组件挂载时加载数据 onMounted(() { fetchData(); }); // 方法处理分页 const handlePageChange (pageNum: number) { queryParams.value.pageNum pageNum; fetchData(); }; /script作用视图渲染和用户交互。通过调用 API 函数获取数据并绑定到模板。关键点ref定义响应式数据。onMounted生命周期钩子用于初始数据加载。使用async/await处理异步请求。API 层 (src/api/book.ts)import request from /utils/request; import type { BookQuery, BookVO, Result } from /types; export function getBookList(params: BookQuery): PromiseResultPageResultBookVO { return request({ url: /book/list, method: get, params // GET请求参数 }); }作用封装所有与“图书”相关的后端接口调用。使组件逻辑更清晰接口地址变更只需修改此处。状态管理 (Pinia StoreuseBookStore.ts) 对于跨多个组件共享的数据如用户登录信息、全局配置可以使用 Pinia。import { defineStore } from pinia; import { ref } from vue; export const useBookStore defineStore(book, () { // 状态 const currentBook refBookVO | null(null); // 动作 const setCurrentBook (book: BookVO) { currentBook.value book; }; return { currentBook, setCurrentBook }; });作用集中管理跨组件的状态。在需要访问或修改currentBook的组件中导入并使用这个 store。6. 从学习到生产你需要关注的优化与扩展点把这个项目跑起来只是第一步。如果你想把它当作一个更严肃的项目或者为简历增加亮点可以考虑以下方向进行深化。6.1 后端优化接口文档集成 Swagger 或 Knife4j自动生成 API 文档。这对于前后端协作和后续维护至关重要。统一响应与异常处理项目可能已经有了基础的Result类。可以进一步细化定义不同的业务异常码和全局异常处理器 (ControllerAdvice)让错误处理更规范。数据校验在 Controller 方法的参数上使用Validated注解并结合NotBlank,Size等注解进行入参校验避免无效数据进入 Service 层。权限控制引入 Spring Security 或 Sa-Token实现基于角色的访问控制RBAC。例如普通管理员和超级管理员应有不同的操作权限。缓存对不常变动的数据如图书分类、读者分类使用 Redis 或 Caffeine 进行缓存减轻数据库压力。日志规范日志输出使用 SLF4J Logback区分INFO,WARN,ERROR级别并合理记录操作日志便于问题追踪。6.2 前端优化路由权限使用 Vue Router 的导航守卫根据用户角色动态加载路由实现页面级权限控制。组件封装将通用的表格、表单、搜索框等封装成高可复用的业务组件。TypeScript 强化定义更严格的接口类型减少any的使用充分利用 TS 的类型检查和智能提示。性能对于大型表格或列表考虑使用虚拟滚动。对图片等资源进行懒加载。构建优化分析package.json中的依赖移除未使用的库。配置 Vite 的打包策略进行代码分割。6.3 部署上线学习项目最终要走向部署。最简单的部署方式后端使用mvn clean package打包生成jar文件。在服务器上安装好 Java 和 MySQL运行java -jar your-app.jar --spring.profiles.activeprodprod配置文件需提前配置好生产环境的数据库等。前端运行npm run build生成静态文件在dist目录。将这些文件放到 Nginx 或 Apache 的 Web 目录下。同时在 Nginx 配置中设置反向代理将/api路径的请求转发到后端服务。数据库确保生产环境的 MySQL 用户、密码、权限配置正确并进行必要的数据备份和迁移。7. 常见问题排查清单在运行和开发过程中你大概率会遇到以下问题。按这个顺序排查能节省大量时间。后端启动失败端口被占用现象Web server failed to start. Port 8080 was already in use.解决更改application.yml中的server.port或找出占用 8080 端口的进程并结束它lsof -i:8080或netstat -ano | findstr :8080。数据库连接失败现象Communications link failure或Access denied for user...排查检查application.yml中的url,username,password是否正确。确认 MySQL 服务是否已启动。确认数据库library和表是否已成功创建。检查 MySQL 用户是否有远程连接权限如果后端和数据库不在同一台机器。前端启动失败依赖安装报错现象npm install时报ERR!或npm run dev时报Cannot find module...解决删除node_modules文件夹和package-lock.json文件重新npm install。检查 Node.js 版本是否符合要求。使用cnpm或配置 npm 镜像源。前端页面能打开但数据不显示控制台报跨域错误现象浏览器控制台 Network 标签下请求状态为CORS error或404。排查确认后端服务 (localhost:8080) 是否真的在运行。检查前端vite.config.ts中的proxy配置target地址是否正确。检查前端 API 请求函数 (src/api/下的文件) 中请求的 URL 路径是否与后端 Controller 定义的RequestMapping路径匹配。页面操作如新增、删除后列表数据没刷新现象操作成功提示有了但页面数据还是旧的。解决在前端执行完新增/删除操作的成功回调里重新调用一次获取列表数据的函数 (fetchData)。分页查询不正常现象点击第二页没反应或数据重复。排查检查前端传给后端的参数名是否正确通常是pageNum(当前页) 和pageSize(每页条数)。检查后端 MyBatis 分页插件如 PageHelper是否正确配置和启用。检查后端 SQL 中是否正确使用了LIMIT语句。这个项目就像一份完整的“地图”它标出了从技术选型到功能实现的主要路径。你的任务不是死记硬背每一行代码而是理解每个模块为什么这样设计数据是如何流动的以及当某个环节出错时应该沿着哪条线索去排查。把这些弄明白了你收获的将不仅仅是一个图书管理系统而是一套应对大多数前后端分离 Web 项目的通用方法和解决思路。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度