SpringBoot+Vue全栈实战：流浪动物救助平台完整开发指南

流浪动物救助平台这个项目我前后带人做过四五版从技术选型到上线部署踩过不少坑。基于SpringBootVue做前后端分离配MyBatis操作MySQL整套源码跑通并不难但要做到页面、接口、权限、状态流转都对得上中间有不少细节值得认真梳理。这篇就把我实际落地这套流浪动物救助平台管理系统的完整思路、表结构设计、核心接口实现、前端页面联调以及常见问题排查一次讲透给准备做类似项目的同学一个可以直接参考的模板。这个项目适合谁想用一套完整案例写毕设的学生、刚学完SSM或者SpringBoot想做综合实战的开发者甚至打算给本地救助站做信息化的朋友都能用上。整个系统从用户注册、动物信息发布、领养申请提交到管理员审核、志愿者回访是一条真实可走通的业务闭环对练手和答辩展示都很合适。下面按我实际开发的顺序从需求拆解一直讲到部署排错。1. 项目定位与需求拆解1.1 为什么救助平台适合作为全栈实战项目很多同学选毕设题目时会纠结要么太简单像学生管理系统要么太复杂像电商秒杀。流浪动物救助平台刚好卡在中间偏上的位置业务链路长但不杂乱角色分明但不重度技术点覆盖广但不至于失控。这个项目天然包含几块硬核内容一个是多角色权限控制普通用户、管理员、志愿者三种身份要区分操作范围另一个是业务状态流转领养申请从待审核到通过、拒绝、再到期满回访每一步都要联动动物信息表的状态变化再有就是文件上传处理流浪动物的照片、救助凭证、回访图片都涉及存储和访问。这些点恰好是面试和答辩时老师最爱追问的地方做完一遍能讲的东西非常多。另一个实际原因在于选题方向有真实场景支撑。流浪动物救助站确实需要信息化工具管理动物档案、领养审核和回访记录而不是凭空造一个伪需求。这意味着项目描述、表设计、业务流程都有据可依写论文或者做答辩PPT时素材也更好组织。1.2 功能模块与角色权限划分我把这套系统的功能按照三种角色拆开每个角色只看到自己能操作的部分。普通用户也就是领养人主要走前端页面注册登录、浏览动物档案、按品种和状态筛选动物、查看动物详情、提交领养申请、在个人中心查看申请进度、收藏感兴趣的动物。管理员负责后台维护用户管理、动物信息的增删改查、领养申请的审核操作、志愿者报名审批、公告发布、以及基础的数据统计。志愿者角色的权限居中可以报名参加线下救助活动或者对已经完成的领养进行回访登记填写回访结果。权限控制我采用了经典的RBAC模型思路没有引入复杂的Spring Security框架而是在用户表里直接用role字段区分角色配合后端拦截器校验接口权限。这样对中小型项目来说最直接也最容易讲清楚。等以后真要做细粒度权限再升级到Security也不迟。1.3 业务流程闭环设计这个项目最值得讲的就是完整业务闭环。救助站工作人员通过管理端录入一只新接收的流浪动物填写品种、年龄、健康状况、疫苗和绝育情况上传照片动物状态默认为“待领养”。前台用户注册登录后在列表页看到这只动物点进详情觉得合适就发起领养申请顺便填写申请理由和联系方式。管理员在后台看到这条待审核申请点进去核对信息可以同意也可以驳回。同意之后动物的状态从“待领养”变成“已领养”申请状态变成“已通过”。领养完成一段时间后志愿者在回访模块登记回访情况比如动物在新家的适应状态、是否按时接种疫苗整个闭环才算走完。设计这个流程时我特别注意了一个点状态变更必须成对出现。审核领养申请的时候不只是改申请表的status字段还要同步更新动物表的status字段。这就是后面要讲的事务控制两个表的更新必须放在同一个事务里否则就会出现动物状态和申请状态对不上的脏数据。2. 技术选型SpringBoot、Vue、MyBatis、MySQL怎么组合最好用2.1 后端为什么非SpringBoot不可SpringBoot在2025年已经是Java Web开发的实际默认选项没有之一。它能被这么广泛使用核心在于“约定大于配置”带来的效率提升。以前用Spring MVC搭一个项目要手动配置DispatcherServlet、配置数据源、配置事务管理器、配置JSON转换器光环境搭建就能耗掉半天。SpringBoot把所有默认配置都做好了我只用写一个带main方法的启动类内嵌的Tomcat就能把项目直接跑起来。这个项目我使用的是SpringBoot 2.7.x版本搭配JDK 8这个组合最稳定市场存量也最大毕业设计和生产环境都还有大量项目在跑。如果你愿意用JDK 17直接上SpringBoot 3.x也没问题核心写法差异不大只是javax包名换成了jakartaMyBatis相关的starter也需要匹配3.x版本。我的建议是以跑通和跑稳为主哲学就是“别在版本升级上给自己加戏”。SpringBoot还有一个实用特性是自动装配。数据库连接池、MyBatis的SqlSessionFactory、事务管理器这些组件只要在pom.xml里加上对应starterSpringBoot会自动配置好。我需要做的只是在application.yml里写好数据库连接信息。这种设计对新手极其友好同时也没有牺牲灵活性真需要自定义配置时可以通过Configuration类覆盖默认行为。2.2 MyBatis还是MyBatis-Plus动态SQL与分页的实际选择标题里写的是MyBatis我就以原生MyBatis为主线来讲。MyBatis最让我喜欢的地方是SQL完全可控尤其适合这个项目里多表关联查询场景。比如查询领养申请列表时需要同时关联用户表拿领养人昵称关联动物表拿动物名称和照片这类SQL写XML里一眼就能看明白执行逻辑排查慢查询或者字段映射问题都方便。MyBatis的动态SQL是另一个刚需功能。动物列表页要支持多条件筛选按品种筛选、按性别筛选、按健康状态筛选、按名称模糊搜索。用户可能只填一个条件也可能三个条件一起填SQL就需要根据条件动态拼装。在XML里用if、where、foreach标签处理这种场景非常成熟比字符串拼接SQL安全得多也能避免SQL注入风险。分页场景我用的是PageHelper插件。这个插件用法极简查询前调用PageHelper.startPage(pageNum, pageSize)紧跟其后的第一条查询语句就会自动拼接LIMIT语句并返回包含总数、页码信息的分页对象。有一点必须提醒PageHelper是作用在执行位置的下一条SQL上中间不要穿插其他查询操作否则会分页错乱。这个坑我帮人排查过很多次。如果你不想在XML里写太多简单的单表增删改查用MyBatis-Plus替代原生MyBatis也完全可以。Plus提供了BaseMapper内置了selectById、selectList、insert等现成方法不用写一行SQL就能完成大部分基础操作。我的意见是这个项目用原生MyBatis能把SQL能力练到位对打基础更有帮助。2.3 前端Vue的版本搭配与UI框架前端我采用的是Vue 3 Vite Element Plus的组合这也是目前社区最主流、新项目默认的选型。Vue 3的组合式APIComposition API比Vue 2的选项式API逻辑复用更灵活配合Vite本地开发启动速度极快几乎秒开。如果你手里的源码是Vue 2 Vue CLI的版本也不用焦虑核心页面写法和接口交互逻辑差异不大迁移成本可以接受。Element Plus提供了现成的后台管理组件el-form做表单校验、el-table做数据列表、el-tag做状态标签、el-dialog做审核弹窗、el-upload做图片上传。我的经验是这类管理系统的前端工作量其实有一半是Element Plus帮我省掉的我只需要确定好数据结构和交互流程剩下就是组件拼装。比起从零手写表格和弹窗效率不是一个量级。Vue最核心的优势是响应式数据绑定。管理员在审核弹窗里点击通过前端只需要把新状态push到数组里表格自动更新不需要手动操作DOM。在这个项目里动物状态、申请状态的实时展示以及用户提交表单后的即时反馈都是靠数据驱动实现的。2.4 数据库和中间件到底需要上到什么程度数据库选MySQL没有悬念。我使用的是MySQL 8.0版本配合前面的MyBatis连接使用。MySQL 8.0的JSON字段支持、窗口函数、默认字符集utf8mb4都是加分项尤其utf8mb4能完整存储emoji字符和多语言文本对保存动物描述这类长文本很友好。有很多人会问这个项目要不要上Redis、消息队列、分布式文件系统这类中间件。我的态度很明确核心源码阶段不上因为业务量根本达不到需要引入它们的程度。流浪动物救助平台的并发量有限MySQL单库完全扛得住JWT本身就可以做无状态会话不需要Redis存Session。盲目堆中间件只会把学习成本拉高还把最简单的业务逻辑复杂化。但有一个组件我建议可以预留扩展点那就是文件存储的抽象。刚开始把图片存本地磁盘写一个FileStorage接口上传和获取都通过这个接口调用。以后如果图片多了需要改成MinIO对象存储只需要新增一个MinIO实现类替换Bean注入就能完成切换业务代码一行不用改。这就是面向接口编程的实用价值。3. 数据库设计一张表一张表拆开讲3.1 核心表结构设计数据库设计是这类项目最关键的地基表结构不对后面所有代码都是空中楼阁。我反复调整过好几版最终确定以六张核心表为骨架。用户表负责承载三种角色的公共信息包含用户ID、用户名、密码、昵称、手机号、角色、头像、状态、创建时间等字段。角色用字符串类型存储值分别是USER、ADMIN、VOLUNTEER清晰直观。密码字段必须存BCrypt加密后的密文绝不允许明文落库。动物信息表是整个系统的中心表字段包括动物ID、名称、品种、性别、年龄、体重、健康状态、疫苗状态、绝育状态、图片地址、详细描述、当前状态。动物当前状态字段很关键我用tinyint存储0表示待领养1表示已申请2表示已领养3表示已下架。每个状态变化都会在代码里联动其他表。领养申请表把用户和动物关联起来包含申请ID、用户ID、动物ID、申请理由、联系电话、家庭住址、申请状态、审核备注、审核时间。这张表是业务流的核心枢纽管理员审核的就是这张表的数据同时还要反向更新动物表状态。除此之外还有志愿者表存储志愿者的真实姓名、技能特长、服务区域回访记录表记录每次回访的时间、内容、结果公告表承载平台通知发布。我用一张表格把这六张核心表的作用和状态字段整理出来表名核心作用关键状态字段user系统用户/三种角色status正常/禁用animal流浪动物档案status待领养/已申请/已领养/已下架adoption_application领养申请流转status待审核/通过/拒绝/已完成volunteer志愿者资料审核status待审核/通过/拒绝visit_record领养后回访登记result正常/异常/待跟进notice平台公告发布status草稿/已发布3.2 字段规范与索引设计细节设计过程中我给自己定了三条硬规范落实后省了非常多麻烦。第一每张表必须有create_time和update_time两个时间字段insert和update操作时在代码里统一填充。这样用户注册时间、申请提交时间、审核操作时间都有据可查做时间排序和时间过滤也顺手。有的表还额外加了create_by字段记录操作人ID方便追溯是谁录入的动物信息。第二使用deleted字段做逻辑删除而不是物理DELETE。管理员误删一条动物档案如果直接物理删除数据就找不回来了逻辑删除只是把deleted置为1查询时统一加上deleted0条件数据还能恢复。代价是写SQL时要记得带条件但收益远大于这点麻烦。第三索引设计遵循“按查询条件建索引”的原则。用户表给username建唯一索引登录查询直接命中索引领养申请表给user_id和animal_id分别建普通索引因为最常见的两种查询就是“某个用户的所有申请”和“某只动物的所有申请”动物表给status建索引因为列表页几乎总是按状态筛选。索引不是越多越好但核心查询字段上的索引必须有。所有ID字段统一使用BIGINT自增主键没有使用雪花算法或者UUID。原因很简单单库单表场景自增ID足够用而且占用空间小、查询效率高。以后真要分库分表再改造也来得及。3.3 多表关联查询的SQL实践这个项目里最典型的多表查询是领养申请列表后台管理页需要把申请记录、用户昵称、动物名称和照片一次性查出来。我用左连接实现保证申请记录不会因为用户或者动物数据异常而丢失SELECT a.id, a.apply_reason, a.contact_phone, a.status, a.create_time, u.nickname AS user_nickname, u.phone AS user_phone, u.username AS user_name, an.name AS animal_name, an.species AS animal_species, an.pictures AS animal_pictures FROM adoption_application a LEFT JOIN user u ON a.user_id u.id LEFT JOIN animal an ON a.animal_id an.id WHERE a.deleted 0 ORDER BY a.create_time DESC在MyBatis的XML里写这条SQL时我用了resultMap来定义查询结果映射而不是简单用resultType自动映射。原因在于查询结果里有a.id和an.id、u.id多个同名字段自动映射时容易取错值。通过resultMap显式指定column和property的对应关系每个字段落到哪个属性一目了然。多表查询还需要注意一个常见问题如果要分页PageHelper的startPage要放在这条SQL执行前而且这条SQL必须是紧跟其后的第一条查询。在联查SQL里先掉用startPage再调用Mapper方法MyBatis插件就能自动解析生成count查询和limit语句。4. 后端核心模块实现4.1 项目分层结构与通用配置后端代码结构我按标准的三层架构来组织Controller负责接收前端请求和参数校验Service层写业务逻辑Mapper层通过MyBatis操作数据库。在这之上我再加了entity实体包、dto请求参数包、vo返回结果包、config配置包、utils工具包、common通用类包。通用返回结果类Result是所有接口的统一返回格式包含code、message、data三个字段。业务成功返回200参数错误返回400未登录返回401无权限返回403服务器异常返回500。前端axios拦截器统一判断code字段而不是只看HTTP状态码这样前后端契约清晰。统一异常处理是我强烈建议每个人都要做的事。写一个全局异常处理器用RestControllerAdvice注解标记加上多个ExceptionHandler方法分别处理参数校验异常、业务异常和兜底异常。这样Service层只需要抛出业务异常并传递描述信息Controller层不用每个方法都写try-catch代码可读性能好很多。4.2 登录鉴权拦截器、JWT与密码加密登录鉴权我采用JWT方案核心思路是服务端不再保存Session而是把用户ID和角色等信息签名后生成一个token字符串返回给前端。前端后续每次请求都在请求头里带上这个token后端拦截器解析token确认用户身份。密码加密用的是Spring Security里的BCryptPasswordEncoder虽然项目没有引入完整Security框架但我会单独引入spring-security-crypto这个依赖工具包。BCrypt的加密逻辑在每次加密时会自动加盐相同的密码在不同次加密后密文都不一样这让彩虹表攻击完全失效。注册时加密存储登录时调用matches方法比对。JWT工具类的核心是两个方法生成token和解析token。生成token时我用Java的UUID工具类设置了过期时间有效期我设为24小时对这类管理平台足够用。解析token时需要捕获异常并返回空值让拦截器判断为未登录。拦截器本身我在preHandle方法里从请求头读取Authorization字段去掉Bearer前缀后调用解析工具类解析成功就把用户ID和角色放进request属性中供后续Service层使用。这里有一个必须处理的细节拦截器要放行登录接口和静态资源路径否则前端连登录都调不通。还有浏览器发起请求前都会先发一个OPTIONS预检请求这种预检请求也要放行否则带token的跨域请求会直接失败。4.3 领养申请的状态流转与事务控制领养申请模块是整个系统业务逻辑最复杂的地方。用户提交申请时后端需要同时做三件事插入一条申请记录状态为待审核检查动物当前状态必须是待领养把动物状态更新为已申请。这三步操作必须放在同一个事务里我用Spring的Transactional注解搞定。管理员审核是另一个事务边界。审核通过时要做四件事更新申请状态为已通过并填充审核备注更新动物状态为已领养把该动物其他还在审核中的申请自动驳回记录审核时间。审核拒绝时也要更新申请状态和动物状态动物状态要恢复成待领养等着下一位领养人来申请。我举个例子说明为什么不加事务会出事。管理员处理一条通过操作申请状态已经改成已通过结果更新动物状态的SQL因为异常没执行动物还停在已申请状态前端页面显示这只动物既不能再次申请也不能下架数据就卡死了。加了事务之后任何一步失败所有操作全部回滚数据库始终处于一致状态。状态枚举管理上我写了AdoptionStatusEnum枚举类把待审核、已通过、已拒绝、已完成几个状态统一管理代码里用枚举判断而不用魔法数字可读性和维护性都好很多。4.4 图片文件上传与访问映射动物档案必须有照片所以文件上传模块绕不开。我的实现思路是图片上传接口接收MultipartFile文件校验文件类型和后缀名用UUID生成新文件名避免重名然后写入服务器本地目录最后把访问路径返回给前端存储到动物表pictures字段里。为了让上传的图片能通过URL直接访问我在WebMvcConfigurer里做了一个资源映射把本地磁盘上的上传目录映射到监听/upload/路径前缀上。比如文件存到D:/adoption/images/abc.jpg前端访问http://localhost:8080/upload/abc.jpg就能看到图。这个方案零成本不依赖任何外部服务本地开发和部署都是开箱即用。如果以后图片量大需要上对象存储我会换成云存储或者自建的MinIO服务。接口抽象思路我在前面提过定义FileStorageService接口提供upload和delete两个方法。本地实现和MinIO实现各写一个类通过ConditionalOnProperty来控制激活哪个实现。这个扩展点设计让我在应对不同部署环境时非常从容。5. 前端Vue核心功能实现5.1 工程结构、路由与状态管理前端工程我按功能模块拆目录不是按文件类型堆大杂烩。src下面分views、api、router、store、components、utils几个目录。views目录里按用户端和管理端再细分比如views/user下面放Home、AnimalList、AnimalDetail、ApplyAdopt、UserCenterviews/admin下面放AnimalManage、ApplicationAudit、UserManage等页面。路由配置用了懒加载方式每个页面对应一个路由项组件用箭头函数动态import。这样首屏只加载首页需要的代码其他页面按需加载页面访问速度会快很多。对于管理系统这种多页面场景懒加载是必做的优化。状态管理我用了PiniaVue 3生态对应的状态库。主要用来存两样东西当前登录用户信息和登录token。用户刷新页面后Pinia里的数据会丢失方案是在App初始化时从localStorage恢复用户信息再根据用户角色动态渲染左侧菜单。路由守卫里我会检查目标路由是否需要登录未登录一律跳转登录页。5.2 接口封装与拦截器处理前端调用后端接口必须做统一封装否则每个页面重复写请求逻辑会非常痛苦。我用axios创建了一个实例设置baseURL为/api然后在请求拦截器里从localStorage取出token放到请求头Authorization字段中。响应拦截器是整套封装里的灵魂。后端所有接口都返回Result格式我在响应拦截器里先判断res.data.code如果等于200就正常返回data给页面如果等于401说明token过期或者未登录就清除本地登录状态并跳转登录页其他错误码统一弹出错误提示。这样页面里调用接口的代码只需要关心成功分支异常处理全部交给拦截器统一搞定。api目录里每类接口单独建文件比如animal.js里导出getAnimalList、getAnimalDetail、addAnimal、updateAnimal等函数。页面组件里只import对应的函数调用甚至不用知道接口地址是什么。这种封装让接口维护成本大幅降低后端接口路径变更时只需要改一个文件。5.3 领养申请与管理员审核页面用户端的领养申请页面我用的Element Plus表单组件。申请理由用文本域要求最少写10个字防止用户乱填联系电话预填当前用户绑定的手机号家庭住址必填。表单提交前通过rules规则做前端校验不通过就不发请求既提升用户体验也减轻后端压力。管理员审核页面用的是el-table加自定义操作列。列表展示申请信息、用户昵称、动物名称、申请理由和状态。状态列用el-tag展示颜色跟状态关联待审核橙色、已通过绿色、已拒绝红色。操作列有查看详情、通过、拒绝三个按钮点击通过会弹出确认框防止误触。这个页面还做了搜索和分页顶部有按动物名称和申请状态的筛选条件底部用el-pagination组件切换页码。每次切换页码或者筛选条件都重新调用列表接口后端配合PageHelper返回分页数据结构前端把total值传给分页组件即可。5.4 开发环境跨域与构建部署开发环境下前后端端口不同前端运行在5173端口后端运行在8080端口直接请求必然跨域。我在Vite配置里添加了server.proxy代理把前端发往/api开头的请求转发到http://localhost:8080前端代码里写接口路径统一以/api开头。这样浏览器看到的请求是同源的跨域问题在开发环境完全消除。如果不用代理也可以在后端单独配置CORS允许跨域两种方案选一种就好。我的建议是优先用代理因为代理方案还能顺便隐藏后端真实地址生产环境前端的Nginx也走类似方式转发。正式部署时前端执行npm run build生成dist目录把dist静态文件交给Nginx托管。后端把项目打成jar包用java -jar直接运行。有一个要注意的坑Vue Router如果用history模式前端页面刷新时Nginx会去查找对应的静态路径导致404需要在Nginx配置里加try_files参数把所有请求都指向index.html。如果不想改Nginx配置直接改用hash模式也是简洁的落地方案。6. 环境部署、初始化与联调全流程6.1 后端启动JDK、Maven与application.yml配置后端启动第一步是确认环境我用的是JDK 8和Maven 3.6以上版本。用IDEA打开项目后Maven会自动根据pom.xml下载依赖第一次加载可能需要几分钟要有点耐心。下载完成后运行AdoptionApplication主类见到Spring Boot启动成功的日志就代表后端起来了。有一个非常关键的文件是application.yml所有环境配置都集中在这里。数据库连接、端口号、JWT密钥、文件上传路径都在这里配置。我给一个实用的配置模板server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/adoption?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalse username: root password: 123456 mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.adoption.entity configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl jwt: secret: your-secret-key-change-in-production expire-days: 1这里的map-underscore-to-camel-case配置建议务必开启数据库字段下划线命名user_name可以自动映射到userName属性省去大量手写映射配置。log-impl配置成StdOutImpl可以在控制台打印SQL语句开发时期排查问题非常有用。6.2 MySQL初始化建库脚本、字符集与时区数据库初始化我用一个init.sql脚本搞定里面先创建数据库再建表最后写入账号和几笔示例数据。创建数据库时我指定了字符集避免后续中文乱码问题CREATE DATABASE IF NOT EXISTS adoption DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;使用utf8mb4而不是utf8的原因在于utf8在MySQL里最多只能存3字节的字符而emoji表情是4字节用utf8会直接报错。动物描述里很可能有人用emoji标记重要信息所以必须用utf8mb4。连接时区方面我在JDBC连接串里加serverTimezoneAsia/Shanghai是为了解决JDBC 8.0以上版本默认时区和MySQL时区不一致导致的8小时偏移问题。如果发现时间查询结果比实际多8小时基本就是时区配置没写对。数据库账号建议自建一个专用账号不直接用root。给专用账号授予adoption库的增删改查权限权限边界越收窄越安全。虽然本地学习无所谓但养成好习惯总没错。6.3 前端启动Node环境、依赖安装与代理配置前端环境我用的Node.js 16以上版本。安装完Node后在项目根目录执行npm install安装依赖安装过程可能比较长需要耐心等待。装完后执行npm run dev启动开发服务器看到Vite的启动日志和本地访问地址就成功了。很多新手在这步会遇到npm install报错的情况常见原因是Node版本过高与旧依赖包不兼容或者网络问题导致依赖下载失败。处理方法有几种清缓存重新安装、使用淘宝镜像源、升级Vite和Vue相关包版本。对我来说最有效的方式是先用nvm切换Node版本再重新装一遍依赖。Vite代理配置写在vite.config.js里核心就是前面提到的把/api路径转发到后端export default defineConfig({ plugins: [vue()], server: { host: 0.0.0.0, port: 5173, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })6.4 前后端联调接口规范与数据流验证前后端分别启动完成后联调环节我建议按照业务闭环从头到尾走一遍而不是随机点页面。具体顺序是先在用户端注册一个新账号登录后查看动物列表任意选择一只动物提交领养申请然后切换到管理员账号在后台看到这条申请并审核通过再回到用户端查看申请进度确认状态已变化最后用志愿者账号对这条申请做回访登记。每走一步在旁边打开浏览器的开发者工具查看Network面板里的请求和响应。如果接口报错优先看响应体里的message字段那是我在Service层抛出的业务异常信息能直接指出问题原因。HTTP状态码500表示后端代码异常这时去后端控制台看堆栈日志定位具体代码行状态码400表示参数不对检查提交的字段名和格式是否正确。全流程走通后我再打开后端控制台观察MyBatis打印的SQL日志确认每个接口执行的SQL语句和预期一致尤其是多表联查是否走了索引、分页语句是否正常拼接。这一步能发现慢查询和SQL逻辑错误。7. 常见问题与避坑实录7.1 启动失败排查清单我整理了一个高频启动失败排查表这些是我帮人调试时遇到次数最多的几类问题现象根本原因解决方案端口被占用导致启动失败8080或5173被其他程序占用修改配置文件里端口或用命令查杀占用进程数据库连接异常URL、账号密码或驱动配置错误检查application.yml连接串确认MySQL已启动依赖下载报错Maven仓库源不稳定或包版本不存在换国内镜像源重新clean和install前后端请求404接口路径或代理路径不匹配确认前端/api前缀和后端Controller映射对应中文乱码数据库或连接串未指定utf8mb4重建库表检查连接串characterEncoding端口占用是新手最容易犯的错我推荐用lsof命令配合kill的方式查看并清理占用端口的进程。还有MySQL 8与MySQL 5.x的驱动类名不同这个也常被忽略MySQL 8要用com.mysql.cj.jdbc.Driver。7.2 MyBatis映射与动态SQL的典型坑Mapper接口扫描不到是MyBatis最常见的启动报错之一。解决办法有两个要么在启动类上加MapperScan注解指定Mapper接口所在包要么在每个Mapper接口上单独加Mapper注解。二选一即可不要混用混用反而可能出现重复扫描警告。XML文件放错位置也是老问题。MyBatis默认不会自动扫描classpath下的XML资源即使放在源码目录下也读不到。正确做法是把XML文件放在resources/mapper目录下并在application.yml里通过mapper-locations属性指定路径。我见过不少人在这个问题上卡很久配置路径和实际路径对不上。动态SQL里的参数问题同样频繁。Mapper接口方法如果有多个参数即使带了Param注解XML里也要用等参数名来引用不能直接写参数名。另外resultMap的column属性一定要和SQL查询的别名一致property属性必须和实体类字段一致一旦错位就会出现字段值串位或者null。排查这类问题最简单的方式就是打印SQL日志和查询结果对比。7.3 跨域与Token失效问题开发环境下前端访问后端接口出现CORS错误百分之八十是因为代理没配置或者路径对不上。配置了代理之后接口路径一定不要写成完整的http://localhost:8080改成/api/xxx这种相对路径才能被代理拦截转发。Token失效有两种典型情况。第一种是token过期后接口返回401但前端没有跳转登录页导致用户看到奇怪的报错页面。我在axios的响应拦截器里统一处理401清除用户缓存并跳转登录页彻底解决这个问题。第二种是后端改了JWT密钥导致所有旧token失效这种情况常见于拷贝项目后忘了修改配置文件。跨域和鉴权组合在一起还有一个隐蔽的坑浏览器请求时先发送OPTIONS预检请求预检请求不会携带自定义请求头如果拦截器没有放行OPTIONS请求就会出现浏览器报跨域但后端日志里根本没有业务代码执行记录的现象。在拦截器里对OPTIONS方法直接返回true是必须的。7.4 数据库乱码、时区和emoji存储问题乱码问题我归类成三种场景。页面显示中文乱码一般是数据库表字符集不是utf8mb4导致用ALTER TABLE修改表字符集即可接口返回JSON中文字符乱码一般是编码过滤器没有配置SpringBoot通常会自动处理但手动指定可以在配置类里加CharacterEncodingFilterMySQL命令行插入中文报错是客户端连接参数没有指定字符集连接时加--default-character-setutf8mb4。时区问题表现在查询结果和实际时间相差8小时。排查时先看连接串是否包含serverTimezone再看MySQL全局时区配置。我的做法是在JDBC连接串里明文指定Asia/Shanghai一个位置解决所有问题。emoji存储问题的本质是字符集字节数不够。MySQL的utf8字符集只支持3字节而emoji需要4字节所以哪怕建库时写了utf8也存不进去必须用utf8mb4。还有一点容易忽略数据库的character_set_server、库级、表级、字段级字符集需要保持一致我用一个固定模板建库建表避免多层字符集不一致的隐性问题。我个人在实际操作中的体会是这套系统从零写一遍比直接跑通拿来用收获大得多。跑通源码只是第一步真正动手改一改需求、加一个功能模块比如给动物档案加上疫苗到期提醒或者增加领养合同的线上签署上传才会真正理解数据表为什么这样设计、接口为什么这样拆分。源码交付之后建议你把核心的表结构和状态流转逻辑亲手画一遍流程图答辩时就能做到心中有数。整个项目做完SpringBoot全栈的常见套路你基本都摸过一遍了再去做更复杂的业务系统会发现很多思路都是相通的。