企业官网建设流程全解析

做宠物健康顾问系统这类管理项目，最怕的就是技术栈太重、跑不起来、代码看不懂。最近整理了一套基于SpringBoot后端+Vue前端+MySQL数据库的宠物健康顾问信息管理系统源码，开箱即用，前后端分离结构清晰，非常适合拿来当课程设计、毕业设计或者SpringBoot/Vue实战练手项目。这套系统不是那种只能看不能跑的演示项目，而是把用户管理、宠物档案、健康记录、在线咨询这些核心功能都做了进去，源码拿下来直接配好数据库就能启动，前后端联调访问，整个开发链路非常完整。

下方我会把项目从技术选型到最后跑起来的完整过程拆开讲清楚，包括后端分了哪些层、接口怎么设计、前端页面怎么对接、数据库表结构长什么样、怎么初始化、部署时容易踩哪些坑，以及这套代码后续怎么扩展成更完整的商业项目。不管你是打算复刻来做毕设，还是单纯想学一下SpringBoot和Vue怎么配合做前后端分离项目，这篇文章都能给你省下大量试错时间。

1. 项目概览与技术选型逻辑

1.1 这套系统到底解决了什么问题

"宠物健康顾问系统"这个名字乍一听有点抽象，实际上它的核心定位是给宠物主和健康顾问之间搭一座信息桥梁。宠物主可以录入自己宠物的基础档案、接种疫苗记录、驱虫记录、体重变化、就诊历史，甚至每天的健康状态备注；健康顾问（或者管理员角色）可以查看这些档案，针对性地给宠物主提供日常护理建议、饮食指导，以及线上咨询答复。整个系统解决的是线下宠物健康信息散乱、顾问和宠物主之间沟通低效的问题——把纸质记录、聊天记录变成一处可查、可管、可追踪的线上数据源。

从系统功能来看，这是一套典型的"信息管理系统"，模块划分围绕宠物全生命周期的健康管理展开。用户模块负责登录注册与角色权限；宠物模块维护宠物基本信息与品种分类；健康模块存储体检记录、疫苗接种、驱虫记录；咨询模块支持宠物主在线提问、顾问回复；再加上数据统计看板、公告管理、个人信息维护这些外围功能，基本覆盖了一个中小型管理系统的全部常见需求。无论你是拿它当毕设、课程设计，还是学习前后端分离开发，这套系统都具备很好的参考价值。

1.2 为什么是SpringBoot、Vue、MySQL这套经典组合

这个技术组合在近几年的Java Web项目里几乎成了"标配"，原因并不在于它有多热门，而在于它的学习曲线和开发效率非常平衡。SpringBoot解决了传统SSM项目中大量繁杂的XML配置问题，默认内置Tomcat，一个main方法就能把服务跑起来；Vue提供组件化和响应式数据绑定，让前端页面的开发效率和可维护性远超传统JSP；MySQL则是开源数据库里生态最完善、上手最轻松的选项，配合Navicat或者命令行工具就能完成可视化管理和数据导入。

选型时还有一个很重要的现实因素：这套组合的招人需求和资料丰富程度都很高。无论去面试Java岗位还是全栈岗位，SpringBoot是必问项，Vue是加分项，MySQL更是基本功。把这些技术串成完整项目跑一遍，比只看零散的教程有价值得多。我在给别人推荐练手项目时通常也不会选特别冷门或新颖的技术栈，能用最主流的技术把业务做清楚，其实才是最符合实际工作需求的。

从项目本身来看，前后端分离架构也让团队协作变得更加自然：前端专注页面交互，后端专注接口和数据，两边通过JSON进行通信。后面我会详细讲到项目结构、接口设计、数据表设计和部署流程，每一步都会结合我在实操中积累的细节来展开。

2. 项目结构与后端核心设计

2.1 后端工程结构与分层设计

拿到源码之后，第一件事应该是先理解后端的工程结构。一个规范的SpringBoot项目，目录结构通常遵循controller、service、mapper、entity这样的分层，这套源码也不例外。

pet-health-backend/ ├── src/main/java/ │ └── com/pethealth/ │ ├── controller/ # 控制层，接收前端请求 │ ├── service/ # 业务逻辑层 │ ├── mapper/ # 数据库操作层（MyBatis-Plus） │ ├── entity/ # 数据库实体类 │ ├── dto/ # 请求参数封装 │ ├── vo/ # 返回结果封装 │ ├── config/ # 配置类（跨域、拦截器等） │ ├── common/ # 通用返回结果、异常处理等 │ └── PetHealthApplication.java ├── src/main/resources/ │ ├── application.yml │ └── mapper/ # MyBatis-Plus SQL映射文件 └── pom.xml

