平时做的管理系统不少但真正让我觉得技术有意义的还是这个以流浪动物救助为主题的网站项目。前后端分离、基于SpringBootVueMyBatisMySQL构建既是一套标准的企业级开发范本也把真实的业务场景落了地。流浪动物救助机构最缺数字化的信息管理工具这套系统刚好补上了这个缺口——动物档案、领养申请、救助登记、公告发布全部在线化普通浏览用户不用登录也能看动物信息管理员在后台维护数据整个流程走得很顺。这个项目适合正在学前后端分离开发的人拿来当练手范例适合准备毕业设计或求职项目的开发者做二次开发基础也适合真正有救助组织背景的人直接部署使用。技术栈不花哨但都是市场主流麻雀虽小五脏俱全。这篇文章我会从设计思路、数据库结构、前后端核心实现、部署步骤到排坑心得一条线讲清楚照着走就能跑起来。1. 项目整体设计与技术选型思路1.1 核心功能拆解动手做这个系统之前我先把流浪动物救助这个场景的业务流程捋了一遍。救助组织日常最烦的事儿不是缺粮而是信息太分散——今天有人在某地捡到一只猫发了条朋友圈明天有人想领养却不知道去哪找靠谱的动物来源。中间全靠人工对接效率低到离谱。所以我给这个系统划了这几个核心模块动物信息管理管理员可以录入、修改、上下架流浪动物的档案包含品种、年龄、性别、健康状况、照片、救助时间等字段这是整个系统的信息底座。领养申请流程普通用户看上某只动物后可以提交领养申请填写居住情况、养宠经验等信息管理员在后台审核状态从待审核流转到已通过或已拒绝。救助登记用户遇到流浪动物时可以提交救助信息填上发现地点、动物状态、联系方式管理员收到后安排后续处理。用户系统区分普通用户和管理员两种角色用JWT做登录认证权限不同看到的页面不同。公告资讯救助组织发布领养活动、物资募集、文明养宠科普等公告让平台不只是一个数据库还有内容属性。这套模块划分的逻辑是让普通用户做得少、看得多让管理员管得多、操作快。前端页面风格偏温暖明快毕竟救助类产品跟电商后台不一样用户路径需要一点情感引导。1.2 为什么选这套技术栈选型这件事我个人有个原则面向场景选技术不面向新技术选技术。很多人喜欢一上来就上微服务、K8s结果项目复杂度比业务复杂度还高得不偿失。这个项目的定位是单体应用但要求前后端能分离开发、并行推进所以选了SpringBootVue这套经典组合SpringBoot省去了繁重的XML配置内嵌Tomcat一条命令就能启动后端服务。生态成熟做接口开发效率极高尤其适合这类以CRUD业务状态流转为主的管理系统。Vue渐进式框架对团队里刚接触前端的人非常友好。组件化开发让页面逻辑清晰配合Element UI这类组件库能很快搭出管理后台。MyBatisSQL由开发者自己掌控比起全自动ORM比如JPA更适合这种存在多表联查、自定义统计查询的场景。后面排查SQL性能问题也方便直接把日志打开就能看到实际执行的语句。MySQL免费的社区版足够满足这个量级的数据存储需求InnoDB引擎支持事务保证领养申请状态流转这类多步操作的数据一致性。有人可能会问为什么不用Redis做缓存我的回答是不是所有项目都需要缓存。动物信息表数据量最多也就几千条MySQL扛起来毫无压力引入Redis反而增加部署复杂度。技术是个工具箱要用对地方。2. 数据库设计与表结构拆解2.1 核心表设计与字段说明数据库设计是整个系统最见功底的部分表设计得好后面写接口就顺表设计拉胯写业务的时候全在跟数据和字段打架。我在设计时遵循了两条主原则单表职责单一多表冗余可控。核心表一共六张表名用途关键字段user用户表id, username, password, nickname, phone, role, avatar, status, create_timeanimal动物信息表id, name, species, breed, gender, age, health_status, description, cover_image, location, status, create_timeadoption领养申请表id, animal_id, user_id, real_name, phone, address, reason, experience, status, apply_time, handle_timerescue救助信息表id, user_id, animal_type, address, description, contact_name, contact_phone, status, create_timenotice公告表id, title, content, cover_image, publisher_id, create_timeadmin并入user用role区分—通过user.role字段区分0/1这里提一个我踩过坑的细节不要把管理员单独建一张表。早期版本我确实单独建了admin表后来发现绝大多数业务逻辑比如查询登录用户的信息都要先判断是普通用户还是管理员两张表联查会让接口变复杂。用role字段区分就行了这是典型的需求驱动设计。2.2 状态字段的设计哲学几乎所有业务表里都有status字段但它们的取值含义是完全独立的千万别设计成一套通用的枚举animal.status0-待审核1-展示中2-已领养3-已下架adoption.status0-待审核1-已通过2-已拒绝3-已取消rescue.status0-待处理1-处理中2-已完成这样设计的好处是每个业务域的状态流转在自己内部闭环写业务代码时逻辑非常清楚。比如领养申请的流转核心保障是申请通过后必须同步把对应动物的status从展示中改成已领养这两个操作要放在一个事务里否则就会出现动物明明已被领养却还在列表里展示的数据不一致问题。数据库字符集这块也提醒一句统一用utf8mb4不是utf8。utf8mb4是真正的四字节UTF-8编码能存emoji和一些特殊字符流浪动物救助这个场景里用户描述动物的时候经常用表情不用utf8mb4存进去就是乱码。3. 后端SpringBootMyBatis核心实现3.1 项目分层与接口设计后端代码我严格按三层架构组织Controller接口层只做参数接收和返回值包装→ Service业务层写核心逻辑→ Mapper数据层对应SQL操作。很多新手喜欢把业务逻辑写在Controller里几十行代码堆在一起当时觉得爽后面改需求时快烦死了。接口设计遵循RESTful风格几个关键的接口路径POST /api/auth/login 登录 GET /api/animal/list 动物分页列表支持关键词搜索/类型筛选 GET /api/animal/detail/{id} 动物详情 POST /api/adoption 提交领养申请 GET /api/adoption/my 我提交的领养申请 POST /api/animal 管理员新增动物 PUT /api/animal/{id} 管理员编辑动物 DELETE /api/animal/{id} 管理员删除动物 GET /api/rescue/list 救助信息列表管理员 POST /api/rescue 用户提交救助登记统一返回结构是我每次做项目都会先定好的基础设施所有接口返回ResultT对象包含code、message、data三个字段。前端拿到结果后不用做一堆判空处理直接看code是不是200就行省事。3.2 登录认证与权限控制这个系统我用了JWT做登录认证流程是登录成功后后端生成一个包含用户ID和角色的Token返回给前端前端存在localStorage里之后每次请求都在请求头带上Authorization: Bearer token。后端用一个**拦截器Interceptor**统一处理Token校验我习惯写一个AuthInterceptor在preHandle方法里解析Token并验证有效性然后把当前用户信息放到ThreadLocal里这样Service层任何时候想拿当前用户ID都能拿到不用在每个接口里重复传参。权限控制这块我加了一个很实用的设计用**自定义注解RequireRole**标记需要管理员权限的接口配合拦截器实现角色校验。代码结构大概是Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface RequireRole { String value() default admin; }在需要管理员权限的Controller方法上加上RequireRole(admin)拦截器扫描到这个注解就校验角色不满足直接返回403。这种方式比在Service代码里写if(!role.equals(admin))要优雅得多也更好维护。3.3 关键业务逻辑领养申请与状态流转领养申请是整个系统业务复杂度最高的模块我在Service层写了完整的流程控制。核心代码如下Transactional public void approveAdoption(Integer adoptionId) { AdoptionRequest request adoptionMapper.selectById(adoptionId); if (request null) { throw new BusinessException(领养申请不存在); } // 1. 更新申请状态 request.setStatus(2); // 已通过 adoptionMapper.updateById(request); // 2. 将对应动物状态改为已领养 Animal animal animalMapper.selectById(request.getAnimalId()); if (animal ! null) { animal.setStatus(2); // 已领养 animalMapper.updateById(animal); } // 3. 将其他待审核的申请自动标记为已取消 ListAdoptionRequest pendingList adoptionMapper.selectByAnimalIdAndStatus(request.getAnimalId(), 0); if (pendingList ! null !pendingList.isEmpty()) { for (AdoptionRequest pending : pendingList) { if (!pending.getId().equals(adoptionId)) { pending.setStatus(3); // 已取消 adoptionMapper.updateById(pending); } } } }这里有三层业务考量事务保证Transactional确保申请通过、动物状态更新、其他申请作废这三步操作要么全部成功要么全部回滚。如果少了第三步就会出现同一只动物同时被多个申请绑定的怪象。状态冲突处理一只动物被人领养后其他排队申请就不能继续处于待审核状态必须自动取消。拒绝时的恢复逻辑如果管理员拒绝了申请要把动物的状态从待审核恢复回去——因为动物还没被领养不能一直挂着。这些状态流转规则如果不提前想清楚测试阶段一定会冒出各种幽灵数据问题。3.4 MyBatis多表联查与XML编写MyBatis的SQL写在Mapper XML文件里我喜欢这种SQL掌控权在开发者手里的感觉。项目里用到的核心SQL场景主要是两个第一个是动物列表分页查询支持按种类猫/狗筛选和关键词搜索select idselectPage resultTypecom.example.pojo.Animal SELECT * FROM animal where if testspecies ! null and species ! AND species #{species} /if if testkeyword ! null and keyword ! AND (name LIKE CONCAT(%, #{keyword}, %) OR breed LIKE CONCAT(%, #{keyword}, %)) /if /where ORDER BY create_time DESC /select注意一下where标签的妙用如果所有条件都是空它不会生成WHERE关键字如果有条件满足它自动处理掉第一个AND避免写成WHERE AND species ...这种SQL语法错误。这是MyBatis动态SQL的基础操作但很多人初学时会疏忽。第二个是领养申请带动物信息的联查管理员的审核列表需要同时显示申请人信息和动物信息select idselectWithAnimal resultTypecom.example.pojo.vo.AdoptionVO SELECT a.*, u.nickname AS user_nickname, u.phone AS user_phone, an.name AS animal_name, an.species AS animal_species, an.breed AS animal_breed FROM adoption a LEFT JOIN user u ON a.user_id u.id LEFT JOIN animal an ON a.animal_id an.id ORDER BY a.apply_time DESC /selectLEFT JOIN而不是INNER JOIN的理由管理员要看的是所有申请记录即使某些数据比如用户已注销缺失申请记录本身仍应该展示。这个细节在高并发的联查场景下尤为重要。4. 前端Vue页面实现与交互4.1 前端项目结构与路由设计前端我用Vue 2 Vue Router Vuex Element UI Axios这一套标准配置。Vue 3虽然已经出来很久了但我个人觉得如果是学习或者快速交付Vue 2的生态组件最稳排查问题也容易搜到答案。项目目录结构src/ ├── api/ // 接口请求统一封装 │ ├── animal.js │ ├── adoption.js │ └── user.js ├── assets/ // 静态资源图片、样式 ├── components/ // 通用组件 ├── router/ // 路由配置 ├── store/ // Vuex状态管理 ├── views/ │ ├── home/ // 前台页面 │ │ ├── Home.vue │ │ ├── AnimalList.vue │ │ ├── AnimalDetail.vue │ │ ├── AdoptionForm.vue │ │ └── RescueForm.vue │ └── admin/ // 后台管理页面 │ ├── Dashboard.vue │ ├── AnimalManage.vue │ ├── AdoptionAudit.vue │ └── RescueManage.vue └── main.js路由设计上做了游客/普通用户/管理员三级的访问控制用Vue Router的beforeEach守卫实现router.beforeEach((to, from, next) { const token localStorage.getItem(token); const role localStorage.getItem(role); if (to.meta.requiresAdmin role ! admin) { next(/login); } else if (to.meta.requiresAuth !token) { next(/login); } else { next(); } });requiresAuth和requiresAdmin是路由配置里的meta字段在定义路由时声明好。前端权限控制只能保证界面不显示、路由不能跳真正的数据安全必须靠后端接口校验兜底——前端权限是体验优化后端权限才是安全底线。4.2 核心页面与组件实现细节动物卡片列表页是这个系统的门面我设计了一个瀑布流卡片布局每张卡片展示动物封面、名字、品种和领养状态。核心数据绑定逻辑template div classanimal-card clickgoDetail(item.id) el-image :srcitem.coverImage fitcover lazy / div classinfo h3{{ item.name }}/h3 p{{ item.species }} · {{ item.breed }}/p el-tag :typestatusMap[item.status].type {{ statusMap[item.status].text }} /el-tag /div /div /template script export default { data() { return { statusMap: { 0: { text: 待审核, type: warning }, 1: { text: 待领养, type: success }, 2: { text: 已领养, type: info }, 3: { text: 已下架, type: danger } } } } } /script这里有个实用性极强的细节列表页的数据变化状态映射要常驻在前端。后端返回的status永远只是一个数字如果前端每次使用都要判断一遍代码会又臭又长。把状态和文案、颜色统一映射管理是管理后台页面开发的通用实践。图片上传组件用的是Element UI的el-upload配合后端接口实现文件存储。后端保存图片的方式有很多种这个项目我用了最简单可靠的方案本地上传目录 静态资源映射。服务器上建一个/upload目录存放图片文件数据库只存访问路径。不用OSS、不用云存储原因还是那条够用就行。上传接口的核心配置Value(${file.upload-path}) private String uploadPath; PostMapping(/upload) public ResultString upload(RequestParam(file) MultipartFile file) { // 生成唯一文件名防止重名覆盖 String originalFilename file.getOriginalFilename(); String ext originalFilename.substring(originalFilename.lastIndexOf(.)); String filename System.currentTimeMillis() _ UUID.randomUUID().toString().substring(0, 8) ext; File dest new File(uploadPath / filename); file.transferTo(dest); return Result.success(/upload/ filename); }文件重名问题是每个做上传功能的人都会遇到的坑所以文件名里混入了时间戳和随机串目的就是让重名概率近乎为零。4.3 后台管理页面表格弹窗表单后台管理页面的套路基本一致一条表格展示列表数据一个弹窗承载新增/编辑表单一个删除确认框防止误操作。我以动物管理页为例说一下核心思路页面的关键逻辑进入页面时调用fetchList()拉取第一页数据分页组件变化时触发handlePageChange重新拉对应页的数据点击新增/编辑时弹窗表单校验通过后调用新增或更新接口操作成功后必须刷新列表让用户看到最新状态。这里有一个提升用户体验的小技巧新增和编辑共用同一个表单组件通过判断dialogType来区分是调createAnimal还是updateAnimal接口。减少了代码重复也方便表单校验逻辑的统一。5. 完整部署教程本地运行与服务器上线5.1 本地环境准备我默认你能跟着这套环境跑起来JDK 1.8、Maven 3.6、Node.js 12、MySQL 5.7、Navicat或任意数据库管理工具。版本不用完全一致但别差太多尤其是Node与Vue 2的兼容性。如果你是本机第一次跑这种项目建议把Maven镜像设置为国内仓库源否则第一次下载SpringBoot依赖会等到怀疑人生。Maven安装目录下的conf/settings.xml里修改镜像地址这个细节能省半小时等待时间。5.2 数据库初始化与后端启动第一步用Navicat创建一个新数据库名字随意比如animal_rescue字符集选utf8mb4排序规则选utf8mb4_general_ci。第二部将项目根目录下提供的animal_rescue.sql脚本文件执行一遍它会把建库建表语句和演示数据全部导入。SQL文件里我包含了十几个动物样品数据和几个测试用户账号方便你立即看到效果。第三步修改后端的配置文件application.yml里的数据库连接server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/animal_rescue?useUnicodetruecharacterEncodingutf8mb4serverTimezoneAsia/Shanghai username: root password: 你的数据库密码 driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.pojo两个容易踩的坑serverTimezoneAsia/Shanghai必须加否则MySQL 8.x默认时区跟本地时间差8小时数据创建时间全是错的。characterEncodingutf8mb4要跟数据库的字符集一致防止中文乱码。第四步在IDEA里打开后端项目等待Maven下载完依赖直接运行主启动类。看到Started Application in xxx seconds就表示后端启动成功了。5.3 前端启动与联调前端项目打开终端执行两条命令npm install npm run servenpm install需要等一会儿同样建议把npm源切到国内镜像否则下载Internet速度会让你怀疑人生。启动成功后终端会显示访问地址一般是http://localhost:8081。这里要注意后端8080端口前端8081端口两者不同。那前端怎么访问后端接口通过代理转发。在Vue项目的vue.config.js里配置开发环境代理module.exports { devServer: { port: 8081, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } };这样前端页面里请求/api/animal/list时开发服务器会自动把请求转发到后端的8080端口避免了前后端联调时最典型的跨域问题。注意生产环境部署时这个代理就不工作了需要靠Nginx来做反向代理。5.4 服务器部署上线本地跑通后发布到线上服务器是另一个常见需求。我把步骤整理清楚后端打包部署mvn clean package -DskipTests这条命令会生成一个target/animal-rescue-0.0.1-SNAPSHOT.jar。把jar包上传到服务器的指定目录比如/webapps然后启动nohup java -jar -Dfile.encodingutf-8 animal-rescue-0.0.1-SNAPSHOT.jar /webapps/log.log 21 nohup让进程在SSH断开后继续运行日志输出到log文件方便排查。如果你用systemd管理服务写一个服务单元文件会更专业。前端构建与Nginx配置npm run build构建产物在dist/目录把dist里的文件上传到服务器Nginx的web目录如/webapps/dist。Nginx配置核心server { listen 80; server_name 你的域名或IP; # 前端页面 location / { root /webapps/dist; index index.html; try_files $uri $uri/ /index.html; # 历史模式路由回退 } # 后端接口反向代理 location /api/ { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # 图片访问 location /upload/ { alias /webapps/upload/; } }这里有个关键配置try_files $uri $uri/ /index.html;。因为Vue Router如果用了history模式前端路由比如/animal/detail/1在刷新页面时Nginx会去磁盘找这个路径对应的文件找不到就会报404。加上这行配置后所有找不到的路径都会回退到index.html由前端路由接管。改完Nginx配置执行nginx -s reload整个系统就能通过域名访问了。6. 常见问题与排查技巧实录6.1 高频问题速查表把我被问得最多的问题整理成一个表格方便你留着备查问题现象可能原因排查思路前端请求接口报404代理未生效 / 后端接口路径写错先看Network里请求的完整URL确认是代理问题还是路径问题跨域请求被拦截后端未配置CORS / 前端代理配置错误开发环境优先用代理方案生产环境用Nginx中文乱码数据库字符集不是utf8mb4 / 连接参数遗漏确认库表字段字符集和JDBC URL参数都正确登录成功但请求返回401Token过期 / 请求头未携带检查前端Axios拦截器是否统一添加Authorization头图片上传成功但访问404静态资源映射没配置后端需要配置/upload/**的静态资源映射路径时间字段与实际差8小时JDBC连接未指定时区URL加serverTimezoneAsia/Shanghainpm install报错Error: EACCESNode权限问题macOS/Linux下用sudo npm install或修复npm全局目录权限6.2 我踩过最深的坑这里专门分享几个我在做这个项目时耗费最久才解决的实际问题第一个坑文件上传后保存的路径与访问路径不匹配我在本地开发时上传目录用的是C:/upload/数据库存的是/upload/xxx.jpg浏览器访问也正常。发布到Linux服务器后上传的文件存在了/upload/xxx.jpg但Nginx配置的alias写成了/webapps/upload/导致图片访问404。排查了半天才想起来Nginx的alias路径必须和实际文件系统路径完全一致。第二个坑前后端联调时中文参数在GET请求中乱码这个比较隐蔽。POST请求有JSON格式一般不会乱码但GET请求带中文关键词搜索时Tomcat默认的URI编码不是UTF-8。解决办法是在application.yml里把Tomcat的URI编码设置为UTF-8server: tomcat: uri-encoding: UTF-8第三个坑领养申请审核状态与动物状态不同步这是业务逻辑层面的坑测试时用两个管理员账号同时审核同一只动物的不同申请结果数据乱了。原因是最早版本没加事务控制后来补上了Transactional并在Service层增加了状态冲突检测逻辑问题才解决。这也印证了前面说的多步操作必须事务控制这是系统的可靠性底线。6.3 几个提升效率的实操心得接口测试优先用Postman/Apifox不要一上来就在前端页面里调。先把每个接口的边界情况测完登录失效、参数为空、传非法ID再去做前端联调能省一大半联调时间。后端日志打关键节点特别是这一句接收参数、校验结果、操作结果。排查问题时日志是你唯一的线索来源哪怕只加一句log.info(审核通过: adoptionId{}, animalId{}, id, animalId);都能让排查速度翻倍。用Git从小项目第一天就建立版本管理。我开始做这个系统时就直接初始化了Git仓库每次改版本都提交一次。有一次改前端样式把整个页面的布局改崩了来回撤销太麻烦直接回滚到上一个稳定提交点省了半小时。结尾再分享一点真实感受做完这个项目我最深的体会不是技术环节的哪个技巧很巧妙而是一个系统能否真正解决问题取决于你多懂业务。流浪动物救助这个场景最核心的不是技术实现而是信息流转的闭环——发现人提交信息、组织方审核跟进、领养人申请、最终完成领养这条链路上每一步都有真实的人在等待。当你看到动物信息页面上那张等待帮助的照片时你会意识到自己写的每一行代码背后都对应着一个具体的生命能否获得关注和机会。这也是我会推荐所有学习全栈开发的人尝试一次非典型业务场景不局限于商品交易、图书馆管理这类常见练手项目的原因。另选一个你身边真实存在的小众需求把它数字化你会在开发过程中遇到很多标准教程里不会出现的业务变体那些不知道怎么做才对的时刻恰恰是最快的成长时刻。最后这个项目里所有代码都是开源的前端构建脚本、后端Jar包、数据库初始化脚本、部署文档都打包在项目目录里了。如果你在学习过程中遇到任何跑不起来的问题最有效的方法是先看日志——前端看浏览器控制台后端看Tomcat输出绝大多数问题日志里都会直接告诉你原因。祝你能顺利跑起来也希望能在这个世界上因为你的代码多一点温暖被看见。