简介这是一套面向计算机相关专业本科生的毕业设计与课程设计实战项目——基于Ruoyi-Vue框架开发的家教一体化系统适用于计科、人工智能、通信工程等方向的学生完成毕设、课设或大作业也适合初学者通过完整业务系统理解前后端协同开发流程。资源包共708个文件涵盖303个Java后端逻辑文件、113个Vue前端组件、83个JS交互脚本、36个XML配置及3个SQL数据库脚本辅以bat自动化构建脚本和多环境配置文件.env.development等整体压缩包仅5.36MB结构清晰、模块解耦明确。已有79人下载学习项目经实机部署验证所有功能模块均可正常运行答辩平均分达96分配套README详述启动步骤与模块说明支持二次开发与功能扩展可直接用于演示、教学或项目立项原型。1. 项目定位与核心需求拆解1.1 家教行业的业务痛点做毕业设计选题的时候我见过太多人一上来就挑学生管理系统图书管理系统这类老掉牙的题目答辩时老师一眼就能看穿工作量。家教一体化系统这个方向表面看也是管理类系统但它的业务链条比传统的单角色CRUD要长得多涵盖了用户注册、课程发布、在线预约、课时管理、评价反馈、统计分析等多个环节非常适合用来展示前后端分离开发的完整能力。先看家教行业的实际场景。家长想给孩子找个靠谱的老师靠的是朋友介绍、线下中介或者各种信息平台。老师想接单往往也是通过微信群、熟人转介绍。这个过程中有几个痛点特别明显第一供需信息不透明家长找不到合适的老师老师找不到稳定的生源第二试听、排课、课时记录全部靠人工沟通时间一长就乱第三课消统计和费用结算没有统一口径容易扯皮。家教一体化系统要解决的就是把这些线下散落的流程搬到线上让家长、老师、平台管理员三方在同一个系统里完成信息匹配和服务闭环。把痛点翻译成系统需求核心就一句话让不同角色在统一的平台上完成信息发布、预约、确认、执行、评价的完整闭环。围绕这句话往下拆系统就至少需要三类角色的支撑——管理员做平台运营和审核教师做课程供给和服务执行学生/家长做需求发起和服务反馈。至于具体功能后面第2章会展开。1.2 为什么选 RuoYi-Vue 作为基座确定了业务方向后接下来就是技术选型。我见过不少同学直接裸写Spring Boot加Vue从零搭权限系统、用户系统、日志系统结果光基础功能就写了一两个月留给业务功能的时间所剩无几。这个项目选型RuoYi-Vue核心原因有三个。第一RuoYi是国内使用率极高的开源后台管理框架基于Spring Boot和Vue实现前后端分离自带完整的RBAC权限体系、用户管理、菜单管理、字典管理、操作日志、定时任务、代码生成器。这些是几乎所有后台系统都需要的通用能力不需要重复造轮子。第二RuoYi的代码生成器可以根据数据库表直接生成Java代码和Vue页面对于毕业设计这种需要赶时间的项目来说相当于把CRUD部分的开发效率提了一倍以上。第三RuoYi的社区活跃度很高遇到问题随便一搜就有解决方案对经验不够丰富的学生党来说这一点太重要了。当然选型RuoYi也有需要注意的地方。它的框架代码风格偏传统没有Spring Cloud那套微服务体系但这恰恰是毕业设计该有的复杂度——单体应用加前后端分离既能展示技术能力又不会把工程量撑爆。另外RuoYi自带的功能默认是英文菜单部分版本或通用业务你需要花时间把菜单、权限配置成家教业务的专属结构。这块我在第4章实操部分会详细说。2. 系统功能模块全解2.1 平台管理端管人、管课、管数据先看管理端。管理端是平台运营方使用的后台也是RuoYi框架原本就很擅长的部分。核心功能包括管理员管理、教师审核、课程科目管理、订单监控、数据统计等。教师入驻审核是管理端一个非常重要的功能。家长对老师的信任度直接决定成交率所以系统里我会设计一个教师认证的流程。用户注册为教师后需要提交资质信息比如学历认证、教学经历状态默认为待审核。管理员登录后台看到待审核列表点击详情查看资料审核通过后教师在用户端的教师认证标识才会点亮。这个功能本质上是RuoYi通用用户表的一个状态字段扩展但业务价值很高写论文和答辩时都能拿出来讲。订单监控和课时消课监控也建议放在管理端。家长预约课程、教师确认排课、实际上课打卡、课时费结算这些关键节点的数据都应该在管理端有可视化的列表和统计图表方便平台方知道系统每天产生了多少交易、有多少课被消化掉。2.2 教师端课程发布与课时管理教师端是业务链条里的供给方。教师在完成认证后可以在系统里发布课程课程信息包括课程名称、适用年级、科目、授课方式线上/线下、课时单价、可授课时段。这块的难点在于数据建模一门课程对应一个教师一个教师可以发布多门课程数据库里要用外键关联好。排课管理是教师端的核心也是最容易出Bug的地方。一个合理的排课系统需要做到教师在某个时间段已经排了课就不能再排新的课家长预约某个时段后其他家长看不到这个时段。最简单的实现思路是设计一张可用课时表教师先维护自己未来N天的可授课时段家长预约时段后把状态改成已预约冲突判断在生成可授课时段时做一次即可。如果想让系统更智能可以再加一个排课冲突校验的工具类但毕设阶段做到状态机层面就够了。课时记录同样值得做细。每完成一节课教师端可以提交课时小结记录上课内容、学生表现、课后练习建议。家长端可以看到这些记录形成服务的留痕。课时记录表要和订单表、课程表做关联同时在管理端能够按教师、按时间维度统计课时消课情况方便后续做课时费结算。2.3 学生与家长端找老师、约课、看反馈学生/家长端的消费路径可以拆成两条一条是找老师一条是上完课后的反馈闭环。找老师的场景系统需要提供课程搜索和教师列表。搜索条件应该包括科目、年级、授课方式、价格区间、好评率排序这些条件在SQL层面都可以通过RuoYi生成的查询条件扩展实现。课程详情页要展示教师信息、课程介绍、课时单价、已购人数和历史评价。这里我要提一个热词里的点——有同学问vue播放m3u8怎么处理。如果课程包含线上录播视频视频回放建议用m3u8格式做切片前端用video.js配合hls.js播放兼容性比直接放mp4好很多拖动进度也流畅。把视频地址放在课程详情里已经购买的学员可以点击播放这是系统的加分项。反馈闭环包括预约、支付模拟、上课打卡、评价。考虑到毕业设计不接入真实支付可以用一个预约下单按钮代替支付环节订单状态从待上课到已完成。上完课后家长可以给教师打分和写评价评价数据反哺到教师列表的好评率和精选评价模块。这样一个消费闭环就完整了。2.4 核心业务闭环与状态机设计整个系统最核心的业务闭环是教师发布课程 - 家长搜索浏览 - 家长预约下单 - 教师确认排课 - 按时上课 - 提交课时记录 - 家长评价 - 管理员统计分析。围绕这个闭环订单表的状态设计至关重要。我的建议是订单状态至少要有这几个待确认家长下单后等待教师确认、待上课教师已确认、已完成课时记录提交且家长评价完成、已取消任何一方在待确认状态下都可取消。在代码层面这个状态机可以用一个枚举类来定义在Service层做状态流转的校验。这里给一个通用的状态校验模板思路public enum OrderStatus { PENDING_CONFIRM(0, 待确认), TO_BE_HELD(1, 待上课), COMPLETED(2, 已完成), CANCELLED(3, 已取消); private final Integer code; private final String desc; // 构造方法、getter... }每次更新订单状态前先用当前状态和期望流转的目标状态做一次合法性校验不允许跳状态。这个设计在答辩时是很好的亮点说明你考虑了业务健壮性而不只是写了增删改查。3. 技术栈选型与架构分析3.1 RuoYi-Vue 的架构成熟度RuoYi-Vue这个组合在毕业设计里的地位相当于手机圈的水桶机——它未必有最惊艳的单项能力但整体素质均衡什么场景都能打。前端是Vue 2 Element UI Vuex Vue Router后端是Spring Boot MyBatis Shiro或Spring Security取决于你下的版本配套MySQL和Redis。对于毕设级别的项目这套组合无论从开发效率还是答辩展示角度都完全够用。我尤其想说的是RuoYi的权限设计。它基于RBACRole-Based Access Control基于角色的访问控制模型用户-角色-菜单三层解耦。你在系统管理-角色管理里给某个角色勾选菜单权限该角色下的用户登录后只能看到被授权的菜单和接口。对于家教系统来说管理员、教师、家长天然就是三种角色用RuoYi的权限体系可以非常清爽地完成界面隔离和数据权限隔离。这里的数据权限不只是菜单级别RuoYi还有数据范围控制可以按角色配置仅查看本人数据教师端只能用自己ID查询课程数据就是这个机制实现的。3.2 后端目录结构与分层思路第一次打开RuoYi后端项目的人往往会对着一大堆模块发懵。我这里逐个讲清楚。RuoYi-Vue后端是一个Maven多模块工程主要模块包括ruoyi-admin、ruoyi-framework、ruoyi-system、ruoyi-common、ruoyi-quartz、ruoyi-generator。ruoyi-admin启动模块包含Controller层也是系统的入口。ruoyi-framework框架核心配置包括安全配置、拦截器、AOP切面、Redis配置等。ruoyi-system业务模块包含Service和Mapper。ruoyi-common公共工具模块包括通用常量、工具类、统一返回结果。ruoyi-quartz定时任务模块。ruoyi-generator代码生成模块。在RuoYi中写业务代码Controller放在ruoyi-admin的web目录下Service接口和实现放在ruoyi-system的service目录Mapper接口和XML放在ruoyi-system的mapper目录。做家教系统时建议单独包一层比如com.ruoyi.web.controller.tutor、com.ruoyi.system.service.impl.TutorCourseServiceImpl这样自己的业务代码和框架代码之间有清晰的边界后续升级框架版本也不会互相干扰。分层设计上我强烈建议遵守RuoYi自带的规范Controller只做参数接收、调用Service、返回结果Service层写业务逻辑Mapper层访问数据库。不要图省事在Controller里怼SQL后期维护会非常痛苦。RuoYi的AOP日志切面默认记录了所有Controller的访问日志操作日志记录在sys_oper_log表这在答辩演示环节很有展示价值。3.3 前端目录结构与Vue实践前端Vue项目默认是vue-element-admin风格核心目录包括src/api按业务模块拆分的接口定义文件比如tutorCourse.js、tutorOrder.js。src/views页面组件一个页面通常对应一个目录目录里包含index.vue。src/components公共组件比如上传组件、富文本编辑器。src/router路由配置。RuoYi支持后端动态路由菜单从后端数据库读取前端根据菜单配置动态生成路由表。src/storeVuex状态管理存放用户信息、权限标识、标签页状态。这里和热词里对应的几个Vue知识点可以串起来说。比如vue-router中RuoYi默认使用history模式但打包部署到Nginx时需要配置try_files否则刷新页面会404。有同学在本地npm run dev跑得好好的一部署就白屏九成是这个问题。再比如vue keep-alive。RuoYi内置了标签页导航功能也就是热词里的$tab.closeOpenPage相关功能点击左侧菜单会在顶部生成标签页切换标签页时默认会缓存页面状态。如果你在做课时列表页发现切换路由再回来时el-table滚动条位置或者查询条件丢了那就是keep-alive缓存策略没生效。RuoYi路由配置里meta有个keepAlive字段只有设为true的页面才会被keep-alive包裹缓存。打开代码看src/layout/components/AppMain.vue逻辑很清晰keep-alive router-view v-if$route.meta.keepAlive / /keep-alive router-view v-if!$route.meta.keepAlive /如果你的列表页在切换课程分类后表格滚回顶部重点检查页面name和路由meta.keepAlive是否匹配。这个坑我在第5章还会提到。vue computed的计算属性在课时费展示这类场景很实用。比如教师首页要汇总本月完成课时数和预期收入完全可以用computed基于list数据做计算数据变化时视图自动更新比在methods里手动累加优雅得多。3.4 数据库设计要点数据库设计是毕业设计的核心评分点之一。家教系统我建议至少准备这些核心表用户表可以在RuoYi的sys_user上扩展、教师认证信息表、课程表、可预约课时表、订单表、课时记录表、评价表、科目字典表。课程表建议这样设计字段名类型说明idbigint主键teacher_idbigint教师用户ID关联sys_usersubjectvarchar科目关联字典gradevarchar适用年级teach_modechar线上/线下pricedecimal课时单价covervarchar课程封面本地文件路径introtext课程介绍statuschar上架/下架/审核中可预约课时表是这个系统的设计亮点。字段包括id、course_id、teacher_id、start_time、end_time、status可用/已预约/已完成。每次教师新增排课时在Service层做一次时间段重叠校验。这里给个SQL思路SELECT count(*) FROM t_teacher_slot WHERE teacher_id #{teacherId} AND status ! CANCELLED AND (start_time #{endTime} AND end_time #{startTime})如果查出来大于0说明该时间段已有排课返回提示。3.5 关键技术点权限、文件上传、地图与视频家教系统里还有几个值得单独写进论文的关键技术点。权限这块RuoYi后端默认用PreAuthorize(ss.hasPermi(tutor:course:add))这种注解做接口鉴权前端用v-hasPermi指令控制按钮显示。做毕设时建议把每个业务接口的权限标识都配置好演示的时候管理员账号和教师账号登录看到的界面完全不同这个效果非常直观。文件上传在RuoYi里开箱即用本地路径配置在application.yml的ruoyi.profile字段。教师上传资质证明、课程封面都走这个接口。注意如果要部署到服务器需要把上传路径改成服务器上的绝对路径并且给Nginx配置一个静态资源映射否则上传的图片无法通过URL访问。地图和视频是加分项。如果系统做线下家教希望教师列表展示地理位置可以用腾讯地图JavaScript API GL在Vue组件里通过script标签引入SDK然后用经纬度做标记点展示。注意需要去控制台申请Key开发阶段可以不校验域名白名单部署后必须配置。视频方面如果是录播课在线播放m3u8格式需要前端用hls.js做转换Element UI本身没有封装播放器可以自己封装一个video组件把hls.js实例挂到video标签上。4. 实操部署与二次开发指南4.1 本地环境准备先把环境搞定。RuoYi-Vue官方推荐的运行环境是JDK 1.8、MySQL 5.7或8.0、Redis 3.x以上、Maven 3.6以上、Node.js 12以上。如果你拿到的是标题里这个打包好的.zip项目解压后应该是ruoyi-ui前端和后端多模块工程两个目录。后端Idea打开时记得先配置Maven的settings.xml指向阿里云镜像不然下载依赖能让你等到怀疑人生。JDK版本这里多说一句热词里有ruoyi docker jdk17说明有人试着用JDK17跑RuoYi。坦率讲RuoYi官方推荐JDK1.8如果你图省事就用1.8如果老师要求高版本JDK你得处理CGLIB代理和反射相关的兼容问题这个折腾成本不低非必要不建议。前端依赖安装是另一个大坑。有同学npm install之后报the project can not found node_modules本质就是依赖没装全。建议使用npm install命令时如果失败优先检查Node版本和registry源。也可以用淘宝镜像源npm config set registry https://registry.npmmirror.com实测下载速度能快好几倍。4.2 数据库初始化和配置调整数据库初始化分两步。第一步创建数据库字符集选utf8mb4注意不是utf8utf8mb4才能完整支持中文和特殊字符。第二步导入RuoYi自带的ry_xxx.sql脚本这个文件在项目sql目录下导入后系统就能跑起来。如果你拿到的是已经做好的家教系统项目压缩包里应该还有一份业务库的SQL里面应该包含t_course、t_order这些业务表。导入顺序很重要先导RuoYi基础SQL再导业务SQL。数据库连接配置在ruoyi-admin/src/main/resources/application-druid.yml里。需要改三处url中的数据库地址、username、password。如果MySQL端口不是默认的3306记得一并改掉。Redis配置在application.yml里默认连127.0.0.1:6379如果你本机Redis有密码也要填上。注意RuoYi启动时会检查Redis连接Redis没启动的话后端会一直报错所以本地跑项目之前一定先启动Redis服务。我见过太多同学在这里卡一晚上。4.3 后端启动验证后端启动比较简单找到ruoyi-admin模块里的RuoYiApplication类右键运行。日志里如果出现Started RuoYiApplication字样说明启动成功。默认端口8080启动后建议先用浏览器或Postman访问http://localhost:8080如果能返回一个服务启动成功之类的提示就说明后端没问题。接口文档方面RuoYi自带Swagger访问路径是/swagger-ui/index.html可以快速查看所有Controller接口的入参和出参调试业务接口时很有用。4.4 前端启动与环境变量配置前端项目启动前先看根目录的.env.development文件里面写了VUE_APP_BASE_API这个环境变量默认是/dev-api前端通过Vue CLI的代理把请求转发到后端8080端口。代理配置在vue.config.js里代码类似proxy: { /dev-api: { target: http://localhost:8080, changeOrigin: true, pathRewrite: { ^/dev-api: } } }这个配置的意思是前端请求/dev-api/system/user/list会被转发到http://localhost:8080/system/user/list。如果后端启动在其他端口改这里的target即可。在ruoyi-ui目录下执行npm install装完依赖后执行npm run dev启动成功后浏览器访问http://localhost:80或控制台提示的端口用admin账号登录。注意第一次安装依赖时间可能比较长耐心等待。如果npm install中途报错可以把node_modules目录删掉重新装这个操作我干过不下十次。4.5 二次开发从建表到页面生成拿到项目后你肯定要改造成自己的家教系统。RuoYi的代码生成器是整个二次开发流程里效率最高的一环强烈建议用好。第一步在数据库里建好你的业务表注释要写得规范字段要有备注因为生成器会读取注释作为代码的说明。第二步在系统工具_代码生成里选择数据源找到刚才建的表点击导入。第三步配置生成信息包括类名比如TutorCourse、包名com.ruoyi、模块名tutor、生成模板单表或树表。生成方式可以选按包下载会生成一个zip。第四步把zip里的文件解压到对应目录controller放到ruoyi-adminservice和mapper放到ruoyi-system前端vue文件放到src/views/tutor下API文件放到src/api/tutor下。第五步在菜单管理里创建菜单并给菜单添加按钮权限标识把权限标识配给管理员角色。第六步重启后端刷新前端新页面就出来了。这个过程我在实际跑通之后最大的感受是RuoYi生成器生成的代码可以跑但业务逻辑绝不能只靠生成器。生成的页面是通用的增删改查你要在此基础上增加预约按钮、排课时间选择器、评价星级组件等业务元素。代码生成器解决的是基础框架问题业务价值还是要靠手动开发。5. 常见问题与避坑记录5.1 环境启动类问题后端启动报Application run failed、端口占用、数据库连接失败这类问题占毕设排查的一半。端口占用最简单netstat -ano | findstr 8080Windows或lsof -i:8080macOS/Linux找到占用进程杀掉即可。数据库连接失败重点看application-druid.yml里url的时区参数serverTimezoneAsia/Shanghai这个不设置的话MySQL 8.x必然报时区错误连不上数据库。Redis连接失败的话先确认Redis是否启动。Windows命令行启动Redis直接把redis-server.exe拖进终端回车即可macOS如果装了Homebrewbrew services start redis命令搞定。还有一个小概率问题Redis设置过密码但配置里没填或者在配置里填了密码但Redis改成了无密码模式这两种都会导致认证失败。5.2 RuoYi框架认知类问题前端登录后菜单空白是新手上路最大的拦路虎。原因通常是以下几点之一数据库里菜单配置没导入完整、当前登录用户的角色没有分配菜单权限、动态路由没加载成功。排查思路是先看接口返回登录后打开开发者工具Network里找getRouters这个请求看返回的JSON里是否包含菜单数据如果返回为空回数据库检查sys_menu表里是否有对应菜单以及sys_role_menu关联是否正确。这个排查流程走一遍你就能理解RuoYi动态路由的加载机制了。还有同学问RuoYi和Spring Security版本的问题。RuoYi-Vue官方有两个分支RuoYi-Vue基于Spring SecurityRuoYi-Vue旧版本基于ShiroShiro版本使用单表登录。下载项目时看清楚是哪个版本因为两者的权限注解和登录逻辑写法不同。一般新版RuoYi-Vue默认是Spring Security代码里用PreAuthorize注解做权限控制密码加密用BCrypt。如果看到网上教程用的是RequiresPermissions那可能是老版本的Shiro写法别直接照抄。5.3 Vue前端类问题热词里vue is not defined这种报错通常是忽略了对Vue的引入方式。在Vue 2项目中组件内用Vue对象时不要忘记import Vue from vue新版Element UI按需引入时也要注意Vue.use的调用顺序顺序错了同样会报错。node_modules找不到的问题前面提过这里再补充一个操作建议不要用cnpm它虽然快但依赖的目录结构和npm有些差异RuoYi这类严格的项目可能跑出奇怪的Bug。实在要用镜像直接设置npm官方registry的镜像源依然用npm命令操作最稳。热词里还有vue devtools插件下载。调试Vue项目强烈建议安装Vue DevtoolsChrome插件商店直接搜Vue.js devtools安装即可登录页面和菜单页面打开可以看到组件树和Vuex状态。排查菜单为何空白时在Devtools里看store里的permission路由数组是否被正确赋值能快速定位问题环节。5.4 业务实现类问题排课时间冲突是家教系统里最容易出现的业务Bug。仅仅靠前端禁用某些时间段不够因为用户可以同时开两个页面提交。后端Service层必须做校验逻辑就是前面给的重叠区间查询SQL。实际开发中建议再加一层数据库乐观锁或唯一索引防止并发请求穿透校验不过毕设阶段能把Service校验做好就已经够优秀了。课时状态流转错乱常见原因是页面多次点击提交按钮。解决方案是在前端提交后给按钮加loading状态同时后端在状态流转前做判断状态不匹配直接抛异常。RuoYi的Service事务管理默认只回滚RuntimeException业务异常如果要回滚需要自己抛出RuntimeException类型或者使用Transactional(rollbackFor Exception.class)注解。这块是面试和答辩的高频问题值得提前准备理解。使用腾讯地图展示家教位置时有一个常见坑地图初始化时容器还没渲染完成导致地图显示空白。解决办法是在Vue的nextTick回调里初始化地图组件this.$nextTick(() { this.map new TMap.Map(this.$refs.mapContainer, {...}); });如果是列表循环多个地图组件还需要注意lat和lng的类型接口返回的坐标可能是字符串地图API要求数字提前Number()转换一下否则标记点不显示。m3u8视频播放失败排查方向如下第一确认视频文件本身能不能通过浏览器直接访问第二hls.js的CORS配置如果视频文件在OSS或CDN上跨域响应头必须正确第三如果是混合内容HTTPS页面引入HTTP视频浏览器会直接拦截本地开发用http://localhost问题不大部署到HTTPS环境就必须让视频源也支持HTTPS。6. 拿去答辩时的扩展建议这块算是我额外送的经验。如果你的毕设题目是这个答辩时不能只讲功能还要能讲清楚设计决策。比如老师问你为什么选RuoYi不要只说速度快要说RuoYi提供了成熟的RBAC权限模型和代码生成机制让我能把精力集中在家教业务的核心流程上这符合软件工程中复用成熟组件、聚焦核心业务的理念。如果想让项目更有竞争力可以考虑加这三个扩展方向。第一个方向是课程评价的算法优化。普通评价是星级加文本你可以在此基础上做教师综合分综合分由评分均值、评价数量、响应速度等维度加权计算在教师列表页按综合分排序。这个功能工作量和复杂度适中但讲出来很唬人。第二个方向是数据可视化大屏。RuoYi自带Echarts依赖你可以做一个管理员数据大屏页面展示平台GMV趋势、各科目预约占比、教师排行Top10、课时消课热力图。用Echarts做几个图表拼一个页面配上一句基于Echarts实现平台运营指标可视化轻松多两页论文篇幅。第三个方向是消息通知。RuoYi集成过WebSocket可以在教师确认排课、课时完成、订单取消这些节点给对应角色发送站内消息提醒。这个功能在真实业务中不可或缺——线上服务不像线下面对面沟通一切通知都要靠系统主动推送。最后我根据自己的实际操作补一句踩坑心得这类系统项目最怕的不是技术壁垒而是你花了大量时间在环境配置和框架适配的杂活上。拿到一个陌生的RuoYi项目第一步要做的不是看代码而是先启动起来、登录进去、点到每个菜单看一遍对项目有什么功能、数据结构长什么样心里有数再开始自己的改造。这个流程走下来后面写代码会顺很多。我上面写的这些内容基本覆盖了从拿到项目到跑通改造再到答辩展示的全过程照着这个思路去准备至少能让你的毕设少走一大半弯路。本文还有配套的精品资源点击获取 
长河君 · 2026/8/31 21:53:00 · 阅读 1.2k 基于RuoYi-Vue的家教系统开发实战：从架构到避坑全指南
简介这是一套面向计算机相关专业本科生的毕业设计与课程设计实战项目——基于Ruoyi-Vue框架开发的家教一体化系统适用于计科、人工智能、通信工程等方向的学生完成毕设、课设或大作业也适合初学者通过完整业务系统理解前后端协同开发流程。资源包共708个文件涵盖303个Java后端逻辑文件、113个Vue前端组件、83个JS交互脚本、36个XML配置及3个SQL数据库脚本辅以bat自动化构建脚本和多环境配置文件.env.development等整体压缩包仅5.36MB结构清晰、模块解耦明确。已有79人下载学习项目经实机部署验证所有功能模块均可正常运行答辩平均分达96分配套README详述启动步骤与模块说明支持二次开发与功能扩展可直接用于演示、教学或项目立项原型。1. 项目定位与核心需求拆解1.1 家教行业的业务痛点做毕业设计选题的时候我见过太多人一上来就挑学生管理系统图书管理系统这类老掉牙的题目答辩时老师一眼就能看穿工作量。家教一体化系统这个方向表面看也是管理类系统但它的业务链条比传统的单角色CRUD要长得多涵盖了用户注册、课程发布、在线预约、课时管理、评价反馈、统计分析等多个环节非常适合用来展示前后端分离开发的完整能力。先看家教行业的实际场景。家长想给孩子找个靠谱的老师靠的是朋友介绍、线下中介或者各种信息平台。老师想接单往往也是通过微信群、熟人转介绍。这个过程中有几个痛点特别明显第一供需信息不透明家长找不到合适的老师老师找不到稳定的生源第二试听、排课、课时记录全部靠人工沟通时间一长就乱第三课消统计和费用结算没有统一口径容易扯皮。家教一体化系统要解决的就是把这些线下散落的流程搬到线上让家长、老师、平台管理员三方在同一个系统里完成信息匹配和服务闭环。把痛点翻译成系统需求核心就一句话让不同角色在统一的平台上完成信息发布、预约、确认、执行、评价的完整闭环。围绕这句话往下拆系统就至少需要三类角色的支撑——管理员做平台运营和审核教师做课程供给和服务执行学生/家长做需求发起和服务反馈。至于具体功能后面第2章会展开。1.2 为什么选 RuoYi-Vue 作为基座确定了业务方向后接下来就是技术选型。我见过不少同学直接裸写Spring Boot加Vue从零搭权限系统、用户系统、日志系统结果光基础功能就写了一两个月留给业务功能的时间所剩无几。这个项目选型RuoYi-Vue核心原因有三个。第一RuoYi是国内使用率极高的开源后台管理框架基于Spring Boot和Vue实现前后端分离自带完整的RBAC权限体系、用户管理、菜单管理、字典管理、操作日志、定时任务、代码生成器。这些是几乎所有后台系统都需要的通用能力不需要重复造轮子。第二RuoYi的代码生成器可以根据数据库表直接生成Java代码和Vue页面对于毕业设计这种需要赶时间的项目来说相当于把CRUD部分的开发效率提了一倍以上。第三RuoYi的社区活跃度很高遇到问题随便一搜就有解决方案对经验不够丰富的学生党来说这一点太重要了。当然选型RuoYi也有需要注意的地方。它的框架代码风格偏传统没有Spring Cloud那套微服务体系但这恰恰是毕业设计该有的复杂度——单体应用加前后端分离既能展示技术能力又不会把工程量撑爆。另外RuoYi自带的功能默认是英文菜单部分版本或通用业务你需要花时间把菜单、权限配置成家教业务的专属结构。这块我在第4章实操部分会详细说。2. 系统功能模块全解2.1 平台管理端管人、管课、管数据先看管理端。管理端是平台运营方使用的后台也是RuoYi框架原本就很擅长的部分。核心功能包括管理员管理、教师审核、课程科目管理、订单监控、数据统计等。教师入驻审核是管理端一个非常重要的功能。家长对老师的信任度直接决定成交率所以系统里我会设计一个教师认证的流程。用户注册为教师后需要提交资质信息比如学历认证、教学经历状态默认为待审核。管理员登录后台看到待审核列表点击详情查看资料审核通过后教师在用户端的教师认证标识才会点亮。这个功能本质上是RuoYi通用用户表的一个状态字段扩展但业务价值很高写论文和答辩时都能拿出来讲。订单监控和课时消课监控也建议放在管理端。家长预约课程、教师确认排课、实际上课打卡、课时费结算这些关键节点的数据都应该在管理端有可视化的列表和统计图表方便平台方知道系统每天产生了多少交易、有多少课被消化掉。2.2 教师端课程发布与课时管理教师端是业务链条里的供给方。教师在完成认证后可以在系统里发布课程课程信息包括课程名称、适用年级、科目、授课方式线上/线下、课时单价、可授课时段。这块的难点在于数据建模一门课程对应一个教师一个教师可以发布多门课程数据库里要用外键关联好。排课管理是教师端的核心也是最容易出Bug的地方。一个合理的排课系统需要做到教师在某个时间段已经排了课就不能再排新的课家长预约某个时段后其他家长看不到这个时段。最简单的实现思路是设计一张可用课时表教师先维护自己未来N天的可授课时段家长预约时段后把状态改成已预约冲突判断在生成可授课时段时做一次即可。如果想让系统更智能可以再加一个排课冲突校验的工具类但毕设阶段做到状态机层面就够了。课时记录同样值得做细。每完成一节课教师端可以提交课时小结记录上课内容、学生表现、课后练习建议。家长端可以看到这些记录形成服务的留痕。课时记录表要和订单表、课程表做关联同时在管理端能够按教师、按时间维度统计课时消课情况方便后续做课时费结算。2.3 学生与家长端找老师、约课、看反馈学生/家长端的消费路径可以拆成两条一条是找老师一条是上完课后的反馈闭环。找老师的场景系统需要提供课程搜索和教师列表。搜索条件应该包括科目、年级、授课方式、价格区间、好评率排序这些条件在SQL层面都可以通过RuoYi生成的查询条件扩展实现。课程详情页要展示教师信息、课程介绍、课时单价、已购人数和历史评价。这里我要提一个热词里的点——有同学问vue播放m3u8怎么处理。如果课程包含线上录播视频视频回放建议用m3u8格式做切片前端用video.js配合hls.js播放兼容性比直接放mp4好很多拖动进度也流畅。把视频地址放在课程详情里已经购买的学员可以点击播放这是系统的加分项。反馈闭环包括预约、支付模拟、上课打卡、评价。考虑到毕业设计不接入真实支付可以用一个预约下单按钮代替支付环节订单状态从待上课到已完成。上完课后家长可以给教师打分和写评价评价数据反哺到教师列表的好评率和精选评价模块。这样一个消费闭环就完整了。2.4 核心业务闭环与状态机设计整个系统最核心的业务闭环是教师发布课程 - 家长搜索浏览 - 家长预约下单 - 教师确认排课 - 按时上课 - 提交课时记录 - 家长评价 - 管理员统计分析。围绕这个闭环订单表的状态设计至关重要。我的建议是订单状态至少要有这几个待确认家长下单后等待教师确认、待上课教师已确认、已完成课时记录提交且家长评价完成、已取消任何一方在待确认状态下都可取消。在代码层面这个状态机可以用一个枚举类来定义在Service层做状态流转的校验。这里给一个通用的状态校验模板思路public enum OrderStatus { PENDING_CONFIRM(0, 待确认), TO_BE_HELD(1, 待上课), COMPLETED(2, 已完成), CANCELLED(3, 已取消); private final Integer code; private final String desc; // 构造方法、getter... }每次更新订单状态前先用当前状态和期望流转的目标状态做一次合法性校验不允许跳状态。这个设计在答辩时是很好的亮点说明你考虑了业务健壮性而不只是写了增删改查。3. 技术栈选型与架构分析3.1 RuoYi-Vue 的架构成熟度RuoYi-Vue这个组合在毕业设计里的地位相当于手机圈的水桶机——它未必有最惊艳的单项能力但整体素质均衡什么场景都能打。前端是Vue 2 Element UI Vuex Vue Router后端是Spring Boot MyBatis Shiro或Spring Security取决于你下的版本配套MySQL和Redis。对于毕设级别的项目这套组合无论从开发效率还是答辩展示角度都完全够用。我尤其想说的是RuoYi的权限设计。它基于RBACRole-Based Access Control基于角色的访问控制模型用户-角色-菜单三层解耦。你在系统管理-角色管理里给某个角色勾选菜单权限该角色下的用户登录后只能看到被授权的菜单和接口。对于家教系统来说管理员、教师、家长天然就是三种角色用RuoYi的权限体系可以非常清爽地完成界面隔离和数据权限隔离。这里的数据权限不只是菜单级别RuoYi还有数据范围控制可以按角色配置仅查看本人数据教师端只能用自己ID查询课程数据就是这个机制实现的。3.2 后端目录结构与分层思路第一次打开RuoYi后端项目的人往往会对着一大堆模块发懵。我这里逐个讲清楚。RuoYi-Vue后端是一个Maven多模块工程主要模块包括ruoyi-admin、ruoyi-framework、ruoyi-system、ruoyi-common、ruoyi-quartz、ruoyi-generator。ruoyi-admin启动模块包含Controller层也是系统的入口。ruoyi-framework框架核心配置包括安全配置、拦截器、AOP切面、Redis配置等。ruoyi-system业务模块包含Service和Mapper。ruoyi-common公共工具模块包括通用常量、工具类、统一返回结果。ruoyi-quartz定时任务模块。ruoyi-generator代码生成模块。在RuoYi中写业务代码Controller放在ruoyi-admin的web目录下Service接口和实现放在ruoyi-system的service目录Mapper接口和XML放在ruoyi-system的mapper目录。做家教系统时建议单独包一层比如com.ruoyi.web.controller.tutor、com.ruoyi.system.service.impl.TutorCourseServiceImpl这样自己的业务代码和框架代码之间有清晰的边界后续升级框架版本也不会互相干扰。分层设计上我强烈建议遵守RuoYi自带的规范Controller只做参数接收、调用Service、返回结果Service层写业务逻辑Mapper层访问数据库。不要图省事在Controller里怼SQL后期维护会非常痛苦。RuoYi的AOP日志切面默认记录了所有Controller的访问日志操作日志记录在sys_oper_log表这在答辩演示环节很有展示价值。3.3 前端目录结构与Vue实践前端Vue项目默认是vue-element-admin风格核心目录包括src/api按业务模块拆分的接口定义文件比如tutorCourse.js、tutorOrder.js。src/views页面组件一个页面通常对应一个目录目录里包含index.vue。src/components公共组件比如上传组件、富文本编辑器。src/router路由配置。RuoYi支持后端动态路由菜单从后端数据库读取前端根据菜单配置动态生成路由表。src/storeVuex状态管理存放用户信息、权限标识、标签页状态。这里和热词里对应的几个Vue知识点可以串起来说。比如vue-router中RuoYi默认使用history模式但打包部署到Nginx时需要配置try_files否则刷新页面会404。有同学在本地npm run dev跑得好好的一部署就白屏九成是这个问题。再比如vue keep-alive。RuoYi内置了标签页导航功能也就是热词里的$tab.closeOpenPage相关功能点击左侧菜单会在顶部生成标签页切换标签页时默认会缓存页面状态。如果你在做课时列表页发现切换路由再回来时el-table滚动条位置或者查询条件丢了那就是keep-alive缓存策略没生效。RuoYi路由配置里meta有个keepAlive字段只有设为true的页面才会被keep-alive包裹缓存。打开代码看src/layout/components/AppMain.vue逻辑很清晰keep-alive router-view v-if$route.meta.keepAlive / /keep-alive router-view v-if!$route.meta.keepAlive /如果你的列表页在切换课程分类后表格滚回顶部重点检查页面name和路由meta.keepAlive是否匹配。这个坑我在第5章还会提到。vue computed的计算属性在课时费展示这类场景很实用。比如教师首页要汇总本月完成课时数和预期收入完全可以用computed基于list数据做计算数据变化时视图自动更新比在methods里手动累加优雅得多。3.4 数据库设计要点数据库设计是毕业设计的核心评分点之一。家教系统我建议至少准备这些核心表用户表可以在RuoYi的sys_user上扩展、教师认证信息表、课程表、可预约课时表、订单表、课时记录表、评价表、科目字典表。课程表建议这样设计字段名类型说明idbigint主键teacher_idbigint教师用户ID关联sys_usersubjectvarchar科目关联字典gradevarchar适用年级teach_modechar线上/线下pricedecimal课时单价covervarchar课程封面本地文件路径introtext课程介绍statuschar上架/下架/审核中可预约课时表是这个系统的设计亮点。字段包括id、course_id、teacher_id、start_time、end_time、status可用/已预约/已完成。每次教师新增排课时在Service层做一次时间段重叠校验。这里给个SQL思路SELECT count(*) FROM t_teacher_slot WHERE teacher_id #{teacherId} AND status ! CANCELLED AND (start_time #{endTime} AND end_time #{startTime})如果查出来大于0说明该时间段已有排课返回提示。3.5 关键技术点权限、文件上传、地图与视频家教系统里还有几个值得单独写进论文的关键技术点。权限这块RuoYi后端默认用PreAuthorize(ss.hasPermi(tutor:course:add))这种注解做接口鉴权前端用v-hasPermi指令控制按钮显示。做毕设时建议把每个业务接口的权限标识都配置好演示的时候管理员账号和教师账号登录看到的界面完全不同这个效果非常直观。文件上传在RuoYi里开箱即用本地路径配置在application.yml的ruoyi.profile字段。教师上传资质证明、课程封面都走这个接口。注意如果要部署到服务器需要把上传路径改成服务器上的绝对路径并且给Nginx配置一个静态资源映射否则上传的图片无法通过URL访问。地图和视频是加分项。如果系统做线下家教希望教师列表展示地理位置可以用腾讯地图JavaScript API GL在Vue组件里通过script标签引入SDK然后用经纬度做标记点展示。注意需要去控制台申请Key开发阶段可以不校验域名白名单部署后必须配置。视频方面如果是录播课在线播放m3u8格式需要前端用hls.js做转换Element UI本身没有封装播放器可以自己封装一个video组件把hls.js实例挂到video标签上。4. 实操部署与二次开发指南4.1 本地环境准备先把环境搞定。RuoYi-Vue官方推荐的运行环境是JDK 1.8、MySQL 5.7或8.0、Redis 3.x以上、Maven 3.6以上、Node.js 12以上。如果你拿到的是标题里这个打包好的.zip项目解压后应该是ruoyi-ui前端和后端多模块工程两个目录。后端Idea打开时记得先配置Maven的settings.xml指向阿里云镜像不然下载依赖能让你等到怀疑人生。JDK版本这里多说一句热词里有ruoyi docker jdk17说明有人试着用JDK17跑RuoYi。坦率讲RuoYi官方推荐JDK1.8如果你图省事就用1.8如果老师要求高版本JDK你得处理CGLIB代理和反射相关的兼容问题这个折腾成本不低非必要不建议。前端依赖安装是另一个大坑。有同学npm install之后报the project can not found node_modules本质就是依赖没装全。建议使用npm install命令时如果失败优先检查Node版本和registry源。也可以用淘宝镜像源npm config set registry https://registry.npmmirror.com实测下载速度能快好几倍。4.2 数据库初始化和配置调整数据库初始化分两步。第一步创建数据库字符集选utf8mb4注意不是utf8utf8mb4才能完整支持中文和特殊字符。第二步导入RuoYi自带的ry_xxx.sql脚本这个文件在项目sql目录下导入后系统就能跑起来。如果你拿到的是已经做好的家教系统项目压缩包里应该还有一份业务库的SQL里面应该包含t_course、t_order这些业务表。导入顺序很重要先导RuoYi基础SQL再导业务SQL。数据库连接配置在ruoyi-admin/src/main/resources/application-druid.yml里。需要改三处url中的数据库地址、username、password。如果MySQL端口不是默认的3306记得一并改掉。Redis配置在application.yml里默认连127.0.0.1:6379如果你本机Redis有密码也要填上。注意RuoYi启动时会检查Redis连接Redis没启动的话后端会一直报错所以本地跑项目之前一定先启动Redis服务。我见过太多同学在这里卡一晚上。4.3 后端启动验证后端启动比较简单找到ruoyi-admin模块里的RuoYiApplication类右键运行。日志里如果出现Started RuoYiApplication字样说明启动成功。默认端口8080启动后建议先用浏览器或Postman访问http://localhost:8080如果能返回一个服务启动成功之类的提示就说明后端没问题。接口文档方面RuoYi自带Swagger访问路径是/swagger-ui/index.html可以快速查看所有Controller接口的入参和出参调试业务接口时很有用。4.4 前端启动与环境变量配置前端项目启动前先看根目录的.env.development文件里面写了VUE_APP_BASE_API这个环境变量默认是/dev-api前端通过Vue CLI的代理把请求转发到后端8080端口。代理配置在vue.config.js里代码类似proxy: { /dev-api: { target: http://localhost:8080, changeOrigin: true, pathRewrite: { ^/dev-api: } } }这个配置的意思是前端请求/dev-api/system/user/list会被转发到http://localhost:8080/system/user/list。如果后端启动在其他端口改这里的target即可。在ruoyi-ui目录下执行npm install装完依赖后执行npm run dev启动成功后浏览器访问http://localhost:80或控制台提示的端口用admin账号登录。注意第一次安装依赖时间可能比较长耐心等待。如果npm install中途报错可以把node_modules目录删掉重新装这个操作我干过不下十次。4.5 二次开发从建表到页面生成拿到项目后你肯定要改造成自己的家教系统。RuoYi的代码生成器是整个二次开发流程里效率最高的一环强烈建议用好。第一步在数据库里建好你的业务表注释要写得规范字段要有备注因为生成器会读取注释作为代码的说明。第二步在系统工具_代码生成里选择数据源找到刚才建的表点击导入。第三步配置生成信息包括类名比如TutorCourse、包名com.ruoyi、模块名tutor、生成模板单表或树表。生成方式可以选按包下载会生成一个zip。第四步把zip里的文件解压到对应目录controller放到ruoyi-adminservice和mapper放到ruoyi-system前端vue文件放到src/views/tutor下API文件放到src/api/tutor下。第五步在菜单管理里创建菜单并给菜单添加按钮权限标识把权限标识配给管理员角色。第六步重启后端刷新前端新页面就出来了。这个过程我在实际跑通之后最大的感受是RuoYi生成器生成的代码可以跑但业务逻辑绝不能只靠生成器。生成的页面是通用的增删改查你要在此基础上增加预约按钮、排课时间选择器、评价星级组件等业务元素。代码生成器解决的是基础框架问题业务价值还是要靠手动开发。5. 常见问题与避坑记录5.1 环境启动类问题后端启动报Application run failed、端口占用、数据库连接失败这类问题占毕设排查的一半。端口占用最简单netstat -ano | findstr 8080Windows或lsof -i:8080macOS/Linux找到占用进程杀掉即可。数据库连接失败重点看application-druid.yml里url的时区参数serverTimezoneAsia/Shanghai这个不设置的话MySQL 8.x必然报时区错误连不上数据库。Redis连接失败的话先确认Redis是否启动。Windows命令行启动Redis直接把redis-server.exe拖进终端回车即可macOS如果装了Homebrewbrew services start redis命令搞定。还有一个小概率问题Redis设置过密码但配置里没填或者在配置里填了密码但Redis改成了无密码模式这两种都会导致认证失败。5.2 RuoYi框架认知类问题前端登录后菜单空白是新手上路最大的拦路虎。原因通常是以下几点之一数据库里菜单配置没导入完整、当前登录用户的角色没有分配菜单权限、动态路由没加载成功。排查思路是先看接口返回登录后打开开发者工具Network里找getRouters这个请求看返回的JSON里是否包含菜单数据如果返回为空回数据库检查sys_menu表里是否有对应菜单以及sys_role_menu关联是否正确。这个排查流程走一遍你就能理解RuoYi动态路由的加载机制了。还有同学问RuoYi和Spring Security版本的问题。RuoYi-Vue官方有两个分支RuoYi-Vue基于Spring SecurityRuoYi-Vue旧版本基于ShiroShiro版本使用单表登录。下载项目时看清楚是哪个版本因为两者的权限注解和登录逻辑写法不同。一般新版RuoYi-Vue默认是Spring Security代码里用PreAuthorize注解做权限控制密码加密用BCrypt。如果看到网上教程用的是RequiresPermissions那可能是老版本的Shiro写法别直接照抄。5.3 Vue前端类问题热词里vue is not defined这种报错通常是忽略了对Vue的引入方式。在Vue 2项目中组件内用Vue对象时不要忘记import Vue from vue新版Element UI按需引入时也要注意Vue.use的调用顺序顺序错了同样会报错。node_modules找不到的问题前面提过这里再补充一个操作建议不要用cnpm它虽然快但依赖的目录结构和npm有些差异RuoYi这类严格的项目可能跑出奇怪的Bug。实在要用镜像直接设置npm官方registry的镜像源依然用npm命令操作最稳。热词里还有vue devtools插件下载。调试Vue项目强烈建议安装Vue DevtoolsChrome插件商店直接搜Vue.js devtools安装即可登录页面和菜单页面打开可以看到组件树和Vuex状态。排查菜单为何空白时在Devtools里看store里的permission路由数组是否被正确赋值能快速定位问题环节。5.4 业务实现类问题排课时间冲突是家教系统里最容易出现的业务Bug。仅仅靠前端禁用某些时间段不够因为用户可以同时开两个页面提交。后端Service层必须做校验逻辑就是前面给的重叠区间查询SQL。实际开发中建议再加一层数据库乐观锁或唯一索引防止并发请求穿透校验不过毕设阶段能把Service校验做好就已经够优秀了。课时状态流转错乱常见原因是页面多次点击提交按钮。解决方案是在前端提交后给按钮加loading状态同时后端在状态流转前做判断状态不匹配直接抛异常。RuoYi的Service事务管理默认只回滚RuntimeException业务异常如果要回滚需要自己抛出RuntimeException类型或者使用Transactional(rollbackFor Exception.class)注解。这块是面试和答辩的高频问题值得提前准备理解。使用腾讯地图展示家教位置时有一个常见坑地图初始化时容器还没渲染完成导致地图显示空白。解决办法是在Vue的nextTick回调里初始化地图组件this.$nextTick(() { this.map new TMap.Map(this.$refs.mapContainer, {...}); });如果是列表循环多个地图组件还需要注意lat和lng的类型接口返回的坐标可能是字符串地图API要求数字提前Number()转换一下否则标记点不显示。m3u8视频播放失败排查方向如下第一确认视频文件本身能不能通过浏览器直接访问第二hls.js的CORS配置如果视频文件在OSS或CDN上跨域响应头必须正确第三如果是混合内容HTTPS页面引入HTTP视频浏览器会直接拦截本地开发用http://localhost问题不大部署到HTTPS环境就必须让视频源也支持HTTPS。6. 拿去答辩时的扩展建议这块算是我额外送的经验。如果你的毕设题目是这个答辩时不能只讲功能还要能讲清楚设计决策。比如老师问你为什么选RuoYi不要只说速度快要说RuoYi提供了成熟的RBAC权限模型和代码生成机制让我能把精力集中在家教业务的核心流程上这符合软件工程中复用成熟组件、聚焦核心业务的理念。如果想让项目更有竞争力可以考虑加这三个扩展方向。第一个方向是课程评价的算法优化。普通评价是星级加文本你可以在此基础上做教师综合分综合分由评分均值、评价数量、响应速度等维度加权计算在教师列表页按综合分排序。这个功能工作量和复杂度适中但讲出来很唬人。第二个方向是数据可视化大屏。RuoYi自带Echarts依赖你可以做一个管理员数据大屏页面展示平台GMV趋势、各科目预约占比、教师排行Top10、课时消课热力图。用Echarts做几个图表拼一个页面配上一句基于Echarts实现平台运营指标可视化轻松多两页论文篇幅。第三个方向是消息通知。RuoYi集成过WebSocket可以在教师确认排课、课时完成、订单取消这些节点给对应角色发送站内消息提醒。这个功能在真实业务中不可或缺——线上服务不像线下面对面沟通一切通知都要靠系统主动推送。最后我根据自己的实际操作补一句踩坑心得这类系统项目最怕的不是技术壁垒而是你花了大量时间在环境配置和框架适配的杂活上。拿到一个陌生的RuoYi项目第一步要做的不是看代码而是先启动起来、登录进去、点到每个菜单看一遍对项目有什么功能、数据结构长什么样心里有数再开始自己的改造。这个流程走下来后面写代码会顺很多。我上面写的这些内容基本覆盖了从拿到项目到跑通改造再到答辩展示的全过程照着这个思路去准备至少能让你的毕设少走一大半弯路。本文还有配套的精品资源点击获取