分层不只是为了好看，而是为了让每一层职责单一。controller只负责接收参数和返回结果，不写业务逻辑；service承载核心业务，比如新增宠物时同时校验用户权限、生成默认健康档案；mapper只做数据持久化。这样后续要做代码审查、加功能、排查问题，都能快速定位到文件，不会在一个大Controller里翻几千行代码。

很多新手拿到项目喜欢从Controller开始读，这没错，但同时建议先去service层看业务流向，否则会有大量接口"看过就忘"。我习惯的做法是：先跑一次系统、用Postman登录拿token，然后跟着一个核心功能（比如新增宠物档案）从前端请求路径追到后端service方法，这样整个调用链就串起来了。等你想二次开发时，这套熟悉流程能帮你节省大量时间。

2.2 核心接口设计与业务逻辑梳理

后端接口的设计直接决定了前端好不好对接，也决定了整个系统的可扩展性。这套系统的接口风格是标准的RESTful + 统一返回格式，比如用户模块有注册、登录、获取用户信息；宠物模块有新增、编辑、删除、分页查询；健康档案模块有新增体检记录、查询宠物历史健康记录；咨询模块有发起咨询、顾问回复、查看咨询列表等接口。

以登录接口为例，它的典型调用流程是：前端把用户名和密码POST到/api/user/login，后端先做基础参数校验，接着用MyBatis-Plus的QueryWrapper按用户名查询用户，然后用工具类做密码的MD5或BCrypt加密比对。比对通过后生成JWT token返回给前端，前端把它存在localStorage里，之后每次带token请求受限接口，后端通过拦截器解析token并判断角色权限。

这里有一个非常关键的设计细节：统一返回结果。后端没有在controller里直接返回一个裸的User对象或List，而是统一用R对象包了一层，格式大致长这样：

{ "code": 200, "msg": "操作成功", "data": { "token": "eyJhbGciOiJIUzUxMiJ9..." } }

这么做的好处是前端可以统一拦截响应，在axios响应拦截器里判断code字段，拒绝登录过期、业务异常时弹统一的错误信息，而不是每个接口单独写一遍判断逻辑。很多半路出家的项目没注意这个细节，导致前端到处散落着res.data.code === 200这类重复代码，后续维护非常痛苦。

另外要特别注意handler层对全局异常的处理。项目里通常会加一个@RestControllerAdvice的全局异常处理器，把业务异常、参数校验异常、未知异常统一封装成指定格式返回给前端。这样数据库报错、空指针这样的问题不会把整堆堆栈信息直接抛给用户，线上排查起来也更安全。这个模式也是大厂开发中的通用做法，值得仔细看。

2.3 关键配置与常见版本坑

后端跑起来之前，必须检查application.yml里的配置。最核心的是数据源配置、端口配置、MyBatis-Plus配置和JWT相关配置。

server: port: 8080 servlet: context-path: / spring: datasource: url: jdbc:mysql://localhost:3306/pet_health?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT+8 mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: id-type: auto

关于serverTimezone=Asia/Shanghai和useSSL=false这两个参数，是从SpringBoot整合MySQL时最容易踩坑的地方。MySQL 8.0以上默认启用SSL，如果不显式关闭，启动连接时可能出现握手失败或SSL相关错误；时区不设置，Java 8的LocalDateTime存进MySQL时会出现时区偏移，导致前后端展示的时间差8个小时。这两个属于"不亲眼遇到根本不会在意"但一遇到就要折腾半天的坑。

版本问题更要留心。这套源码如果基于SpringBoot 2.x，就不建议盲目升级到SpringBoot 3.x，因为3.0之后强制要求JDK 17，很多旧版依赖的API也变了，硬升级会带来一堆莫名其妙的报错。我也见过有朋友拿到源码后把pom.xml换成最新的SpringBoot 3.1.0版本，结果项目直接无法启动。正确的做法是：先看项目原版的依赖版本，如果能跑通，就不要去改大版本；如果必须用高版本，就准备好额外的时间去适配。

另外，MyBatis-Plus分页插件需要手动在配置类里注册MybatisPlusInterceptor并添加PaginationInnerInterceptor，很多分页功能失效的问题都出在漏配这个Bean上。老手可能觉得这是常识，但新手在全新环境中很常见，我会在后文的排查清单里再提到。

