如果你是一名Java开发者正在寻找一个能快速上手、功能全面且能帮你深入理解Spring Boot、MyBatis-Plus、Vue3等主流技术栈整合的实战项目那么你很可能已经厌倦了千篇一律的“增删改查”Demo。今天要聊的《斩妖录》正是这样一个项目。它不是一个简单的CRUD模板而是一个以“妖怪管理”为背景完整覆盖前后端分离开发全流程的实战案例。它的核心价值在于通过一个有趣且结构清晰的主题将权限管理、数据可视化、文件上传、工作流引擎等企业级开发中常见的“硬骨头”模块进行了系统性的串联和实现。很多人学习框架时总感觉知识点是散的Spring Security的配置看懂了但不知道怎么和业务角色结合ECharts图表会用了但数据从哪来、怎么动态更新不清楚MyBatis-Plus的Lambda查询很强大但复杂的多表关联和分页怎么优雅处理《斩妖录》项目正是为了解决这种“知识孤岛”问题。它把技术栈变成了解决具体业务问题的工具让你能看到从数据库设计、接口定义、权限控制到前端渲染的完整闭环。本文将带你深入拆解《斩妖录》项目。我们不会停留在“这个项目用了什么技术”的表面介绍而是聚焦于它如何用“妖怪管理”这个业务模型具象化地演绎了RBAC权限、数据报表等抽象概念。从零开始的环境搭建到核心模块的代码实现提供可复现的实操路径。剖析那些在官方文档里不会细讲但在实际开发中一定会遇到的“坑”和最佳实践。无论你是想找一个高质量的项目丰富简历还是希望深化对现代Java Web开发体系的理解这篇文章都将提供一条清晰的路径。1. 项目核心定位不止于技术栈演示在开始看代码之前我们必须先理解《斩妖录》项目的真正定位。它不是一个追求技术炫技的“玩具”而是一个面向教学与原型开发的“企业级应用微缩模型”。它解决了什么痛点对于中级开发者而言最大的瓶颈往往不是学习单个技术点而是缺乏将多个技术点有机组合构建一个完整、健壮应用系统的经验。《斩妖录》通过“妖怪信息管理系统”这个业务场景将以下核心诉求串联起来权限控制不同的用户如“管理员”、“捉妖师”、“游客”能看到和操作的数据范围完全不同。数据管理妖怪信息包含文本、数值、状态、甚至图片需要完整的CRUD、复杂查询和分页展示。数据可视化需要直观地展示妖怪的分布、战力统计、捉拿趋势等。业务流程一个妖怪从“发现”到“登记”再到“处置完成”可能涉及状态流转和审核。文件处理上传妖怪的画像或相关证据文件。技术选型的考量项目采用了经典且稳定的“Spring Boot Vue3”前后端分离架构。这个组合的成熟度极高社区资源丰富是大多数企业项目的起点。后端Spring Boot 2.x 作为基石集成 MyBatis-Plus 极大提升数据库操作效率Spring Security 或 Sa-Token 负责权限认证Hutool 等工具库处理通用任务。前端Vue 3 Element Plus 构建管理后台界面Axios 处理HTTP请求ECharts 实现图表。这套组合能快速搭建出美观且交互良好的中后台系统。数据库通常选用 MySQL表结构设计会体现业务关系。这个项目的价值在于它用具体的代码告诉你这些技术栈在真实的业务上下文里应该如何协作而不仅仅是独立的API调用示例。2. 环境准备与项目初始化在开始编码之前确保你的开发环境就绪。这是后续一切操作的基础。2.1 基础环境清单你需要准备以下软件并建议使用指定或更高版本以保证兼容性JDK: 版本 8 或 11 (推荐11长期支持版)。安装后配置好JAVA_HOME环境变量。Maven: 版本 3.6。用于管理后端项目的依赖和构建。Node.js: 版本 16 (推荐18 LTS)。附带 npm 包管理器用于前端项目。IDE:后端IntelliJ IDEA (社区版或旗舰版) 或 Eclipse with STS。前端Visual Studio Code并安装 Vue 官方插件 (Volar)。数据库: MySQL 5.7 或 8.0。确保服务已启动并记住 root 密码或已创建有权限的专用用户。Git: 用于克隆项目代码。2.2 获取项目代码假设项目托管在 GitHub 或 Gitee 上使用 Git 克隆到本地。# 示例命令实际仓库地址需替换 git clone https://github.com/username/zhan-yao-lu.git cd zhan-yao-lu项目结构通常如下zhan-yao-lu/ ├── backend/ # Spring Boot 后端项目 ├── frontend/ # Vue 3 前端项目 ├── sql/ # 数据库初始化脚本 └── README.md # 项目说明文档2.3 数据库初始化使用 MySQL 客户端如命令行、Navicat、DBeaver连接你的数据库服务。创建一个新的数据库例如zhan_yao_lu。CREATE DATABASE IF NOT EXISTS zhan_yao_lu DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;执行项目sql/目录下的初始化脚本通常是init.sql或按版本号命名。这个脚本会创建所有必要的表并插入初始数据如管理员账号、基础字典数据。# 假设在sql文件所在目录 mysql -u root -p zhan_yao_lu init.sql3. 后端项目启动与核心配置详解进入backend目录让我们看看一个典型的 Spring Boot 项目是如何配置的。3.1 关键依赖分析 (pom.xml)打开pom.xml你会看到项目依赖的核心组件dependencies !-- Spring Boot 核心启动器 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId !-- 或 sa-token-spring-boot-starter -- /dependency !-- 数据访问层 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3/version !-- 注意版本 -- /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency !-- 工具类 -- dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version5.8.20/version /dependency !-- 其他常用JWT、Redis、Swagger等 -- !-- dependency ... /dependency -- /dependencies关键点注意mybatis-plus和hutool的版本不同版本 API 可能有细微差别。如果启动时出现ClassNotFoundException或NoSuchMethodError首先检查依赖版本冲突。3.2 核心配置文件 (application.yml)Spring Boot 的配置集中在src/main/resources/application.yml中。这是连接数据库、设置服务器端口、配置安全规则的地方。server: port: 8080 servlet: context-path: /api # API统一前缀 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/zhan_yao_lu?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root # 强烈建议在生产环境使用非root用户 password: your_password_here # 替换为你的数据库密码 # 文件上传配置 servlet: multipart: max-file-size: 10MB max-request-size: 100MB # 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 # 逻辑未删除值 # 自定义应用配置 zyl: file: upload-dir: /tmp/zyl-uploads/ # 文件上传目录根据系统调整 jwt: secret: your-jwt-secret-key-change-in-production # JWT密钥必须修改 expire: 7200 # 过期时间(秒)配置要点数据库连接确保url、username、password与你的本地环境一致。serverTimezone设置很重要避免时间错误。SQL日志log-impl配置在开发阶段非常有用可以查看MyBatis-Plus生成的SQL便于调试。生产环境务必关闭。逻辑删除logic-delete-field是MyBatis-Plus提供的优雅删除方案执行删除操作时实际是更新deleted字段而非物理删除数据。JWT密钥zyl.jwt.secret是安全核心绝对不能使用示例中的值必须用一个足够复杂且保密的字符串替换。3.3 启动后端服务在IDE中直接运行BackendApplication类的main方法或在项目根目录下使用Maven命令cd backend mvn spring-boot:run看到控制台输出类似Started BackendApplication in 5.123 seconds (JVM running for 5.789)的信息且没有报错说明后端启动成功。默认API地址为http://localhost:8080/api。4. 前端项目启动与结构解析切换到frontend目录这是一个标准的 Vue 3 Vite Element Plus 项目。4.1 安装依赖并启动cd frontend npm install # 或使用 yarn/pnpm npm run dev命令执行成功后终端会提示本地开发服务器地址通常是http://localhost:5173。用浏览器打开即可看到登录界面。4.2 前端项目结构概览理解前端结构有助于你快速定位代码frontend/ ├── public/ # 静态资源 ├── src/ │ ├── api/ # 所有与后端交互的接口函数使用axios封装 │ ├── assets/ # 图片、字体等资源 │ ├── components/ # 可复用的Vue组件 │ ├── layout/ # 布局组件如侧边栏、顶部导航 │ ├── router/ # Vue Router路由配置 │ ├── store/ # Pinia状态管理或Vuex │ ├── utils/ # 工具函数请求封装、日期格式化等 │ ├── views/ # 页面视图组件妖怪列表、新增、图表页等 │ ├── App.vue # 根组件 │ └── main.js # 应用入口文件 ├── .env.development # 开发环境配置如后端API基础URL ├── vite.config.js # Vite构建配置 └── package.json # 项目依赖和脚本4.3 关键配置连接后端API前端需要知道后端服务的地址。这通常在.env.development文件中配置# .env.development VITE_APP_BASE_API http://localhost:8080/api在src/utils/request.js(或类似文件) 中会使用这个环境变量来创建Axios实例import axios from axios; import { ElMessage } from element-plus; // 创建axios实例 const service axios.create({ baseURL: import.meta.env.VITE_APP_BASE_API, // 读取环境变量 timeout: 10000 // 请求超时时间 }); // 请求拦截器通常用于添加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; // 假设后端统一返回格式为 { code: 200, data: ..., message: success } if (res.code ! 200) { ElMessage.error(res.message || Error); return Promise.reject(new Error(res.message || Error)); } return res.data; // 直接返回业务数据 }, error { ElMessage.error(error.message || Request Failed); return Promise.reject(error); } ); export default service;这个拦截器模式是前后端分离项目的核心它统一处理了认证添加Token、错误提示和数据结构让业务组件可以更专注于UI和逻辑而不必每次请求都写重复的代码。5. 核心业务模块代码拆解现在我们进入最核心的部分看看《斩妖录》是如何用代码实现具体业务的。我们以“妖怪管理”模块为例。5.1 后端实体、Mapper、Service与Controller遵循经典的四层架构Entity-Mapper-Service-Controller。1. 实体类 (Monster.java)// 文件路径backend/src/main/java/com/zyl/entity/Monster.java package com.zyl.entity; import com.baomidou.mybatisplus.annotation.*; import lombok.Data; import java.time.LocalDateTime; Data TableName(t_monster) // 指定对应数据库表名 public class Monster { TableId(type IdType.AUTO) // 主键自增 private Long id; private String name; // 妖怪名称 private String type; // 妖怪类型如水怪、山精 private Integer dangerLevel; // 危险等级 (1-5) private String location; // 出没地点 private String description; // 描述 private String status; // 状态 (如未收服、已收服、在逃) TableField(fill FieldFill.INSERT) // 插入时自动填充 private LocalDateTime createTime; TableField(fill FieldFill.INSERT_UPDATE) // 插入和更新时自动填充 private LocalDateTime updateTime; TableLogic // 标记为逻辑删除字段 private Integer deleted; }注解解析TableField(fill ...)需要配合 MyBatis-Plus 的MetaObjectHandler实现类自动填充时间。TableLogic使删除操作变为逻辑删除。2. Mapper 接口 (MonsterMapper.java)// 文件路径backend/src/main/java/com/zyl/mapper/MonsterMapper.java package com.zyl.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.zyl.entity.Monster; import org.apache.ibatis.annotations.Mapper; Mapper // 或是在启动类上用 MapperScan 批量扫描 public interface MonsterMapper extends BaseMapperMonster { // 继承 BaseMapper 即拥有了基本的 CRUD 方法 // 复杂查询可以通过 XML 或注解方式在此定义 }继承BaseMapper后无需编写任何SQL即可使用selectById,insert,updateById,selectPage等方法。3. Service 接口与实现 (IMonsterService.javaMonsterServiceImpl.java)// 文件路径backend/src/main/java/com/zyl/service/IMonsterService.java package com.zyl.service; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.baomidou.mybatisplus.extension.service.IService; import com.zyl.entity.Monster; import com.zyl.query.MonsterQuery; // 自定义的查询条件封装类 public interface IMonsterService extends IServiceMonster { // 分页条件查询 PageMonster getMonsterPage(MonsterQuery query); } // 文件路径backend/src/main/java/com/zyl/service/impl/MonsterServiceImpl.java package com.zyl.service.impl; import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl; import com.zyl.entity.Monster; import com.zyl.mapper.MonsterMapper; import com.zyl.query.MonsterQuery; import com.zyl.service.IMonsterService; import org.springframework.stereotype.Service; import org.springframework.util.StringUtils; Service public class MonsterServiceImpl extends ServiceImplMonsterMapper, Monster implements IMonsterService { Override public PageMonster getMonsterPage(MonsterQuery query) { // 1. 构建分页对象 PageMonster page new Page(query.getPageNum(), query.getPageSize()); // 2. 构建查询条件 (使用Lambda避免字段名硬编码) LambdaQueryWrapperMonster wrapper new LambdaQueryWrapper(); wrapper.like(StringUtils.hasText(query.getName()), Monster::getName, query.getName()) .eq(StringUtils.hasText(query.getType()), Monster::getType, query.getType()) .eq(query.getDangerLevel() ! null, Monster::getDangerLevel, query.getDangerLevel()) .orderByDesc(Monster::getCreateTime); // 按创建时间倒序 // 3. 执行分页查询 return baseMapper.selectPage(page, wrapper); } }Service层是关键业务逻辑所在。这里演示了如何使用LambdaQueryWrapper构建动态查询条件仅当参数不为空时才添加条件以及如何执行分页查询。MonsterQuery是一个简单的POJO用于接收前端传来的查询参数。4. Controller 层 (MonsterController.java)// 文件路径backend/src/main/java/com/zyl/controller/MonsterController.java package com.zyl.controller; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.zyl.common.Result; import com.zyl.entity.Monster; import com.zyl.query.MonsterQuery; import com.zyl.service.IMonsterService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import javax.validation.Valid; RestController RequestMapping(/monster) public class MonsterController { Autowired private IMonsterService monsterService; // 分页条件查询 GetMapping(/page) public ResultPageMonster getPage(MonsterQuery query) { PageMonster page monsterService.getMonsterPage(query); return Result.success(page); } // 新增妖怪 PostMapping public ResultString addMonster(Valid RequestBody Monster monster) { // Valid 会触发实体类中的校验注解如NotBlank boolean saved monsterService.save(monster); return saved ? Result.success(新增成功) : Result.error(新增失败); } // 更新妖怪信息 PutMapping public ResultString updateMonster(Valid RequestBody Monster monster) { boolean updated monsterService.updateById(monster); return updated ? Result.success(更新成功) : Result.error(更新失败); } // 删除妖怪逻辑删除 DeleteMapping(/{id}) public ResultString deleteMonster(PathVariable Long id) { boolean removed monsterService.removeById(id); // 由于配置了TableLogic这里执行的是逻辑删除 return removed ? Result.success(删除成功) : Result.error(删除失败); } }Controller设计要点RestController表明这是一个返回JSON数据的控制器。RequestMapping(/monster)定义了该控制器下所有接口的根路径。使用ResultT统一封装返回结果包含code, data, message这是前后端约定的良好实践。Valid注解用于触发对Monster实体字段的校验需要在实体字段上加NotBlank等注解。RESTful风格GET查询POST新增PUT更新DELETE删除。5.2 前端页面组件与API调用对应后端的妖怪列表页。1. API 封装 (src/api/monster.js)// 文件路径frontend/src/api/monster.js import request from /utils/request; // 导入我们封装好的axios实例 // 获取妖怪分页列表 export function getMonsterPage(params) { return request({ url: /monster/page, method: get, params // GET请求参数 }); } // 新增妖怪 export function addMonster(data) { return request({ url: /monster, method: post, data // POST请求体 }); } // 更新妖怪 export function updateMonster(data) { return request({ url: /monster, method: put, data }); } // 删除妖怪 export function deleteMonster(id) { return request({ url: /monster/${id}, method: delete }); }2. Vue 页面组件 (src/views/monster/List.vue)这是一个简化的列表页包含查询表单和表格。template div classmonster-list !-- 查询表单 -- el-form :modelqueryParams inline el-form-item label妖怪名称 el-input v-modelqueryParams.name placeholder请输入名称 clearable / /el-form-item el-form-item label危险等级 el-select v-modelqueryParams.dangerLevel placeholder请选择 clearable el-option label一级 :value1 / el-option label二级 :value2 / !-- ... -- /el-select /el-form-item el-form-item el-button typeprimary clickhandleQuery搜索/el-button el-button clickresetQuery重置/el-button /el-form-item /el-form !-- 操作按钮和表格 -- div stylemargin-bottom: 16px; el-button typeprimary clickhandleAdd新增妖怪/el-button /div el-table :datatableData border v-loadingloading el-table-column propname label名称 / el-table-column proptype label类型 / el-table-column propdangerLevel label危险等级 template #defaultscope el-tag :typegetDangerTagType(scope.row.dangerLevel) {{ scope.row.dangerLevel }}级 /el-tag /template /el-table-column el-table-column proplocation label出没地点 / el-table-column propstatus label状态 / el-table-column propcreateTime label创建时间 / el-table-column label操作 width200 template #defaultscope el-button sizesmall clickhandleEdit(scope.row)编辑/el-button el-button sizesmall typedanger clickhandleDelete(scope.row)删除/el-button /template /el-table-column /el-table !-- 分页组件 -- el-pagination size-changehandleSizeChange current-changehandleCurrentChange :current-pagequeryParams.pageNum :page-sizes[10, 20, 50] :page-sizequeryParams.pageSize layouttotal, sizes, prev, pager, next, jumper :totaltotal /el-pagination !-- 新增/编辑对话框 (此处省略实际项目中是一个独立的子组件) -- /div /template script setup import { ref, onMounted } from vue; import { ElMessage, ElMessageBox } from element-plus; import { getMonsterPage, deleteMonster } from /api/monster; // 响应式数据 const loading ref(false); const tableData ref([]); const total ref(0); // 查询参数 const queryParams ref({ pageNum: 1, pageSize: 10, name: , dangerLevel: null, }); // 方法获取表格数据 const fetchData async () { loading.value true; try { const res await getMonsterPage(queryParams.value); tableData.value res.records; // 假设后端返回的Page对象里有records数组 total.value res.total; } catch (error) { console.error(获取数据失败:, error); } finally { loading.value false; } }; // 方法处理查询 const handleQuery () { queryParams.value.pageNum 1; // 搜索时回到第一页 fetchData(); }; // 方法重置查询 const resetQuery () { queryParams.value { pageNum: 1, pageSize: 10, name: , dangerLevel: null, }; fetchData(); }; // 方法处理分页 const handleSizeChange (val) { queryParams.value.pageSize val; fetchData(); }; const handleCurrentChange (val) { queryParams.value.pageNum val; fetchData(); }; // 方法删除 const handleDelete (row) { ElMessageBox.confirm(确认删除妖怪【${row.name}】吗, 提示, { confirmButtonText: 确定, cancelButtonText: 取消, type: warning, }).then(async () { await deleteMonster(row.id); ElMessage.success(删除成功); fetchData(); // 刷新列表 }).catch(() {}); }; // 生命周期钩子 onMounted(() { fetchData(); }); /script这个组件清晰地展示了前端如何与后端协作通过调用封装好的API函数传递查询参数处理响应数据并利用Element Plus组件渲染表格和分页。script setup语法是 Vue 3 的组合式 API 写法让逻辑更集中。6. 进阶功能实现权限控制与文件上传一个完整的系统离不开权限和文件处理。6.1 基于Token的接口权限控制以后端使用 Spring Security JWT 为例。1. 登录接口与Token生成// AuthController.java 片段 PostMapping(/login) public ResultMapString, String login(RequestBody LoginForm form) { // 1. 验证用户名密码 (伪代码) User user userService.validateUser(form.getUsername(), form.getPassword()); // 2. 生成JWT Token String token JwtUtil.generateToken(user.getId(), user.getUsername(), user.getRoles()); // 3. 返回Token和用户基本信息 MapString, String data new HashMap(); data.put(token, token); data.put(username, user.getUsername()); return Result.success(data); }2. 配置Spring Security过滤器链// SecurityConfig.java 核心配置 Configuration EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Autowired private JwtAuthenticationTokenFilter jwtAuthenticationTokenFilter; Override protected void configure(HttpSecurity http) throws Exception { http // 关闭CSRF因为使用Token无状态认证 .csrf().disable() // 设置会话管理为无状态 .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() // 配置请求授权规则 .authorizeRequests() .antMatchers(/auth/login, /auth/register).permitAll() // 登录注册放行 .antMatchers(/admin/**).hasRole(ADMIN) // /admin/ 开头的需要ADMIN角色 .antMatchers(/monster/**).hasAnyRole(ADMIN, USER) // 妖怪管理需要角色 .anyRequest().authenticated() // 其他所有请求都需要认证 .and() // 添加JWT过滤器 .addFilterBefore(jwtAuthenticationTokenFilter, UsernamePasswordAuthenticationFilter.class) // 配置异常处理 .exceptionHandling() .authenticationEntryPoint(new MyAuthenticationEntryPoint()) // 未认证处理 .accessDeniedHandler(new MyAccessDeniedHandler()); // 权限不足处理 } }关键点JwtAuthenticationTokenFilter是一个自定义过滤器它会从HTTP请求头中解析Authorization: Bearer token验证Token有效性并将用户信息设置到SecurityContext中供后续的PreAuthorize注解或方法内使用。6.2 文件上传功能后端接收文件// FileController.java RestController RequestMapping(/file) public class FileController { Value(${zyl.file.upload-dir}) private String uploadDir; PostMapping(/upload) public ResultString uploadFile(RequestParam(file) MultipartFile file) { if (file.isEmpty()) { return Result.error(文件不能为空); } try { // 生成唯一文件名防止覆盖 String originalFilename file.getOriginalFilename(); String fileExtension originalFilename.substring(originalFilename.lastIndexOf(.)); String newFileName UUID.randomUUID().toString() fileExtension; // 构建存储路径 Path uploadPath Paths.get(uploadDir); if (!Files.exists(uploadPath)) { Files.createDirectories(uploadPath); } Path filePath uploadPath.resolve(newFileName); // 保存文件 Files.copy(file.getInputStream(), filePath, StandardCopyOption.REPLACE_EXISTING); // 返回文件访问路径需要配置静态资源映射或使用云存储URL String fileUrl /uploads/ newFileName; return Result.success(fileUrl); } catch (IOException e) { e.printStackTrace(); return Result.error(文件上传失败); } } }前端上传组件template el-upload classupload-demo action/api/file/upload !-- 上传地址 -- :on-successhandleSuccess :before-uploadbeforeUpload :show-file-listfalse el-button typeprimary点击上传/el-button template #tip div classel-upload__tip只能上传jpg/png文件且不超过2MB/div /template /el-upload /template script setup const handleSuccess (response) { if (response.code 200) { ElMessage.success(上传成功); const fileUrl response.data; // 后端返回的文件URL // 将fileUrl绑定到表单数据中随其他数据一起提交 } else { ElMessage.error(response.message); } }; const beforeUpload (file) { const isImage file.type image/jpeg || file.type image/png; const isLt2M file.size / 1024 / 1024 2; if (!isImage) { ElMessage.error(只能上传JPG/PNG图片!); } if (!isLt2M) { ElMessage.error(图片大小不能超过2MB!); } return isImage isLt2M; }; /script7. 常见问题与排查思路在运行《斩妖录》或类似项目时你可能会遇到以下问题问题现象可能原因排查方式解决方案后端启动失败端口被占用8080端口已被其他程序如另一个Spring Boot应用、Tomcat使用。1. 查看启动日志中的错误信息。2. 使用命令netstat -ano | findstr :8080(Windows) 或lsof -i:8080(Linux/Mac) 查看占用进程。1. 终止占用端口的进程。2. 在application.yml中修改server.port为其他端口如 8081。前端无法访问后端API出现CORS错误浏览器因同源策略阻止了跨域请求。打开浏览器开发者工具查看Console或Network标签页错误信息会明确提示CORS。在后端添加CORS配置。创建一个配置类Configurationpublic class CorsConfig implements WebMvcConfigurer {Overridepublic void addCorsMappings(...) {registry.addMapping(/**).allowedOriginPatterns(*).allowedMethods(*).allowCredentials(true);}}生产环境应将allowedOriginPatterns替换为具体的前端域名。数据库连接失败1. 数据库服务未启动。2.application.yml中数据库配置错误IP、端口、库名、用户名、密码。3. 数据库驱动版本不匹配。1. 检查MySQL服务状态。2. 仔细核对配置文件。3. 查看启动日志中的SQL异常堆栈。1. 启动MySQL服务。2. 修正配置文件。3. 确保pom.xml中的mysql-connector-java版本与MySQL服务器版本兼容。前端npm install失败1. 网络问题。2. Node.js版本过低。3. 项目依赖的某个包版本冲突或已不存在。1. 查看npm错误日志通常会有明确提示。2. 使用node -v检查版本。1. 切换npm源如使用淘宝镜像npm config set registry https://registry.npmmirror.com。2. 升级Node.js到LTS版本。3. 删除node_modules和package-lock.json重新执行npm install。页面能打开但列表数据为空1. 后端API未成功返回数据。2. 前端API请求地址或参数错误。3. 数据库表中无数据。1. 打开浏览器开发者工具的Network面板查看API请求的响应状态码和返回体。2. 检查前端请求的URL和参数是否与后端Controller定义匹配。3. 直接使用数据库工具查询对应表。1. 根据Network中的错误信息修正后端或前端代码。2. 检查后端Controller的GetMapping(/page)等注解路径。3. 在数据库中插入测试数据。执行删除操作后数据仍在列表中MyBatis-Plus的逻辑删除未生效。1. 检查实体类中的逻辑删除字段是否加了TableLogic。2. 检查application.yml中mybatis-plus.global-config.db-config的逻辑删除配置是否正确。3. 查看控制台SQL日志看执行的语句是UPDATE还是DELETE。1. 确保注解和配置正确。2. 数据库表中的逻辑删除字段默认值应为0未删除。8. 最佳实践与项目扩展建议当你成功运行《斩妖录》项目后可以尝试以下实践来深化理解和提升项目质量代码分层与分包规范严格遵循Controller - Service - Mapper - Entity的分层。可以按功能模块分包如com.zyl.monster,com.zyl.user而不是按技术类型分包。统一响应封装与异常处理像示例中的Result类一样统一所有API的返回格式。创建一个全局异常处理器ControllerAdvice将系统异常转化为友好的Result对象返回给前端。参数校验不仅在Controller方法参数上使用Valid更要在实体类的字段上使用NotBlank,Size,Email等注解进行声明式校验让代码更清晰健壮。使用DTO和VO避免直接使用Entity作为接口的请求/响应体。创建MonsterDTO(Data Transfer Object) 用于接收前端请求创建MonsterVO(View Object) 用于返回给前端。这可以隐藏数据库细节进行数据脱敏以及组合多个实体字段。添加API文档集成Swagger或Knife4j自动生成在线API文档极大方便前后端联调和团队协作。引入缓存对于不常变动的字典数据如妖怪类型、危险等级枚举可以使用Spring Cache集成Redis进行缓存减轻数据库压力。前端路由权限根据用户角色动态生成侧边栏菜单src/router/index.js中配置路由元信息meta.roles实现前端页面级的权限控制。容器化部署为前后端项目分别编写Dockerfile并使用docker-compose.yml定义MySQL、Redis、后端、前端服务实现一键部署这是现代DevOps的必备技能。《斩妖录》项目提供了一个绝佳的起点和脚手架。它的价值不在于实现了多么复杂的业务而在于清晰地展示了一个现代Java Web应用从技术选型、环境搭建、模块开发到前后端联调的完整脉络。建议你在理解现有代码的基础上尝试添加新的模块如“法宝管理”、“任务派发”或将其中的技术方案如权限控制、文件上传替换成你更熟悉的框架如用Sa-Token替代Spring Security这个过程本身就是最好的学习。
如果你是一名Java开发者正在寻找一个能快速上手、功能全面且能帮你深入理解Spring Boot、MyBatis-Plus、Vue3等主流技术栈整合的实战项目那么你很可能已经厌倦了千篇一律的“增删改查”Demo。今天要聊的《斩妖录》正是这样一个项目。它不是一个简单的CRUD模板而是一个以“妖怪管理”为背景完整覆盖前后端分离开发全流程的实战案例。它的核心价值在于通过一个有趣且结构清晰的主题将权限管理、数据可视化、文件上传、工作流引擎等企业级开发中常见的“硬骨头”模块进行了系统性的串联和实现。很多人学习框架时总感觉知识点是散的Spring Security的配置看懂了但不知道怎么和业务角色结合ECharts图表会用了但数据从哪来、怎么动态更新不清楚MyBatis-Plus的Lambda查询很强大但复杂的多表关联和分页怎么优雅处理《斩妖录》项目正是为了解决这种“知识孤岛”问题。它把技术栈变成了解决具体业务问题的工具让你能看到从数据库设计、接口定义、权限控制到前端渲染的完整闭环。本文将带你深入拆解《斩妖录》项目。我们不会停留在“这个项目用了什么技术”的表面介绍而是聚焦于它如何用“妖怪管理”这个业务模型具象化地演绎了RBAC权限、数据报表等抽象概念。从零开始的环境搭建到核心模块的代码实现提供可复现的实操路径。剖析那些在官方文档里不会细讲但在实际开发中一定会遇到的“坑”和最佳实践。无论你是想找一个高质量的项目丰富简历还是希望深化对现代Java Web开发体系的理解这篇文章都将提供一条清晰的路径。1. 项目核心定位不止于技术栈演示在开始看代码之前我们必须先理解《斩妖录》项目的真正定位。它不是一个追求技术炫技的“玩具”而是一个面向教学与原型开发的“企业级应用微缩模型”。它解决了什么痛点对于中级开发者而言最大的瓶颈往往不是学习单个技术点而是缺乏将多个技术点有机组合构建一个完整、健壮应用系统的经验。《斩妖录》通过“妖怪信息管理系统”这个业务场景将以下核心诉求串联起来权限控制不同的用户如“管理员”、“捉妖师”、“游客”能看到和操作的数据范围完全不同。数据管理妖怪信息包含文本、数值、状态、甚至图片需要完整的CRUD、复杂查询和分页展示。数据可视化需要直观地展示妖怪的分布、战力统计、捉拿趋势等。业务流程一个妖怪从“发现”到“登记”再到“处置完成”可能涉及状态流转和审核。文件处理上传妖怪的画像或相关证据文件。技术选型的考量项目采用了经典且稳定的“Spring Boot Vue3”前后端分离架构。这个组合的成熟度极高社区资源丰富是大多数企业项目的起点。后端Spring Boot 2.x 作为基石集成 MyBatis-Plus 极大提升数据库操作效率Spring Security 或 Sa-Token 负责权限认证Hutool 等工具库处理通用任务。前端Vue 3 Element Plus 构建管理后台界面Axios 处理HTTP请求ECharts 实现图表。这套组合能快速搭建出美观且交互良好的中后台系统。数据库通常选用 MySQL表结构设计会体现业务关系。这个项目的价值在于它用具体的代码告诉你这些技术栈在真实的业务上下文里应该如何协作而不仅仅是独立的API调用示例。2. 环境准备与项目初始化在开始编码之前确保你的开发环境就绪。这是后续一切操作的基础。2.1 基础环境清单你需要准备以下软件并建议使用指定或更高版本以保证兼容性JDK: 版本 8 或 11 (推荐11长期支持版)。安装后配置好JAVA_HOME环境变量。Maven: 版本 3.6。用于管理后端项目的依赖和构建。Node.js: 版本 16 (推荐18 LTS)。附带 npm 包管理器用于前端项目。IDE:后端IntelliJ IDEA (社区版或旗舰版) 或 Eclipse with STS。前端Visual Studio Code并安装 Vue 官方插件 (Volar)。数据库: MySQL 5.7 或 8.0。确保服务已启动并记住 root 密码或已创建有权限的专用用户。Git: 用于克隆项目代码。2.2 获取项目代码假设项目托管在 GitHub 或 Gitee 上使用 Git 克隆到本地。# 示例命令实际仓库地址需替换 git clone https://github.com/username/zhan-yao-lu.git cd zhan-yao-lu项目结构通常如下zhan-yao-lu/ ├── backend/ # Spring Boot 后端项目 ├── frontend/ # Vue 3 前端项目 ├── sql/ # 数据库初始化脚本 └── README.md # 项目说明文档2.3 数据库初始化使用 MySQL 客户端如命令行、Navicat、DBeaver连接你的数据库服务。创建一个新的数据库例如zhan_yao_lu。CREATE DATABASE IF NOT EXISTS zhan_yao_lu DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;执行项目sql/目录下的初始化脚本通常是init.sql或按版本号命名。这个脚本会创建所有必要的表并插入初始数据如管理员账号、基础字典数据。# 假设在sql文件所在目录 mysql -u root -p zhan_yao_lu init.sql3. 后端项目启动与核心配置详解进入backend目录让我们看看一个典型的 Spring Boot 项目是如何配置的。3.1 关键依赖分析 (pom.xml)打开pom.xml你会看到项目依赖的核心组件dependencies !-- Spring Boot 核心启动器 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId !-- 或 sa-token-spring-boot-starter -- /dependency !-- 数据访问层 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3/version !-- 注意版本 -- /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency !-- 工具类 -- dependency groupIdcn.hutool/groupId artifactIdhutool-all/artifactId version5.8.20/version /dependency !-- 其他常用JWT、Redis、Swagger等 -- !-- dependency ... /dependency -- /dependencies关键点注意mybatis-plus和hutool的版本不同版本 API 可能有细微差别。如果启动时出现ClassNotFoundException或NoSuchMethodError首先检查依赖版本冲突。3.2 核心配置文件 (application.yml)Spring Boot 的配置集中在src/main/resources/application.yml中。这是连接数据库、设置服务器端口、配置安全规则的地方。server: port: 8080 servlet: context-path: /api # API统一前缀 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/zhan_yao_lu?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root # 强烈建议在生产环境使用非root用户 password: your_password_here # 替换为你的数据库密码 # 文件上传配置 servlet: multipart: max-file-size: 10MB max-request-size: 100MB # 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 # 逻辑未删除值 # 自定义应用配置 zyl: file: upload-dir: /tmp/zyl-uploads/ # 文件上传目录根据系统调整 jwt: secret: your-jwt-secret-key-change-in-production # JWT密钥必须修改 expire: 7200 # 过期时间(秒)配置要点数据库连接确保url、username、password与你的本地环境一致。serverTimezone设置很重要避免时间错误。SQL日志log-impl配置在开发阶段非常有用可以查看MyBatis-Plus生成的SQL便于调试。生产环境务必关闭。逻辑删除logic-delete-field是MyBatis-Plus提供的优雅删除方案执行删除操作时实际是更新deleted字段而非物理删除数据。JWT密钥zyl.jwt.secret是安全核心绝对不能使用示例中的值必须用一个足够复杂且保密的字符串替换。3.3 启动后端服务在IDE中直接运行BackendApplication类的main方法或在项目根目录下使用Maven命令cd backend mvn spring-boot:run看到控制台输出类似Started BackendApplication in 5.123 seconds (JVM running for 5.789)的信息且没有报错说明后端启动成功。默认API地址为http://localhost:8080/api。4. 前端项目启动与结构解析切换到frontend目录这是一个标准的 Vue 3 Vite Element Plus 项目。4.1 安装依赖并启动cd frontend npm install # 或使用 yarn/pnpm npm run dev命令执行成功后终端会提示本地开发服务器地址通常是http://localhost:5173。用浏览器打开即可看到登录界面。4.2 前端项目结构概览理解前端结构有助于你快速定位代码frontend/ ├── public/ # 静态资源 ├── src/ │ ├── api/ # 所有与后端交互的接口函数使用axios封装 │ ├── assets/ # 图片、字体等资源 │ ├── components/ # 可复用的Vue组件 │ ├── layout/ # 布局组件如侧边栏、顶部导航 │ ├── router/ # Vue Router路由配置 │ ├── store/ # Pinia状态管理或Vuex │ ├── utils/ # 工具函数请求封装、日期格式化等 │ ├── views/ # 页面视图组件妖怪列表、新增、图表页等 │ ├── App.vue # 根组件 │ └── main.js # 应用入口文件 ├── .env.development # 开发环境配置如后端API基础URL ├── vite.config.js # Vite构建配置 └── package.json # 项目依赖和脚本4.3 关键配置连接后端API前端需要知道后端服务的地址。这通常在.env.development文件中配置# .env.development VITE_APP_BASE_API http://localhost:8080/api在src/utils/request.js(或类似文件) 中会使用这个环境变量来创建Axios实例import axios from axios; import { ElMessage } from element-plus; // 创建axios实例 const service axios.create({ baseURL: import.meta.env.VITE_APP_BASE_API, // 读取环境变量 timeout: 10000 // 请求超时时间 }); // 请求拦截器通常用于添加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; // 假设后端统一返回格式为 { code: 200, data: ..., message: success } if (res.code ! 200) { ElMessage.error(res.message || Error); return Promise.reject(new Error(res.message || Error)); } return res.data; // 直接返回业务数据 }, error { ElMessage.error(error.message || Request Failed); return Promise.reject(error); } ); export default service;这个拦截器模式是前后端分离项目的核心它统一处理了认证添加Token、错误提示和数据结构让业务组件可以更专注于UI和逻辑而不必每次请求都写重复的代码。5. 核心业务模块代码拆解现在我们进入最核心的部分看看《斩妖录》是如何用代码实现具体业务的。我们以“妖怪管理”模块为例。5.1 后端实体、Mapper、Service与Controller遵循经典的四层架构Entity-Mapper-Service-Controller。1. 实体类 (Monster.java)// 文件路径backend/src/main/java/com/zyl/entity/Monster.java package com.zyl.entity; import com.baomidou.mybatisplus.annotation.*; import lombok.Data; import java.time.LocalDateTime; Data TableName(t_monster) // 指定对应数据库表名 public class Monster { TableId(type IdType.AUTO) // 主键自增 private Long id; private String name; // 妖怪名称 private String type; // 妖怪类型如水怪、山精 private Integer dangerLevel; // 危险等级 (1-5) private String location; // 出没地点 private String description; // 描述 private String status; // 状态 (如未收服、已收服、在逃) TableField(fill FieldFill.INSERT) // 插入时自动填充 private LocalDateTime createTime; TableField(fill FieldFill.INSERT_UPDATE) // 插入和更新时自动填充 private LocalDateTime updateTime; TableLogic // 标记为逻辑删除字段 private Integer deleted; }注解解析TableField(fill ...)需要配合 MyBatis-Plus 的MetaObjectHandler实现类自动填充时间。TableLogic使删除操作变为逻辑删除。2. Mapper 接口 (MonsterMapper.java)// 文件路径backend/src/main/java/com/zyl/mapper/MonsterMapper.java package com.zyl.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.zyl.entity.Monster; import org.apache.ibatis.annotations.Mapper; Mapper // 或是在启动类上用 MapperScan 批量扫描 public interface MonsterMapper extends BaseMapperMonster { // 继承 BaseMapper 即拥有了基本的 CRUD 方法 // 复杂查询可以通过 XML 或注解方式在此定义 }继承BaseMapper后无需编写任何SQL即可使用selectById,insert,updateById,selectPage等方法。3. Service 接口与实现 (IMonsterService.javaMonsterServiceImpl.java)// 文件路径backend/src/main/java/com/zyl/service/IMonsterService.java package com.zyl.service; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.baomidou.mybatisplus.extension.service.IService; import com.zyl.entity.Monster; import com.zyl.query.MonsterQuery; // 自定义的查询条件封装类 public interface IMonsterService extends IServiceMonster { // 分页条件查询 PageMonster getMonsterPage(MonsterQuery query); } // 文件路径backend/src/main/java/com/zyl/service/impl/MonsterServiceImpl.java package com.zyl.service.impl; import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl; import com.zyl.entity.Monster; import com.zyl.mapper.MonsterMapper; import com.zyl.query.MonsterQuery; import com.zyl.service.IMonsterService; import org.springframework.stereotype.Service; import org.springframework.util.StringUtils; Service public class MonsterServiceImpl extends ServiceImplMonsterMapper, Monster implements IMonsterService { Override public PageMonster getMonsterPage(MonsterQuery query) { // 1. 构建分页对象 PageMonster page new Page(query.getPageNum(), query.getPageSize()); // 2. 构建查询条件 (使用Lambda避免字段名硬编码) LambdaQueryWrapperMonster wrapper new LambdaQueryWrapper(); wrapper.like(StringUtils.hasText(query.getName()), Monster::getName, query.getName()) .eq(StringUtils.hasText(query.getType()), Monster::getType, query.getType()) .eq(query.getDangerLevel() ! null, Monster::getDangerLevel, query.getDangerLevel()) .orderByDesc(Monster::getCreateTime); // 按创建时间倒序 // 3. 执行分页查询 return baseMapper.selectPage(page, wrapper); } }Service层是关键业务逻辑所在。这里演示了如何使用LambdaQueryWrapper构建动态查询条件仅当参数不为空时才添加条件以及如何执行分页查询。MonsterQuery是一个简单的POJO用于接收前端传来的查询参数。4. Controller 层 (MonsterController.java)// 文件路径backend/src/main/java/com/zyl/controller/MonsterController.java package com.zyl.controller; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.zyl.common.Result; import com.zyl.entity.Monster; import com.zyl.query.MonsterQuery; import com.zyl.service.IMonsterService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; import javax.validation.Valid; RestController RequestMapping(/monster) public class MonsterController { Autowired private IMonsterService monsterService; // 分页条件查询 GetMapping(/page) public ResultPageMonster getPage(MonsterQuery query) { PageMonster page monsterService.getMonsterPage(query); return Result.success(page); } // 新增妖怪 PostMapping public ResultString addMonster(Valid RequestBody Monster monster) { // Valid 会触发实体类中的校验注解如NotBlank boolean saved monsterService.save(monster); return saved ? Result.success(新增成功) : Result.error(新增失败); } // 更新妖怪信息 PutMapping public ResultString updateMonster(Valid RequestBody Monster monster) { boolean updated monsterService.updateById(monster); return updated ? Result.success(更新成功) : Result.error(更新失败); } // 删除妖怪逻辑删除 DeleteMapping(/{id}) public ResultString deleteMonster(PathVariable Long id) { boolean removed monsterService.removeById(id); // 由于配置了TableLogic这里执行的是逻辑删除 return removed ? Result.success(删除成功) : Result.error(删除失败); } }Controller设计要点RestController表明这是一个返回JSON数据的控制器。RequestMapping(/monster)定义了该控制器下所有接口的根路径。使用ResultT统一封装返回结果包含code, data, message这是前后端约定的良好实践。Valid注解用于触发对Monster实体字段的校验需要在实体字段上加NotBlank等注解。RESTful风格GET查询POST新增PUT更新DELETE删除。5.2 前端页面组件与API调用对应后端的妖怪列表页。1. API 封装 (src/api/monster.js)// 文件路径frontend/src/api/monster.js import request from /utils/request; // 导入我们封装好的axios实例 // 获取妖怪分页列表 export function getMonsterPage(params) { return request({ url: /monster/page, method: get, params // GET请求参数 }); } // 新增妖怪 export function addMonster(data) { return request({ url: /monster, method: post, data // POST请求体 }); } // 更新妖怪 export function updateMonster(data) { return request({ url: /monster, method: put, data }); } // 删除妖怪 export function deleteMonster(id) { return request({ url: /monster/${id}, method: delete }); }2. Vue 页面组件 (src/views/monster/List.vue)这是一个简化的列表页包含查询表单和表格。template div classmonster-list !-- 查询表单 -- el-form :modelqueryParams inline el-form-item label妖怪名称 el-input v-modelqueryParams.name placeholder请输入名称 clearable / /el-form-item el-form-item label危险等级 el-select v-modelqueryParams.dangerLevel placeholder请选择 clearable el-option label一级 :value1 / el-option label二级 :value2 / !-- ... -- /el-select /el-form-item el-form-item el-button typeprimary clickhandleQuery搜索/el-button el-button clickresetQuery重置/el-button /el-form-item /el-form !-- 操作按钮和表格 -- div stylemargin-bottom: 16px; el-button typeprimary clickhandleAdd新增妖怪/el-button /div el-table :datatableData border v-loadingloading el-table-column propname label名称 / el-table-column proptype label类型 / el-table-column propdangerLevel label危险等级 template #defaultscope el-tag :typegetDangerTagType(scope.row.dangerLevel) {{ scope.row.dangerLevel }}级 /el-tag /template /el-table-column el-table-column proplocation label出没地点 / el-table-column propstatus label状态 / el-table-column propcreateTime label创建时间 / el-table-column label操作 width200 template #defaultscope el-button sizesmall clickhandleEdit(scope.row)编辑/el-button el-button sizesmall typedanger clickhandleDelete(scope.row)删除/el-button /template /el-table-column /el-table !-- 分页组件 -- el-pagination size-changehandleSizeChange current-changehandleCurrentChange :current-pagequeryParams.pageNum :page-sizes[10, 20, 50] :page-sizequeryParams.pageSize layouttotal, sizes, prev, pager, next, jumper :totaltotal /el-pagination !-- 新增/编辑对话框 (此处省略实际项目中是一个独立的子组件) -- /div /template script setup import { ref, onMounted } from vue; import { ElMessage, ElMessageBox } from element-plus; import { getMonsterPage, deleteMonster } from /api/monster; // 响应式数据 const loading ref(false); const tableData ref([]); const total ref(0); // 查询参数 const queryParams ref({ pageNum: 1, pageSize: 10, name: , dangerLevel: null, }); // 方法获取表格数据 const fetchData async () { loading.value true; try { const res await getMonsterPage(queryParams.value); tableData.value res.records; // 假设后端返回的Page对象里有records数组 total.value res.total; } catch (error) { console.error(获取数据失败:, error); } finally { loading.value false; } }; // 方法处理查询 const handleQuery () { queryParams.value.pageNum 1; // 搜索时回到第一页 fetchData(); }; // 方法重置查询 const resetQuery () { queryParams.value { pageNum: 1, pageSize: 10, name: , dangerLevel: null, }; fetchData(); }; // 方法处理分页 const handleSizeChange (val) { queryParams.value.pageSize val; fetchData(); }; const handleCurrentChange (val) { queryParams.value.pageNum val; fetchData(); }; // 方法删除 const handleDelete (row) { ElMessageBox.confirm(确认删除妖怪【${row.name}】吗, 提示, { confirmButtonText: 确定, cancelButtonText: 取消, type: warning, }).then(async () { await deleteMonster(row.id); ElMessage.success(删除成功); fetchData(); // 刷新列表 }).catch(() {}); }; // 生命周期钩子 onMounted(() { fetchData(); }); /script这个组件清晰地展示了前端如何与后端协作通过调用封装好的API函数传递查询参数处理响应数据并利用Element Plus组件渲染表格和分页。script setup语法是 Vue 3 的组合式 API 写法让逻辑更集中。6. 进阶功能实现权限控制与文件上传一个完整的系统离不开权限和文件处理。6.1 基于Token的接口权限控制以后端使用 Spring Security JWT 为例。1. 登录接口与Token生成// AuthController.java 片段 PostMapping(/login) public ResultMapString, String login(RequestBody LoginForm form) { // 1. 验证用户名密码 (伪代码) User user userService.validateUser(form.getUsername(), form.getPassword()); // 2. 生成JWT Token String token JwtUtil.generateToken(user.getId(), user.getUsername(), user.getRoles()); // 3. 返回Token和用户基本信息 MapString, String data new HashMap(); data.put(token, token); data.put(username, user.getUsername()); return Result.success(data); }2. 配置Spring Security过滤器链// SecurityConfig.java 核心配置 Configuration EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Autowired private JwtAuthenticationTokenFilter jwtAuthenticationTokenFilter; Override protected void configure(HttpSecurity http) throws Exception { http // 关闭CSRF因为使用Token无状态认证 .csrf().disable() // 设置会话管理为无状态 .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) .and() // 配置请求授权规则 .authorizeRequests() .antMatchers(/auth/login, /auth/register).permitAll() // 登录注册放行 .antMatchers(/admin/**).hasRole(ADMIN) // /admin/ 开头的需要ADMIN角色 .antMatchers(/monster/**).hasAnyRole(ADMIN, USER) // 妖怪管理需要角色 .anyRequest().authenticated() // 其他所有请求都需要认证 .and() // 添加JWT过滤器 .addFilterBefore(jwtAuthenticationTokenFilter, UsernamePasswordAuthenticationFilter.class) // 配置异常处理 .exceptionHandling() .authenticationEntryPoint(new MyAuthenticationEntryPoint()) // 未认证处理 .accessDeniedHandler(new MyAccessDeniedHandler()); // 权限不足处理 } }关键点JwtAuthenticationTokenFilter是一个自定义过滤器它会从HTTP请求头中解析Authorization: Bearer token验证Token有效性并将用户信息设置到SecurityContext中供后续的PreAuthorize注解或方法内使用。6.2 文件上传功能后端接收文件// FileController.java RestController RequestMapping(/file) public class FileController { Value(${zyl.file.upload-dir}) private String uploadDir; PostMapping(/upload) public ResultString uploadFile(RequestParam(file) MultipartFile file) { if (file.isEmpty()) { return Result.error(文件不能为空); } try { // 生成唯一文件名防止覆盖 String originalFilename file.getOriginalFilename(); String fileExtension originalFilename.substring(originalFilename.lastIndexOf(.)); String newFileName UUID.randomUUID().toString() fileExtension; // 构建存储路径 Path uploadPath Paths.get(uploadDir); if (!Files.exists(uploadPath)) { Files.createDirectories(uploadPath); } Path filePath uploadPath.resolve(newFileName); // 保存文件 Files.copy(file.getInputStream(), filePath, StandardCopyOption.REPLACE_EXISTING); // 返回文件访问路径需要配置静态资源映射或使用云存储URL String fileUrl /uploads/ newFileName; return Result.success(fileUrl); } catch (IOException e) { e.printStackTrace(); return Result.error(文件上传失败); } } }前端上传组件template el-upload classupload-demo action/api/file/upload !-- 上传地址 -- :on-successhandleSuccess :before-uploadbeforeUpload :show-file-listfalse el-button typeprimary点击上传/el-button template #tip div classel-upload__tip只能上传jpg/png文件且不超过2MB/div /template /el-upload /template script setup const handleSuccess (response) { if (response.code 200) { ElMessage.success(上传成功); const fileUrl response.data; // 后端返回的文件URL // 将fileUrl绑定到表单数据中随其他数据一起提交 } else { ElMessage.error(response.message); } }; const beforeUpload (file) { const isImage file.type image/jpeg || file.type image/png; const isLt2M file.size / 1024 / 1024 2; if (!isImage) { ElMessage.error(只能上传JPG/PNG图片!); } if (!isLt2M) { ElMessage.error(图片大小不能超过2MB!); } return isImage isLt2M; }; /script7. 常见问题与排查思路在运行《斩妖录》或类似项目时你可能会遇到以下问题问题现象可能原因排查方式解决方案后端启动失败端口被占用8080端口已被其他程序如另一个Spring Boot应用、Tomcat使用。1. 查看启动日志中的错误信息。2. 使用命令netstat -ano | findstr :8080(Windows) 或lsof -i:8080(Linux/Mac) 查看占用进程。1. 终止占用端口的进程。2. 在application.yml中修改server.port为其他端口如 8081。前端无法访问后端API出现CORS错误浏览器因同源策略阻止了跨域请求。打开浏览器开发者工具查看Console或Network标签页错误信息会明确提示CORS。在后端添加CORS配置。创建一个配置类Configurationpublic class CorsConfig implements WebMvcConfigurer {Overridepublic void addCorsMappings(...) {registry.addMapping(/**).allowedOriginPatterns(*).allowedMethods(*).allowCredentials(true);}}生产环境应将allowedOriginPatterns替换为具体的前端域名。数据库连接失败1. 数据库服务未启动。2.application.yml中数据库配置错误IP、端口、库名、用户名、密码。3. 数据库驱动版本不匹配。1. 检查MySQL服务状态。2. 仔细核对配置文件。3. 查看启动日志中的SQL异常堆栈。1. 启动MySQL服务。2. 修正配置文件。3. 确保pom.xml中的mysql-connector-java版本与MySQL服务器版本兼容。前端npm install失败1. 网络问题。2. Node.js版本过低。3. 项目依赖的某个包版本冲突或已不存在。1. 查看npm错误日志通常会有明确提示。2. 使用node -v检查版本。1. 切换npm源如使用淘宝镜像npm config set registry https://registry.npmmirror.com。2. 升级Node.js到LTS版本。3. 删除node_modules和package-lock.json重新执行npm install。页面能打开但列表数据为空1. 后端API未成功返回数据。2. 前端API请求地址或参数错误。3. 数据库表中无数据。1. 打开浏览器开发者工具的Network面板查看API请求的响应状态码和返回体。2. 检查前端请求的URL和参数是否与后端Controller定义匹配。3. 直接使用数据库工具查询对应表。1. 根据Network中的错误信息修正后端或前端代码。2. 检查后端Controller的GetMapping(/page)等注解路径。3. 在数据库中插入测试数据。执行删除操作后数据仍在列表中MyBatis-Plus的逻辑删除未生效。1. 检查实体类中的逻辑删除字段是否加了TableLogic。2. 检查application.yml中mybatis-plus.global-config.db-config的逻辑删除配置是否正确。3. 查看控制台SQL日志看执行的语句是UPDATE还是DELETE。1. 确保注解和配置正确。2. 数据库表中的逻辑删除字段默认值应为0未删除。8. 最佳实践与项目扩展建议当你成功运行《斩妖录》项目后可以尝试以下实践来深化理解和提升项目质量代码分层与分包规范严格遵循Controller - Service - Mapper - Entity的分层。可以按功能模块分包如com.zyl.monster,com.zyl.user而不是按技术类型分包。统一响应封装与异常处理像示例中的Result类一样统一所有API的返回格式。创建一个全局异常处理器ControllerAdvice将系统异常转化为友好的Result对象返回给前端。参数校验不仅在Controller方法参数上使用Valid更要在实体类的字段上使用NotBlank,Size,Email等注解进行声明式校验让代码更清晰健壮。使用DTO和VO避免直接使用Entity作为接口的请求/响应体。创建MonsterDTO(Data Transfer Object) 用于接收前端请求创建MonsterVO(View Object) 用于返回给前端。这可以隐藏数据库细节进行数据脱敏以及组合多个实体字段。添加API文档集成Swagger或Knife4j自动生成在线API文档极大方便前后端联调和团队协作。引入缓存对于不常变动的字典数据如妖怪类型、危险等级枚举可以使用Spring Cache集成Redis进行缓存减轻数据库压力。前端路由权限根据用户角色动态生成侧边栏菜单src/router/index.js中配置路由元信息meta.roles实现前端页面级的权限控制。容器化部署为前后端项目分别编写Dockerfile并使用docker-compose.yml定义MySQL、Redis、后端、前端服务实现一键部署这是现代DevOps的必备技能。《斩妖录》项目提供了一个绝佳的起点和脚手架。它的价值不在于实现了多么复杂的业务而在于清晰地展示了一个现代Java Web应用从技术选型、环境搭建、模块开发到前后端联调的完整脉络。建议你在理解现有代码的基础上尝试添加新的模块如“法宝管理”、“任务派发”或将其中的技术方案如权限控制、文件上传替换成你更熟悉的框架如用Sa-Token替代Spring Security这个过程本身就是最好的学习。
