如果要做一个高校或培训机构的招生宣传管理系统很多团队的惯性思维是直接买一套现成的CMS或者用低代码平台拖几个页面出来。但我个人在实际开发中的体会是招生宣传这个业务看起来只是“发发文章、传传图”真正落地时却涉及宣传计划、素材审批、渠道跟踪、咨询登记、数据统计等多个环节流程很容易被改来改去定制化需求又特别多。这种情况下用Java SpringBoot Vue3 MyBatis这套前后端分离的方案自己搭一套反而更可控、更好迭代。我搭建的这个招生宣传管理系统源码项目就是基于这一套技术栈实现的今天把整个项目的设计思路、核心功能、技术细节和踩坑记录完整梳理一遍。先说清楚这套系统能做什么面向学校、教育机构的市场部和招生办提供宣传任务创建与分发、宣传物料图文、海报、视频管理、多招生渠道官网、公众号、线下活动的效果跟踪、潜在生源咨询登记与跟进以及基于MySQL数据的多维度统计报表。前端采用Vue3 Vite构建使用Element Plus组件库后端基于SpringBoot提供RESTful API持久层使用MyBatis操作MySQL数据库整体采用前后端分离架构可通过Docker或传统jar包方式部署。这套源码适合谁参考如果你是正在做毕业设计或课设的学生需要一套结构清晰、注释完整、能现场跑起来的全栈项目如果你是刚转Java全栈的初级工程师想理解SpringBoot Vue3在实际项目里如何协作如果你所在的机构正好需要类似的招生宣传系统想拿一套代码做二次开发——这个项目都很值得研究。下面我按项目建设的真实流程把整体设计、核心模块实现、数据库设计、部署方案和典型问题全部摊开来讲。1. 系统整体设计与技术选型思路1.1 为什么是前后端分离而不是服务端渲染招生宣传管理系统有一个很典型的场景运营人员在外地参加线下招生咨询会时需要随时用手机或笔记本电脑上传现场照片、填写咨询登记表市场部主管需要同步查看各个宣传渠道的实时数据。这种多终端访问、交互逻辑偏重的场景用传统的Thymeleaf服务端渲染会非常别扭——每次页面跳转都要刷新整个页面表单校验、图片预览等交互实现起来也更麻烦。所以我在设计这套系统时坚定选了前后端分离架构Vue3负责前端页面渲染和交互逻辑SpringBoot只提供纯数据接口。好处非常明显第一前后端可以并行开发前端用Mock数据调试后端用Postman测试接口互不阻塞第二后续如果要出小程序或移动端App后端API可以直接复用不需要重写业务逻辑第三部署时前端打包成静态资源放到Nginx下后端独立运行服务器资源分配更灵活。1.2 技术栈选型与版本搭配技术选型上的几个关键决定SpringBoot版本我在项目里使用的是SpringBoot 2.7.x而不是3.x。很多人追新会用3.0但要注意SpringBoot 3.x强制要求JDK 17而很多学校、企业的服务器还停留在JDK 1.8环境。为了减少部署环境冲突我主动锁定了2.7.18版本搭配JDK 1.8。这一点对于要跑在现有服务器上的项目尤其重要千万别在版本问题上给自己挖坑。MyBatis还是MyBatis-Plus项目核心使用的是原生MyBatis可以在XML里完全掌控SQL。为什么不用MyBatis-Plus因为招生宣传系统里有很多动态查询条件比如按时间范围、宣传渠道、素材类型等组合筛选原生MyBatis的where、if、foreach标签在这类场景下其实更好用。当然BaseMapper提供的单表CRUD确实省事所以我在代码里同时集成了MyBatis通用Mapper插件单表操作用通用方法复杂查询手写XML。Vue3 Vite Element PlusVue3用组合式APIComposition API配合script setup语法代码比Options API清爽很多。Vite作为构建工具开发环境下热更新秒级响应比Webpack那种动辄等几秒的体验舒服太多。UI组件库用Element Plus因为它在Vue3生态里最成熟表格、表单、日期选择器、上传组件这些后台管理系统的核心组件都覆盖到了。MySQL版本开发环境用MySQL 8.0。如果还在用MySQL 5.7建议尽早升级。8.0的窗口函数做统计报表非常方便比如计算每个渠道的宣传效果排名、按月份对比报名转化趋势一条SQL就搞定了。2. 核心功能模块与数据库设计实战2.1 功能模块划分从业务调研到模块落地的思考做管理系统最忌讳一上来就写代码。我在动手前先把招生宣传的业务流程完整梳理了一遍核心链路是制定宣传计划 - 制作宣传物料 - 多渠道投放 - 收集咨询线索 - 跟进转化 - 复盘统计。基于这条链路系统划分了以下核心模块模块核心功能目标用户宣传计划管理创建年度/季度宣传计划分配任务到个人跟踪完成进度市场部主管宣传物料管理图文、海报、视频的上传、审核、版本管理素材库分类检索宣传专员渠道投放管理官网站点、公众号、线下展会等多渠道投放记录与链接跟踪运营人员咨询登记管理报名咨询线索录入、分配、跟进记录意向等级标记招生办老师数据统计分析渠道线索量、转化率、计划完成度、素材使用效果的统计图表管理层每个模块内部再拆成列表页、详情页、表单页这样前端页面结构就非常清晰了。这套划分方式你可以在任何类似的管理系统中复用核心思路是先找业务主线再按角色职责切功能边界。2.2 数据库表结构设计要点数据库设计是这套系统的地基。我重点讲几张核心表的设计思路。宣传计划表promotion_plan除了计划名称、负责人、开始/结束时间这些常规字段外有两个字段很关键——plan_status和task_count。plan_status用tinyint类型存状态码0未开始、1进行中、2已完成、3已延期task_count冗余存储该计划下的子任务数量。为什么冗余因为在计划列表页需要展示每个计划下的任务总数如果每次都用COUNT(*)去关联子表查询数据量上来后性能会明显下降。冗余字段最怕数据不一致所以要在子任务的增删接口里同步维护这个字段用事务保证原子性。宣传物料表promotion_material设计时重点考虑了素材的多类型需求。类型字段material_type区分图文、海报、视频、H5链接file_url存储文件访问路径cover_url存缩略图或封面图路径。这里有几个容易踩的坑一是文件删除不能物理删除只能逻辑删除deleted字段置1否则历史数据里的链接全部失效二是审核状态audit_status和发布时间publish_time要分离素材可以审核通过但暂不发布这在招生季前集中准备的场景下非常常见。咨询登记表consultation_record这张表是招生转化的核心重点关注两个点了——咨询来源渠道用channel_code字段关联渠道字典表意向等级用intention_level字段A/B/C/D四级这是后续跟进优先级排序的依据。因为一个学生可能同时在官网和线下展会两个渠道咨询我还加了一个visitor_phone字段并通过visitor_phone_hash做轻量级去重避免重复跟进。渠道投放统计表channel_metrics这张表是数据报表的基础核心设计思路是空间换时间。不做实时统计而是在投放记录更新时同步写入当天的PV、UV、咨询量等累计值。统计报表查询时只需要按日期范围和渠道分组聚合这张表而不需要去扫描海量的原始访问日志或咨询记录表。这在中小体量系统里是非常实用的过度设计——保证报表查询永远秒开。2.3 动态SQL在复杂筛选场景中的边界处理前面提到选择原生MyBatis的一个重要原因是动态SQL。我举一个具体的例子咨询登记列表页需要支持按时间范围、咨询渠道、意向等级、是否已分配跟进人这4个条件任意组合筛选。在Mapper XML里我用where标签配合if标签来拼条件中间有个特别容易出问题的陷阱——时间范围条件。如果只传开始日期不传结束日期SQL会写成create_time ?只传结束日期不传开始日期就变成create_time ?两个都传则用BETWEEN。这种场景如果都写在同一个if里就会漏掉边界情况我是这样拆开的select idselectConsultationList resultTypeConsultationRecord SELECT * FROM consultation_record where if testchannelCode ! null and channelCode ! AND channel_code #{channelCode} /if if testintentionLevel ! null and intentionLevel ! AND intention_level #{intentionLevel} /if choose when teststartDate ! null and endDate ! null AND create_time BETWEEN #{startDate} AND #{endDate} /when when teststartDate ! null AND create_time gt; #{startDate} /when when testendDate ! null AND create_time lt; #{endDate} /when /choose /where ORDER BY create_time DESC /select这里用choose做多分支判断比if更清晰。gt;和lt;是因为XML解析器不能直接识别和必须用转义字符。这个细节很多人第一次写都会报错排查半天才发现是XML转义的问题。3. 前端Vue3 Element Plus核心实现3.1 项目结构与状态管理方案整个前端工程使用Vite初始化目录结构是这样组织的frontend/ ├── src/ │ ├── api/ # 按业务模块拆分的API请求 │ ├── assets/ # 静态资源 │ ├── components/ # 通用组件图片上传、富文本等 │ ├── layouts/ # 后台布局侧边栏顶栏 │ ├── router/ # 路由配置 │ ├── stores/ # Pinia状态管理 │ ├── views/ # 页面组件 │ ├── utils/ # 工具函数request封装等 │ └── App.vue ├── package.json └── vite.config.js状态管理我用了Pinia而不是Vuex。Pinia对TypeScript支持更好而且API设计更简单去掉了mutation的概念直接在store里定义action然后调用即可。在这个项目里Pinia主要负责两件事一是保存登录用户的信息和权限标识二是管理全局的部门或校区切换状态。这里要重点讲一下前端API请求的封装。我在utils/request.js里基于axios做了一层统一封装核心逻辑包括请求拦截器自动在Header里带上JWT Token响应拦截器统一处理HTTP异常码和业务异常码。遇到401状态码自动跳转登录页业务错误码则用Element Plus的Message组件弹出提示。这样一来业务代码里只需要写import request from /utils/request export function getConsultationList(params) { return request({ url: /api/consultation/list, method: get, params }) }页面里调接口时focus在手写业务逻辑上统一处理都交给拦截器代码干净不少。3.2 基于Element Plus的表格与表单组合实践列表页搜索表单分页表格是后台管理系统的标配模式。我用Element Plus的el-table和el-pagination组件搭建这里有两个经验值得分享。表格操作列固定与溢出处理咨询登记列表的操作列有“查看详情”“分配跟进人”“编辑”“删除”4个按钮操作列要设置fixedright避免横向滚动时操作按钮被挤到视口外。表格列的文字溢出统一使用show-overflow-tooltip属性鼠标悬浮显示完整内容列表整体会非常整洁。表单校验不是摆设新增宣传计划时计划名称必填、时间范围必填且结束时间要晚于开始时间、负责人必选。这些规则全部在el-form的rules中声明日期范围校验用自定义验证函数const validateDateRange (rule, value, callback) { if (!value || value.length ! 2) { callback(new Error(请选择完整的时间范围)) } else if (value[0] value[1]) { callback(new Error(结束时间必须晚于开始时间)) } else { callback() } }别看这段校验逻辑简单实际项目中因为日期格式或边界值问题导致的数据错误不在少数表单这关把严了能省很多事。3.3 文件上传与富文本编辑的特殊处理宣传物料模块涉及图片、视频上传这是前端最容易踩坑的地方。我统一封装了一个FileUpload组件基于Element Plus的el-upload实现。关键配置是action指向后端的上传接口headers动态传入JWT Token——这里有个常见错误很多人直接在el-upload的action属性上写字符串URL结果请求头里没有带Token上传接口返回401。正确做法是用:headers绑定一个计算属性去读Pinia里的Token。视频上传还有一个大坑默认的el-upload会先读文件内容到内存再发送大文件容易导致浏览器卡顿甚至崩溃。我的方案是关闭自动上传:auto-uploadfalse拿到File对象后用upload配合FormData手动提交const handleUpload async (file) { const formData new FormData() formData.append(file, file.file) const res await uploadMaterial(formData) formData.value.fileUrl res.data.url }这样文件以流式方式上传不会一次性把整个文件载入内存。如果你要上传的视频经常超过50MB建议直接对接阿里云OSS或MinIO走前端直传STS临时凭证的方式服务器只做凭证签发能极大缓解带宽和存储压力。3.4 Vue3组合式API的业务逻辑组织方式在单文件组件中我用script setup配合组合式API把一个页面的逻辑拆分成“搜索条件、表格数据、分页参数、操作函数”四个部分。不用把所有逻辑堆在setup里而是用小的组合函数去切分。以咨询登记列表页为例我把状态和逻辑拆成了useSearch、useTableData、usePagination三个组合函数// useTableData.js export function useTableData(loadData) { const tableData ref([]) const loading ref(false) const refresh async () { loading.value true try { const params { ...searchParams.value, pageNum: pagination.pageNum, pageSize: pagination.pageSize } const res await getConsultationList(params) tableData.value res.data.records pagination.total res.data.total } finally { loading.value false } } return { tableData, loading, refresh } }这样做的好处是页面组件的代码量大幅减少而且这些组合函数可以跨页面复用——比如宣传物料列表页的搜索分页逻辑几乎完全一样直接复用即可。很多人写Vue3还是习惯把所有东西堆在一个大文件里组件超过800行之后就很难维护了。4. SpringBoot后端接口设计与角色权限控制4.1 接口RESTful设计与统一返回体约定后端接口设计我遵循RESTful风格比如GET /api/plan/list——分页查询宣传计划POST /api/plan/save——新建或更新宣传计划POST /api/plan/delete——删除计划逻辑删除GET /api/channel/metrics——获取渠道统计数据POST /api/consultation/assign——分配咨询线索每个接口的返回体统一用ResultT包装代码结构如下public class ResultT { private Integer code; private String message; private T data; }code为200表示成功401表示未认证403表示无权限500表示业务异常。前端拦截器就是根据这个code做全局处理的。需要留意的是接口URL路径上我加了/api前缀这样在Nginx做反向代理时可以直接把/api开头的请求转发到SpringBoot服务静态资源则交给Nginx本地处理前后端联动很顺畅。4.2 JWT登录认证与拦截器实现系统的登录认证方案是JWT 拦截器。用户登录成功后后端生成一个有效期为2小时的JWT Token返回给前端前端存储在Pinia中并持久化到localStorage。每次请求在请求头中携带Authorization: Bearer token后端通过拦截器验证Token有效性。拦截器里有一个需要重点处理的问题——白名单。登录接口、验证码接口、静态资源这些不需要认证的路径必须在拦截器中放行。我建议把白名单路径集中放在WebConfig里配置Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(jwtInterceptor) .addPathPatterns(/**) .excludePathPatterns( /api/auth/login, /api/auth/captcha, /error ); }这里千万要注意/api/material/preview这类需要公开访问的素材预览路径也要放进白名单否则前端渲染海报图片时图片请求会因为没有Token被拦截导致所有页面图片裂开。这个问题我自己就踩过排查了很久才想到是CDN图片请求不会带Header这个原因。4.3 基于拦截器的接口权限控制光有登录认证还不够招生宣传系统里有三种角色管理员、主管、专员。管理员能管理用户和系统配置主管能审核宣传物料和查看统计报表专员只能维护自己名下的宣传计划和咨询记录。我用一个RequireRole注解实现接口级权限控制在拦截器中做判断Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface RequireRole { String[] value(); }然后在Controller接口上标注需要访问权限的角色RequireRole({ADMIN, MANAGER}) PostMapping(/api/material/audit) public ResultVoid auditMaterial(RequestBody AuditDTO dto) { materialService.audit(dto); return Result.success(); }拦截器里获取当前登录用户角色再与注解要求的角色做比对。这个方案比引入Spring Security或Shiro这种重型安全框架要轻量得多而且对于这种管理系统已经够用。如果你后面要扩展更细粒度的数据权限比如只能看本部门数据可以在查询SQL中基于用户维度动态拼接条件这样最直观。5. 数据统计模块与MySQL查询优化5.1 招生统计报表的数据来源与聚合逻辑数据统计模块是这套系统的亮点也是管理层最关心的功能。主要包含三类报表宣传计划完成度报表按计划维度展示任务完成数量、延期任务数量、整体完成百分比。渠道效果对比报表按渠道维度统计曝光量、咨询量、有效线索量、转化率。月度趋势报表展示近6个月各渠道咨询量的变化趋势辅助决策下个季度的投放预算分配。前两类报表我直接基于业务表统计比如渠道效果报表的核心SQL是SELECT channel_code, COUNT(*) AS total_visits, SUM(CASE WHEN intention_level IN (A,B) THEN 1 ELSE 0 END) AS valid_leads, ROUND(SUM(CASE WHEN intention_level IN (A,B) THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) AS conversion_rate FROM consultation_record WHERE create_time BETWEEN #{startDate} AND #{endDate} GROUP BY channel_code ORDER BY valid_leads DESC需要注意ROUND函数的第二个参数指定保留两位小数同时GROUP BY之后的结果如果有索引支撑会快很多。所以在consultation_record表上我给(create_time, channel_code)建了联合索引这个索引对统计查询的提升非常明显。5.2 MySQL统计查询的慢SQL优化实战项目测试阶段出现过一次报表页面的严重卡顿运营人员选择近一年的时间范围后页面要转圈5秒以上才能出数据。我分析了执行计划后发现问题出在咨询登记表的数据量已经达到50万而统计SQL在扫描条件create_time上走的不是索引全值匹配而是索引范围扫描导致行数还是很大。优化思路是建立汇总统计表channel_daily_stats每天晚上通过定时任务把当天的渠道数据按天汇总插入报表查询时直接查聚合表不再热查明细表。这个方案让报表接口的查询时间从5秒锐减到200毫秒以内体感是完全不同的两个系统。这种“明细表汇总表”的双表设计在大数据量统计场景下是最常用的手段不需要引入ClickHouse等重型OLAP组件。定时任务我用SpringBoot的Scheduled注解实现每天晚上凌晨1点执行汇总。5.3 列表分页查询的数据量边界分页查询的边界问题也很值得聊。咨询登记列表的分页接口一开始用的是MySQL默认的LIMIT offset, size写法当用户翻到第10000页时offset会膨胀到几十万MySQL需要先扫描再丢弃大量无效数据行响应会明显变慢。我改用“末尾ID分页”方案每次查询传入上一页最后一条记录的ID或时间戳SQL中带上WHERE id #{lastId}条件。这种方案在数据量大时性能稳定而且对用户无感。当然对于普通后台管理系统数据量撑死几十万条的情况下LIMIT 索引也能接受不必过度优化。但如果你预判数据会快速膨胀一开始就把这种方案做进去能省去后期改造成本。6. 部署流程与安全加固6.1 前后端分离部署完整步骤部署对于一个前后端分离项目来说是特别容易翻车的一环。我强烈建议一步到位用Docker Compose管理整套环境。下面是我在项目中使用的docker-compose.yml核心配置version: 3.8 services: mysql: image: mysql:8.0 container_name: enroll_mysql environment: MYSQL_ROOT_PASSWORD: root123456 MYSQL_DATABASE: enroll_system ports: - 3306:3306 volumes: - ./mysql-data:/var/lib/mysql backend: build: ./backend container_name: enroll_backend ports: - 8080:8080 depends_on: - mysql environment: SPRING_PROFILES_ACTIVE: prod frontend: build: ./frontend container_name: enroll_frontend ports: - 80:80 depends_on: - backend后端Dockerfile里要特别注意我使用的是多阶段构建FROM maven:3.8-openjdk-8 AS builder COPY . /build WORKDIR /build RUN mvn clean package -DskipTests FROM openjdk:8-jre-alpine COPY --frombuilder /build/target/enroll-backend.jar /app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, /app.jar, --spring.profiles.activeprod]这样做的好处是构建镜像时不会把Maven仓库和源码带进去最终镜像只有运行时依赖体积从800MB降到180MB左右。对于部署到云服务器或内网服务器这个体积差异非常影响拉取速度。6.2 接口安全与数据防泄漏系统安全这块我做了几件事一是管理端接口全部走JWT认证且登录接口加验证码防止暴力破解二是敏感信息脱敏咨询登记表里查看学生电话号码时列表页默认只显示中间四位加星号点击“查看详情”且有权限时才能看到完整号码三是防止SQL注入所有查询都通过MyBatis预编译的#{}占位符禁止用${}拼接字符串只有少数动态表名、排序字段场景才需要白名单校验后使用。这里有个细节容易被忽略MySQL在生产环境不要直接用root账号连接应用应该创建独立的数据库账号并只授予应用库的最小权限比如SELECT/INSERT/UPDATE/DELETE不授予DROP/ALTER等DDL权限。哪怕应用被注入攻击者也无法删库。6.3 开发环境与生产环境的配置隔离SpringBoot的多环境配置是标准做法application-dev.yml和application-prod.yml分开维护。开发环境数据库连接本地开启SQL日志打印生产环境数据库连接内网地址关闭SQL日志。启动时通过SPRING_PROFILES_ACTIVE环境变量指定使用哪个配置而不是在每个环境手动改配置文件——手动改配置是部署事故的高发源头一定要用环境变量或配置中心统一管理。注意如果把spring.jpa.show-sql或MyBatis的SQL日志打印在生产环境打开高并发下日志文件会飞速膨胀磁盘很快被打满。生产环境务必关闭SQL打印需要排查问题时再临时用--logging.level.com.example.mapperDEBUG这种级别开关来针对性打开。7. 常见问题与排查技巧实录7.1 前端跨域请求失败开发环境最常见的报错就是浏览器控制台出现CORS policy相关错误。原因是前端跑在Vite的5173端口后端接口在8080端口浏览器对跨域请求默认拦截。解决方案有两种一是在后端加CORS跨域配置二是在前端Vite配置代理。我更推荐第二种方案。因为生产环境通常用Nginx做同源代理开发环境用Vite代理可以保持和生产环境一致后端不需要特殊处理。Vite的vite.config.js配置如下server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }配置完后前端请求/api/xxx就会自动转发到http://localhost:8080/api/xxx浏览器看到的是同源请求不存在跨域问题。7.2 Vue3响应式丢失导致页面不更新使用组合式API时一个高频踩坑点是解构ref或reactive数据导致响应式丢失。比如在setup中直接割裂解构// 错误的写法 const { total } toRefs(pagination) // total是Ref对象 const { pageNum } toRefs(pagination) // pageNum是Ref对象但在模板中这个问题的本质是从响应式对象中解构出的基本类型属性如果直接使用会变成普通值丢失响应式追踪。正确的做法是在模板中直接引用响应式对象的属性pagination.total或者在脚本中用toRefs保持引用关系。这个坑不踩一次很难理解建议你在写列表页面时特别注意。7.3 MyBatis传入参数为null导致SQL条件失效MyBatis里有一个非常隐蔽的问题if testname ! null中的name来自参数对象但如果用的是Param注解传参test语句里的变量名必须和注解里的名称一致否则if判断永远成立或永远不成立。我习惯在Mapper接口上显式用Param声明参数名ListConsultationRecord selectByCondition( Param(channelCode) String channelCode, Param(startDate) String startDate, Param(endDate) String endDate );然后在XML里用testchannelCode ! null判断。XML和接口方法参数名不一致时MyBatis运行期不会直接报错而是静默跳过条件导致查询结果比预期多出很多数据。这种Bug排查起来非常消耗时间建议从一开始就统一参数命名规范。7.4 大字段导致的列表页查询卡顿宣传物料表里有content字段存储富文本内容这个字段可能很大几万字符。在列表页查询时如果写了SELECT *每次查询都会把这几个大字段全部读取到内存再传给前端即使列表页根本没有用到这些字段白白浪费数据库IO和网络带宽。解决方案是在列表查询的SQL中只查必填字段SELECT id, title, material_type, file_url, cover_url, audit_status, create_time, update_time FROM promotion_material WHERE deleted 0 ORDER BY create_time DESC在详情页查询时才把content字段带上。这个优化对响应速度的提升非常明显尤其是素材数量到了几千条以后差距可能从几秒降到几百毫秒。7.5 前后端联调时日期格式不一致前后端日期格式不一致是联调过程中最容易出现的问题。Java后端默认LocalDateTime序列化格式是2025-06-01T10:30:00而前端Element Plus的日期选择器默认格式是2025-06-01两边拼接后就会导致解析错误。我在后端统一配置了全局的日期格式化Configuration public class JacksonConfig { Bean public Jackson2ObjectMapperBuilderCustomizer jsonCustomizer() { return builder - { builder.serializers(new LocalDateTimeSerializer(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))); builder.deserializers(new LocalDateTimeDeserializer(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))); }; } }前端请求传参时时间范围用时间戳或统一格式字符串后端再用DateTimeFormat注解解析。两边约定统一后这类问题就能彻底避免。8. 项目扩展与二次开发建议8.1 消息通知模块的快速接入如果要在现有系统上扩展消息通知功能比如物料审核通过后通过短信、站内信通知给提交人建议直接接入SpringBoot自带的spring-boot-starter-mail或集成企业微信/钉钉机器人。核心思路是定义消息中心表在审核状态变更时向消息表插入一条未读消息前端通过轮询或WebSocket推送拉取新消息。WebSocket推送在SpringBoot里实现相对轻量引入spring-boot-starter-websocket后定义一个TextWebSocketHandler处理前端连接及消息推送即可。这套方案比集成第三方IM服务SDK要省心得多完全满足室内的通知场景。8.2 数据大屏的可视化对接招生宣传系统跑一个招生季之后数据积累下来说不定管理层又想要一个数据大屏把实时咨询量、渠道排名、计划完成度投屏展示。这时候不要重新开发直接把现有统计接口的数据源稍作调整前端用ECharts或DataV即可。因为系统的统计接口在设计时就考虑了按日期范围、渠道等维度查询大屏只是换了展示形式数据对接成本很低。如果要做大屏前端部分建议用Vue3 ECharts配置几个图表组件渠道转化漏斗图展示从曝光到有效咨询再到报名的转化链路。区域热度地图如果是区域招生可以用地图展示各省份的咨询热度。实时滚动消息用ElNotification或自定义滚动列表展示最新咨询线索。8.3 从单体到微服务的演进判断这个系统目前是标准的单体应用只要数据量控制在百万级以内、并发量在几百以内单体应用完全扛得住优先把性能优化做透不要盲目上微服务。如果未来要拆可以按业务域拆分两个服务一个是宣传内容服务管理计划、物料、审核一个是咨询转化服务管理咨询记录、跟进、统计中间通过Feign调用。拆分的前提是业务模块之间已经做了明确的领域边界划分而不是把所有代码堆在一起然后按Controller切分。我在设计包结构时就已经按模块划分了com.enroll.plan、com.enroll.material、com.enroll.consultation、com.enroll.stats这几个包以后要拆服务直接把包代码搬出去就能复用。9. 实操心得与经验总结项目做到这里整体已经能支撑一个招生季的完整业务运转了。我个人在实际操作中最深的两点体会是第一前后端分离的项目接口契约管理一定要前置。前后端各有自己的开发节奏如果接口文档不提前定清楚联调阶段会陷入“改接口、等前端、再改接口”的循环中。我自己用Apifox管理接口文档前端看文档就能Mock出所有数据联调效率提升非常明显。第二点是权限模型再简单也要预留扩展空间。招生宣传管理系统的用户角色现在只有三种但实际业务中很可能出现“分校管理员”“合作渠道商”这样的新角色。所以我设计的用户表里有role_id字段权限判断也统一走拦截器 注解要加角色只需要在角色表和注解允许值里扩展不需要改动核心业务逻辑。最后再分享一个实用的小技巧物料上传和统计报表是招生宣传系统里最容易出性能问题的两个点建议你在还没有遇到瓶颈时就把这些优化方案从设计阶段就考虑进去比如文件存储独立到OSS/MinIO、统计查询走汇总表。很多问题等到线上出了再改成本是开发时的好几倍。这套系统的代码结构整体按照“模块化、接口隔离、配置外部化”的原则组织你要拿去扩展新的业务模块照着现有模式推就行。 基于SpringBoot+Vue3的招生宣传管理系统设计与实现
如果要做一个高校或培训机构的招生宣传管理系统很多团队的惯性思维是直接买一套现成的CMS或者用低代码平台拖几个页面出来。但我个人在实际开发中的体会是招生宣传这个业务看起来只是“发发文章、传传图”真正落地时却涉及宣传计划、素材审批、渠道跟踪、咨询登记、数据统计等多个环节流程很容易被改来改去定制化需求又特别多。这种情况下用Java SpringBoot Vue3 MyBatis这套前后端分离的方案自己搭一套反而更可控、更好迭代。我搭建的这个招生宣传管理系统源码项目就是基于这一套技术栈实现的今天把整个项目的设计思路、核心功能、技术细节和踩坑记录完整梳理一遍。先说清楚这套系统能做什么面向学校、教育机构的市场部和招生办提供宣传任务创建与分发、宣传物料图文、海报、视频管理、多招生渠道官网、公众号、线下活动的效果跟踪、潜在生源咨询登记与跟进以及基于MySQL数据的多维度统计报表。前端采用Vue3 Vite构建使用Element Plus组件库后端基于SpringBoot提供RESTful API持久层使用MyBatis操作MySQL数据库整体采用前后端分离架构可通过Docker或传统jar包方式部署。这套源码适合谁参考如果你是正在做毕业设计或课设的学生需要一套结构清晰、注释完整、能现场跑起来的全栈项目如果你是刚转Java全栈的初级工程师想理解SpringBoot Vue3在实际项目里如何协作如果你所在的机构正好需要类似的招生宣传系统想拿一套代码做二次开发——这个项目都很值得研究。下面我按项目建设的真实流程把整体设计、核心模块实现、数据库设计、部署方案和典型问题全部摊开来讲。1. 系统整体设计与技术选型思路1.1 为什么是前后端分离而不是服务端渲染招生宣传管理系统有一个很典型的场景运营人员在外地参加线下招生咨询会时需要随时用手机或笔记本电脑上传现场照片、填写咨询登记表市场部主管需要同步查看各个宣传渠道的实时数据。这种多终端访问、交互逻辑偏重的场景用传统的Thymeleaf服务端渲染会非常别扭——每次页面跳转都要刷新整个页面表单校验、图片预览等交互实现起来也更麻烦。所以我在设计这套系统时坚定选了前后端分离架构Vue3负责前端页面渲染和交互逻辑SpringBoot只提供纯数据接口。好处非常明显第一前后端可以并行开发前端用Mock数据调试后端用Postman测试接口互不阻塞第二后续如果要出小程序或移动端App后端API可以直接复用不需要重写业务逻辑第三部署时前端打包成静态资源放到Nginx下后端独立运行服务器资源分配更灵活。1.2 技术栈选型与版本搭配技术选型上的几个关键决定SpringBoot版本我在项目里使用的是SpringBoot 2.7.x而不是3.x。很多人追新会用3.0但要注意SpringBoot 3.x强制要求JDK 17而很多学校、企业的服务器还停留在JDK 1.8环境。为了减少部署环境冲突我主动锁定了2.7.18版本搭配JDK 1.8。这一点对于要跑在现有服务器上的项目尤其重要千万别在版本问题上给自己挖坑。MyBatis还是MyBatis-Plus项目核心使用的是原生MyBatis可以在XML里完全掌控SQL。为什么不用MyBatis-Plus因为招生宣传系统里有很多动态查询条件比如按时间范围、宣传渠道、素材类型等组合筛选原生MyBatis的where、if、foreach标签在这类场景下其实更好用。当然BaseMapper提供的单表CRUD确实省事所以我在代码里同时集成了MyBatis通用Mapper插件单表操作用通用方法复杂查询手写XML。Vue3 Vite Element PlusVue3用组合式APIComposition API配合script setup语法代码比Options API清爽很多。Vite作为构建工具开发环境下热更新秒级响应比Webpack那种动辄等几秒的体验舒服太多。UI组件库用Element Plus因为它在Vue3生态里最成熟表格、表单、日期选择器、上传组件这些后台管理系统的核心组件都覆盖到了。MySQL版本开发环境用MySQL 8.0。如果还在用MySQL 5.7建议尽早升级。8.0的窗口函数做统计报表非常方便比如计算每个渠道的宣传效果排名、按月份对比报名转化趋势一条SQL就搞定了。2. 核心功能模块与数据库设计实战2.1 功能模块划分从业务调研到模块落地的思考做管理系统最忌讳一上来就写代码。我在动手前先把招生宣传的业务流程完整梳理了一遍核心链路是制定宣传计划 - 制作宣传物料 - 多渠道投放 - 收集咨询线索 - 跟进转化 - 复盘统计。基于这条链路系统划分了以下核心模块模块核心功能目标用户宣传计划管理创建年度/季度宣传计划分配任务到个人跟踪完成进度市场部主管宣传物料管理图文、海报、视频的上传、审核、版本管理素材库分类检索宣传专员渠道投放管理官网站点、公众号、线下展会等多渠道投放记录与链接跟踪运营人员咨询登记管理报名咨询线索录入、分配、跟进记录意向等级标记招生办老师数据统计分析渠道线索量、转化率、计划完成度、素材使用效果的统计图表管理层每个模块内部再拆成列表页、详情页、表单页这样前端页面结构就非常清晰了。这套划分方式你可以在任何类似的管理系统中复用核心思路是先找业务主线再按角色职责切功能边界。2.2 数据库表结构设计要点数据库设计是这套系统的地基。我重点讲几张核心表的设计思路。宣传计划表promotion_plan除了计划名称、负责人、开始/结束时间这些常规字段外有两个字段很关键——plan_status和task_count。plan_status用tinyint类型存状态码0未开始、1进行中、2已完成、3已延期task_count冗余存储该计划下的子任务数量。为什么冗余因为在计划列表页需要展示每个计划下的任务总数如果每次都用COUNT(*)去关联子表查询数据量上来后性能会明显下降。冗余字段最怕数据不一致所以要在子任务的增删接口里同步维护这个字段用事务保证原子性。宣传物料表promotion_material设计时重点考虑了素材的多类型需求。类型字段material_type区分图文、海报、视频、H5链接file_url存储文件访问路径cover_url存缩略图或封面图路径。这里有几个容易踩的坑一是文件删除不能物理删除只能逻辑删除deleted字段置1否则历史数据里的链接全部失效二是审核状态audit_status和发布时间publish_time要分离素材可以审核通过但暂不发布这在招生季前集中准备的场景下非常常见。咨询登记表consultation_record这张表是招生转化的核心重点关注两个点了——咨询来源渠道用channel_code字段关联渠道字典表意向等级用intention_level字段A/B/C/D四级这是后续跟进优先级排序的依据。因为一个学生可能同时在官网和线下展会两个渠道咨询我还加了一个visitor_phone字段并通过visitor_phone_hash做轻量级去重避免重复跟进。渠道投放统计表channel_metrics这张表是数据报表的基础核心设计思路是空间换时间。不做实时统计而是在投放记录更新时同步写入当天的PV、UV、咨询量等累计值。统计报表查询时只需要按日期范围和渠道分组聚合这张表而不需要去扫描海量的原始访问日志或咨询记录表。这在中小体量系统里是非常实用的过度设计——保证报表查询永远秒开。2.3 动态SQL在复杂筛选场景中的边界处理前面提到选择原生MyBatis的一个重要原因是动态SQL。我举一个具体的例子咨询登记列表页需要支持按时间范围、咨询渠道、意向等级、是否已分配跟进人这4个条件任意组合筛选。在Mapper XML里我用where标签配合if标签来拼条件中间有个特别容易出问题的陷阱——时间范围条件。如果只传开始日期不传结束日期SQL会写成create_time ?只传结束日期不传开始日期就变成create_time ?两个都传则用BETWEEN。这种场景如果都写在同一个if里就会漏掉边界情况我是这样拆开的select idselectConsultationList resultTypeConsultationRecord SELECT * FROM consultation_record where if testchannelCode ! null and channelCode ! AND channel_code #{channelCode} /if if testintentionLevel ! null and intentionLevel ! AND intention_level #{intentionLevel} /if choose when teststartDate ! null and endDate ! null AND create_time BETWEEN #{startDate} AND #{endDate} /when when teststartDate ! null AND create_time gt; #{startDate} /when when testendDate ! null AND create_time lt; #{endDate} /when /choose /where ORDER BY create_time DESC /select这里用choose做多分支判断比if更清晰。gt;和lt;是因为XML解析器不能直接识别和必须用转义字符。这个细节很多人第一次写都会报错排查半天才发现是XML转义的问题。3. 前端Vue3 Element Plus核心实现3.1 项目结构与状态管理方案整个前端工程使用Vite初始化目录结构是这样组织的frontend/ ├── src/ │ ├── api/ # 按业务模块拆分的API请求 │ ├── assets/ # 静态资源 │ ├── components/ # 通用组件图片上传、富文本等 │ ├── layouts/ # 后台布局侧边栏顶栏 │ ├── router/ # 路由配置 │ ├── stores/ # Pinia状态管理 │ ├── views/ # 页面组件 │ ├── utils/ # 工具函数request封装等 │ └── App.vue ├── package.json └── vite.config.js状态管理我用了Pinia而不是Vuex。Pinia对TypeScript支持更好而且API设计更简单去掉了mutation的概念直接在store里定义action然后调用即可。在这个项目里Pinia主要负责两件事一是保存登录用户的信息和权限标识二是管理全局的部门或校区切换状态。这里要重点讲一下前端API请求的封装。我在utils/request.js里基于axios做了一层统一封装核心逻辑包括请求拦截器自动在Header里带上JWT Token响应拦截器统一处理HTTP异常码和业务异常码。遇到401状态码自动跳转登录页业务错误码则用Element Plus的Message组件弹出提示。这样一来业务代码里只需要写import request from /utils/request export function getConsultationList(params) { return request({ url: /api/consultation/list, method: get, params }) }页面里调接口时focus在手写业务逻辑上统一处理都交给拦截器代码干净不少。3.2 基于Element Plus的表格与表单组合实践列表页搜索表单分页表格是后台管理系统的标配模式。我用Element Plus的el-table和el-pagination组件搭建这里有两个经验值得分享。表格操作列固定与溢出处理咨询登记列表的操作列有“查看详情”“分配跟进人”“编辑”“删除”4个按钮操作列要设置fixedright避免横向滚动时操作按钮被挤到视口外。表格列的文字溢出统一使用show-overflow-tooltip属性鼠标悬浮显示完整内容列表整体会非常整洁。表单校验不是摆设新增宣传计划时计划名称必填、时间范围必填且结束时间要晚于开始时间、负责人必选。这些规则全部在el-form的rules中声明日期范围校验用自定义验证函数const validateDateRange (rule, value, callback) { if (!value || value.length ! 2) { callback(new Error(请选择完整的时间范围)) } else if (value[0] value[1]) { callback(new Error(结束时间必须晚于开始时间)) } else { callback() } }别看这段校验逻辑简单实际项目中因为日期格式或边界值问题导致的数据错误不在少数表单这关把严了能省很多事。3.3 文件上传与富文本编辑的特殊处理宣传物料模块涉及图片、视频上传这是前端最容易踩坑的地方。我统一封装了一个FileUpload组件基于Element Plus的el-upload实现。关键配置是action指向后端的上传接口headers动态传入JWT Token——这里有个常见错误很多人直接在el-upload的action属性上写字符串URL结果请求头里没有带Token上传接口返回401。正确做法是用:headers绑定一个计算属性去读Pinia里的Token。视频上传还有一个大坑默认的el-upload会先读文件内容到内存再发送大文件容易导致浏览器卡顿甚至崩溃。我的方案是关闭自动上传:auto-uploadfalse拿到File对象后用upload配合FormData手动提交const handleUpload async (file) { const formData new FormData() formData.append(file, file.file) const res await uploadMaterial(formData) formData.value.fileUrl res.data.url }这样文件以流式方式上传不会一次性把整个文件载入内存。如果你要上传的视频经常超过50MB建议直接对接阿里云OSS或MinIO走前端直传STS临时凭证的方式服务器只做凭证签发能极大缓解带宽和存储压力。3.4 Vue3组合式API的业务逻辑组织方式在单文件组件中我用script setup配合组合式API把一个页面的逻辑拆分成“搜索条件、表格数据、分页参数、操作函数”四个部分。不用把所有逻辑堆在setup里而是用小的组合函数去切分。以咨询登记列表页为例我把状态和逻辑拆成了useSearch、useTableData、usePagination三个组合函数// useTableData.js export function useTableData(loadData) { const tableData ref([]) const loading ref(false) const refresh async () { loading.value true try { const params { ...searchParams.value, pageNum: pagination.pageNum, pageSize: pagination.pageSize } const res await getConsultationList(params) tableData.value res.data.records pagination.total res.data.total } finally { loading.value false } } return { tableData, loading, refresh } }这样做的好处是页面组件的代码量大幅减少而且这些组合函数可以跨页面复用——比如宣传物料列表页的搜索分页逻辑几乎完全一样直接复用即可。很多人写Vue3还是习惯把所有东西堆在一个大文件里组件超过800行之后就很难维护了。4. SpringBoot后端接口设计与角色权限控制4.1 接口RESTful设计与统一返回体约定后端接口设计我遵循RESTful风格比如GET /api/plan/list——分页查询宣传计划POST /api/plan/save——新建或更新宣传计划POST /api/plan/delete——删除计划逻辑删除GET /api/channel/metrics——获取渠道统计数据POST /api/consultation/assign——分配咨询线索每个接口的返回体统一用ResultT包装代码结构如下public class ResultT { private Integer code; private String message; private T data; }code为200表示成功401表示未认证403表示无权限500表示业务异常。前端拦截器就是根据这个code做全局处理的。需要留意的是接口URL路径上我加了/api前缀这样在Nginx做反向代理时可以直接把/api开头的请求转发到SpringBoot服务静态资源则交给Nginx本地处理前后端联动很顺畅。4.2 JWT登录认证与拦截器实现系统的登录认证方案是JWT 拦截器。用户登录成功后后端生成一个有效期为2小时的JWT Token返回给前端前端存储在Pinia中并持久化到localStorage。每次请求在请求头中携带Authorization: Bearer token后端通过拦截器验证Token有效性。拦截器里有一个需要重点处理的问题——白名单。登录接口、验证码接口、静态资源这些不需要认证的路径必须在拦截器中放行。我建议把白名单路径集中放在WebConfig里配置Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(jwtInterceptor) .addPathPatterns(/**) .excludePathPatterns( /api/auth/login, /api/auth/captcha, /error ); }这里千万要注意/api/material/preview这类需要公开访问的素材预览路径也要放进白名单否则前端渲染海报图片时图片请求会因为没有Token被拦截导致所有页面图片裂开。这个问题我自己就踩过排查了很久才想到是CDN图片请求不会带Header这个原因。4.3 基于拦截器的接口权限控制光有登录认证还不够招生宣传系统里有三种角色管理员、主管、专员。管理员能管理用户和系统配置主管能审核宣传物料和查看统计报表专员只能维护自己名下的宣传计划和咨询记录。我用一个RequireRole注解实现接口级权限控制在拦截器中做判断Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface RequireRole { String[] value(); }然后在Controller接口上标注需要访问权限的角色RequireRole({ADMIN, MANAGER}) PostMapping(/api/material/audit) public ResultVoid auditMaterial(RequestBody AuditDTO dto) { materialService.audit(dto); return Result.success(); }拦截器里获取当前登录用户角色再与注解要求的角色做比对。这个方案比引入Spring Security或Shiro这种重型安全框架要轻量得多而且对于这种管理系统已经够用。如果你后面要扩展更细粒度的数据权限比如只能看本部门数据可以在查询SQL中基于用户维度动态拼接条件这样最直观。5. 数据统计模块与MySQL查询优化5.1 招生统计报表的数据来源与聚合逻辑数据统计模块是这套系统的亮点也是管理层最关心的功能。主要包含三类报表宣传计划完成度报表按计划维度展示任务完成数量、延期任务数量、整体完成百分比。渠道效果对比报表按渠道维度统计曝光量、咨询量、有效线索量、转化率。月度趋势报表展示近6个月各渠道咨询量的变化趋势辅助决策下个季度的投放预算分配。前两类报表我直接基于业务表统计比如渠道效果报表的核心SQL是SELECT channel_code, COUNT(*) AS total_visits, SUM(CASE WHEN intention_level IN (A,B) THEN 1 ELSE 0 END) AS valid_leads, ROUND(SUM(CASE WHEN intention_level IN (A,B) THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) AS conversion_rate FROM consultation_record WHERE create_time BETWEEN #{startDate} AND #{endDate} GROUP BY channel_code ORDER BY valid_leads DESC需要注意ROUND函数的第二个参数指定保留两位小数同时GROUP BY之后的结果如果有索引支撑会快很多。所以在consultation_record表上我给(create_time, channel_code)建了联合索引这个索引对统计查询的提升非常明显。5.2 MySQL统计查询的慢SQL优化实战项目测试阶段出现过一次报表页面的严重卡顿运营人员选择近一年的时间范围后页面要转圈5秒以上才能出数据。我分析了执行计划后发现问题出在咨询登记表的数据量已经达到50万而统计SQL在扫描条件create_time上走的不是索引全值匹配而是索引范围扫描导致行数还是很大。优化思路是建立汇总统计表channel_daily_stats每天晚上通过定时任务把当天的渠道数据按天汇总插入报表查询时直接查聚合表不再热查明细表。这个方案让报表接口的查询时间从5秒锐减到200毫秒以内体感是完全不同的两个系统。这种“明细表汇总表”的双表设计在大数据量统计场景下是最常用的手段不需要引入ClickHouse等重型OLAP组件。定时任务我用SpringBoot的Scheduled注解实现每天晚上凌晨1点执行汇总。5.3 列表分页查询的数据量边界分页查询的边界问题也很值得聊。咨询登记列表的分页接口一开始用的是MySQL默认的LIMIT offset, size写法当用户翻到第10000页时offset会膨胀到几十万MySQL需要先扫描再丢弃大量无效数据行响应会明显变慢。我改用“末尾ID分页”方案每次查询传入上一页最后一条记录的ID或时间戳SQL中带上WHERE id #{lastId}条件。这种方案在数据量大时性能稳定而且对用户无感。当然对于普通后台管理系统数据量撑死几十万条的情况下LIMIT 索引也能接受不必过度优化。但如果你预判数据会快速膨胀一开始就把这种方案做进去能省去后期改造成本。6. 部署流程与安全加固6.1 前后端分离部署完整步骤部署对于一个前后端分离项目来说是特别容易翻车的一环。我强烈建议一步到位用Docker Compose管理整套环境。下面是我在项目中使用的docker-compose.yml核心配置version: 3.8 services: mysql: image: mysql:8.0 container_name: enroll_mysql environment: MYSQL_ROOT_PASSWORD: root123456 MYSQL_DATABASE: enroll_system ports: - 3306:3306 volumes: - ./mysql-data:/var/lib/mysql backend: build: ./backend container_name: enroll_backend ports: - 8080:8080 depends_on: - mysql environment: SPRING_PROFILES_ACTIVE: prod frontend: build: ./frontend container_name: enroll_frontend ports: - 80:80 depends_on: - backend后端Dockerfile里要特别注意我使用的是多阶段构建FROM maven:3.8-openjdk-8 AS builder COPY . /build WORKDIR /build RUN mvn clean package -DskipTests FROM openjdk:8-jre-alpine COPY --frombuilder /build/target/enroll-backend.jar /app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, /app.jar, --spring.profiles.activeprod]这样做的好处是构建镜像时不会把Maven仓库和源码带进去最终镜像只有运行时依赖体积从800MB降到180MB左右。对于部署到云服务器或内网服务器这个体积差异非常影响拉取速度。6.2 接口安全与数据防泄漏系统安全这块我做了几件事一是管理端接口全部走JWT认证且登录接口加验证码防止暴力破解二是敏感信息脱敏咨询登记表里查看学生电话号码时列表页默认只显示中间四位加星号点击“查看详情”且有权限时才能看到完整号码三是防止SQL注入所有查询都通过MyBatis预编译的#{}占位符禁止用${}拼接字符串只有少数动态表名、排序字段场景才需要白名单校验后使用。这里有个细节容易被忽略MySQL在生产环境不要直接用root账号连接应用应该创建独立的数据库账号并只授予应用库的最小权限比如SELECT/INSERT/UPDATE/DELETE不授予DROP/ALTER等DDL权限。哪怕应用被注入攻击者也无法删库。6.3 开发环境与生产环境的配置隔离SpringBoot的多环境配置是标准做法application-dev.yml和application-prod.yml分开维护。开发环境数据库连接本地开启SQL日志打印生产环境数据库连接内网地址关闭SQL日志。启动时通过SPRING_PROFILES_ACTIVE环境变量指定使用哪个配置而不是在每个环境手动改配置文件——手动改配置是部署事故的高发源头一定要用环境变量或配置中心统一管理。注意如果把spring.jpa.show-sql或MyBatis的SQL日志打印在生产环境打开高并发下日志文件会飞速膨胀磁盘很快被打满。生产环境务必关闭SQL打印需要排查问题时再临时用--logging.level.com.example.mapperDEBUG这种级别开关来针对性打开。7. 常见问题与排查技巧实录7.1 前端跨域请求失败开发环境最常见的报错就是浏览器控制台出现CORS policy相关错误。原因是前端跑在Vite的5173端口后端接口在8080端口浏览器对跨域请求默认拦截。解决方案有两种一是在后端加CORS跨域配置二是在前端Vite配置代理。我更推荐第二种方案。因为生产环境通常用Nginx做同源代理开发环境用Vite代理可以保持和生产环境一致后端不需要特殊处理。Vite的vite.config.js配置如下server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }配置完后前端请求/api/xxx就会自动转发到http://localhost:8080/api/xxx浏览器看到的是同源请求不存在跨域问题。7.2 Vue3响应式丢失导致页面不更新使用组合式API时一个高频踩坑点是解构ref或reactive数据导致响应式丢失。比如在setup中直接割裂解构// 错误的写法 const { total } toRefs(pagination) // total是Ref对象 const { pageNum } toRefs(pagination) // pageNum是Ref对象但在模板中这个问题的本质是从响应式对象中解构出的基本类型属性如果直接使用会变成普通值丢失响应式追踪。正确的做法是在模板中直接引用响应式对象的属性pagination.total或者在脚本中用toRefs保持引用关系。这个坑不踩一次很难理解建议你在写列表页面时特别注意。7.3 MyBatis传入参数为null导致SQL条件失效MyBatis里有一个非常隐蔽的问题if testname ! null中的name来自参数对象但如果用的是Param注解传参test语句里的变量名必须和注解里的名称一致否则if判断永远成立或永远不成立。我习惯在Mapper接口上显式用Param声明参数名ListConsultationRecord selectByCondition( Param(channelCode) String channelCode, Param(startDate) String startDate, Param(endDate) String endDate );然后在XML里用testchannelCode ! null判断。XML和接口方法参数名不一致时MyBatis运行期不会直接报错而是静默跳过条件导致查询结果比预期多出很多数据。这种Bug排查起来非常消耗时间建议从一开始就统一参数命名规范。7.4 大字段导致的列表页查询卡顿宣传物料表里有content字段存储富文本内容这个字段可能很大几万字符。在列表页查询时如果写了SELECT *每次查询都会把这几个大字段全部读取到内存再传给前端即使列表页根本没有用到这些字段白白浪费数据库IO和网络带宽。解决方案是在列表查询的SQL中只查必填字段SELECT id, title, material_type, file_url, cover_url, audit_status, create_time, update_time FROM promotion_material WHERE deleted 0 ORDER BY create_time DESC在详情页查询时才把content字段带上。这个优化对响应速度的提升非常明显尤其是素材数量到了几千条以后差距可能从几秒降到几百毫秒。7.5 前后端联调时日期格式不一致前后端日期格式不一致是联调过程中最容易出现的问题。Java后端默认LocalDateTime序列化格式是2025-06-01T10:30:00而前端Element Plus的日期选择器默认格式是2025-06-01两边拼接后就会导致解析错误。我在后端统一配置了全局的日期格式化Configuration public class JacksonConfig { Bean public Jackson2ObjectMapperBuilderCustomizer jsonCustomizer() { return builder - { builder.serializers(new LocalDateTimeSerializer(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))); builder.deserializers(new LocalDateTimeDeserializer(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss))); }; } }前端请求传参时时间范围用时间戳或统一格式字符串后端再用DateTimeFormat注解解析。两边约定统一后这类问题就能彻底避免。8. 项目扩展与二次开发建议8.1 消息通知模块的快速接入如果要在现有系统上扩展消息通知功能比如物料审核通过后通过短信、站内信通知给提交人建议直接接入SpringBoot自带的spring-boot-starter-mail或集成企业微信/钉钉机器人。核心思路是定义消息中心表在审核状态变更时向消息表插入一条未读消息前端通过轮询或WebSocket推送拉取新消息。WebSocket推送在SpringBoot里实现相对轻量引入spring-boot-starter-websocket后定义一个TextWebSocketHandler处理前端连接及消息推送即可。这套方案比集成第三方IM服务SDK要省心得多完全满足室内的通知场景。8.2 数据大屏的可视化对接招生宣传系统跑一个招生季之后数据积累下来说不定管理层又想要一个数据大屏把实时咨询量、渠道排名、计划完成度投屏展示。这时候不要重新开发直接把现有统计接口的数据源稍作调整前端用ECharts或DataV即可。因为系统的统计接口在设计时就考虑了按日期范围、渠道等维度查询大屏只是换了展示形式数据对接成本很低。如果要做大屏前端部分建议用Vue3 ECharts配置几个图表组件渠道转化漏斗图展示从曝光到有效咨询再到报名的转化链路。区域热度地图如果是区域招生可以用地图展示各省份的咨询热度。实时滚动消息用ElNotification或自定义滚动列表展示最新咨询线索。8.3 从单体到微服务的演进判断这个系统目前是标准的单体应用只要数据量控制在百万级以内、并发量在几百以内单体应用完全扛得住优先把性能优化做透不要盲目上微服务。如果未来要拆可以按业务域拆分两个服务一个是宣传内容服务管理计划、物料、审核一个是咨询转化服务管理咨询记录、跟进、统计中间通过Feign调用。拆分的前提是业务模块之间已经做了明确的领域边界划分而不是把所有代码堆在一起然后按Controller切分。我在设计包结构时就已经按模块划分了com.enroll.plan、com.enroll.material、com.enroll.consultation、com.enroll.stats这几个包以后要拆服务直接把包代码搬出去就能复用。9. 实操心得与经验总结项目做到这里整体已经能支撑一个招生季的完整业务运转了。我个人在实际操作中最深的两点体会是第一前后端分离的项目接口契约管理一定要前置。前后端各有自己的开发节奏如果接口文档不提前定清楚联调阶段会陷入“改接口、等前端、再改接口”的循环中。我自己用Apifox管理接口文档前端看文档就能Mock出所有数据联调效率提升非常明显。第二点是权限模型再简单也要预留扩展空间。招生宣传管理系统的用户角色现在只有三种但实际业务中很可能出现“分校管理员”“合作渠道商”这样的新角色。所以我设计的用户表里有role_id字段权限判断也统一走拦截器 注解要加角色只需要在角色表和注解允许值里扩展不需要改动核心业务逻辑。最后再分享一个实用的小技巧物料上传和统计报表是招生宣传系统里最容易出性能问题的两个点建议你在还没有遇到瓶颈时就把这些优化方案从设计阶段就考虑进去比如文件存储独立到OSS/MinIO、统计查询走汇总表。很多问题等到线上出了再改成本是开发时的好几倍。这套系统的代码结构整体按照“模块化、接口隔离、配置外部化”的原则组织你要拿去扩展新的业务模块照着现有模式推就行。