3. Vue前端落地细节

3.1 前端工程结构与路由设计

前端部分用的是标准Vue项目结构，整体技术栈以Vue 2为核心配合Element UI、Vue Router和Vuex，构建工具为Webpack（对应Vue CLI 4或5版本）。依赖安装命令是npm install，建议不要直接装最新版本，而是用项目里package.json锁定的版本，避免Element UI和Vue 3、Vite这些新生态混在一起出现兼容性灾难。

pet-health-web/ ├── public/ │ └── index.html ├── src/ │ ├── api/ # 接口请求封装 │ ├── assets/ # 静态资源 │ ├── components/ # 公共组件（文件上传、富文本等） │ ├── router/ # 路由配置 │ ├── store/ # Vuex状态管理 │ ├── views/ # 页面组件 │ ├── utils/ # 请求工具、token处理 │ ├── App.vue │ └── main.js └── package.json

路由设计是前端骨架的关键。项目里通常把页面分成两个层级：不需要登录校验的页面（登录、注册）和需要登录校验的业务页面（首页、宠物档案、健康档案、咨询中心、个人中心等）。实现这套区分最常见的方式是路由守卫，在router.beforeEach里读取localStorage里是否存有token，没有就重定向到登录页；有token但访问的是登录页，就重定向到首页。这套机制看着简单，却是必须写好的安全底线，前端路由只是交互层面的限制，真正鉴权和越权控制还得依赖后端权限校验。

很多学习Vue的同学容易忽略路由层级设计。不要把宠物列表、健康列表全部平铺在/views下面，建议按模块分文件夹，比如views/pet、views/health、views/consult、views/user，组件放在components里统一管理。这套源码的目录划分就做得比较清楚，拿来学习Vue Router的嵌套路由、动态路由以及组件复用都很合适。

3.2 核心页面与交互逻辑说明

打开系统之后，第一个有感觉的页面通常就是登录页和注册页。这两个页面在Element UI基础上封装了一个表单组件，包含基本的手机号或用户名输入、密码输入、登录和注册切换逻辑。表单校验用的是rules规则对象，比如用户名不能为空、密码长度必须大于等于6位，这些校验能做到在请求发出之前先把明显错误拦截下来。

宠物档案列表页是系统的核心页面之一。这里的交互逻辑很有代表性：页面一进来就调用getPetPage接口拿分页数据，点新增按钮弹出一个Dialog，Dialog里是宠物表单（宠物名、品种、年龄、性别、体重、是否绝育等），提交时调addPet接口，成功后刷新列表。这里有一个值得学习的交互细节：删除宠物前使用this.$confirm做二次确认，避免用户误操作。很多初学项目忽略这类交互细节，做得比较糙，但从实际投入使用角度，这类细节恰恰是体验感提升的关键。

健康档案页面会用到大量的时间线和卡片展示。宠物健康记录在系统中不是一张单表无限堆数据，而是以宠物为维度，将疫苗接种、驱虫、体检、日常体征维护成多类记录。前端通过标签页或者时间线组件将不同类别的记录展示出来。这里值得提一下Vue组件的"插槽"用法——Element UI的表格卡片组件大量支持插槽，自定义操作列、自定义状态显示都是通过插槽完成的。如果你不太理解Vue插槽，到了这个页面就能非常直观地看到它的实战场景：同样的表格组件，每列的显示方式是可以通过具名插槽灵活控制的，数据字段和展示UI被彻底解耦。

3.3 接口请求封装与状态管理

大型Vue项目必须做的事，是把axios请求统一封装起来，避免每个页面里直接写一堆axios.get加上重复的loading、错误处理代码。这套源码里utils/request.js就是干这件事的，它的基本做法是创建axios实例，设置baseURL为/api，然后通过请求拦截器把存在localStorage里的token拼到请求头Authorization字段上，再通过响应拦截器统一处理code码。

import axios from 'axios' const service = axios.create({ baseURL: '/api', timeout: 10000 }) service.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers['Authorization'] = token } return config }) service.interceptors.response.use( response => { const res = response.data if (res.code === 401) { localStorage.removeItem('token') router.push('/login') return Promise.reject(new Error('登录已过期')) } if (res.code !== 200) { Message.error(res.msg || '系统错误') return Promise.reject(new Error(res.msg || '系统错误')) } return res }, error => { Message.error(error.message) return Promise.reject(error) } )

