前后端分离的宠物健康顾问系统用 SpringBoot Vue MyBatis MySQL 这套组合做出来很多人第一反应是“又一个毕设项目”但我实际把它从零搭完、部署上线之后发现这里面的门道远不止“跑起来”这么简单。这篇文章我会把整个系统的设计思路、核心模块怎么拆、前后端怎么联调、部署时踩过的坑一次说清楚适合正在做课程设计、毕业设计或者想用一套真实业务练手前后端分离项目的读者。1. 项目整体设计与思路拆解1.1 宠物健康顾问系统到底做什么先把这个系统的业务边界理清楚。宠物健康顾问系统不是简单的“宠物信息登记表”它核心解决的是宠物主人和兽医之间的信息断层问题。主人需要记录宠物的基础档案、疫苗时间、驱虫周期、就诊历史兽医需要快速了解一只宠物的完整健康脉络。所以系统功能上我拆成两大块用户端的日常记录与预约管理端的档案审核与数据维护。用户端核心功能包括宠物档案管理品种、年龄、体重、绝育状态、健康记录添加体温、症状描述、诊断结果、用药建议、疫苗与驱虫提醒、在线预约兽医时间。管理端则包括宠物档案审核、健康记录归类统计、预约订单处理、系统公告发布。这个需求模型关键在“记录”和“提醒”两条线。记录线解决数据从无到有提醒线解决数据怎么产生实际价值。很多类似项目只做CRUD做完发现很空就是因为只做了记录线没有把提醒、预约这类业务闭环串起来。1.2 为什么坚持用前后端分离架构前后端分离在这个项目里不是赶时髦是真实需求驱动的。项目里有面向宠物主人的H5页面有面向管理员的桌面端后台两套界面的交互复杂度、视觉风格差别很大。如果混在一个工程里改一个端就要重新构建整个应用发布风险高开发效率也低。分离之后前后端通过 HTTP 接口通信契约就是接口文档。前端专心处理交互和渲染后端专心处理业务逻辑和数据持久化。实际开发中并行推进效率提升非常明显——我在搭后端接口的同时前端同事可以先用 Mock 数据把页面写完联调阶段再替换成真实接口双方互不阻塞。部署层面分离也占便宜。前端打包成纯静态文件丢到 Nginx后端打成 jar 包独立运行。任何一端需要升级只需要替换对应的产物不需要同时重启整套服务。这个优势在后续迭代里会越来越明显。1.3 技术栈选型的底层逻辑SpringBoot Vue MyBatis MySQL 这套组合被选做系统底座每个组件都有清晰的分工逻辑SpringBoot 负责后端基础框架。内嵌 Tomcat 让应用可以直接用 java -jar 启动不用额外配置外部容器自动配置机制把数据源、JSON 序列化、参数校验这些基础工作都处理好了开发者只需要关注业务代码。Vue 负责前端交互层。响应式数据绑定让页面状态和视图保持同步组件化开发让宠物档案列表、健康记录表单、预约时间选择器这类UI都能复用。配上 Vue Router 做前端路由管理端的侧边栏切换页面的体验和原生应用几乎没差别。MyBatis 负责数据访问层。选择它而不是 JPA是因为宠物健康记录这种场景里查询条件经常是动态拼接的——按品种查、按年龄段查、按症状查用 XML 里写动态 SQL 比对象导航查询直观得多也更容易针对复杂查询做 SQL 级别优化。MySQL 负责数据存储。这类管理系统的数据量级在百万以内MySQL 完全够用事务支持让“预约操作 库存扣减”这类组合操作保持一致性。部署运维成本也很低一台2核4G的云服务器就能跑得很稳。2. 核心细节解析与实操要点2.1 数据库设计要避开哪些坑数据库是整个系统最不能糊弄的部分。我先说一个很多人会犯的错直接把“宠物健康记录”设计成一张大宽表字段堆到二十多个。这样写查询是真的方便但一旦要加新字段比如增加“疫苗接种批号”整张表都要 ALTER风险极高。我的方案是拆成三张核心表和两张辅助表。核心表是 pet宠物档案、health_record健康记录、appointment预约。辅助表是 user用户账号和 vaccine_reminder疫苗提醒计划。pet 和 user 之间是 JPA 里说的多对一关系一只宠物只属于一个主人一个主人可以有多只宠物。health_record 关联 pet记录每次就诊、体检、用药的完整信息。appointment 关联 user 和 pet同时记录预约的兽医时段和状态。建表时注意几个细节时间字段统一用 datetime 类型不要用 varchar排序和范围查询会快得多状态字段用 tinyint 加注释比如 appointment_status 的 0、1、2、3 分别代表待确认、已确认、已完成、已取消不要直接存中文否则改需求时维护成本极高所有表都加上 create_time 和 update_time 字段排查数据问题的时候这两列能救命。外键我建议不加物理外键只加逻辑关联和索引。物理外键在删除主表记录时会触发级联检查运行期性能损耗虽然小但一旦数据量大、删除频繁很容易出现锁等待。逻辑外键配合 ON DELETE 策略在应用层控制灵活性和性能都更好。2.2 后端模块划分的合理边界后端我按业务模块而不是按技术层来分包。每个模块内部再分 controller、service、mapper 三个层次。宠物模块目录结构大致是com.pethealth ├── common // 通用返回结果、异常处理、工具类 ├── config // 全局配置跨域、拦截器、MyBatis配置 ├── module │ ├── pet │ │ ├── controller │ │ ├── service │ │ └── mapper │ ├── record │ │ ├── controller │ │ ├── service │ │ └── mapper │ ├── appointment │ └── user └── PetApplication.java有人会把所有 Controller 堆在一个 controller 包里所有 Service 堆一个包里短期看没什么问题但模块一多就会乱。按模块分包之后每个模块的代码量保持在几百行以内排查问题时直接定位到对应模块阅读成本低很多。Controller 层只做参数接收、参数校验、调用 Service 后把结果封装成统一结构返回。Service 层写业务逻辑比如判断预约时间是否冲突、检查宠物档案是否已存在。Mapper 层只做数据库查询映射对应 XML 文件里写 SQL。这种分层的好处是每层职责单一出了问题能精准定位是接口问题、业务问题还是 SQL 问题。2.3 统一返回结果与全局异常处理前后端分离之后接口的返回结构必须统一这是联调顺畅的前提。我定义了一个通用返回类结构是 code、message、data 三个字段。所有接口都返回这个结构前端拿到响应后先判断 code 是否为 200再决定走正常渲染还是走错误提示。如果没有统一结构每个接口返回格式都不一样前端要写一堆兼容代码完全是浪费工时。全局异常处理用 RestControllerAdvice 注解实现。业务异常、参数校验异常、SQL异常分别定义处理器返回对应错误码和提示信息。比如预约时间段已经被占满抛一个带业务错误码的异常前端就能把这个错误码映射成友好的弹窗文案。这里有个实际操作经验日志一定要打全。异常处理器里除了返回前端信息还要用 log.error 把堆栈完整打出来。我曾经遇到一个只在特定环境下出现的空指针前端只看到“系统繁忙”后端日志里堆栈信息被吞了排查了很久。后来把日志补全这种问题定位时间能缩减一大半。2.4 前端路由与状态管理的设计前端部分我用的 Vue 3 Vite 的组合路由用 Vue Router 4。页面结构上是登录页、用户端主布局、管理端主布局三块。用户端包含宠物档案列表、健康记录时间线、预约表单管理端包含数据概览、档案审核、预约管理。路由设计上有一个关键点路由守卫。未登录用户访问需要鉴权的页面直接重定向到登录页。这里我直接在前端做路由守卫后端在接口层也统一校验 token两层保护缺一不可。有人说后端校验就够了前端守卫意义不大——实际上前端守卫还能拦截无效页面跳转省掉一次必然失败的接口请求体验上差异是能感知的。状态管理用的 Pinia管理当前登录用户信息、宠物列表缓存、预约状态筛选条件。把宠物列表缓存到状态里切换页面时不用每次都拉接口数据量小的情况下响应几乎是瞬时的。2.5 前后端联调与跨域处理联调阶段最容易炸的就是跨域问题。后端接口跑在 8080前端开发服务器跑在 5173浏览器会拦截跨域请求。开发环境我直接用后端配置跨域在 SpringBoot 里实现 WebMvcConfigurer 的 addCorsMappings 方法允许本地前端的地址跨域访问。生产环境则反过来Nginx 把静态文件请求和 API 请求通过路径区分开API 请求反向代理到后端的 8080 端口。因为浏览器看到的请求是同源的跨域问题从根上就不存在了。这个方案比在后端开全局 CORS 要安全得多生产环境不建议把 CORS 放开给所有来源。联调时为了让流程更顺畅可以用 Apifox 或 Postman 先建好接口文档各个参数的含义、必填项都标注清楚。前端把 Mock 数据和真实接口之间的切换封装在一个 request.js 文件里切换环境只需改一个 baseURL 变量省心不少。3. 实操过程与核心环节实现3.1 开发环境准备清单动手写代码之前环境必须先捋顺。我把用到的工具和版本列一个清单版本不一定要完全一致但大版本要相近否则会遇到很多莫名奇妙的兼容问题工具版本说明JDK1.8 或 11建议 1.8SpringBoot 2.x 兼容性最好Maven3.6管理后端依赖Node.js16运行 Vue 前端项目MySQL5.7 或 8.05.7 部署成本低8.0 功能更强IDEIDEA / VSCode后端用 IDEA前端用 VSCode 都行这里要提醒两个容易踩坑的点。第一个是 MySQL 8.0 的驱动类名变了从 com.mysql.jdbc.Driver 改成了 com.mysql.cj.jdbc.Driverpom.xml 里的依赖坐标也变了。第二是 MySQL 8.0 对时区敏感连接字符串里要显式加上 serverTimezoneAsia/Shanghai否则会报时区相关的 SQLException。这两个问题我见过太多新手栽在上面。3.2 后端工程搭建核心步骤后端工程我用 Spring Initializr 生成基础骨架再手动加上 MyBatis 依赖。最核心的 pom.xml 依赖就这几个dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.1/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependencyapplication.yml 配置文件里数据源、MyBatis 映射文件位置、日志级别这三项是重点。我的配置大概是这样的spring: datasource: url: jdbc:mysql://localhost:3306/pet_health?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 你的密码 driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.pethealth.module.*.entity configuration: map-underscore-to-camel-case: truemap-underscore-to-camel-case 这个配置项是我强烈建议开的。数据库字段是 create_timeJava 属性是 createTime开启这个配置后 MyBatis 会自动映射不用在每个 resultMap 里手动写字段对应关系能省大量模板代码。代价是要求数据库字段命名规范统一用下划线风格否则这个配置反而会帮倒忙。建好工程之后先写一个最简单的“根据ID查询宠物档案”接口把 Controller、Service、Mapper 三层跑通再往下扩展其他模块。这样做的目的很明确先验证项目基础链路没问题再堆业务代码排查问题时不会因为“整个工程都起不来”而阻塞进度。3.3 前端工程搭建关键配置前端我用 Vite 初始化 Vue 3 项目命令是 npm create vitelatest pet-health-web -- --template vue。初始化完成后安装核心依赖 vue-router、pinia、axios。这里要说一下 Vite 和 Vue CLI 的选择问题。Vue CLI 基于 Webpack生态成熟但启动速度慢Vite 基于原生 ES Module开发服务器冷启动几乎是秒开热更新速度也快一个量级。新项目我推荐直接上 Vite直观感受就是保存代码后浏览器几乎是瞬间刷新开发体验好很多。前端工程里有两个文件需要提前配好。第一个是 vite.config.js配开发服务器的代理把 /api 开头的请求转发到后端 8080export default defineConfig({ server: { port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })第二个是封装 axios 实例的 request.js统一处理后端返回结构和错误状态。axios 拦截器里添加 token 到请求头、统一处理 code 非 200 的情况。这两个文件配好之后后面的业务代码写起来会非常顺手。3.4 核心接口实现与演示这节我挑一个最有业务代表性的接口来详细说明预约时间校验接口。这个接口的逻辑是收到预约请求后先查询该时间段是否已被其他人预约再检查宠物状态是否异常都通过才创建预约记录。public Appointment createAppointment(AppointmentDTO dto) { // 1. 校验时间段是否冲突 int conflictCount appointmentMapper.countByTimeSlot( dto.getVetId(), dto.getAppointmentTime()); if (conflictCount 0) { throw new BusinessException(该时间段已被预约请选择其他时间); } // 2. 校验宠物状态 Pet pet petMapper.selectById(dto.getPetId()); if (pet null || pet.getStatus() ! 1) { throw new BusinessException(宠物档案不存在或已禁用); } // 3. 创建预约 Appointment appointment new Appointment(); // 省略属性赋值... appointmentMapper.insert(appointment); return appointment; }这里有个事务问题需要注意。如果后续要扩展“预约的同时扣减号源数量”步骤1和步骤3必须放在同一个事务里否则并发情况下会出现超卖。我用 Transactional 注解把整个方法包起来数据库层面用行级锁保证并发安全。新手最容易忽略这个等上线后出现并发问题再补就晚了。3.5 本地完整启动与联调流程整套系统本地启动流程按顺序走先启动 MySQL 服务用 source pet_health.sql 导入数据库脚本。再启动后端命令行执行 mvn spring-boot:run 或者 IDE 里直接运行 main 方法看到 Tomcat started on port 8080 就说明后端起来了。然后启动前端在 pet-health-web 目录下执行 npm install 安装依赖再执行 npm run dev 启动开发服务器。联调的时候我习惯先测登录接口拿到 token 之后再看其他接口是否能正常访问。用同一个 token 串起整个流程实际上就是在验证系统的主链路登录 → 获取宠物列表 → 添加健康记录 → 创建预约 → 管理端处理预约。这条链路通了系统就算真正跑起来了。4. 部署上线与常见问题排查4.1 部署方案对比与选择部署方式有三种常见选择我分别对比一下适用场景方案优点缺点适用场景Nginx jar 分离部署前后端独立升级性能好需配置 Nginx 反向代理推荐的生产部署方式前端打包装进 SpringBoot只部署一个 jar管理简单静态资源由 Java 应用服务性能略差小型个人项目Docker Compose 容器化环境一致扩展方便需要 Docker 基础团队合作或多环境部署我实际部署选的是 Nginx 分离方案。SpringBoot 后端打成 jar 包前端构建出 dist 静态目录Nginx 把根路径指到 dist把 /api 路径反向代理到 8080 端口。Nginx 配置核心部分server { listen 80; server_name your-domain.com; location / { root /opt/pet-health/dist; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }try_files 这行配置是前端路由生效的关键。Vue Router 默认用 history 模式直接访问 /pet/123 这样的路径时Nginx 找不到对应文件会返回 404。加上 try_files 把所有路径都回退到 index.html让前端路由接管页面渲染问题就解决了。如果用的是 hash 模式则没有这个问题但 history 模式对 SEO 和路径美观度都更好我推荐用 history 加 try_files 组合。4.2 后端部署的关键操作后端部署其实很直接但有几个细节值得注意。打包前确认配置文件里数据库地址、密码等参数是生产环境的不要把本地的 localhost 打包进去。执行 mvn clean package -DskipTests 跳过测试打包生成 target/pet-health.jar。上传到服务器后用 nohup 命令启动nohup java -jar pet-health.jar --spring.profiles.activeprod app.log 21 后台启动并输出日志到 app.log随时可以用 tail -f app.log 查看运行状态。端口和配置信息可以用命令行参数覆盖这样同一个 jar 包可以在不同环境跑不需要重新打包。这里说一个我踩过的坑服务器内存只有 2G 的时候同时跑 MySQL 和 jar 应用经常出现内存不够导致应用被杀。解决方案是给 JVM 限定内存启动参数加上 -Xms256m -Xmx512m限制堆内存大小给系统留足余量。虽然 512M 对这个小系统来说资源很紧张但换来的稳定性和可用性才是最重要的。4.3 常见问题排查与避坑指南整个开发和部署过程里我把最典型的几个问题整理成表格这些问题在群里、社区里反复出现如果你也遇到可以直接对照排查现象可能原因解决方案前端接口全部 404后端没启动接口路径不对确认 8080 端口是否监听核对接口路径前缀后端启动报端口占用8080 被其他进程占用用 netstat -ano 查占用进程换端口或杀进程接口返回 401token 过期或没携带重新登录获取 token检查 axios 拦截器是否加请求头数据库中文乱码连接串缺少编码参数url 添加 characterEncodingutf8预约接口超时数据库连接池耗尽检查连接池配置增加最大连接数前端打包后白屏静态资源路径配置错误确认 vite 的 base 配置为相对路径或部署路径Nginx 代理后接口 502后端没启动或代理地址错误检查后端进程代理地址是否写的 127.0.0.1还有个很隐蔽的问题值得单独说MyBatis 的二级缓存。基础配置下 MyBatis 默认开启一级缓存同一个 SqlSession 内查询会缓存结果。但在前后端分离场景里每次请求都会新建 SqlSession一级缓存意义不大而二级缓存如果不做任何配置就开启会引入脏数据问题——比如更新了宠物档案缓存里还是旧数据。我的建议是在没有充分理解缓存机制之前保持默认配置即可这个系统当前的数据库查询压力根本用不上缓存提前优化反而增加出错概率。另外关于 MySQL 版本选择。如果服务器配置一般5.7 版本占用内存更小部署更省心如果对新特性有需求比如窗口函数、JSON 增强功能就选 8.0。两个版本的初始化过程有所差异8.0 的认证插件默认是 caching_sha2_password旧版连接驱动会报认证失败需要单独处理。从稳定性和排错成本上考虑我实际部署时用了 5.7 版本除了安装包好找之外网上踩坑资料也丰富遇到问题基本都能搜到解决方案。4.4 上线后的日常维护建议系统上线不是终点日常维护同样不能掉以轻心。第一件要做的事是数据库备份。我写了一个简单的备份脚本每天凌晨用 mysqldump 把 pet_health 库导出成 SQL 文件保留最近7天的备份。脚本虽简单但真碰上误删数据的时候它能救命。#!/bin/bash mysqldump -u root -p密码 pet_health /backup/pet_health_$(date %Y%m%d).sql find /backup -name *.sql -mtime 7 -exec rm {} \;第二件事是监控日志。后端日志里重点关注异常关键字和慢 SQL 日志。MyBatis 可以配置慢 SQL 打印超过指定时间的 SQL 会输出到日志里定期清理这些慢查询能保证接口响应速度稳定。上线初期我习惯每周看一下日志文件增长量和异常频率一个月后基本稳定了再拉长到每月检查。第三件事是静态资源缓存。前端打包后的文件带 hash 后缀Nginx 里可以给这些文件设置较长的浏览器缓存过期时间能显著减少重复访问时的带宽消耗。但 index.html 本身不能缓存否则前端发版后用户会一直看到旧页面。这类静态资源策略属于小投入大回报值得花几分钟配置好。5. 完整源码获取与后续扩展方向项目完整源码包含后端 Java 工程、前端 Vue 工程、数据库脚本文件、Nginx 配置文件四部分拿到后按上面的流程部署即可跑通不需要额外配置环境变量或复杂的参数调整。源码里我把核心模块都做了详细注释关键业务逻辑处的注释和说明能直接帮助理解代码走向。尝试复现这个项目之后有几个扩展方向很值得继续投入。第一个是消息提醒功能给疫苗到期、预约确认的场景接入通知渠道例如短信、邮件或小程序订阅消息能把“提醒线”做成真正的闭环。第二个是健康趋势分析基于健康记录数据做体重变化曲线、体温趋势图这部分用 ECharts 就能实现界面效果提升非常明显。第三个是引入权限框架做更细粒度的角色管理比如区分普通兽医和管理员的操作权限可以接入 Spring Security 或 Sa-Token。按照个人经验来说这个项目从零到部署完成最大的收获不是在技术上用了多少新框架而是把前后端分离这条完整链路真正走通了——从需求拆解、数据库建模、接口设计到前端页面渲染、联调排错再到线上部署和运维每个环节都亲身踩了一遍。遇到问题时先查日志再定位代码的习惯也在实际工作中受益。如果这个项目能帮你把这条链路走通那它的价值就不止是“一个毕设项目”那么简单。