1. 项目定位与核心需求拆解1.1 这个平台到底在解决什么问题读书笔记共享平台我猜不少朋友一看到这个名字就觉得这不就是那个烂大街的毕设题目吗。确实每年到了三四月份这个题目都会和各种员工管理系统、在线商城一起出现在各大毕设辅导群里。但烂大街不代表没有含金量。恰恰相反正因为做的人多你反而更容易找到一条已经踩过坑、趟过雷的完整路线。2025年这个时候如果你还在用纯 JSP Servlet 去交作业那基本就是跟时代对着干。换成 SpringBoot Vue 这一套前后端分离的组合项目体量合适、技术栈主流、答辩的时候可讲的东西也多。如果你正在准备毕业设计或者想找一个完整的全栈项目练手这个题目确实值得认真跟一遍。这个平台解决的核心痛点其实很清楚。大学生群体里读书笔记的需求一直存在但传统的笔记方式很零散纸质笔记本容易丢电子笔记存在本地没法分享同一个课程小组想参考彼此的读书报告还得靠群里传文件。共享平台就是把笔记集中起来按书籍归档同学们可以浏览别人的读书感悟可以评论互动可以收藏点赞。管理员在后台做内容把关避免出现灌水内容。这就是一个标准的社区化内容管理场景业务逻辑不复杂但该有的功能一个不少非常适合用来做全栈实战。1.2 功能模块全景拆解我按照目前最常见的毕设需求把整个系统的功能模块拆一下你在做的时候可以直接照着规划数据库和接口。用户端模块登录注册用户名密码登录注册时校验用户名唯一性密码加密存储。笔记广场分页展示所有公开笔记支持按书名、作者、笔记标题的关键词搜索还可以按书籍筛选。笔记详情页展示笔记正文内容显示作者、所属书籍、发布时间支持点赞、收藏、发表评论以及查看评论列表。发布与编辑笔记选择关联的书籍填写笔记标题和正文可以选择公开或私密。私密笔记只有自己可见。个人中心我的笔记列表包含公开和私密、我的收藏、我的评论记录以及个人资料的修改包括昵称和头像。后台管理模块数据概览统计平台用户数、笔记总数、评论总数、书籍总数。用户管理查看所有注册用户可以禁用或启用某个账号。笔记管理查看所有笔记对涉嫌灌水或违规的内容进行下架处理。这两个角色放在同一个前端工程里通过登录用户的角色字段动态渲染菜单比单独做两个前端项目要省力而且答辩时老师问起来你可以解释为单页应用的角色权限控制比双前端方案反而更有说服力。1.3 角色权限设计系统主要有两类角色学生用户和管理员。学生用户的权限边界是维护自己的笔记增删改查、浏览公开笔记、参与评论点赞收藏、管理个人资料。管理员则在普通用户权限之上增加了用户管理和笔记管控的后台接口。在项目里我用一张 user 表的 role 字段来区分角色0 表示普通用户1 表示管理员。前端根据登录用户的路由 meta 信息判断能否进入 /admin 路径下的页面。后端则通过两个拦截器规则来保护接口所有 /api/note/** 和 /api/comment/** 的写操作必须携带合法 token而 /api/admin/** 前缀的接口必须在 token 中解析出 role1 才放行。这样前端控制页面展示后端控制接口安全两端都守住不会出现绕过按钮直接调用接口的权限漏洞。2. 技术选型解析为什么是这套组合2.1 SpringBoot MyBatis 的后端组合考量先说后端SpringBoot 在这个场景下几乎没有悬念。内嵌 Tomcat一键启动不用单独配置外部容器开发效率比传统 SSM 的 XML 配置方式高太多了。我给你的建议是直接用 SpringBoot 2.7.x 搭配 JDK 1.8这个组合经过了大量生产环境验证网上遇到的问题解决方案最多毕设阶段千万别为了追新去用 SpringBoot 3 加 JDK 17除非你本机已经装了 JDK 17 并且对 jakarta 命名空间切换非常熟悉否则会白白浪费很多调试时间。MyBatis 的选择则是经过一番考量的。现在很多教程推荐 MyBatis-Plus确实开发效率高、CRUD 都不用写 SQL但我不推荐在毕设里用它理由有两个第一MyBatis 是高校软件工程课程里最常见的教学框架答辩时老师问到底层实现你至少能解释清楚 SQL 是怎么执行的第二手写 SQL 恰恰是面试时的高频考点你做了一个项目连联表查询都没写过被问到了就会露怯。MyBatis 的核心价值就是让你把 SQL 控制权握在自己手里复杂的多表查询、动态条件拼接、批量插入都能精准控制。2.2 Vue3 Element Plus 的前端组合前端在 2025 年选择 Vue3 Element Plus Vite 是理所当然的。Vue2 虽然资源多但已经处于维护末期新项目没有必要选一个即将过时的版本。Vite 作为构建工具启动速度比 Webpack 快了一个数量级对开发体验的提升是实打实的。Element Plus 提供了表格、表单、分页、上传等一堆现成组件做管理后台界面效率极高。笔记广场这类面向 C 端的页面我建议你用 Element Plus 的基础布局加少量自定义 CSS 来实现既保证了视觉统一又不用重新造轮子。这是我做这个项目最核心的效率来源前端 70% 的页面交互逻辑都在跟组件库打交道而不是在写样式。2.3 MySQL 表设计思路数据库设计是整个项目的基石表结构设计得好不好直接决定了后面写代码是顺滑还是痛苦。这个项目我拆成五张核心表用户表、书籍表、笔记表、评论表、收藏表。点赞记录我单独建了第六张表后面会解释为什么。user 表的字段设计id 主键自增、username 唯一索引、password 加密存储、nickname 昵称、avatar 头像 URL、role 角色字段 0/1、status 状态字段 0 禁用 1 正常、create_time 注册时间。book 表的设计id、title 书名、author 作者、publisher 出版社、isbn 国际标准书号、cover 封面图 URL、introduction 简介、create_time。独立出书籍表的好处是笔记表不需要冗余作者的出版社信息只保存一个 book_id 外键关联即可这也方便后续做按书籍筛选的功能。note 表是整个平台的核心id、user_id 作者外键、book_id 关联书籍、title 笔记标题、content 正文内容类型用 TEXT 或 LONGTEXT、status 0 私密 1 公开、view_count 浏览量、like_count 点赞数、favorite_count 收藏数、create_time、update_time。浏览量、点赞数、收藏数这三个字段是冗余统计字段每次点赞或收藏时直接对该字段进行增减看起来有并发风险但在毕设体量下完全够用而且查列表时不需要临时聚合统计性能好很多。comment 表id、note_id、user_id、content、create_time。favorite 收藏表id、user_id、note_id、create_time其中 user_id 和 note_id 建联合唯一索引防止重复收藏。最后是 like_record 点赞记录表字段结构和 favorite 一致这样用户下次进入详情页时能直接查出他是否已经点赞和收藏从而正确渲染按钮状态。2.4 项目目录结构与分层规范一个结构清晰的项目不仅自己后期维护方便答辩时给老师看目录也能留下好印象。后端我沿用经典的 Controller-Service-Mapper 三层架构包结构这样划分config 放跨域配置和拦截器配置controller 放接口层service 及 impl 放业务逻辑mapper 放 MyBatis 接口和 XML 映射文件entity 放数据库实体类dto 放接收参数的类vo 放返回前端的视图对象common 放统一返回结果类 Result、状态码常量utils 放 JWT 工具类。前端目录api 按领域拆成 auth.js、note.js、comment.js、book.js、user.jsrouter 配置路由表store 放 Pinia 的全局状态views 放页面级组件components 放复用的界面组件如笔记卡片、评论列表、分页栏等。这个划分是我在多个项目里反复调整后确定的前后端职责边界清晰写到哪里东西该放哪个目录几乎不需要思考。3. 后端核心实现从登录到笔记共享3.1 登录注册与 JWT 权限控制登录注册是后端第一个要做的模块它涉及的不只是查表比对密码还牵扯到整个系统的权限体系。我采用 JWT 方案主要原因有两个一是无状态后端不需要保存会话符合前后端分离的架构风格二是 JWT 里可以自定义携带用户 ID 和角色拦截器解析一次就能拿到当前用户的身份信息不用每次请求都回查数据库。密码安全这块我需要重点提醒千万不要用明文存储密码也不要只做一次简单 MD5。在没有 HTTPS 的纯本地环境下密码传输本身就不安全如果存储再不加盐一旦数据库泄露后果不堪设想。我使用的是 BCryptPasswordEncoder它是 Spring Security 框架里的密码加密器每次对同一个明文生成的哈希值都不一样自带了随机盐你只需要调用 matches 方法做校验非常省心。JWT 工具类我直接基于 hutool 的 JWT 工具封装代码非常简洁。生成 token 时把用户 ID 和角色塞进 payload签名密钥从配置文件读取不要硬编码在 Java 类里。拦截器里解析 token 后从 Claims 里取出 userId 和 role存入 ThreadLocal 或直接给 Controller 方法注入参数后续业务逻辑就能知道当前操作者是哪个用户。拦截器需要处理的一个细节是放行 OPTIONS 预检请求。前后端分离的项目浏览器在发起跨域请求时会先发一个 OPTIONS 请求试探服务器如果你的拦截器不放行它前端所有请求都会报跨域错误。这个坑我在早期项目里踩过后来在拦截器 preHandle 方法第一行判断了请求方法如果是 OPTIONS 直接返回 true。3.2 笔记模块的增删改查与状态管理笔记模块是整个系统的核心业务我把接口设计成 RESTful 风格这样前后端对接非常清晰。列表接口 GET /api/note/page 接收 page、size、keyword 三个参数keyword 为空时查全部公开笔记不为空时对书籍名、书名、笔记标题三个字段做模糊匹配。SQL 使用动态标签拼接注意多个条件之间的关系用 AND 连接并用括号保证优先级不出错。笔记详情的逻辑稍微复杂一点第一步查出笔记基本信息和作者昵称、书籍信息第二步根据当前登录用户的 ID 去 like_record 和 favorite 表查是否点赞、是否收藏第三步把对象返回给前端。如果是私密笔记还要校验当前用户是否就是作者本人否则提示无权查看。这个权限判断我把它放在 service 层通过一个简单的用户 ID 比对实现虽然简单但属于内容安全的基础防护。创建和更新笔记时有一个细节要处理好前端会做表单校验但后端必须再做一次。比如笔记标题长度限制、正文不能为空、关联的书籍必须存在于 book 表这些校验在 Controller 层可以通过手动校验或参数注解实现。我习惯使用手动校验因为可以给出更友好的中文错误提示。更新笔记时MyBatis 的 update 语句用 set 标签动态更新避免把 null 值覆盖到原有字段上。3.3 评论、点赞、收藏的数据库设计与实现这三个交互功能是平台活跃度的来源它们的实现思路相似但又各有注意点。评论模块最简单新增评论时向 comment 表插入一条记录同时返回包含用户昵称和头像的评论列表。查询评论列表用多表联查评论表关联用户表一次性查出评论内容和发表人的信息避免循环查库。这里有个性能优化的小点评论列表的分页可以单独做也可以在详情页一次性加载最近二十条我建议列表接口直接开放分页参数前端滚动时再加载更多。点赞和收藏的逻辑是同一个模式操作前先查 like_record 或 favorite 表如果记录不存在则插入记录同时 note 表的 like_count 或 favorite_count 加一反之则删除记录并减一。两个操作放在一个事务里要么都成功要么都失败。这里有个业务细节值得说一下点赞和收藏是两回事点赞更像是一种认同的轻量表达收藏则代表用户想把这篇笔记留作后用。很多新手会把它们混成一个功能答辩时老师一问就会露馅你如果能把这两者的语义区别讲清楚会显得对产品有真正的理解。3.4 MyBatis XML 映射的几个关键细节MyBatis 的问题排查是整个后端开发的隐形时间杀手我在这里集中讲几个最常见的坑。第一mapper 接口和 XML 文件的绑定。XML 文件命名空间必须写 mapper 接口的全限定名方法 ID 必须和接口方法名一致参数类型和返回类型要匹配。出现 Invalid bound statement 错误十有八九是 namespace 写错或 XML 配置文件没有被扫描到在 application.yml 里要配置 mybatis.mapper-locations: classpath:mapper/*.xml。第二下划线和驼峰的映射。数据库字段 user_id 对应 Java 属性 userId在 application.yml 开启 mybatis.configuration.map-underscore-to-camel-case: true 后能自动转换但要注意这仅适用于单表自动映射。多表联查时必须使用 resultMap 显式声明映射关系字段多的时候别偷懒提前把 resultMap 写好后面每条查询都能复用。第三动态 SQL 的构建。后端做模糊查询、多条件筛选时使用 where 标签加 if 标签是最灵活的方案。if 条件判断要注意参数值不能为 null 也不能为空字符串否则拼接出来的 SQL 可能出现错误。排序字段是一个特殊场景使用 ${} 占位符时存在 SQL 注入风险但排序字段用 #{} 又会被当作字符串值导致排序失效解决的办法是把排序字段做一次白名单校验只允许 asc、desc 和固定的几个字段名。4. 前端核心实现页面与接口的协作逻辑4.1 路由划分与登录守卫前端路由表是整个页面结构的骨架我在开发初始阶段就规划好了所有需要路由的页面。不需要登录的页面有登录页和注册页其余所有页面都放在需要登录的分组里。笔记详情页允许未登录用户浏览但点赞收藏按钮在未登录状态下点击时要提示先登录这个交互细节很常见一定不要忽略。实现登录守卫的核心代码在 router 的全局前置守卫里。每次路由跳转前先判断是否访问的是登录和注册页是则直接放行否则从 localStorage 里取 token有 token 再判断目标路由的 meta 中是否标记了 requireAdmin如果需要管理员权限再从 Pinia 的 user store 里读出当前用户角色角色不是管理员就跳转到首页。这样一套逻辑下来用户无法通过直接修改 URL 进入管理后台。4.2 api 请求封装与拦截器前端的 axios 封装是项目整洁度的关键。我习惯使用统一的 axios 实例设置 baseURL 为 /api这样所有的接口路径都写相对路径开发时通过 Vite 代理转发到后端部署时只要改 nginx 的反向代理不用动任何前端代码。请求拦截器就是在每次请求发出前从 localStorage 读取 token如果有就加到 Authorization 头。响应拦截器的功能是统一处理错误当后端的 Result 返回 code 不等于 200 时用 Element Plus 的 ElMessage 弹出错误提示当 HTTP 状态码是 401 时说明 token 无效或过期清掉本地存储的 token 和用户信息跳转到登录页。这个统一的错误处理机制会让页面代码干净很多每个接口只需关心成功分支的数据处理不用每个请求都写一遍错误分支。接口请求函数要按模块拆分每个模块是一个独立文件例如 note.js 里导出 getNotePage、getNoteDetail、createNote、updateNote、deleteNote 等方法每个方法内部调用封装好的 request 实例。这样做的好处是当后端接口路径调整时只需要改对应的 api 文件页面组件不受任何影响。4.3 笔记广场与个人中心的核心页面逻辑笔记广场是用户进入系统后看到的第一个页面它的交互流程是这样的页面加载时调用笔记分页接口传入当前页码和每页条数。搜索区域有搜索框、书籍下拉选项和搜索按钮点击搜索时重置页码为 1重新请求数据。笔记列表渲染时使用卡片式布局每张卡片展示笔记标题、作者昵称、所属书籍、点赞数、收藏数和发布时间的摘要信息。Element Plus 的 Pagination 组件绑定当前页码和总条数切换页面实时请求新数据。个人中心涉及的数据较多我用 el-tabs 做分区切换。我的笔记区域默认展示当前用户所有笔记私密的显示带锁标记的图标每条笔记后面有编辑和删除按钮。我的收藏区域调用收藏列表接口以同样的卡片形式展示收藏的笔记。评论记录区域把当前用户发表过的评论展示出来。这里有个易错点修改个人资料后Pinia 里存储的 user 对象也要同步更新否则界面显示的昵称还是旧值我们的实现是把更新接口返回的最新 user 对象重新写入 store。5. 常见问题与排查技巧实录5.1 数据库连接和乱码问题这一块是项目从零到能跑的阶段最常遇到的我见过的案例足够整理成一个速查表了。MySQL 8 的连接 URL 必须带 serverTimezone 参数否则启动项目时会在建立数据库连接阶段直接报时区错误。中文乱码的问题则要检查三个地方MySQL 表本身的字符集是否为 utf8mb4、数据库连接 URL 是否带 characterEncodingutf8、页面 meta 标签是否设置了 charset。三个环节一个都不能少少了任何一个都会出现问号或者乱码。连接数据库还有一个容易踩的坑是驱动类名。MySQL 5 用 com.mysql.jdbc.DriverMySQL 8 要用 com.mysql.cj.jdbc.Driver版本不匹配会出现各种让人摸不着头脑的报错。我建议你建好项目后先用一个最简单的查询测试数据库连通性确认 DAO 层通了再写业务代码这样可以把问题隔离在早期。5.2 MyBatis 映射失败与字段对应写 MyBatis XML 时报错最多的就是 Invalid bound statement not found遇到这个问题先按三步排查看 XML 文件的 namespace 是否等于 mapper 接口的全限定名看接口方法名和 XML 里的 id 是否完全一致看 Maven 构建后的 target 目录里有没有把 XML 文件打包进去。第三步是最容易忽略的因为 Maven 默认只打包 src/main/resources 下的文件如果你把 XML 放在了 java 源码目录下构建时就会被跳过必须要在 pom.xml 里配置资源插件把 mapper 目录也包含进去。多表联查时如果发现返回的实体类某些字段是 null先不要怀疑数据有问题九成是 resultMap 里 column 和 property 对不上了。还有一个小概率情况开启了下划线转驼峰后实体字段如果命名不符合驼峰规范也会导致映射失败。我的习惯是统一用 IntelliJ IDEA 的数据库插件生成实体类字段名生成规则保持一致从源头上规避这类问题。5.3 跨域与接口联调问题前后端联调阶段跨域问题几乎人人都会遇到。浏览器控制台报 Access-Control-Allow-Origin 错误时处理方案有两个一是在后端添加全局 CORS 配置二是在前端 Vite 配置文件里设置代理。我推荐两个都配上原因很实际前端代理解决的是本地开发环境的问题后端 CORS 配置解决的是部署后跨域访问的问题。二者并不冲突因为经过代理后前端请求同源后端配置只在外部访问时需要生效。如果你配置了后端 CORS 但前端请求还是跨域八成是拦截器把 OPTIONS 预检请求拦住了我在前面强调过拦截器 preHandle 方法里必须先放行 OPTIONS 请求。还有一个容易忽视的细节是自定义的 CorsFilter 和 Spring Security 过滤器链的执顺序不过我们这个项目没有引入 Spring Security直接用 CorsRegistry 添加配置即可简单且不容易出问题。5.4 其他几个容易忽略的坑启动后端时端口被占用是最常见的报错Windows 下用 netstat -ano 找出占用进程的 PID然后在任务管理器里杀掉或者直接在 application.yml 里把服务端口改成 8081 以免和本机其他开发环境冲突。前端 npm install 失败通常是因为网络源的问题把 npm 源切换为国内镜像源后基本能解决。如果安装过程中有 ENOENT 之类的报错优先清缓存重新安装。部署上线也是很多人的痛点。如果只是交作业把项目打包后在本地演示就足够。但如果你想部署到服务器上前端构建后的 dist 目录和后端打成的 jar 包分开处理前端用 Nginx 托管静态资源并反向代理 /api 请求到后端端口后端 jar 包用 java -jar 命令启动。后端要注意服务器防火墙开放对应端口数据库要导出 SQL 文件到服务器端导入服务器上的数据库账号和本地尽量保持一致避免因为权限问题导致连接失败。我做完这个项目最大的体会是这个选题看起来朴素但每一层技术栈都被实打实地用了一遍后端的权限设计、MyBatis 的动态 SQL、前端的路由守卫和状态管理、跨域处理和打包部署任何一个环节掉链子整个项目都跑不起来。也正因为如此只要你把它从头到尾做通一遍大学四年学到的东西基本都能串起来了。