这段逻辑在项目里是一种"标准答案"，几乎所有Vue后台管理系统都是这么做的。单独拿出来讲是因为很多初学者会在每个组件里重复写接口请求，结果就是token失效后到处弹错误、接口报错后每页都要手动处理。把请求统一收敛到一个文件后，你在任何新页面里只需要import { getPetList } from '@/api/pet'就可以用了，维护成本直接降一个级别。

Vuex在项目里主要用来管理当前登录用户的信息。登录成功后把用户对象存入Vuex和localStorage，页面刷新后再通过getUserInfo接口重新拉取用户信息。这里说一下我个人的建议：用户名、头像这类展示型数据放Vuex方便，但token持久化一定用localStorage，因为Vuex的数据刷新就没了。有些项目把token也放进Vuex，刷新后必须重新登录，体验极差，把这个点写进你日后自己的项目注意事项里。

4. MySQL数据库设计

4.1 核心表结构一：用户与宠物档案

数据库是这套系统的地基，表设计不合理，后期改起来成本极高。这套项目采用的是比较经典的多表设计，核心表包括用户表、宠物表、健康档案表、体检记录表、疫苗记录表、咨询表等，各自职责清晰、关系明确。

用户表是最基础的一张表，字段上至少要包含用户名、密码、昵称、头像、手机号、角色标识（管理员/普通用户）、状态（是否禁用）、创建时间、更新时间。需要注意密码字段不能存明文，而是存加密后的密文。宠物表则记录宠物所属用户、宠物名、品种、性别、出生日期、体重、绝育状态、头像URL。宠物表通过user_id外键关联用户表，这就保证了一个用户下可以拥有多只宠物，符合实际业务场景。

外键在MySQL里到底建不建，很多项目分两派。这套项目我更建议以逻辑外键为主，也就是在Java代码层面维护关联关系，表结构层面不强制加外键约束。原因很简单：加了物理外键，删除宠物或用户时会被约束卡住，还得先删关联数据，很多业务场景并不希望这样，更重要的是分库分表和后续数据迁移时，物理外键会成为很大的阻碍。实际开发中见过大量表是保留user_id字段但不用物理外键的方式，这属于行业默认做法。

4.2 核心表结构二：健康档案与体检记录

健康档案表可以理解为一个"动态的体检记录集合"表，它并不直接存"健康状态"这种宽泛概念，而是把每一次具体的健康行为都记录成一行。体检记录表会存宠物ID、体检日期、体检医院、体重、体温、诊断结果、医嘱建议、下一次复查时间。疫苗记录表则存疫苗名称、接种日期、接种剂量、下次接种提醒时间。为什么要拆成多张表而不合并成一张"健康记录表"？因为不同记录类型的字段差异太大了，硬塞进一张表会造成大量空字段和解析困难，查询和维护都是灾难。

在设计这些记录表时，有一个容易忽略但很关键的点：业务上的"冗余字段"要留够。比如体检记录里存了宠物ID，看似查宠物表就能拿到宠物名，但在列表展示时每次都去关联查一次宠物，会导致性能下降。更常见的做法是冗余一个pet_name字段在记录表里，这样宠物改名字后历史记录展示的仍是当时体检时的名字，这其实也是一种业务严谨性。数据分析时统计某只宠物一年内体重变化，也只需要过滤宠物ID加日期区间就可以完成，查询效率更高。

4.3 索引、锁与数据一致性注意点

数据库设计绕不开索引和数据一致性问题。这套项目的数据量不大，索引策略不需要很激进，但有几个字段一定要建索引：用户表的username字段、宠物表的user_id字段、健康记录表的pet_id和record_date字段。这些字段是查询条件里的高频字段，建了索引后的提升非常明显。

新手最容易忽略的一个索引问题是，在MySQL 8.0里一个普通的多列查询如果没走索引，数据量一旦上千条就能感到明显卡顿。比如查询"某个用户的所有宠物在某个日期之后的体检记录"，如果只在pet表上建了主键索引，而体检记录表上没有pet_id + record_date的联合索引，这条SQL就会变成全表扫描。搭建这个项目后，如果想做更复杂的数据统计，建议用EXPLAIN看一遍常用SQL的执行计划，看看有没有用上索引，这是很好的MySQL排查习惯。

