基于Node.js+Vue的前后端分离管理系统开发全记录

先说一下背景。去年学校就业办找我做一个大学生创业项目申报评比系统要求是学生能在线上报项目材料评委能在线打分评审管理员能配置评审指标并导出最终排名。技术栈指定了Node.js Vue前后端分离。这活儿听起来简单真做起来踩了不少坑尤其是Node环境和Vue工程化这两块网上资料虽多但碎片化严重。这篇文章我就把这套系统的设计思路、核心模块实现、以及我在Windows环境下从零搭建到部署的完整过程写出来给准备做类似管理系统或者刚入门全栈开发的同行做个参考。1. 项目整体设计与技术选型思路1.1 为什么选Node.js做后端而不是Java或PHP说实话这类校园管理系统的后端用Spring Boot或者ThinkPHP的人更多毕竟高校里Java系的老项目多接手维护方便。但这次是从零开发的新系统没有历史包袱我选Node.js有几个实际考量。首先是开发效率。创业项目申报评比系统的业务逻辑不算复杂主要就是申报、评审、统计排名三块但流程状态多、角色权限划分细。Node.js搭配Express框架写RESTful API非常轻快一个路由文件对应一个业务模块半天就能把申报接口的骨架搭完。如果用Spring Boot光是配置类和依赖注入的初始化工作就要多花两三天。其次是前端后端语言统一。这套系统前端用Vue后端用Node.js两边都是JavaScript数据格式天然协调。比如日期格式化、数组去重、对象深拷贝这类工具函数我在前后端可以直接复用同一套逻辑思路不用在Java里写完一遍再用JS写一遍。对于小团队开发这种心智负担的降低是很实在的。第三是部署轻量。Node.js应用打包后就是一个主进程配合PM2做进程守护比Tomcat加WAR包的部署方式简单太多。我们学校的服务器配置一般2核4G的云主机跑Node.js加MySQL完全够用不需要为这套系统单独上大内存的机器。当然Node.js也有短板比如CPU密集型计算能力弱但申报评比系统里最重的操作也就是算平均分和排名几百个项目的计算量在毫秒级完全戳不到性能瓶颈。我当时的判断是这个项目用Node.js是性价比最高的选择。1.2 Vue前端框架的选型与工程化优势前端这块Vue的决定基本没有犹豫。Vue的模板语法直观中文文档完善团队成员上手成本低。我们有个同学之前只写过原生JS和jQuery看了一下午Vue文档就能写页面了这换React是做不到的。具体到这套系统Vue的优势集中在三个地方。第一是组件化开发。申报表单、评审打分卡、项目列表、排名表格这些都是独立组件路由切换时组件复用和懒加载非常方便。比如用户从评审列表点进某个项目的详情页打分组件通过props接收项目ID子组件内部维护评分状态互不干扰。第二是Vue Router的路由管理。这套系统有学生端、评委端、管理员端三种界面路由结构差异很大。我用路由嵌套加动态路由的方式根据登录用户的角色动态注册对应模块的页面避免把三种角色的页面全塞在一起导致路由臃肿。详情我在后面核心模块部分会展开。第三是前后端分离的开发模式。Vue项目通过webpack-dev-server跑在8080端口后端Node接口跑在3000端口联调时用http-proxy-middleware做代理转发前端代码里不需要写死后端地址。这样在本地开发环境和生产环境之间切换只用改Vue Router的base路径和Nginx的代理配置代码层面零改动。1.3 整体架构与数据流向这套系统的架构并不复杂但分层必须清楚。客户端是Vue单页应用通过Axios调用后端的RESTful API。后端分为三层路由层controller、服务层service、数据访问层model。路由层只负责解析请求参数、调用服务层方法、返回HTTP响应。服务层写业务逻辑比如申报项目时校验材料完整性、评审时判断打分是否超出指标范围。数据访问层用mysql2库直接写SQL操作数据库没有上ORM因为这套系统的查询模式比较固定手写SQL更可控而且方便后面做排名统计这种复杂查询。数据流向举个例子学生提交创业项目申报前端申报表单收集数据 - Axios POST到 /api/projects - 路由层校验登录态和角色 - 服务层检查项目信息完整性和是否重复申报 - 数据访问层插入projects表 - 返回申报成功和项目ID给前端 - 前端路由跳转到我的项目列表页。评审打分流程类似评委在待评审列表点开项目详情 - 前端调用GET /api/projects/:id获取项目完整信息 - 评委在打分组件填入各项分数和评语 - POST到 /api/reviews - 服务层计算该评委是否已评过此项目防止重复打分 - 写入reviews表 - 更新该项目的平均分缓存。这个架构模式是我在实际开发中反复验证过的对于中小型管理系统比引入消息队列、微服务之类的东西实用得多。2. 环境搭建与工程初始化全记录2.1 Nodejs安装及环境配置的完整步骤很多新手在第一步装Node.js就会被卡住我自己也遇到过。这里把完整流程写清楚照着做基本不会出问题。第一步去Node.js官网下载LTS版本安装包。注意两点一是安装路径不要带中文和空格我建议直接把默认的C:\Program Files\nodejs改成D:\nodejs省得后面环境变量出幺蛾子二是安装到选择组件那一步时把Add to PATH选项勾上这选项默认就是勾选的但有人手滑取消过导致装完node命令找不到。第二步验证安装。安装完成后打开命令行WinR输入cmd分别执行node -v和npm -v能输出版本号就说明装成功了。我这边装的是Node 18 LTS对应的npm版本是9.x。第三步设置npm镜像源。这一步强烈建议做否则国内网络直接npm install拉取依赖速度慢到你怀疑人生。执行npm config set registry https://registry.npmmirror.com然后npm config get registry确认一下输出的是镜像地址就行。我见过有人不设镜像装一个Vue CLI等了二十分钟还在转圈。第四步配置环境变量。虽然安装时勾了Add to PATH但为了保险还是要检查一下。右键此电脑 - 属性 - 高级系统设置 - 环境变量在系统变量的Path里确认nodejs安装目录存在。另外建议新增一个NODE_PATH环境变量变量值填node_modules的全局路径比如D:\nodejs\node_global\node_modules这是给全局安装的模块用的。这里有个容易踩的坑全局安装的包如果用默认路径在Windows上经常会遇到权限不足的报错。解决办法是修改npm的全局安装路径执行npm config set prefix D:\nodejs\node_global再配合上面的NODE_PATH环境变量之后全局安装的vue-cli、pm2之类工具就会装到D盘不会有权限问题。2.2 Vue项目初始化与依赖安装避坑环境变量搞定了接下来创建Vue项目。我用的是官方脚手架Vue CLI先全局安装npm install -g vue/cli然后vue create project-name选择Vue 3的预设我用的是Vue 3 Vue Router Pinia的组合没选Vuex因为新项目完全没必要用Vuex那套旧东西。创建过程里有两个小坑说一下。第一个是选择包管理器。Vue CLI会问你用npm还是yarn这里选npm就行因为前面已经配置了镜像源而yarn的镜像源是独立配置的还得单独再设一遍。第二个是项目创建完成后的依赖安装阶段如果网络不稳定会中途报错我建议分两步走先npm install --save core-js把核心库单独装上再执行npm install这样报错概率低很多。依赖装好之后我会做三件标配的事安装Element Plus组件库和Axios。 npm install element-plus axios在main.js里全局注册Element Plus并且引入中文语言包不然日期组件默认是英文。 import ElementPlus from element-plus import element-plus/dist/index.css import zhCn from element-plus/es/locale/lang/zh-cn app.use(ElementPlus, { locale: zhCn })配置Axios的基础路径和拦截器。我把Axios抽取成独立的request.js工具模块设置baseURL为/api请求拦截器里从localStorage取出token放到Authorization请求头响应拦截器里统一处理401跳转登录页。这里多说一句Vue CLI创建的默认项目结构里src目录下有views、components、router、store或pinia几个文件夹。我会按业务模块再细分比如views下面按角色建student、reviewer、admin三个子目录对应的页面文件放各自目录里这样多角色系统才不会混乱。2.3 前后端联调的基础配置前后端分离开发本地联调绕不开跨域问题。我常用的方案是在Vue项目的vue.config.js里配置devServer的proxy。module.exports { devServer: { port: 8080, proxy: { /api: { target: http://localhost:3000, changeOrigin: true } } } }这样配置之后前端代码里的axios请求URL写的都是/api/xxx在开发环境下会被webpack-dev-server代理转发到后端的3000端口。生产环境部署时这一层代理由Nginx负责配置逻辑完全一样前端代码不用动第二个地方。还有一个基础配置是跨域CORS的兜底。虽然devServer的proxy解决了开发环境的跨域但万一有人不走代理直接访问后端比如用Postman调试接口后端还是要做一层CORS开放。在Express里我用cors中间件一行代码搞定app.use(cors({ origin: true, credentials: true }))。credentials设置为true是为了让JWT认证时前端能带上cookie凭证。3. 核心功能模块的拆分与实现3.1 项目申报模块表单设计、文件上传与状态流转申报模块是整个系统的数据源头学生填的所有信息都会沉淀成项目记录后面评审和评比都依赖这批数据。所以我把申报表单设计得比较细致一共分四个页签。基本信息页签项目名称、项目类别下拉选择包括科技创新、文化创意、社会服务等、负责人信息、团队成员列表动态增删最多6人、指导老师。项目计划书页签项目的背景、目标、实施方案、预期成果、风险评估。这个页签用富文本编辑器我选的是wangeditor上传图片的功能也能直接嵌进来。预算信息页签经费预算表分支出科目、预算金额、测算依据三列前端做金额格式校验并自动统计总额。附件材料页签支持上传商业计划书PDF、专利证明、获奖证书等材料。核心交互是文件上传。我用Element Plus的Upload组件上传接口指向后端的 /api/upload后端用multer中间件处理保存到服务器上的uploads目录返回文件路径给前端。这里有一个非常关键的细节生产环境部署时uploads目录必须设置为Nginx的静态资源映射路径否则前端拿到的文件URL是404。我第一次部署就栽在这上面浏览器能打开页面但附件图片全裂排查了半天才发现是Nginx没把uploads目录暴露出去。申报提交后的状态流转是这样设计的草稿 - 待审核 - 审核通过进入评审 / 审核驳回可修改后重新提交。状态的每次变更都写入projects表的status字段并记录操作日志表的记录防止学生对审核结果有争议时无据可查。3.2 评审打分模块评分指标动态配置与防重复评审评审模块是这套系统的核心业务点。我一开始设想的很简单就是一个总分直接填数字。后来跟就业办的老师聊需求发现实际评审要按多个维度分别打分比如创新性30分、可行性30分、团队能力20分、社会价值20分每个维度的权重可以调整算总分时加权平均。所以我把评审指标设计成了独立的表review_indicators字段有指标名称、满分值、权重、是否启用。管理员可以在后台动态增删指标、调整权重。评委打分页面从接口拉取指标列表按每个指标的满分值渲染对应的数字输入框前端实时计算加权总分展示后端评审提交接口再次计算校验以服务端计算结果为准。防重复评审这个坑我是在测试阶段发现的。一个评委如果手滑提交了两次打分或者先把页面开着然后换了电脑再评一次数据库里就会出现两条评审记录排名时如果直接SUM就会把分数算重了。我的处理方法是在reviews表加一个唯一索引(project_id, reviewer_id)数据库层面直接阻断重复插入。同时还做了一个兜底检查评审提交前先查询该评委是否已评过此项目已评过就直接返回提示。两道保险实测下来基本杜绝了重复评审的问题。还有个小细节是评语的可见性。系统的评审规则是在评比结果公示前评委之间的评语互不可见防止个别评委受他人意见影响。这个通过查询接口实现拉取评审列表时只返回分数评语字段只有在系统管理员导出数据时才带出。3.3 评比汇总模块排名算法与结果公示评比汇总就是根据所有评委的打分算出每个项目的最终成绩并排名。这里用的算法是去掉一个最高分、去掉一个最低分然后取平均分这是校园类评比最常用的规则能有效避免个别极端分数的影响。SQL是这样的SELECT project_id, AVG(score) AS final_score FROM reviews GROUP BY project_id但如果要精确实现去掉最高最低分的逻辑一句GROUP BY不够要配合子查询SELECT r.project_id, (SUM(r.score) - MAX(r.score) - MIN(r.score)) / (COUNT(r.score) - 2) AS final_score FROM reviews r WHERE r.project_id ? GROUP BY r.project_id HAVING COUNT(r.score) 3这里必须满足一个前提每个项目至少有3个评委打分才能进入排名否则去掉最高最低之后分母为0。管理员后台可以设置参与评比的评委数量下限系统在后台任务中自动检查未达标项目并提示管理员补充评委。排名结果公示也有讲究。我做的公示页面把总排名列表、每个项目每项指标的得分明细不显示评委身份、统计图表三块放在一起。统计图表用ECharts的雷达图展示各维度的得分情况方便老师和学生直观看到项目的优劣势。公示期设置一个倒计时公示期内结果只读公示期结束后管理员可以一键导出最终排名Excel。3.4 角色权限控制JWT认证与前端路由守卫这套系统有三种角色学生、评委、管理员。权限控制的精度要求是学生只能看和管理自己申报的项目评委只能看到分配给自己的评审任务管理员拥有全部功能。后端我用JWT做无状态认证登录成功后签发包含用户ID和角色的token有效期为24小时。后端中间件express-jwt统一校验请求头里的token然后根据接口定义的角色要求做二次校验。比如提交评审接口只允许评委角色调用我写了一个requireRole(reviewer)的中间件路由里这样挂载router.post(/reviews, requireAuth, requireRole(reviewer), reviewController.create)前端这边的路由守卫配合做体验层控制。Vue Router的beforeEach钩子里每次跳转先检查是否登录再检查目标路由的meta信息里配置的角色白名单。如果当前用户的角色不匹配直接跳转到登录页或403提示页。router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.meta.requiresAuth !token) { next(/login) } else if (to.meta.roles !to.meta.roles.includes(userRole)) { next(/403) } else { next() } })这个双层权限设计看起来冗余实际是必须的。前端守卫只是提升用户体验真正防越权必须靠后端接口级别的校验否则别人直接发HTTP请求就能干坏事。这个道理我是在第一次上线后被一个学生用Postman扫了一遍接口之后才彻底明白的。4. 开发中的高频踩坑与排查实录4.1 Windows系统下npm.ps1无法加载的问题这个坑估计每个Windows上跑Node的人都会遇到。新建Vue项目后在PowerShell里执行npm run serve直接报红npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本原因很简单Windows PowerShell的脚本执行策略Execution Policy默认是Restricted禁止运行任何.ps1脚本而npm命令在PowerShell环境里会走npm.ps1这个壳脚本刚好被卡住。解决办法有两种我推荐第二种。第一种是每次打开PowerShell时先执行Set-ExecutionPolicy RemoteSigned作用域是当前用户需要确认后生效。优点是简单缺点是要记住每次新建终端窗口都执行一遍很麻烦。第二种是直接在系统里放开策略执行一次 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这个命令只对当前用户生效不会影响系统其他用户RemoteSigned表示本地的.ps1脚本可以运行从网络下载的脚本必须要有可信签名。执行完再打开PowerShell就正常了。如果你嫌麻烦还有个一劳永逸的办法以后命令行操作统一用CMD窗口CMD里执行npm不会走.ps1脚本自然没有这个限制。但PowerShell在Windows终端里的体验更好我个人还是建议改策略一劳永逸。4.2 Vue路由动态参数与刷新丢失问题的处理这套系统里有大量从列表页点进详情页的场景比如评委从待评审列表点开某个项目我会把项目ID放在路由参数里router.push({ path:/review/detail/${projectId}})这里有个经典问题项目详情页刷新后路由参数还在但如果我用的是params方式而忘记配置对应路由时刷新后参数会丢失页面拿不到projectId直接白屏。我之前用this.$route.params.projectId在mounted里取参数刷新后有一次就崩了。排查后的根本原因是刷新时组件重新创建如果参数在beforeRouteEnter或created里拿不到页面就废了。我的解决方案是双保险路由配置时给详情页的path写明动态参数路径{ path: /review/detail/:projectId, component: DetailPage }页面里用watch监听$route.params.projectId的变化确保路由参数变化时页面数据同步更新。这样无论是从列表进入还是直接刷新项目ID都能稳定获取。4.3 前后端联调时的跨域与代理配置问题开发环境联调时我遇到过一种看似诡异的情况通过npm run serve启动前端浏览器控制台报跨域错误但接口明明能在Postman里正常调用。原因是我在vue.config.js里配置了proxy但由于后端接口路径写的是完整URLhttp://localhost:3000/api/xxx而不是相对路径/api/xxx请求没有经过devServer的代理直接跨域了。解决方法是前端axios的baseURL统一设为/api所有请求都写相对路径由devServer代理到后端。如果哪个接口直接写了http://localhost:3000这种地址就会被浏览器拦截。这个规则我后来列入了团队开发规范避免再犯。4.4 文件上传大小限制与类型校验学生申报创业项目时经常会传很大的附件比如几十页的商业计划书PDF。Express默认的body大小限制是100kb超过就报413错误。我一开始没改这个配置学生上传3MB的PDF直接失败。解决办法是给文件上传单独走multer中间件不经过body-parser的JSON解析const upload multer({ dest: uploads/, limits: { fileSize: 20 * 1024 * 1024 } })同时在前端Upload组件加上beforeUpload钩子校验文件类型只允许pdf、docx、jpg、png和大小20MB以内。前端校验配合后端limits限制双端都拦住超大文件避免服务器磁盘被塞满。这个经验是在有一次学生上传了个2GB的视频文件把服务器磁盘写满之后才学到的差点导致系统宕机。4.5 Excel导出乱码与百分比格式问题评比结果导出Excel是管理员的刚需。我用了node-xlsx库后端直接生成xlsx文件返回给前端下载。第一次导出后发现两个问题中文文件名乱码、数字格式全变成文本。中文文件名乱码是因为Content-Disposition响应头里没做URL编码要这样设置res.setHeader(Content-Disposition,attachment; filename*UTF-8${encodeURIComponent(filename)})数字格式问题是因为node-xlsx默认把所有cell都当字符串处理。解决办法是在生成数组时把数值型字段明确设置为数字类型node-xlsx支持直接传JSON对象数组然后指定列类型。这个细节不处理排名分数导出来全部是文本格式老师没法直接做数据透视。5. 部署上线与长期运维建议5.1 生产环境的Nginx反向代理配置本地开发完成后部署这一步很多人会栽跟头。我的部署方案是前端Vue打包成静态文件npm run build放在服务器Nginx的html目录下后端Node项目用PM2启动监听3000端口Nginx配置反向代理把/api路径转发到3000端口。关键配置片段如下server { listen 80; server_name your-domain.com;root /var/www/vue-dist; index index.html; location /api/ { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /uploads/ { alias /var/www/node-app/uploads/; } location / { try_files $uri $uri/ /index.html; }}这里有两个容易漏的配置。一个是try_files $uri $uri/ /index.html这是SPA应用刷新时路由不404的关键。如果不写用户刷新详情页时Nginx去找对应的服务器文件找不到就返回404控制台一片红。另一个是location /uploads/的alias这就是我前面提到的那处附件404问题的正解uploads目录必须单独暴露出来。5.2 服务器端PM2进程管理与日志排查Node应用裸跑在服务器上非常不稳进程挂了没人知道重启也要手动操作。我用PM2做进程守护效果很好pm2 start app.js --name project-system --max-memory-restart 500M安装PM2后启动命令带上了进程名和内存限制。PM2的生态文件ecosystem.config.js里我会配置好了环境变量和日志路径。这样即使某个接口写崩了导致进程OOMPM2会自动重启应用系统不会长时间不可用。排查看日志也是运维必备技能。PM2的日志文件一般在~/.pm2/logs目录下我对应用日志做了分级普通接口访问日志、错误日志和业务操作日志分开记录。有一次线上用户反馈评审打分一直保存失败我直接去查错误日志发现是接口里写错了一个字段名MySQL报Unknown column。定位这种问题如果没有日志在黑盒状态下去猜效率极低。5.3 数据库备份与数据安全这套系统里最重要的是学生提交的材料和评委的打分记录丢数据是不可接受的。我的备份策略包含两个层面一是每天凌晨用crontab执行mysqldump备份全库保留最近7天的备份文件二是针对uploads附件目录做每日增量同步到另一台服务器或者云存储取决于经费预算。另外提一句数据安全相关的事。登录接口我使用的是bcryptjs做密码哈希数据库里存的是密文而不是明文。有次帮别的项目查问题发现他们数据库里直接存了用户明文密码这个习惯真的不好出了事故追责都说不清楚。无论系统多小密码必须加盐哈希这是从业者的底线。还有一点是敏感数据的脱敏。评分公示页面展示的排名表评委的个人信息一律不展示只显示评语和分数。这个我在后端接口设计时就做了字段过滤前端根本拿不到非授权的数据。6. 实测下来的几个实用优化系统上线运行了三个月我根据实际使用反馈做了几个小优化这里单独列出来给有类似需求的同行参考。第一个优化是申报表单的自动保存草稿功能。学生填一个创业计划书往往要几天时间中途关闭浏览器再打开如果之前填的内容全没了体验非常糟糕。我加了草稿自动保存表单内容有变动就防抖3秒自动调接口存草稿用户下次打开表单时直接回填上次的草稿内容。这个需求最初没在需求文档里属于使用过程中反馈出来的真需求。第二个优化是评审分配的智能均衡。最初评委的项目分配是管理员手动指定的几十个项目逐个分配很烦。我做了自动分配逻辑按评委的历史已评审数量升序排列优先把新项目分配给评审量最少的评委保证大家工作量接近。同时管理员还可以手动干预分配结果系统保留手动调整的优先级。第三个优化是移动端适配。学生和评委很多时间是在手机上使用的特别是评委在开会评审时基本都拿手机看项目材料。我用flexible布局加rem单位做了主要页面的响应式适配并在Element Plus的栅格系统里针对手机屏幕优化了表单布局。现在在手机上打开申报表单体验虽说不算顶级但起码不会出现表格撑破屏幕的情况。第四个优化是评比结果的可视化。最初的排名页就是一张列表老师反馈不够直观。后来我在结果页集成了ECharts把总分分布做成柱状图、各维度平均分做成雷达图、类别占比做成饼图一套数据三个维度的图表不仅看着专业也方便校领导在汇报时直接截图使用。这些优化都不是需求文档里提前写好的全是用户在实际使用过程中提出的合理需求或者说是我自己用着用着觉得别扭才改的。所以我的体会是管理系统的开发不是一锤子买卖上线只是起点持续迭代才能真正贴合用户习惯。最后分享一点个人实操中的体会。这套系统从需求梳理到部署上线我大概花了三周时间其中真正写代码的时间只占六成剩下四成都在处理环境问题、联调问题和部署问题。Node.js和Vue本身是成熟的框架难点并不在语法层面而在工程化配套的细节npm镜像、环境变量、代理配置、权限守卫、Nginx路由回退、附件静态资源映射这些才是实际开发中反复消耗精力的地方。如果你正准备做一个类似的前后端分离管理系统我的建议是先把环境这层彻底搞定写业务代码之前解决所有工具链问题后面真的能顺畅很多。