最近帮一个学弟把“校园便利平台”这类型的老项目从零到一重新梳理了一遍顺手把源码、SQL 脚本和接口文档全部整理成了一套可以直接跑起来的毕设级交付物。说实话这类题目在 Java Web 毕设里非常典型表面看是“一个 SpringBoot 后端 一个 Vue 前端”但实际要交付的东西远不止代码数据库脚本要能一跑就过接口文档要有统一的返回体前后端联调要不出幺蛾子最后还得拿这套东西顺利过答辩。我今天就把整个项目的拆解思路、每一块的核心实现、踩过的坑以及最后整理交付物的经验全部抖出来。不管你是准备开题的学生还是给毕设项目做主流程开发的初学者这篇文章大概率能帮你少走一堆弯路。1. 项目整体设计与思路拆解1.1 这个平台到底在解决什么问题很多同学看到“校园便利平台”这种题目第一反应就是“这不就是个商城吗”然后一头扎进商品列表、购物车、下单支付这些功能里。结果做着做着发现校园场景里的需求和普通电商差异很大而且大部分现成商城模板照搬过来非常别扭。我梳理题目时把它拆成了三层需求最底层的是“用户侧”学生需要一个能浏览商品、下单、查看订单、评价、维护个人信息的地方中间层是“交易侧”包括订单状态流转、库存或者物品数量的变化、交易双方的沟通记录最上层是“管理侧”平台管理员要能审核商品、管理用户、处理举报或者查看平台关键数据。这三个层次串起来才是一个完整的“校园便利平台”。如果只做用户下单管理员发货那本质上就是个简化版商城真正值得拿出来讲的是订单状态机怎么设计、多角色权限怎么隔离、商品审核流程怎么走、前后端接口怎么约定。这些才是你在答辩时能撑住场面、在简历上能写成具体技能点的东西。1.2 技术选型为什么是 SpringBoot Vue而不是其他组合毕设项目选型最重要的原则是三件事自己熟悉、生态成熟、演示稳定。SpringBoot Vue 这套组合在校园里几乎成了默认答案不是没有原因的。后端用 SpringBoot开发效率确实高。自动配置帮你省掉了大量 XML 配置内嵌 Tomcat 让部署变得很轻配合 MyBatis-Plus 之后CRUD 代码几乎就是体力活不需要自己写一堆重复的 JDBC 模板代码。前端用 Vue主要看中它的组件化能力和响应式数据流。尤其对毕设这种“页面多、交互中等”的应用用 Vue 写页面比用传统的模板引擎舒服太多。Element UI 或者 Element Plus 组件库直接拖出来用后台管理的表格、表单、弹窗半小时就能搭完。还有一个很重要的原因这套技术栈开源资料多。你遇到任何运行报错把关键日志往搜索引擎里一放基本都能找到对应的解决方案。这点对时间紧、任务重的毕设来说价值比技术本身的新旧重要得多。当然如果你非要选 JSP Servlet也不是不行但那个年代的东西已经很难让答辩老师眼前一亮了。相比之下前后端分离的架构本身就是一个“设计亮点”你可以在答辩时讲清楚前端通过 Axios 请求后端接口后端提供 RESTful API数据用 JSON 传递两边完全解耦。这一句话就值不少分数。1.3 模块划分与功能清单我实际落地的模块划分是这样的模块说明核心功能点用户模块学生用户、管理员、商家三类角色注册登录、信息修改、密码加密、头像上传商品模块平台核心内容载体商品发布、列表筛选、搜索、详情、上下架订单模块完整闭环校验创建订单、订单状态流转、取消、完成评论模块交易后互动评分、文字评价、评价列表通知模块信息触达站内通知、已读未读管理模块平台管控用户禁用、商品审核、数据统计我当时没有做真正的在线支付。原因很简单学生项目接入支付是有门槛的而且支付牵扯到资金安全、商户资质这些很现实的问题不是写个接口就完事。所以这里用“模拟支付”替代用户提交订单后点击“模拟支付”按钮后端直接把这笔订单状态改成已支付。这个点在设计文档里明确写清楚答辩老师完全能接受毕竟我们做的是业务逻辑演示不是生产支付系统。2. 数据库设计与 SQL 脚本的坑与思路2.1 核心表结构设计数据库设计是整个项目里最不能浮躁的部分。表建得烂后面所有代码都要围绕烂设计打补丁。我最终一共建了八张表这里挑几张核心表说一下设计思路。用户表sys_user字段大概是这样id、username、password、nickname、phone、role、avatar、status、create_time。其中role字段用字符串存储取值为USER、ADMIN、MERCHANT比用数字 0/1/2 更直观写条件判断时也不用去翻文档。商品表product和普通商城表有区别因为是校园二手和便利服务混搭所以我加了一个type字段区分是全新商品还是闲置转让。关键字段有seller_id、title、description、price、original_price、stock、cover、status其中status很关键用于区分0待审核、1已上架、2已下架、3审核驳回、4已卖出这五种状态。订单表orders是最需要动脑筋的。因为平台同时有“普通购买”和“跑腿代取”两种交易形态我把它们做成了一张订单表和一张扩展信息表。订单表存公共字段订单号、买家 ID、卖家 ID、商品 ID、金额、状态、创建时间扩展表存与业务相关的信息比如代取地点、期望送达时间、备注。订单状态我用一串常量表示0待支付、1已支付待处理、2已完成、3已取消、4退款中。不要用中文存状态后端定义枚举前端展示时再映射成中文这样接口返回更规范也不会出现一处改中文另一处漏改的问题。2.2 外键和索引该用的时候用该省的时候省我看到很多毕设代码里特别喜欢加物理外键好像建了外键才叫规范。实际开发里尤其是 SpringBoot MyBatis-Plus 这种组合物理外键带来的麻烦远大于收益。我的做法是逻辑外键 必要的索引。表与表之间的关联全靠业务代码去维护数据库层面只加索引不建 FOREIGN KEY。理由有三条MyBatis-Plus 做插入、删除、分页时物理外键会影响操作的灵活性尤其是一对多关系的删除容易被外键约束卡住在线演示环境跑数据初始化脚本时有外键就意味着建表顺序必须严格依赖一个不小心就报外键关联错误毕设规模的数据量根本不需要数据库去“保护完整性”应用层的判断已经足够。索引这一块我的原则是给查询频繁的字段加普通索引。比如orders表的buyer_id、seller_idproduct表的seller_id、status。注意别给每个字段都加索引那会让插入变慢而且也没有实际意义。2.3 SQL 脚本里必须注意的几个细节SQL 脚本是整个交付物里最先被演示的东西也是很多项目翻车的重灾区。我见过太多人把 SQL 文件导出一个几百兆、一坨一坨的复杂脚本结果别人在另一台电脑上导入要么字符集错误要么主键冲突。我整理 SQL 脚本时做了三件事在脚本开头加SET NAMES utf8mb4;并且把建库语句写成CREATE DATABASE IF NOT EXISTS campus_platform DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;DEFAULT CHARACTER SET 必须指定否则中文很容易变乱码使用DROP TABLE IF EXISTS先清理旧表再CREATE TABLE避免重复导入时报表已存在写一批干净的初始化数据包含一个管理员账号、一个商家账号、两个学生账号还有十条左右商品数据。演示的时候直接登录就能看到效果不需要现场注册再拍照上传。提示账号密码不要用明文写在 SQL 里先把密码用 BCrypt 生成好密文再插入。一方面是对的另一方面也展示了你在安全这块的认知。3. 后端 SpringBoot 实现中的关键环节3.1 项目结构与分层设计很多同学拿到代码之后根本分不清哪个类该放哪个包最后项目结构成了一锅粥。我建议的分层方式是下面这样的com.campus.platform ├── config // 配置类跨域、WebMVC、拦截器、MybatisPlus分页 ├── controller // 控制层接收请求、参数校验、返回统一结果 ├── service // 业务层业务逻辑的核心 │ └── impl ├── mapper // 数据访问层MyBatis-Plus的Mapper接口 ├── entity // 实体类对应数据库表 ├── dto // 传输对象前端传来的复杂参数 ├── vo // 视图对象返回给前端的结构 ├── utils // 工具类JWT工具、文件上传工具 └── exception // 全局异常处理这种分层的价值在答辩时特别好讲。你可以说控制层只负责参数接收和结果返回业务逻辑全部在 Service 层数据访问职责交给 Mapper每一层各司其职这种设计思路在企业开发里是通用的。实际写代码时我也确实受益于此比如后来加了一个收藏功能我只需要在 Controller 加一个接口、Service 加一个方法、Mapper 加一条 SQL完全不影响已有模块。3.2 用户认证与权限控制这个项目我没直接引入 Spring Security而是用了更轻量的 JWT 拦截器方案。不是 Spring Security 不好高中低配场景选择同样要考虑到对代码的可控性。Spring Security 的门槛在于它拥有一套完整的过滤器链和配置体系如果你不熟悉从头配置反而会浪费大量调试时间。JWT 方案的逻辑其实非常清晰用户登录成功后后端验证用户名密码通过后生成一个 JWT Token 返回给前端前端拿到 Token 存到本地存储之后每次请求在请求头里带上Authorization: Bearer token后端写一个拦截器拦截所有需要登录才能访问的请求解析 Token解析失败或过期就返回 401解析成功之后把用户 ID、角色这些信息放到请求上下文中后续业务代码可以直接取。拦截器代码里有个细节值得单独提一下放行名单一定要配置好。登录接口、注册接口、商品列表、商品详情这些是可以匿名访问的其他接口都需要校验 Token。如果你不小心把所有接口都拦截了前端就连商品列表都刷新不出来这种低级错误排查起来还挺费劲因为前后端日志都可能不报错只是拿到 401。我做权限控制时用了两个注解配合自定义拦截器RequireRole(ADMIN)标注在需要管理员权限的接口上拦截器里判断当前用户的角色是否匹配。这样比在每个 Controller 方法里去 if 判断角色优雅得多。3.3 文件上传与订单状态机文件上传是毕设演示的常见功能用来做商品图片上传、用户头像上传。SpringBoot 的 MultipartFile 处理这个还是很顺手的我把图片保存到了服务端的本地目录然后把静态资源映射到/upload/**路径前端就能直接通过 URL 访问图片。这里有个容易忽略的问题上传目录的路径是写绝对路径还是相对路径我踩过一次坑用绝对路径写死换一台机器后目录不存在启动就报错。后来我在配置文件里写file.upload-dir./upload/然后在代码里判断目录不存在就Files.createDirectories()主动创建这才彻底解决。订单状态机是整个后端里最值得讲的部分。我画过很多次图代码却很简单。所谓状态机就是明确定义“当前状态 操作 - 新状态”的映射关系。我用了一个OrderStatus枚举里面不仅定义常量还定义了一个canTransitionTo(targetStatus)方法。比如待支付状态允许执行取消、支付已支付状态允许执行发货、申请退款已完成状态不允许任何操作。然后在订单更新的 Service 方法里先取出老订单检查状态转换是否合法合法才继续更新。这个东西看着不起眼但它保护了数据一致性而且你可以在答辩时用实际例子说明为什么“已完成的订单不能再次支付”。状态机这个词一旦说出来项目档次马上就上去了。3.4 统一返回体和全局异常处理前后端联调最怕什么最怕后端每个接口返回的 JSON 结构都不一样。有的成功直接返回数据有的失败返回错误信息前端就得每个接口单独写逻辑。我实现了一套统一的返回体前端所有请求拿到的结构永远是{ code: 200, message: 操作成功, data: {} }code用于判断业务是否成功message是展示给用户的提示data才是真正的业务数据。Controller 里的方法全部返回这个结构我为此写了一个R工具类里面提供R.ok(data)、R.fail(message)这些静态方法调用起来非常顺。配合全局异常处理后端代码就可以减少大量 try-catch。在GlobalExceptionHandler类上用RestControllerAdvice注解针对BusinessException、校验异常、未知异常分别处理统一包装成上面的 R 结构返回。前端只需在 Axios 拦截器里判断code 200即可出错弹提示全程不用关心具体是哪个接口报的错。4. 前端 Vue 实现中的核心细节4.1 前端工程化配置前端我用了 Vue 3 Vite Element Plus Pinia 这套组合。用 Vite 替代 Webpack 的最大感受就是启动快、热更新快写页面基本不用等编译。工程创建之后第一件事是配置开发环境代理。后端接口跑在 8080 端口前端跑在 5173 端口浏览器直接请求后端接口会跨域。我这里用的是 Vite 的server.proxy配置server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true, rewrite: path path.replace(/^\/api/, ) } } }前端所有请求都发到/api/xxxVite 在开发环境帮我把请求转发到后端。这样开发时不需要后端额外做跨域配置生产部署时再用 Nginx 做同样的事情思路是一致的。4.2 Axios 封装和拦截器前端如果每个页面都直接axios.get()代码会很散。我的做法是在src/utils/request.js里封装一个统一的 Axios 实例配置好baseURL、超时时间然后加上请求拦截器和响应拦截器。请求拦截器里每次都从本地存储读取 Token如果存在给请求头加上 Authorization 字段。响应拦截器就比较核心了service.interceptors.response.use( response { const res response.data if (res.code 200) { return res } if (res.code 401) { store.dispatch(logout) router.push(/login) } ElementPlus.ElMessage.error(res.message || 请求失败) return Promise.reject(new Error(res.message)) }, error { ElementPlus.ElMessage.error(网络异常请稍后重试) return Promise.reject(error) } )这样封装完之后每个页面的业务代码就非常干净只关心自己的data不用每个接口都处理错误弹窗。我后来写商品管理页面时一个表格加一个弹窗页面代码总共才两百多行大部分逻辑都在通用封装里。4.3 路由守卫与权限控制前端路由也要配合后端做权限控制。我设计了三套路由公开路由、用户路由、管理端路由。公开路由登录和注册直接可用用户路由需要登录后访问管理端路由要求当前用户角色是管理员。路由守卫写在全局前置守卫里核心逻辑是router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.meta.requiresAuth !token) { next(/login) return } if (to.meta.role !userStore.hasRole(to.meta.role)) { next(/403) return } next() })这里有个小技巧前端路由守卫只能控制页面能不能看到真正安全还是要靠后端接口权限判断。前端做的只是用户体验层面的拦截后端才是安全最后的底线。这个观念我在答辩时主动说了老师认可度很高。4.4 页面设计与交互细节页面设计上我没有追求花哨而是把精力放在流程完整度上。整个前端一共做了这些页面登录注册页、首页商品列表、商品详情页、购物车页、下单页、订单列表页、订单详情页、个人中心页、商家商品管理页、后台管理页。有几个交互细节提一下商品列表的筛选条件放在左侧分类筛选用单选按钮价格筛选用输入区间搜索框放顶部这是最不容易出错的布局订单列表的状态用标签Tag展示不同状态用不同颜色比如待支付橙色、已支付蓝色、已完成绿色信息辨识度很高前台页面全部使用响应式布局虽然是 PC 为主也顺手兼容了平板尺寸答辩演示时如果投影分辨率比较宽不会出现挤压问题。数据刷新方面我的经验是完成一个操作后只更新局部数据不要整页刷新。比如支付成功之后把订单数据重新请求一次更新当前组件的状态。这样页面不会闪烁体验也更像真实产品。5. 接口文档该怎么写才能直接拿去答辩5.1 接口文档的整体结构很多学生的接口文档就是拿 Postman 导出的一串 URL连参数说明都没有。这种文档交付出去别说别人看不懂过一个月自己看都费劲。我整理接口文档时是按模块归类写的每个接口包含以下信息接口名称和功能描述请求地址和请求方式请求参数参数名、类型、是否必填、说明响应结果成功响应的 JSON 示例可能出现的错误码和说明。比如用户管理模块的登录接口POST /api/user/login 参数username必填用户名、password必填密码 返回 { code: 200, message: 登录成功, data: { token: xxx.yyy.zzz, user: { id: 1, username: admin, nickname: 管理员, role: ADMIN } } }参数说明清楚之后前后端联调几乎不需要来回问。别人拿到接口文档能直接按照文档把接口调通这份文档才有交付价值。5.2 状态码与统一返回体的设计规范统一返回体和状态码搭配使用接口文档的价值才能完整体现。我定义的业务状态码有这几类code含义典型场景200请求成功数据查询、提交成功400参数错误必填参数缺失、格式不对401未认证Token 失效、未携带 Token403无权限普通用户访问管理员接口404资源不存在查询的商品已被删除500服务器异常数据库异常、空指针建议把常见的业务码写进文档开头前端拿到错误码后可以根据码值做差异化提示。因为 JavaScript 的判断很方便前端拦截器里完全可以根据 code 区分是跳登录页还是提示无权限。5.3 文档生成工具的选择写文档的方式有两种一种是手写 Markdown一种是用工具自动生成。我实际用的是 Markdown 人工维护。理由很简单项目接口数量大概四五十个Markdown 写起来虽然要敲不少字但结构完全可控复制给任何人都能直接打开看。像 Swagger 这类在线接口文档工具也可以做但需要额外引入依赖、写注解对毕设项目来说会明显增加工作量。如果非要用工具推荐一下可以用 Knife4j它对 SpringBoot 集成程度高自动扫描 Controller 生成文档省去手写的麻烦。但你自己得知道每个接口参数的含义工具不会帮你写业务说明。我的观点是毕设阶段把 Markdown 文档写好已经足够工具选型不是重点。6. 项目部署、启动与演示环境搭建6.1 本地环境准备为了让别人拿到项目之后能快速跑起来我专门写了一个环境准备清单包括JDK 1.8 或 11推荐 1.8因为老的 Java Web 教程大多基于 1.8 写兼容性更好Maven 3.6用来构建后端依赖MySQL 8.0推荐用 8.0字符集和时区设置更顺手Node.js 16用来跑前端项目任意现代浏览器演示时常用 Chrome。后端依赖里还有一个容易被忽略的东西Lombok。很多人项目跑不起来就是因为 IDE 里没有安装 Lombok 插件编译报错找不到方法。这个我在 README 里加粗提醒了。6.2 数据库初始化步骤拿到项目之后第一步永远是初始化数据库。正确顺序是打开 MySQL 命令行或图形化工具执行SQL脚本.sql文件脚本执行完毕后确认已经生成campus_platform库并能看到八张表检查表里是否已经有管理员账号比如用户名admin密码统一的初始化值打开后端配置文件application.yml修改数据库用户名和密码。我见过最多的现象就是后端代码没改数据库密码启动报Access denied for user。这个异常信息其实很直接但还是会有同学盯着日志半天找不出原因。所以我在文档里反复强调拿到项目第一步是改数据库账号密码不要直接启动。6.3 后端与前端启动流程后端启动非常简单在项目根目录执行mvn spring-boot:run或者用 IDEA 直接运行启动类。启动成功后控制台会打印Tomcat started on port(s): 8080之类的日志。前端启动步骤稍多一点进入前端目录cd frontend安装依赖npm install如果依赖安装慢可以配置一下镜像源启动开发服务器npm run dev浏览器访问http://localhost:5173。如果npm install期间出现网络超时不要反复重试把 node_modules 删掉清掉 npm 缓存换镜像源再次运行大概率能解决。启动顺序上推荐先数据库再后端最后前端。后端的健康检查可以通过浏览器直接访问http://localhost:8080/api/user/check这类简单接口来判断而不是只看启动日志。6.4 演示时的几个要点到了演示环节我建议在正式演示前自己跑一遍核心流程至少确保下面几条链路是通的普通用户注册 - 登录 - 浏览商品 - 加入购物车 - 下单 - 模拟支付 - 查看订单商家用户登录 - 发布商品 - 修改商品信息 - 下架商品管理员用户登录 - 查看用户列表 - 审核商品 - 查看订单统计。演示时按照这个流程走逻辑上是闭环的每一步都会用到前一步产生的数据非常顺畅。如果时间充裕可以提前创建好测试数据演示的时候直接用已有账号登录再补几个新操作兼顾效率与展示效果。7. 常见问题与排查技巧实录7.1 典型问题速查表我把实际开发和部署过程中遇到的、以及帮别人排查过的高频问题汇总成一份速查表。现象根本原因处理方式前端请求一直 404代理没配好或者实际请求的 URL 与后端的 RequestMapping 不一致打开浏览器控制台看请求的具体 URL对准后端接口路径数据库中文乱码数据库或表的字符集不是 utf8mb4在 SQL 开头强制设置字符集重导一次启动报端口被占用8080 端口被其他进程占用Windows 执行 netstat -ano登录一直 401Token 过期或者登录接口返回的字段名和前端取的不一致看接口返回的 JSON 字段名确认token字段名是不是一致图片上传后访问 404静态资源映射目录配置不对检查配置的映射路径和实际保存目录是否一致订单支付后状态没变前端改了列表数据但没重新拉取最新数据支付成功后调用一次订单详情接口刷新状态字段不要用旧对象表格数据比实际少一条分页参数从 0 还是 1 开始没对齐确认前端的页码和后端分页插件的 interpretIndex 是否一致排查这类问题最核心的思路永远是打开浏览器 F12看 Network 面板找到对应的接口请求观察请求地址、请求头、响应体。大部分联调问题在这一步就能看出来。7.2 独家避坑技巧这里分享三个我踩了多次坑之后的个人经验。第一实体类里不要用基本数据类型。比如商品价格、用户状态码这些字段用Integer、BigDecimal而不是int、double。原因是数据库字段可能为空查询出来时基本类型没法表示 null容易在 JSON 序列化或数值计算时空指针。这类 bug 往往只会在特定数据下触发极难复现。第二用实体类直接接收前端参数要小心。我习惯了用 DTO 接收比如ProductUpdateDTO里面的字段名和前端表单的prop名保持一致。这样不会出现“前端传了 description实体类字段叫 content”的错位问题也方便单独加校验注解。第三静态资源加载慢时不要总怀疑后端。前端图片如果走的是/upload/映射路径Vite 开发环境和 Nginx 生产的路径可能不一样。我在生产环境部署时踩过这个坑开发环境图片显示正常部署到服务器上图片全部裂了。原因就是 Nginx 没有把/upload/路径代理到后端的磁盘目录。这个排查思路比重新压缩图片有效得多。8. 这份毕设交付物还可以往哪些方向延伸写到最后我是想补充一点后续思路。校园便利平台这个题目在毕设里算是一个中规中矩、但可以做得很有深度的选题。如果你有多余精力可以考虑几个扩展方向加入 Redis 缓存首页热销商品讲清楚缓存击穿、穿透的概念性能调优这块一下子就有了话头增加消息通知模块用 WebSocket 实现下单后的实时提醒前端不用轮询技术亮点直接上升一个台阶做一个简单的数据分析面板统计每天订单数量的变化趋势前端用图表库展示可视化这块又补上了用 Docker 把后端、前端、数据库全部容器化随手写个 docker-compose.yml一键启动这在部署环节特别加分。我自己在这个项目里花的精力大头根本不是写 CRUD而是在 Java 后端“状态管理”“权限控制”“异常统一处理”这些看似细节、实际很磨人的地方。把细节处理好你的项目才叫一套能交付的完整系统而不是若干 demo 代码的拼凑。这个项目后续如果再让我做一轮重构我会优先把旧版本 SpringBoot 的依赖升级一遍同时把接口文档迁到线上工具里维护再补一些单元测试。别小看这些收尾工作经历过一次答辩的人会明白你的项目预答辩能顺畅跑完一遍比你提前多写一百行代码都有价值。