关于MySQL锁的分类，这在面试里是高频问题，在项目里也值得对应理解。简单说，锁从粒度上分为表锁和行锁，从模式上分为共享锁和排他锁，InnoDB引擎支持行级锁，这也是为什么它适合高并发写操作。在这个宠物健康系统里，同时有多位顾问去更新同一只宠物的健康档案时，如果两个事务同时写入同一条记录，就需要行锁来保证数据一致性。实际开发中我建议尽量不要在业务代码里手动加锁，而是通过事务隔离级别和乐观锁（比如在表里加version字段）来解决，MySQL的默认隔离级别Repeatable Read在这个系统完全够用。

整理一下核心表的结构参考：

5. 从零到一跑起来

5.1 环境准备：JDK、Maven、Node、MySQL

拿到源码想直接"run"起来，环境这块就得先过关。后端需要JDK 8或11（取决于pom.xml里的版本设置），Maven 3.6以上，MySQL 5.7或8.0；前端需要Node.js 14到16之间的版本（Vue CLI 4/5对Node 18以上会有兼容问题，这是我踩过实实在在的坑）。建议先打开命令行分别执行java -version、mvn -v、node -v、npm -v、mysql --version，确认这些命令都正常返回，再往下走。

JDK安装没有太多悬念，配好JAVA_HOME环境变量就行。Maven需要改一下本地仓库路径和镜像源，国内建议在settings.xml里配置阿里云镜像，否则首次拉取依赖会慢到你怀疑人生。Node.js安装更简单，直接去官网下载LTS版本安装即可，装完之后顺手把npm的registry切换成https://registry.npmmirror.com，可以显著提升依赖安装速度。MySQL安装时要注意字符集选择utf8mb4，不然后面在Windows命令行里插入中文数据会出现乱码。

5.2 数据库初始化与账号配置

项目里如果带了SQL脚本，那就是最省心的情况，通常是一个pet_health.sql文件。执行导入的方式很简单：

mysql -u root -p pet_health < pet_health.sql

或者直接在Navicat里右键"运行SQL文件"。导入的时候如果报错，大概率是SQL文件里的字符集和当前数据库不一致，或者MySQL版本太低导致某些语法不兼容。建议手工在MySQL里先创建好库再导表：

CREATE DATABASE pet_health DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

这里强烈建议使用utf8mb4而不是utf8，因为utf8在MySQL里最多存3个字节，一些特殊字符（比如生僻字和部分符号）会存不进去，而utf8mb4完全兼容并且还支持emoji。虽然管理系统里不太会出现emoji，但宠物名里偶尔会有特殊字符，从源头把字符集设置对能避开很多脏数据问题。

导入完SQL后，检查一下t_user表里有没有内置管理员账号。这个很关键，很多项目第一次登录用的就是预设的admin/admin123这样的账号密码。如果SQL里没有，你需要自行注册一个账号，然后手动在数据库里把角色改成管理员，才能进入后台管理界面。我第一次跑一个开源项目时就遇到这种情况，一开始没注意，注册了一个普通用户，结果很多管理接口报"无权限"，排查了半天才意识到角色字段没改。

5.3 后端启动与常见启动错误排查

环境都准备好后，先启动后端。用IDEA打开后端工程目录，等Maven把依赖下载完成后，在PetHealthApplication.java里运行main方法即可。如果你的IDEA没有自动导入Maven依赖，可以右键pom.xml选择Add as Maven Project，这是一个很隐蔽但很影响体验的坑。

启动成功后会看到类似下面这样的日志：

Tomcat started on port(s): 8080 (http) with context path '' Started PetHealthApplication in 5.348 seconds (JVM running for 6.123)

如果启动时端口被占用，会直接报Port 8080 was already in use，这时候要么关闭占用端口的进程，要么在application.yml里换一个端口。用命令行查一下谁占用了8080：

netstat -ano | findstr 8080

然后去任务管理器里找到对应PID的进程结束掉，或者嫌麻烦直接把端口改成8081，但注意改成8081后，前端所有接口请求地址也要对应修改。通常我在本地调试时会直接固定使用8080端口，避免后面前端代理还要改来改去。

数据库连不上的错误也很常见，报错信息一般是Access denied for user 'root'@'localhost'或者Communications link failure。前者是账号或密码错了，后者是MySQL没启动或者连接地址不对。MySQL在Windows上安装后默认不会自动启动服务，需要在"服务"里找到MySQL服务并手动启动，或者运行net start mysql命令。这个环节也是很多新手一走就卡壳的地方。

5.4 前端安装依赖与启动联调

后端跑起来后，进入前端目录安装依赖：

cd pet-health-web npm install npm run serve

