Uniapp+SpringBoot+Vue：公考移动学习平台全栈实践

做公考在线学习平台这个项目是我去年完整跟下来的一个商业项目。客户的诉求很直接要一套能在手机App、微信小程序同时跑起来的学习系统覆盖视频课、题库刷题、错题本、模拟考试这几个核心场景还得配一个运营人员能轻松维护内容的管理后台。当时摆在面前的可选方案不少原生开发、跨端框架、纯H5都能做反复对比之后我选了 Uniapp SpringBoot Vue 这套组合。原因也很简单Uniapp 一套代码出双端SpringBoot 后端生态成熟稳定Vue 做管理后台组件化程度高、上手快。这篇文章就围绕这套公考移动学习平台的完整设计实现来写从技术选型思路、数据库设计、客户端关键功能、后端安全防护到 Vue 管理后台的搭建再到我实际踩过的坑都会展开讲。如果你正准备做类似的在线教育、题库类项目或者正在评估 Uniapp 跨端方案能不能承载这类业务这篇文章应该能帮你省不少时间。1. 整体技术选型与架构设计1.1 为什么是 Uniapp 跨端方案公考学习平台的用户使用习惯很分裂有人习惯用安卓手机刷题有人用苹果手机看课还有相当一部分人喜欢在小程序里打卡学习。如果每个端都单独开发一遍原生应用光 UI 适配和发版节奏就能把人耗死。Uniapp 最核心的价值就在于它基于 Vue 语法编译一次就能产出 iOS、Android、微信小程序、H5 多端产物业务逻辑代码复用率能做到八九成。我选择 Uniapp 还有一层现实考量项目交付周期非常紧团队里熟悉 Vue 的成员可以直接上手不需要额外学习 Swift、Kotlin 或者小程序原生语法。对比 FlutterUniapp 对小程序端的支持更成熟原生 SDK 集成也方便比如需要接入微信登录、分享、支付时直接调用 uni API 就好。虽然 Uniapp 在复杂动画和极致性能上不如纯原生但对公考学习这类页面结构相对固定、交互不复杂的业务性能完全够用。1.2 前后端职责划分与协作模式后端我用 SpringBoot 2.7配合 MyBatis-Plus 做持久层MySQL 8.0 存储业务数据Redis 扛缓存和登录会话。整个后端拆成用户、课程、题库、考试、订单等模块采用经典的分层结构Controller 负责接收参数和返回结果Service 处理业务逻辑Mapper 访问数据库。这样的分层在多人协作时边界非常清晰每个人负责自己的模块代码冲突的概率低很多。管理后台用 Vue 3 Element Plus Vite 搭建。Vite 的开发服务器启动速度比 Webpack 快一个量级Element Plus 的表单、表格、弹窗组件做运营后台非常顺手。客户端通过 uni.request 封装好的请求模块访问后端接口管理后台通过 axios 实例访问同一套 API。前后端只通过 JSON 交互接口文档用 YApi 维护前端拿到文档就可以并行开发不依赖后端代码先写完。1.3 架构分层与请求链路从整体上看这个平台的请求链路是这样的用户在 Uniapp 客户端里触发某个操作客户端把 token 放在请求头里发给后端接口后端网关层先做 token 校验和权限判断然后进入对应的 ControllerController 调 ServiceService 操作 Mapper 访问 MySQL期间需要缓存的数据走 Redis最终结果统一封装成{ code, message, data }格式返回给前端。管理后台的请求链路完全一致只是在接口权限上做了区分比如管理端接口要求管理员角色才能访问。值得一提的是客户端、管理端、后端服务这三部分的部署是独立的。后端构建成 jar 包部署在云服务器上管理后台构建成静态文件部署在 Nginx 下客户端则是通过 HBuilderX 打包成安装包或者直接上传到小程序平台。这样每部分都可以独立迭代发版不需要牵一发动全身。2. 功能模块拆解与数据模型设计2.1 公考学习平台的核心功能地图动手写代码之前我先花了大量时间跟客户确认功能范围。公考学习平台用户端最核心的场景其实就四个看课、刷题、模考、复盘。具体拆开看看课指的是视频录播课的学习要有课程目录、播放进度记忆、上次看到哪里下次接着看刷题指的是按章节练习、历年真题练习做题时要有答案解析做完要自动记录模考指的是模拟真实考试环境限时答题、自动评分、生成成绩报告复盘指的是错题本功能做错的题自动进错题本同时支持用户手动收藏经典题目按知识点分类反复练习。管理后台的功能则围绕内容维护展开课程管理上传视频、设置章节、题库管理批量导入题目、维护答案解析、试卷管理组卷、设置考试时间、用户管理查看用户学习数据、订单管理处理 VIP 购买、内容管理发布备考资讯、公告。2.2 数据模型设计的关键取舍数据库设计是整个项目里最不能含糊的部分因为后续所有功能都建立在这套数据模型上。用户表user除了基础字段外我额外加了vip_expire_time用来判断会员是否过期study_duration累计学习时长这两个字段在很多查询场景里都能直接复用避免每次都去关联其他表计算。课程模块我设计了课程表、章节表、视频表三层结构。一个课程包含多个章节一个章节可以挂多个视频。为什么单独拆出视频表因为视频的时长、大小、转码状态这些属性跟章节内容关系不大单独存放更灵活而且后面要接入视频点播服务时改动面最小。题库模块是重头戏。题目表question我设计了question_type字段区分单选、多选、判断三种题型analysis字段存解析内容difficulty字段标难度级别。这里有个我踩过的坑一开始想着把选项直接存成 JSON 字符串塞进一个字段后来发现查询和统计特别痛苦最后规规矩矩拆出了question_option子表每条选项一行记录。错题本我用了独立的wrong_book表记录用户 ID、题目 ID、错误答案、错误次数、最后错误时间。这样做的好处是用户查看错题时可以直接 JOIN 题目表拿到完整的题干和解析而错误次数和最后错误时间这两个字段可以用来做智能复习提醒。2.3 学习记录与考试模块的设计思路学习记录表study_record记录了用户每次观看视频的进度字段包括user_id、video_id、watch_position看到第几秒、watch_duration本次看了多久。这个表的数据量增长很快我做了按用户 ID 的索引优化并且只保留最近 90 天的明细记录更早的数据做聚合统计。考试模块我设计了试卷表paper、试卷题目关联表paper_question、考试记录表exam_record。考试开始时生成一份考试记录状态标记为进行中用户每答一题答案实时保存到exam_answer表交卷时后端统一判分。这里的设计要点在于模拟考必须支持断点续考用户中途退出再进来还能看到之前的作答状态所以答案必须逐题落库不能等交卷才一次性提交。3. Uniapp 客户端的几个关键实现3.1 manifest 配置与多端打包Uniapp 项目的manifest.json是第一个要处理好的文件。很多人不重视这个文件的配置等到打包上线才发现各种问题。以我的项目为例微信小程序的mp-weixin.appid要提前填好App 端的app-plus节点下要声明需要用到的原生模块权限比如Payment微信支付、Share分享、Oauth微信登录。Android 的打包还要配置包名和版本号一旦上架后包名就不能改了。这里分享一个实战细节在 HBuilderX 里打包前一定要检查manifest.json里app-plus的distribute.sdkConfigs配置。微信登录和微信分享需要填微信开放平台生成的 AppID 和 AppSecret而且必须保证跟应用中配置的包名和签名一致否则真机调用时会一直报-1错误。我第一次打包就是因为这里填错了信息微信登录弹不出来排查了半天。3.2 多环境与多域名指向的处理Uniapp 项目开发时联调后端接口上线时要切换到正式服务器地址再加上管理后台可能部署在不同的域名下这就涉及多环境配置的问题。我的做法是在项目根目录建一个config.js根据不同的编译环境导出不同的配置项。// config.js const config { // 开发环境本地联调 dev: { baseUrl: http://192.168.1.100:8080, h5BaseUrl: http://192.168.1.100:8081 }, // 生产环境正式服务器 prod: { baseUrl: https://api.example.com, h5BaseUrl: https://admin.example.com } } // 通过 process.env.NODE_ENV 区分环境 const env process.env.NODE_ENV development ? dev : prod export default config[env]请求封装时根据当前运行平台拼接不同的 BaseURL。App 端和小程序端直接请求后端接口域名H5 端因为存在跨域问题需要在开发环境通过 devServer 的 proxy 把/api路径转发到后端地址生产环境则依靠 Nginx 反向代理解决跨域。这样做的好处是同一套代码在不同平台运行时会自动选择合适的请求域名不需要手工改代码。3.3 自定义分享好友功能的实现公考学习平台天然需要用户之间的分享拉新比如把某个免费课程分享给备考好友。微信小程序端的分享相对简单在页面中定义onShareAppMessage生命周期函数就行onShareAppMessage() { return { title: 我正在用这个App刷行测题推荐给你, path: /pages/course/detail?id123, imageUrl: https://api.example.com/share/course-banner.png } }App 端做分享则要复杂一些需要调用uni.share接口前提是 manifest 里已经配置好了分享相关的 SDK。这里有一个特别容易踩的坑分享图标的链接必须是可以公网访问的 HTTPS 地址不能是小程序本地图片路径也不能是没有备案的域名否则分享卡片拉取图片会失败显示默认灰图。3.4 视频播放与学习进度记录公考录播课是我这个项目的核心内容。视频存储上我选了对象存储服务视频文件上传后自动转码成多码率的 HLS 流也就是.m3u8格式。这样做的好处很明显用户可以根据网络情况自动切换清晰度而且切片播放天然支持拖动进度比直接放一个 MP4 文件灵活得多。Uniapp 中播放视频直接使用video组件src指向 m3u8 地址即可。Android 端和 iOS 端对这个格式的支持都很好小程序端需要在后台配置域名白名单。学习进度记录的实现是监听timeupdate事件每 15 秒向后端上报一次当前播放位置和累计时长。为了不频繁请求接口我在前端做了一层节流只有播放位置变化超过 5 秒才上报同时页面卸载时上报最终位置用户下次进来直接从上次位置续播。3.5 生命周期与页面状态管理Uniapp 的页面生命周期跟 Vue 不太一样它有onLoad、onShow、onReady、onHide、onUnload这一套。我实际开发中总结了一个经验数据初始化放在onLoad里做但如果页面从后台切回来需要刷新数据就要在onShow里做检查。比如考试倒计时页面用户切到后台再回来倒计时必须重新校准这就是onShow的典型应用场景。另外Uniapp 的页面跳转方式要特别注意。navigateTo会保留当前页面适合跳转详情页redirectTo关闭当前页面适合登录页跳转switchTab用于底部 tab 页之间的切换。用错跳转方式经常会导致页面栈混乱尤其是从小程序分享链接进入页面后返回按钮的行为会变得很奇怪这需要结合onLoad的参数判断来处理。4. SpringBoot 后端的核心实现4.1 项目分层与统一响应结构后端项目的包结构我严格按模块划分controller、service、mapper、entity、dto、vo、config、common。其中dto放接收前端参数的类vo放返回给前端的视图对象这两者的区分很重要。一开始我偷懒直接用 entity 接收参数和返回结果后来发现接口参数变了就得改实体类牵涉面太大而且会把数据库字段暴露给前端存在安全隐患。统一响应结构我用了一个泛型类ResultT包含code、message、data三个字段。成功时 code 为 0失败时返回错误码和提示信息。配合全局异常处理器RestControllerAdvice任何业务异常都会被捕获并转换成统一的 JSON 结构返回前端封装的请求拦截器只需要判断 code 就能知道请求是否成功避免到处写 try-catch。4.2 全局过滤器处理 XSS 攻击公考平台有题库管理功能运营人员会通过管理后台批量上传题目包括 PDF 格式的试卷。这里有一个安全问题题目内容如果包含恶意脚本存储后渲染在管理后台或其他用户页面时可能触发 XSS 攻击。我的做法是写了一个全局过滤器对所有进入后端的请求进行内容检测和转义处理。Component public class XssFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest req (HttpServletRequest) request; // 如果是文件上传请求跳过XSS处理避免破坏文件内容 if (req.getContentType() ! null req.getContentType().contains(multipart/form-data)) { chain.doFilter(request, response); return; } chain.doFilter(new XssWrapper(req), response); } }关键点在于判断multipart/form-data请求要跳过处理。因为上传 PDF 或者图片时请求体是二进制流如果做文本替换会把文件内容搞坏。普通 JSON 请求则通过包装HttpServletRequestWrapper对参数值中的script、iframe等危险标签进行转义。这个过滤器在项目上线前帮我拦截了好几次测试人员输入的恶意脚本算是一个低成本高回报的安全措施。4.3 MyBatis 分页插件与多条件查询题库管理后台的列表页需要支持多条件筛选按题型、难度、知识点、关键字搜索。这类查询条件组合多变用 MyBatis-Plus 的QueryWrapper可以写出比较灵活的动态 SQL配合分页插件 PageHelper 实现分页。Override public PageResultQuestionVO pageQuery(QuestionQueryDTO dto) { PageQuestion page new Page(dto.getPageNum(), dto.getPageSize()); LambdaQueryWrapperQuestion wrapper new LambdaQueryWrapper(); // 动态拼接查询条件 wrapper.eq(dto.getType() ! null, Question::getType, dto.getType()) .eq(dto.getDifficulty() ! null, Question::getDifficulty, dto.getDifficulty()) .like(StringUtils.hasText(dto.getKeyword()), Question::getContent, dto.getKeyword()) .orderByDesc(Question::getCreateTime); PageQuestion result questionMapper.selectPage(page, wrapper); return convertToPageResult(result); }这里有个容易踩的坑PageHelper 和 MyBatis-Plus 的分页插件不要同时引入两者会在底层产生冲突导致分页失效或者 SQL 被异常拦截。我项目中只用了 MyBatis-Plus 自带的selectPage方法它通过分页拦截器自动在 SQL 后面拼接 LIMIT只要配置好MybatisPlusInterceptor就可以。4.4 Token 认证与接口权限控制用户端的登录认证我用的是 JWT。用户登录成功后后端用用户 ID 和过期时间生成 token 返回客户端存在本地存储每次请求带上Authorization头。后端通过拦截器解析 token把用户信息放进ThreadLocal里后续业务代码直接取就拿到当前登录用户。这里推荐一个小技巧token 里不要放太多用户信息只放userId和loginTime。因为 token 一旦签发里面的数据就固定了如果用户修改了昵称或者 VIP 状态token 里的旧数据不会自动更新。我的做法是每次请求时根据userId从 Redis 里拉取最新的用户信息Redis 里没有再从数据库加载并缓存这样既保证了数据新鲜度又不会每次都打数据库。管理后台的接口权限我用注解RequirePermission加拦截器实现。比如编辑题库需要question:edit权限删除用户需要user:delete权限运营人员分配角色后拿到对应的权限码集合。拦截器在进入 Controller 前校验当前用户是否有该权限码没有就返回 403。这个方案比 Spring Security 轻量很多也够用。4.5 PDF 上传与解析处理管理后台需要上传 PDF 格式的试卷上传后系统要能提取出里面的题目文本。这个功能我实现得比较简单PDF 上传到服务器后用 Apache PDFBox 把文本内容抽取出来再交给后端的题目解析服务按格式切分。PDF 文本抽取的难点在于格式不统一有的试卷是两栏排版有的有表格解析出来的文本顺序跟人工预期不一样。针对这个问题我的建议是不要试图做全自动解析。在这个项目中PDF 上传后只作为附件存储同时运营人员在管理后台手动录入题目内容PDF 只是留档和核对用。这样既满足了客户留存原卷的需求又规避了 PDF 解析不稳定的问题。如果你确实需要自动解析那就要在 PDF 生成源头做规范比如要求合作的老师按模板输出 Word 后再转 PDF。5. Vue 管理后台的实现要点5.1 后台框架搭建与路由设计管理后台我选择了 Vue 3 Element Plus Vite 的组合。路由设计上采用了动态路由的方案用户登录后后端返回该用户有权限访问的菜单列表前端根据菜单列表动态注册路由。这样做的好处是不同角色的运营人员登录后台看到的菜单天然是被过滤过的不会有权限越级的入口。动态路由的实现有一个需要注意的细节刷新页面时动态注册的路由会丢失导致页面 404。我的解决办法是把菜单数据缓存在sessionStorage里刷新后先从缓存取菜单、重新注册路由再渲染当前页面。这个逻辑看起来简单但顺序必须对先注册路由再跳转页面否则首次刷新还是会白屏。5.2 路由参数传递的正确姿势管理后台里最常见的场景是列表页跳转到详情页或者编辑页这时需要传递当前行的 ID。Vue Router 有两种传参方式query方式和params方式。我推荐使用query// 跳转编辑页面 this.$router.push({ path: /question/edit, query: { id: row.id } })// 编辑页面接收参数 const id this.$route.query.id为什么不用params因为params传参刷新页面后参数会丢失尤其是被router.push以name方式跳转时刷新经常拿不到参数。而query的参数会同步到 URL 地址栏刷新也不会丢天然支持分享链接和收藏链接。代价是 URL 里会多出参数串对管理后台来说完全能接受。5.3 富文本编辑与图片上传管理后台的内容管理模块运营人员需要发布备考资讯和课程介绍这里用到了富文本编辑器。我选了wangeditor它跟 Vue 3 配合比较顺功能也覆盖了常用的格式调整需求。富文本内容里的图片上传需要自定义上传接口把图片上传到后端返回可供访问的 URL 后插入编辑器内容区。这里有个我处理过的坑富文本里如果包含外部图片链接部署后可能因为域名未备案等原因无法加载。我的做法是在保存内容时做一次图片地址校验只允许上传到本项目存储服务的图片地址外部链接一律拦截。这样虽然牺牲了一点灵活度但保证了内容展示的稳定性。5.4 表格批量操作与数据导出题库管理需要支持批量删除和批量修改题型/难度Element Plus 的el-table加上多选列可以很轻松实现。选中行的数据通过selection-change事件收集批量操作时把选中 ID 数组提交给后端接口。注意批量删除要在后端做数量限制比如一次最多删除 500 条防止频繁大事务操作数据库。数据导出功能我用的是后端生成 Excel 的方式。运营点导出按钮后端根据筛选条件查询全部数据不分页用 EasyExcel 写出 Excel 文件前端通过window.open直接访问导出接口。这里要注意一个细节导出接口是 GET 请求带 token 比较麻烦我把它改成了 POST 请求前端创建一个隐藏表单提交才能在请求头中带上认证信息。6. 常见问题与排查技巧实录6.1 iOS 端 Canvas 导出白图项目里我做了个生成学习报告的功能把用户的刷题数据渲染成 Canvas 海报分享到朋友圈。开发时安卓手机一切正常iOS 真机上导出图片却是一片空白。排查下来发现问题出在 Canvas 绘制的时序上iOS 需要在绘制完成并且canvasToTempFilePath调用成功后才能导出而且 canvas 必须是显示在页面中且没有设置display: none。我的解决方法是绘制前先确保 canvas 所在节点已经渲染完成绘制后延时 300ms 再调用导出导出时指定canvasId并且不要传宽高参数让它从画布实际尺寸读取。另外还有一个小坑iOS 上 Canvas 如果绘制过慢用户切到后台再回来会导致画布被系统回收此时导出同样会白屏。规避方案是导出前重新触发一次绘制。6.2 小程序扫码参数传不过去公考平台有个线下推广场景把二维码印在宣传册上用户扫码后直接打开对应课程页面。小程序二维码生成时我拼接了scene参数但发现扫码进入页面后参数经常丢失。原因是小程序的scene参数需要 URL 编码而且进入页面后要经过decodeURIComponent解码才能拿到原始值。这是我最终的参数解析代码onLoad(options) { // 场景码扫码进入时参数在 options.scene 里且需要解码 let courseId null if (options.scene) { const scene decodeURIComponent(options.scene) courseId scene.split()[1] } else if (options.id) { // 普通分享链接进入 courseId options.id } }这个坑特别典型因为开发工具里测试二维码时传参是正常的一上真机就出问题很多人会绕很久。6.3 Uniapp 打包上架安卓应用市场的注意事项安卓应用打包上架是整个项目里流程最琐碎的一环。HBuilderX 云打包生成的 APK直接装手机没问题但要上架到各大应用市场必须做签名、加固、处理权限合规声明。华为、小米、OPPO、vivo 各家市场的审核要求还不完全一致其中最容易出问题的是隐私政策弹窗和应用权限说明。我的建议是第一提前在隐私政策里写清楚所有敏感权限的使用场景比如相机权限、存储权限、定位权限即使只是个别功能用到也要列出来第二Android 平台使用相机扫码时必须在拍摄前动态申请权限不能直接调用第三上架前用市场提供的加固工具先做加固不然部分市场会以下载安装被拦截为由驳回审核。6.4 后端接口偶尔超时与慢查询排查项目上线后出现过一次接口偶发超时的问题表现在用户刷题时偶尔提交答案会卡几秒。排查思路是先看接口日志定位到超时集中在exam_answer表批量插入的操作上。进一步查数据库慢查询日志发现插入语句没有走索引而且每次插入前有一条SELECT COUNT(*)的统计语句在全表扫描。优化措施有两项一是给exam_answer表加上user_id和question_id的联合索引二是把交卷时的统计逻辑从实时查询改成异步处理用户交完卷先返回成功成绩统计放到定时任务里批量计算后写入。优化后接口响应时间从 800ms 降到了 100ms 以内超时问题没有再出现。6.5 常见问题速查表我把项目过程中遇到的问题做了一份速查表方便后面维护的人快速对照问题现象排查方向解决方案微信登录弹不出来manifest 的 AppID 与签名不匹配检查微信开放平台配置和打包签名分享卡片是灰图分享图片地址不可访问使用 HTTPS 公网可访问的图片链接iOS 视频播放黑屏视频编码格式不兼容用 HLS 转码或改用 https 视频地址小程序扫码丢参数scene 未解码使用 decodeURIComponent 解析管理后台刷新 404动态路由未重新注册从 sessionStorage 恢复菜单并重新 addRoute导出的 Excel 打不开后端接口需要认证改用 POST 表单提交方式导出PDF 上传后内容为空二进制流被 XSS 过滤器改变了过滤器跳过 multipart 请求整套项目做下来我最大的体会是这类学习平台的业务逻辑其实不算特别复杂真正的挑战在于横跨三个端客户端、管理后台、后端服务时如何把约定统一好把细节处理好。Uniapp 的跨端能力帮我省了一半的客户端开发量SpringBoot 的生态让后端功能的落地非常顺滑Vue 管理后台则是运营团队每天都要面对的界面交互顺手比什么都重要。最后再分享一个小技巧这类平台上线后一定要在管理后台留一个系统配置表把分享文案、积分规则、默认头像、公告内容这些经常需要调整的东西都做成可配置项不要写死在代码里。运营人员自己就能改开发也能少很多琐碎的提需求流程。这个配置表在后来的版本迭代里帮我省了不知道多少次远程改代码的麻烦。