如果npm install报了ERESOLVE unable to resolve dependency tree这种错误，大概率是npm版本和项目依赖的版本冲突。最简单的解决办法是切换Node版本到14或16，或者用npm install --legacy-peer-deps安装依赖。Vue CLI项目通常在node_modules安装完成后，提示Compiled successfully in 2843ms就算成功，浏览器访问http://localhost:8080就能看到登录页。

这里需要注意前端默认的接口代理。vue.config.js里通常配置了proxy，把/api的请求转发到后端的http://localhost:8080：

const { defineConfig } = require('@vue/cli-service') module.exports = defineConfig({ devServer: { port: 3000, proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } } })

启动成功访问http://localhost:3000后，页面能打开但不一定代表前后端联调成功。建议打开浏览器开发者工具的Network面板，刷新页面随便触发一个请求，看看接口返回的状态码是不是200，返回体里是否有正常数据。如果出现401、404或者跨域报错，都说明代理配置或者后端路径有问题，需要回到对应环节排查。我曾经帮别人联调过半天，最后发现是前端代理配了/api但后端接口前缀根本没带/api，两边路径对不上，前端一直在404，这种就属于典型的"单独看都对，连起来就不通"的问题。

5.5 打包部署与"Vue打包放进SpringBoot"方案

开发环境跑通只是完成了第一步，真正交付时还要思考部署方案。最常用的两种方式有两种。第一种是前后端完全分开部署：前端执行npm run build生成dist目录，放到Nginx或者其他静态服务器上，后端打成jar包独立运行，用Nginx把/api反向代理到后端端口，比如：

location /api/ { proxy_pass http://127.0.0.1:8080; }

第二种方式是很多人熟悉的"Vue打包放进SpringBoot"一体化部署：把前端dist目录下的全部文件复制到后端src/main/resources/static目录下，重新打包SpringBoot工程，这样整个系统只需要跑一个jar包就能同时提供页面和接口。这种方案适合小型项目或个人项目，省去了单独维护Nginx的麻烦，但缺点是前端和后端耦合在一起，后续需要分别修改时打包步骤会稍繁琐。

一体化部署的注意点是路由模式。Vue Router默认用history模式，打包后刷新页面容易遇到的404问题，因为SpringBoot内部没有处理前端的history路由回退。要解决这个问题，有两个可行路径：一是把Vue Router模式改成hash模式，URL里带个#，刷新不会404；二是在后端加一个转发控制器，把非接口路径转发到index.html。个人项目为了省事直接用hash模式最稳，这也是很多开源项目在"可直接运行"模式下采用的做法。

生产环境部署时application.yml里的数据库连接、端口、JWT密钥等建议通过--spring.config.additional-location或者环境变量覆盖，而不是直接写死在包里。这些都是让系统具备上线水平的细节，虽然不影响本地跑通，但如果你想拿这套源码去公司里展示落地能力，这些点都非常加分。

6. 常见问题与排查实录

6.1 跨域问题：报了CORS错误怎么办

开发环境下只要配置了devServer代理，一般不会遇到跨域问题。但一旦前端用npm run build之后直接双击index.html访问，或者前后端部署在不同域名下，CORS错误就来了。错误信息长得很典型，常见的是Access to XMLHttpRequest at 'http://localhost:8080/api/...' from origin 'http://localhost:3000' has been blocked by CORS policy。

解决办法就是在后端加一个跨域配置类，允许指定的前端来源访问。最简单的写法是：

@Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/**") .allowedOriginPatterns("*") .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowedHeaders("*") .allowCredentials(true) .maxAge(3600); } }

注意这里我用的allowedOriginPatterns，而不是allowedOrigins。后者在高版本SpringBoot里配合allowCredentials(true)时会因为来源地址精确匹配而报错，使用*通配模式更省心。如果项目里用了Spring Security，跨域配置还需要在Security的过滤链上也放行预检请求，否则前端发OPTIONS预检请求时会被Security拦下来，这种问题表面上是跨域，实际是安全配置冲突，排查起来非常绕。

6.2 MySQL连接失败的三类经典场景

MySQL连接失败是我在这类项目里收到提问最多的一类问题。第一类是MySQL服务没启动，Windows下安装MySQL后服务默认是停止状态，报错见Communications link failure，解决办法是启动服务并设为自动启动。第二类是用户权限问题，报错是Access denied，常见原因是root用户密码记错了，或者没有允许远程连接（本地连一般不会触发）。这时可以试试在MySQL命令行里执行：

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '你的新密码';

这个命令不仅改了密码，还把认证插件改成了mysql_native_password。MySQL 8.0默认的caching_sha2_password认证插件，有些老版本的JDBC驱动和图形客户端不认，就会连接报错。把认证插件改成老格式是最普适的解法。第三类是端口和字符集问题，java.sql.SQLException: Unknown database 'pet_health'基本就是没执行SQL脚本，或者库名写错了。这类问题的排查思路很简单：先用Navicat或命令行自己连一下MySQL，看看能不能正常访问；再用数据库配置里的账号密码去连，看是否报错。这一步如果都没问题，那问题就大概率不在数据库层面，而在于SpringBoot的配置文件有没有生效。

6.3 接口404与服务扫描路径问题

前端页面能打开，但每次接口请求都返回404，这里有一个很隐蔽的坑——Controller的包扫描路径不对。SpringBoot启动类默认扫描的是@SpringBootApplication所在包及其子包，也就是说启动类放在com.pethealth下，Controller也得放在com.pethealth.controller或者com.pethealth的子包里。如果把Controller放到com.xxx.controller这种不相关的包里，SpringBoot启动时根本不会注册这个Bean，接口自然404。

碰到这种问题先检查控制台日志，启动时一般会打印当前项目里所有已注册的接口路径，比如Mapped "{[/api/pet/list],methods=[GET]}"。如果日志里压根没有这个接口，就说明Controller没被扫描到，这时候把启动类往包结构上层移动是最省事的解法。如果日志里能打印接口，但访问还是404，那就得检查前端代理路径和后端context-path是否一致。SpringBoot的spring.mvc配置有时候会加上一个前缀路径，前端如果没跟着改，接口也会全部404。

6.4 Node版本与依赖导致的启动失败

npm run serve命令执行后，控制台报各种语法错误或者TypeError: Cannot read properties of undefined，十有八九是Node版本不兼容。现在想想，身边超过一半的人在这套项目上卡壳都是因为前端环境版本太新。Vue CLI 5推荐Node 14到16，Node 18之后Webpack的热更新和部分模块就会出问题。我用nvm这类版本管理工具在没有nvm的环境下切换很麻烦，但为了这个项目专门装一个老版本Node也值得，不会耽误多久。

另外一个高频坑是npm install的时间过长或者中途报ELIFECYCLE错误。这种一般不是代码问题，而是网络问题，建议把npm源切到国内镜像后再装一次。有些老项目的依赖里有node-sass，这东西在Node 16之后的版本上几乎必装失败，如果遇到这种报错，换成sass（Dart Sass）可以原地解决。问题根源是node-sass是C++插件，每次装都要针对本机Node版本重新编译，极其容易失败，现在的项目基本已经淘汰它了。

6.5 数据能存但查不出来：字符集、时区与排序问题

有朋友遇到过新增宠物后列表里中文是乱码，但是数据库里看却是正常的，这种多数是前端页面渲染字符集设置不对，检查index.html里有charset="utf-8"即可。反过来，数据库乱码则大概率出在连接字符串上，确保URL里带上characterEncoding=utf-8。MySQL的utf8mb4和Java的UTF-8其实是一致的，但中间环节如果没有统一，就会出现"看着对、存进去变样"的问题。

时区问题则集中体现在时间字段上。页面提交一个体检时间，存进数据库后却少了8小时或者多了8小时，第一反应应该是检查MySQL连接串里有没有serverTimezone=Asia/Shanghai，同时检查Jackson的时区是否设置为GMT+8。两边的时区都统一后，时间显示基本就正常了。还有一个MySQL排序的坑，如果列表排序结果不对，很可能是排序字段选错，或者字段类型是varchar导致排序时按字典序而不是数字序排，比如体重字段如果是字符串，10就会排在9前面。解决办法是把这类字段改成decimal或double类型，或者排序时用CAST(weight AS DECIMAL)。

7. 这套源码如何扩展成更完整的业务系统

7.1 功能扩展方向一：预约与提醒

如果只是按源码原样跑通，那它能满足"课程设计/毕设"的要求，但离真正的线上宠物健康服务还有一段距离。我见过很多相关项目，在它的基础上大约可以在三个方向做功能扩充。

第一是预约医生和排班。宠物健康顾问的核心场景是"宠物主有问题，顾问给出建议"，目前咨询模块是留言式的，可以进一步做成排班预约式：顾问维护可预约时段，宠物主选择一个时间段发起预约，系统自动生成一条预约记录。这个功能看似多了一张预约表，其实后端只需要新增一个预约Controller，前端新增一个日历组件，再加一个完整的业务状态流转（待支付、待接诊、进行中、已完成）。从技术上来说并不难，但业务上它能让系统更像一个可用的在线问诊平台。

第二是自动提醒功能。疫苗记录里有下次接种时间字段，可以做一个定时任务，每天扫描这些记录，给临近日期的宠物主推送站内信或短信提醒。SpringBoot实现定时任务非常简单，只需要在启动类上加@EnableScheduling，然后在service里写一个带@Scheduled(cron = "0 0 9 * * ?")的方法即可。每天上午9点跑一次，检索未来三天需要接种疫苗的记录，生成通知数据。这个扩展做出来很能体现"健康管理"的系统价值，也是面试时非常好的加分细节。

7.2 功能扩展方向二：文件上传与数据可视化

宠物档案和体检报告里往往需要上传诊断图片、化验单截图，目前如果只支持URL填写，使用体验会大打折扣。扩展文件上传功能时，可以将本地存储作为最简实现，在application.yml里配置一个上传目录，通过MultipartFile接口接收文件，保存后返回可访问的URL。等将来上了云服务器，再替换成对象存储SDK，业务代码不需要大改。这里我建议把所有上传接口统一定义为/api/file/upload，前端封装一个FileUpload组件，这样宠物档案、健康档案、公告模块都能复用。

数据可视化则是把现有数据变成图表。宠物管理系统最值得统计的数据包括：宠物总数、按品种分类的占比、每月新增宠物数量、各健康指标的异常比例。用Vue生态里的ECharts组件，加上后端的统计接口，就能快速实现一个数据看板。统计接口的做法一般是写一个DashboardController，通过聚合查询返回各指标数据。比如查询每月新增宠物数：

SELECT DATE_FORMAT(create_time, '%Y-%m') AS month, COUNT(*) AS count FROM pet GROUP BY month ORDER BY month

这样前端拿到数据后直接喂给ECharts的柱状图或折线图即可。数据可视化几乎是所有管理系统的加分刚需，如果项目里能展示一个像样的看板，整个系统的完成度和专业性都会明显提升。

7.3 工程化提升与代码规范补充

最后再说一点工程化层面的建议，这是我搭建类似系统时体会最深的部分。这套项目源码目前能"直接运行"，但离规范的团队开发标准还有一段距离，如果要作为正式项目迭代，可以从这几个方面逐步提升。

项目里可以补充统一响应体R类和全局异常处理器，这两块属于最基础的部分，很多系统源码会包含这部分，但也有些简化版的项目里所有接口直接返回Map，后端报错直接堆异常栈。如果你拿到的是简化版本，建议无论如何都要加上统一响应体，它能让你后面所有接口的改动都变得非常统一、非常省事。

接口文档和日志也不能轻视。SpringBoot工程可以引入springdoc-openapi或者knife4j来生成Swagger接口文档，这样前端对接时不用反复翻源码；日志方面，不要到处用System.out.println，要使用SLF4J + Logback，在application.yml里配置Info级别和Error级别的日志文件输出。虽然这些不影响"跑通"，但如果你日后要拿这套项目去面试或接项目，工程化程度就是普通代码和规范代码的分水岭。

单元测试也值得认真写。不要只写Service层的干净方法测试，更重要是用@SpringBootTest写几个核心接口的集成测试，比如宠物新增、咨询回复的整个流程走一遍，保证核心业务不崩。这个投入产出比很高，能让你后续做任何功能扩展时都不用担心改挂了原有逻辑。

8. 最后一点实际体会

我在实际整理和运行这套项目过程中，最大的感受是：SpringBoot、Vue、MySQL这套组合本身就是最好的"教案"。把系统跑通不是终点，你完全可以在此基础上把每条弯路、每个报错变成自己的经验积累。第一次跑通比预期多花了点时间，但踩过那些坑之后，再看其他任何前后端分离项目，基本上第一眼就能定位到大概的部署结构、接口风格和数据流走向。

如果你也正在拿这套源码做二次开发，记住一个原则：先跑通原版，再改业务，最后换技术。不要一开始就想换成最新版本、换UI框架、改数据库类型，那等于给自己叠buff。顺着既定技术路线先跑通，再加预约提醒、上传、图表看板这些扩展功能，每一步都在原项目基础上落地，慢慢就会形成自己的代码资产。到时候这套项目就不只是"可运行的源码"，而是能代表你真实开发能力的一块敲门砖。