上个月帮某民间救助点整理领养登记信息桌上摊着一摞纸质申请表、三个互不通用的 Excel、十几个微信群。志愿者一边在群里发小猫视频一边在表格里手动改状态实际被领养的动物和表格上记的状态常常对不上。我当时就决定与其继续人工同步不如做一套前后端分离的流浪动物救助网站系统。技术栈很主流——SpringBoot承担后端接口Vue构建前端页面MyBatis负责数据库持久层MySQL存储所有业务数据。整个项目从建库到部署上线大约花了一周已经能支撑救助点的日常领养与捐赠登记。下面我把这套系统从需求、数据库、后端、前端、部署到排错完整拆一遍想拿它做全栈入门、交毕业设计、或者给本地救助站做信息化的朋友可以直接照着改。1. 救助站的真实痛点这套系统到底在解决什么问题1.1 三个让我决定必须做网站的事那天的救助站值班室给我看了三样东西。第一样是一沓纸质领养申请表上面不少电话号码已经看不清第二样是救助站自己的 Excel 台账里面祈祷着近两年的动物进出记录第三样是微信群里面同学在问那只橘猫到底有没有人领养。三个信息源互相打架想查一只动物的来龙去脉得翻遍三个地方。这其实是所有小型救助组织都会遇到的问题动物档案没有沉淀领养状态无法同步捐赠信息不透明。纸质表既不能实时查询也不能自动核对是否重复提交Excel 台账容易被人误改而且一旦换电脑就变成孤岛微信群消息很快被刷掉等着领养的小猫小狗在群里发一屏就没了下文。所以系统第一版的功能边界非常明确a) 把动物档案数字化照片、品种、年龄、疫苗、绝育情况都能随时查看b) 让领养申请走线上流程用户在页面提交申请志愿者在后台审核状态自动流转c) 捐赠记录可查可公示d) 公告和数据展示能公开访问。这套系统不解决救助站缺粮缺钱的根本问题但能把负责人从无休止的信息对账里解放出来。1.2 功能模块拆解前台展示 后台管理系统按使用角色分成三块游客、普通用户有登录账号、志愿者管理员。游客在首页看到动物列表可以按猫狗、按状态筛选点进详情看动物照片、健康描述和领养要求。公开的公告和捐赠汇总也在首页展示。普通用户登录后可以做三件事提交领养申请、查看自己申请的处理进度、登记自己的捐赠。志愿者管理员在后台维护动物档案、审核领养申请、登记捐赠物资、发布公告、管理志愿者账号。从这个拆解可以看出来整个系统真正的业务核心不是发布文章或轮播图而是动物状态和领养申请状态之间的联动。后面我给数据库做设计时主要精力也花在这两套状态的流转上。1.3 技术选型逻辑为什么是 SpringBoot Vue MyBatis MySQL不少朋友问过我这种规模的系统用 JSP 加 Servlet 也能写用若依那些后台脚手架更快为什么非要前后端分离我当时的考虑有三点。一是团队协作和后续扩展。救助站的信息化需求不会停在一版后面很可能要接小程序、要改页面前后端分离之后接口是稳定的前端怎么换都行。如果前后端代码写在同一个项目里每次前端调整都得重新打包整个应用。二是技术学习的性价比。对想练全栈的人来说这四样技术覆盖面足够SpringBoot 让你不用纠结容器配置Vue 带来组件化思维MyBatis 保留 SQL 的可控力MySQL 免费且资料遍地都是。对比之下若依这类脚手架虽然开箱即用但生成出来的代码冗余多、业务状态流转反而被封装得看不清学完不太容易真正理解项目架构。三是部署和维护成本可控。后端打一个 jar前端打一批静态文件Nginx 一接就行。下面是当时做的选型对比方案优点缺点JSP Servlet逻辑直白适合入门前后端耦合页面改版成本高Thymeleaf 服务端渲染部署简单复杂交互组件难维护SpringBoot Vue 前后端分离接口复用、分工清晰、组件化需要额外处理跨域和静态资源开源后台脚手架后台功能开箱即用代码冗余多业务状态改造麻烦2. 数据库设计动物状态字段是整个项目的地基2.1 五张核心表的字段设计数据库我建了五张表user、animal、adoption_application、donation、announcement。救助站的信息化不必做到电商系统那么复杂但字段要想清楚因为后面所有页面和接口都是围绕这几张表转的。user表除了常规的账号密码我加了role字段用 0 表示普通用户、1 表示志愿者、2 表示管理员。密码用 BCrypt 加密而不是明文存。注意role不要用字符串存admin这种后续判断和扩展都很别扭。animal表是所有功能的核心字段大概是这样字段类型说明namevarchar(50)动物名字speciestinyint0 猫 1 狗breedvarchar(50)品种gendertinyint0 公 1 母age_monthint年龄按月存vaccinatedtinyint是否已疫苗neuteredtinyint是否已绝育health_statusvarchar(255)健康描述statustinyint0 待领养 1 领养审核中 2 已领养 3 寄养中 4 已下架cover_imagevarchar(255)封面图 URLdescriptiontext详细介绍is_deletedtinyint软删除标记年龄按月存是因为救助站经常只记录大概几个月按年算会丢失精度。软删除字段is_deleted一定要加避免误删档案后救不回来。2.2 状态流转才是业务核心领养申请的并发控制很多写这类系统的人第一版设计是动物表有个 status 字段申请通过时就 UPDATE 一下结果上线后出现大问题用户在页面看到动物待领养点击申请提交后后端只 INSERT 了一条申请记录动物状态没有同步变掉。志愿者在后台看到申请通过了但动物在首页还挂着待领养又有人能继续申请。我设计的流转是这样用户在页面提交领养申请时后端在同一个事务里做两件事——把animal.status从 0 改成 1待领养 - 领养审核中同时插入一条adoption_application申请记录。管理员审核时如果通过把application.status改成 2同时把animal.status改成 2已领养如果拒绝把application.status改成 3同时把animal.status退回 0恢复待领养。这里有个关键细节状态更新不能裸 UPDATE。比如用户 A 和用户 B 同时申请同一只猫两个请求都先 SELECT 出 status0然后都执行 UPDATE 改成 1那就会变成两个人同时申请成功。我的做法是在 UPDATE 的 WHERE 条件里带上旧状态UPDATE animal SET status 1 WHERE id #{animalId} AND status 0这样数据库保证只有一行会被更新。Java 里判断rows 0就说明动物已经被人抢先申请了直接抛异常提示该动物已被其他用户申请。这本质上是一个简单乐观锁很值得在开发阶段就加进去。2.3 MyBatis 持久层的两个配置细节用 MyBatis 时容易踩两个坑。第一是驼峰映射数据库字段cover_image要映射到 Java 实体属性coverImage如果不开启映射代码里就得写一堆resultMap。在application.yml里加一行即可mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.adopt.entity configuration: map-underscore-to-camel-case: true第二是动态 SQL。动物列表页的筛选条件是变化的游客可能只选猫 待领养也可能加上品种搜索。这种多条件查询很适合 MyBatis 的if标签比在 Java 里拼 SQL 字符串干净得多select idselectAnimalPage resultTypecom.example.adopt.entity.Animal SELECT id, name, species, breed, gender, age_month, vaccinated, neutered, health_status, status, cover_image, description, create_time, update_time FROM animal WHERE is_deleted 0 if testspecies ! null AND species #{species} /if if teststatus ! null AND status #{status} /if ORDER BY update_time DESC /select这里我特意没有用 PageHelper 之类的分页插件而是自己写LIMIT和COUNT因为对学习阶段的人来说手写分页能更清楚理解查询 统计两个动作。项目里实际用了简单的 PageResult 封装后面要接插件也很容易。3. SpringBoot 后端接口要贴着业务动作设计3.1 包结构、分层与接口清单后端的包结构很常规controller负责接收请求和参数校验service负责业务逻辑和事务mapper只跟数据库打交道entity放实体dto放接收参数的类vo放返回给前端的类。Controller 里尽量不要写业务判断不然多个接口都要重复校验动物状态代码很快会散成一盘沙。核心接口我在设计阶段就列成清单页面开发时前后端对照着做方法路径说明权限GET/api/animals动物分页列表公开GET/api/animals/{id}动物详情公开POST/api/adoptions提交领养申请登录GET/api/adoptions/my我的领养申请登录GET/api/admin/applications后台申请列表管理员POST/api/admin/applications/{id}/review审核申请管理员POST/api/admin/animals新增动物管理员PUT/api/admin/animals/{id}/status变更动物状态管理员POST/api/donations登记捐赠登录POST/api/uploads图片上传管理员GET/api/announcements公告列表公开这里注意一点后端接口统一带/api前缀开发环境用 Vite 代理生产环境用 Nginx 反向代理这个 I 下面部署章节细说。3.2 领养申请提交背后的事务与状态校验领养申请提交是整条链路最容易写错的地方。很多新手会写先 SELECT 动物然后 INSERT 申请再 UPDATE 动物状态但如果三个操作没有事务保护中途一抛异常数据库就会留下已提交申请但动物没转状态的脏数据。我的做法是给 Service 方法加TransactionalService public class AdoptionService { Autowired private AnimalMapper animalMapper; Autowired private ApplicationMapper applicationMapper; Transactional(rollbackFor Exception.class) public Long submit(AdoptionDTO dto) { // 1. 查询动物是否可领养 Animal animal animalMapper.selectById(dto.getAnimalId()); if (animal null || animal.getStatus() ! 0) { throw new BusinessException(该动物当前不在待领养状态); } // 2. 乐观锁更新动物状态待领养 - 领养审核中 int rows animalMapper.updateStatus(dto.getAnimalId(), 0, 1); if (rows 0) { throw new BusinessException(申请失败该动物可能已被其他用户申请); } // 3. 插入申请记录 AdoptionApplication application new AdoptionApplication(); application.setAnimalId(dto.getAnimalId()); application.setUserId(dto.getUserId()); application.setRealName(dto.getRealName()); application.setPhone(dto.getPhone()); application.setAddress(dto.getAddress()); application.setHouseType(dto.getHouseType()); application.setReason(dto.getReason()); application.setStatus(1); applicationMapper.insert(application); return application.getId(); } }这段代码里最值得学习的是第二步的乐观锁写法。因为updateStatus的 SQL 里带了AND status 0所以两个并发请求只会有一个更新成功另一个rows为 0 被拒绝。业务逻辑虽然简单但考虑并发、考虑事务、考虑异常回滚这就是规范和随便写写的区别。3.3 统一返回体与全局异常处理前后端联调时最烦的就是后端报错信息不规范。返回 500 时前端拿到一堆 HTML没法直接给用户提示。所以我定义了一个统一返回体Data public class ResultT { private Integer code; private String message; private T data; public static T ResultT ok(T data) { ResultT r new Result(); r.setCode(200); r.setMessage(success); r.setData(data); return r; } public static T ResultT fail(String message) { ResultT r new Result(); r.setCode(500); r.setMessage(message); return r; } }配合全局异常处理器RestControllerAdvice把BusinessException统一转成Result.fail(message)。这样前端拦截器只需要判断code是不是 200错误提示直接用message字段联调效率高很多。3.4 图片上传与本地存储的坑救助站每天都要给新到的猫狗拍照图片上传是刚需。后端我提供了一个/api/uploads接口用 MultipartFile 接收文件保存到服务器本地目录然后返回可访问的 URL。上传目录放在配置里upload: path: /data/adopt/upload同时需要配置一个静态资源映射把/img/**的请求映射到上传目录Configuration public class WebMvcConfig implements WebMvcConfigurer { Value(${upload.path}) private String uploadPath; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/img/**) .addResourceLocations(file: uploadPath /); } }这里最容易踩的坑是开发时用 IDEA 的相对路径保存图片换一台机器或者重新打包运行路径就变了。生产环境一定要用绝对路径并且单独建目录、配好写入权限。图片大小限制我设在 5MB超过就提示压缩后再传。4. Vue 前端组件化拆解与后端对接要点4.1 路由、目录结构与两种角色的页面权限前端项目我用的是 Vue 2 Element UI目录结构不算复杂src/ api/ # 按模块封装的接口请求 utils/request.js # axios 实例与拦截器 router/index.js # 路由配置 views/home/ # 前台页面动物列表、详情、公告 views/admin/ # 后台管理页面动物管理、申请审核 components/ # 动物卡片等公共组件路由上区分了游客和管理员。前台页所有人可见后台页加meta.requiresAuth和meta.role在路由守卫里做跳转router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.meta.requiresAuth !token) { next(/login) } else if (to.meta.role to.meta.role ! currentUser().role) { next(/) } else { next() } })注意登录后把用户信息存进localStorage或vuex刷新页面才不会丢失登录态。我在第一版里只存了 token结果一刷新用户头像就没了后来才补了用户信息缓存。4.2 axios 封装拦截器、token 与 401 处理前后端分离的项目一定要把 axios 统一封装一次否则每个页面都要写一遍headers.Authorization还要处理各种错误码。我的request.js大概是这样的import axios from axios import { Message } from element-ui import router from ../router const request axios.create({ baseURL: /api, timeout: 10000 }) request.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer token } return config }) request.interceptors.response.use( response response.data, error { if (error.response error.response.status 401) { localStorage.removeItem(token) router.push(/login) } Message.error(error.response?.data?.message || 请求失败) return Promise.reject(error) } ) export default request这样做的好处是鉴权逻辑收敛在一个文件里后续新的 API 模块只需要引入request就自带 token。后端全局异常处理配上这个拦截器前后端对错误的约定就统一了。4.3 动物卡片组件与列表性能前台首页的动物列表我拆成了一个AnimalCard组件列表页只负责拉数据、循环渲染状态文案和数据格式封装在组件内部template div classanimal-card click$emit(detail) el-image :srcanimal.coverImage fitcover lazy / div classinfo h3{{ animal.name }}/h3 span classtag{{ statusText }}/span p{{ animal.breed }} · {{ animal.ageMonth }}个月/p /div /div /template script export default { name: AnimalCard, props: { animal: { type: Object, required: true } }, computed: { statusText() { const map { 0: 待领养, 1: 审核中, 2: 已找到家, 3: 寄养中, 4: 已下架 } return map[this.animal.status] } } } /script列表性能上注意两点一个是用el-image的lazy属性图片多的时候不会一次性全加载另一个是给v-for绑定稳定的animal.id作为 key千万不要用下标。4.4 表单校验比后端更早拦住无效申请领养申请表看似简单但志愿者最怕收到无效申请比如电话填 11 个 1、理由不到十个字、居住情况乱写。前端表单校验能在用户点击提交之前就把大部分低质量申请拦住。我用 Element UI 的rulesrules: { phone: [ { required: true, message: 请填写联系电话, trigger: blur }, { pattern: /^1[3-9]\d{9}$/, message: 手机号格式不正确, trigger: blur } ], reason: [ { required: true, message: 请填写申请理由, trigger: blur }, { min: 10, max: 500, message: 理由请在10到500字之间, trigger: blur } ] }提交按钮的点击事件里先validate再调接口同时用一个loading状态防止用户重复点击。前端校验不能替代后端校验但能显著减少无效申请还是很有必要。5. 完整部署流程从本地联调到云服务器上线5.1 环境版本对照与初始化数据库部署前先确认环境。我这次是JDK 8 Spring Boot 2.7 MySQL 8.0 Node 14 Vue 2这套组合兼容性最稳教程也最多。如果你用 JDK 17 和 Spring Boot 3需要注意包名从javax变成jakartaMyBatis 的 starter 也要换 3.x 版本。数据库初始化比较简单在 MySQL 里建一个库然后导入 SQL 脚本CREATE DATABASE adopt DEFAULT CHARACTER SET utf8mb4;utf8mb4很重要否则存表情符号或者生僻字可能报错。SQL 脚本里我放好了表结构和初始管理员账号导入后先SELECT * FROM user确认管理员存在。5.2 后端打包、前端构建与 Nginx 反向代理后端打包mvn clean package -DskipTests java -jar target/adopt-server.jar --spring.profiles.activeprod生产环境的配置我单独放在了application-prod.yml里面改成服务器数据库地址和上传路径。前端构建npm install npm run build构建完的dist目录上传到服务器然后配置 Nginx。这是整个部署里最需要小心的部分location /api/的proxy_pass结尾有没有斜杠行为完全不同server { listen 80; server_name your-domain.com; root /usr/share/nginx/html; index index.html; location / { 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; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }我特意没有给proxy_pass末尾加斜杠这样请求/api/animals会原样转发给后端http://127.0.0.1:8080/api/animals和后端的/api前缀对应。如果你看到proxy_pass写成http://127.0.0.1:8080/那/api前缀会被吞掉后端接口必须不带/api否则 404。5.3 systemd 守护进程与开机自启用java -jar直接跑后端关了终端进程就没了所以我加了一个 systemd 服务[Unit] Descriptionadopt-backend Afternetwork.target mysql.service [Service] Typesimple WorkingDirectory/opt/adopt ExecStart/usr/bin/java -jar /opt/adopt/adopt-server.jar --spring.profiles.activeprod Restartalways RestartSec5 Userdeploy [Install] WantedBymulti-user.target把文件放到/etc/systemd/system/adopt.service然后systemctl daemon-reload systemctl enable adopt systemctl start adopt这样后端崩溃会自动重启服务器重启也会自动拉起服务。日志用journalctl -u adopt -f查看排查问题很方便。6. 真实踩坑记录四个让我多花半晚上的问题6.1 前端列表一直转圈CORS、代理与预检请求第一次联调时前端页面打开很顺利但动物列表一直转圈。打开浏览器 Network 面板看到请求/api/animals被 CORS 拦截了。这是因为前端开发地址是localhost:5173后端是localhost:8080跨域了。解决办法有两个方向。开发环境最简单的是用 Vite 代理在vite.config.js里配置server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }这样浏览器永远请求同一个源代理再转发到后端不涉及跨域。生产环境用 Nginx 反向代理同样解决。如果确实想在后端开跨域要注意预检请求OPTIONS的处理最省事的是配一个全局 CORS 过滤器而不是每个 Controller 加CrossOrigin。6.2 上传图片刷新后 404路径映射的相对陷阱图片上传成功后页面里能立刻预览但一刷新就显示 404。排查链路是这样的上传接口返回了一个 URL/img/20240101-xxx.jpg页面直接用这个地址访问。开发环境里 IDEA 的运行目录下有这个文件能正常显示但后端静态资源映射没配好或者说映射的目录和实际保存目录不一致。最后我把上传路径改成配置项upload.path/data/adopt/upload并在WebMvcConfig里把/img/**映射到绝对路径问题才解决。图片这类静态资源永远不要依赖相对路径这是我在自己项目里踩过最深的坑之一。6.3 MySQL 8 连接失败驱动类名与连接参数后端启动报数据库连接失败第一次遇到的报错是Public Key Retrieval is not allowed。MySQL 8 默认认证插件和旧版不一样连接串里需要显式加上参数url: jdbc:mysql://localhost:3306/adopt?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue另外驱动的类名也要改成com.mysql.cj.jdbc.Driver老版本那种com.mysql.jdbc.Driver在 MySQL 8 下直接不行。这些参数我在官方文档里看得很清楚但实际部署时手一快就容易漏。6.4 前端路由 history 模式刷新 404try_files 兜底开发时用的 hash 模式没发现问题上线切成 history 模式后用户从首页点进详情正常但只要手动刷新/animal/3页面就 404。原因是 Nginx 找不到对应的真实文件animal/3默认返回 404。Nginx 配置里的try_files $uri $uri/ /index.html就是干这个的匹配不到静态文件时把请求交给前端入口index.html由前端路由接管。这个配置放在location /下是最容易被忽略但必须写的一行。整套系统从需求梳理到部署跑通我最大的体会是救助站的项目永远做不完功能永远可以往上加。但先把动物档案、领养状态、捐赠登记这三件事做扎实比加多少花哨功能都重要。如果后续要继续扩展可以考虑加领养回访提醒、志愿者排班表、捐赠明细导出报表。最后提个建议上线前一定要造一套完整的假数据把用户申请 - 管理员审核 - 动物状态变更这条链路走通再把页面细节慢慢打磨这样才是真正能用的系统。
上个月帮某民间救助点整理领养登记信息桌上摊着一摞纸质申请表、三个互不通用的 Excel、十几个微信群。志愿者一边在群里发小猫视频一边在表格里手动改状态实际被领养的动物和表格上记的状态常常对不上。我当时就决定与其继续人工同步不如做一套前后端分离的流浪动物救助网站系统。技术栈很主流——SpringBoot承担后端接口Vue构建前端页面MyBatis负责数据库持久层MySQL存储所有业务数据。整个项目从建库到部署上线大约花了一周已经能支撑救助点的日常领养与捐赠登记。下面我把这套系统从需求、数据库、后端、前端、部署到排错完整拆一遍想拿它做全栈入门、交毕业设计、或者给本地救助站做信息化的朋友可以直接照着改。1. 救助站的真实痛点这套系统到底在解决什么问题1.1 三个让我决定必须做网站的事那天的救助站值班室给我看了三样东西。第一样是一沓纸质领养申请表上面不少电话号码已经看不清第二样是救助站自己的 Excel 台账里面祈祷着近两年的动物进出记录第三样是微信群里面同学在问那只橘猫到底有没有人领养。三个信息源互相打架想查一只动物的来龙去脉得翻遍三个地方。这其实是所有小型救助组织都会遇到的问题动物档案没有沉淀领养状态无法同步捐赠信息不透明。纸质表既不能实时查询也不能自动核对是否重复提交Excel 台账容易被人误改而且一旦换电脑就变成孤岛微信群消息很快被刷掉等着领养的小猫小狗在群里发一屏就没了下文。所以系统第一版的功能边界非常明确a) 把动物档案数字化照片、品种、年龄、疫苗、绝育情况都能随时查看b) 让领养申请走线上流程用户在页面提交申请志愿者在后台审核状态自动流转c) 捐赠记录可查可公示d) 公告和数据展示能公开访问。这套系统不解决救助站缺粮缺钱的根本问题但能把负责人从无休止的信息对账里解放出来。1.2 功能模块拆解前台展示 后台管理系统按使用角色分成三块游客、普通用户有登录账号、志愿者管理员。游客在首页看到动物列表可以按猫狗、按状态筛选点进详情看动物照片、健康描述和领养要求。公开的公告和捐赠汇总也在首页展示。普通用户登录后可以做三件事提交领养申请、查看自己申请的处理进度、登记自己的捐赠。志愿者管理员在后台维护动物档案、审核领养申请、登记捐赠物资、发布公告、管理志愿者账号。从这个拆解可以看出来整个系统真正的业务核心不是发布文章或轮播图而是动物状态和领养申请状态之间的联动。后面我给数据库做设计时主要精力也花在这两套状态的流转上。1.3 技术选型逻辑为什么是 SpringBoot Vue MyBatis MySQL不少朋友问过我这种规模的系统用 JSP 加 Servlet 也能写用若依那些后台脚手架更快为什么非要前后端分离我当时的考虑有三点。一是团队协作和后续扩展。救助站的信息化需求不会停在一版后面很可能要接小程序、要改页面前后端分离之后接口是稳定的前端怎么换都行。如果前后端代码写在同一个项目里每次前端调整都得重新打包整个应用。二是技术学习的性价比。对想练全栈的人来说这四样技术覆盖面足够SpringBoot 让你不用纠结容器配置Vue 带来组件化思维MyBatis 保留 SQL 的可控力MySQL 免费且资料遍地都是。对比之下若依这类脚手架虽然开箱即用但生成出来的代码冗余多、业务状态流转反而被封装得看不清学完不太容易真正理解项目架构。三是部署和维护成本可控。后端打一个 jar前端打一批静态文件Nginx 一接就行。下面是当时做的选型对比方案优点缺点JSP Servlet逻辑直白适合入门前后端耦合页面改版成本高Thymeleaf 服务端渲染部署简单复杂交互组件难维护SpringBoot Vue 前后端分离接口复用、分工清晰、组件化需要额外处理跨域和静态资源开源后台脚手架后台功能开箱即用代码冗余多业务状态改造麻烦2. 数据库设计动物状态字段是整个项目的地基2.1 五张核心表的字段设计数据库我建了五张表user、animal、adoption_application、donation、announcement。救助站的信息化不必做到电商系统那么复杂但字段要想清楚因为后面所有页面和接口都是围绕这几张表转的。user表除了常规的账号密码我加了role字段用 0 表示普通用户、1 表示志愿者、2 表示管理员。密码用 BCrypt 加密而不是明文存。注意role不要用字符串存admin这种后续判断和扩展都很别扭。animal表是所有功能的核心字段大概是这样字段类型说明namevarchar(50)动物名字speciestinyint0 猫 1 狗breedvarchar(50)品种gendertinyint0 公 1 母age_monthint年龄按月存vaccinatedtinyint是否已疫苗neuteredtinyint是否已绝育health_statusvarchar(255)健康描述statustinyint0 待领养 1 领养审核中 2 已领养 3 寄养中 4 已下架cover_imagevarchar(255)封面图 URLdescriptiontext详细介绍is_deletedtinyint软删除标记年龄按月存是因为救助站经常只记录大概几个月按年算会丢失精度。软删除字段is_deleted一定要加避免误删档案后救不回来。2.2 状态流转才是业务核心领养申请的并发控制很多写这类系统的人第一版设计是动物表有个 status 字段申请通过时就 UPDATE 一下结果上线后出现大问题用户在页面看到动物待领养点击申请提交后后端只 INSERT 了一条申请记录动物状态没有同步变掉。志愿者在后台看到申请通过了但动物在首页还挂着待领养又有人能继续申请。我设计的流转是这样用户在页面提交领养申请时后端在同一个事务里做两件事——把animal.status从 0 改成 1待领养 - 领养审核中同时插入一条adoption_application申请记录。管理员审核时如果通过把application.status改成 2同时把animal.status改成 2已领养如果拒绝把application.status改成 3同时把animal.status退回 0恢复待领养。这里有个关键细节状态更新不能裸 UPDATE。比如用户 A 和用户 B 同时申请同一只猫两个请求都先 SELECT 出 status0然后都执行 UPDATE 改成 1那就会变成两个人同时申请成功。我的做法是在 UPDATE 的 WHERE 条件里带上旧状态UPDATE animal SET status 1 WHERE id #{animalId} AND status 0这样数据库保证只有一行会被更新。Java 里判断rows 0就说明动物已经被人抢先申请了直接抛异常提示该动物已被其他用户申请。这本质上是一个简单乐观锁很值得在开发阶段就加进去。2.3 MyBatis 持久层的两个配置细节用 MyBatis 时容易踩两个坑。第一是驼峰映射数据库字段cover_image要映射到 Java 实体属性coverImage如果不开启映射代码里就得写一堆resultMap。在application.yml里加一行即可mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.adopt.entity configuration: map-underscore-to-camel-case: true第二是动态 SQL。动物列表页的筛选条件是变化的游客可能只选猫 待领养也可能加上品种搜索。这种多条件查询很适合 MyBatis 的if标签比在 Java 里拼 SQL 字符串干净得多select idselectAnimalPage resultTypecom.example.adopt.entity.Animal SELECT id, name, species, breed, gender, age_month, vaccinated, neutered, health_status, status, cover_image, description, create_time, update_time FROM animal WHERE is_deleted 0 if testspecies ! null AND species #{species} /if if teststatus ! null AND status #{status} /if ORDER BY update_time DESC /select这里我特意没有用 PageHelper 之类的分页插件而是自己写LIMIT和COUNT因为对学习阶段的人来说手写分页能更清楚理解查询 统计两个动作。项目里实际用了简单的 PageResult 封装后面要接插件也很容易。3. SpringBoot 后端接口要贴着业务动作设计3.1 包结构、分层与接口清单后端的包结构很常规controller负责接收请求和参数校验service负责业务逻辑和事务mapper只跟数据库打交道entity放实体dto放接收参数的类vo放返回给前端的类。Controller 里尽量不要写业务判断不然多个接口都要重复校验动物状态代码很快会散成一盘沙。核心接口我在设计阶段就列成清单页面开发时前后端对照着做方法路径说明权限GET/api/animals动物分页列表公开GET/api/animals/{id}动物详情公开POST/api/adoptions提交领养申请登录GET/api/adoptions/my我的领养申请登录GET/api/admin/applications后台申请列表管理员POST/api/admin/applications/{id}/review审核申请管理员POST/api/admin/animals新增动物管理员PUT/api/admin/animals/{id}/status变更动物状态管理员POST/api/donations登记捐赠登录POST/api/uploads图片上传管理员GET/api/announcements公告列表公开这里注意一点后端接口统一带/api前缀开发环境用 Vite 代理生产环境用 Nginx 反向代理这个 I 下面部署章节细说。3.2 领养申请提交背后的事务与状态校验领养申请提交是整条链路最容易写错的地方。很多新手会写先 SELECT 动物然后 INSERT 申请再 UPDATE 动物状态但如果三个操作没有事务保护中途一抛异常数据库就会留下已提交申请但动物没转状态的脏数据。我的做法是给 Service 方法加TransactionalService public class AdoptionService { Autowired private AnimalMapper animalMapper; Autowired private ApplicationMapper applicationMapper; Transactional(rollbackFor Exception.class) public Long submit(AdoptionDTO dto) { // 1. 查询动物是否可领养 Animal animal animalMapper.selectById(dto.getAnimalId()); if (animal null || animal.getStatus() ! 0) { throw new BusinessException(该动物当前不在待领养状态); } // 2. 乐观锁更新动物状态待领养 - 领养审核中 int rows animalMapper.updateStatus(dto.getAnimalId(), 0, 1); if (rows 0) { throw new BusinessException(申请失败该动物可能已被其他用户申请); } // 3. 插入申请记录 AdoptionApplication application new AdoptionApplication(); application.setAnimalId(dto.getAnimalId()); application.setUserId(dto.getUserId()); application.setRealName(dto.getRealName()); application.setPhone(dto.getPhone()); application.setAddress(dto.getAddress()); application.setHouseType(dto.getHouseType()); application.setReason(dto.getReason()); application.setStatus(1); applicationMapper.insert(application); return application.getId(); } }这段代码里最值得学习的是第二步的乐观锁写法。因为updateStatus的 SQL 里带了AND status 0所以两个并发请求只会有一个更新成功另一个rows为 0 被拒绝。业务逻辑虽然简单但考虑并发、考虑事务、考虑异常回滚这就是规范和随便写写的区别。3.3 统一返回体与全局异常处理前后端联调时最烦的就是后端报错信息不规范。返回 500 时前端拿到一堆 HTML没法直接给用户提示。所以我定义了一个统一返回体Data public class ResultT { private Integer code; private String message; private T data; public static T ResultT ok(T data) { ResultT r new Result(); r.setCode(200); r.setMessage(success); r.setData(data); return r; } public static T ResultT fail(String message) { ResultT r new Result(); r.setCode(500); r.setMessage(message); return r; } }配合全局异常处理器RestControllerAdvice把BusinessException统一转成Result.fail(message)。这样前端拦截器只需要判断code是不是 200错误提示直接用message字段联调效率高很多。3.4 图片上传与本地存储的坑救助站每天都要给新到的猫狗拍照图片上传是刚需。后端我提供了一个/api/uploads接口用 MultipartFile 接收文件保存到服务器本地目录然后返回可访问的 URL。上传目录放在配置里upload: path: /data/adopt/upload同时需要配置一个静态资源映射把/img/**的请求映射到上传目录Configuration public class WebMvcConfig implements WebMvcConfigurer { Value(${upload.path}) private String uploadPath; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/img/**) .addResourceLocations(file: uploadPath /); } }这里最容易踩的坑是开发时用 IDEA 的相对路径保存图片换一台机器或者重新打包运行路径就变了。生产环境一定要用绝对路径并且单独建目录、配好写入权限。图片大小限制我设在 5MB超过就提示压缩后再传。4. Vue 前端组件化拆解与后端对接要点4.1 路由、目录结构与两种角色的页面权限前端项目我用的是 Vue 2 Element UI目录结构不算复杂src/ api/ # 按模块封装的接口请求 utils/request.js # axios 实例与拦截器 router/index.js # 路由配置 views/home/ # 前台页面动物列表、详情、公告 views/admin/ # 后台管理页面动物管理、申请审核 components/ # 动物卡片等公共组件路由上区分了游客和管理员。前台页所有人可见后台页加meta.requiresAuth和meta.role在路由守卫里做跳转router.beforeEach((to, from, next) { const token localStorage.getItem(token) if (to.meta.requiresAuth !token) { next(/login) } else if (to.meta.role to.meta.role ! currentUser().role) { next(/) } else { next() } })注意登录后把用户信息存进localStorage或vuex刷新页面才不会丢失登录态。我在第一版里只存了 token结果一刷新用户头像就没了后来才补了用户信息缓存。4.2 axios 封装拦截器、token 与 401 处理前后端分离的项目一定要把 axios 统一封装一次否则每个页面都要写一遍headers.Authorization还要处理各种错误码。我的request.js大概是这样的import axios from axios import { Message } from element-ui import router from ../router const request axios.create({ baseURL: /api, timeout: 10000 }) request.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer token } return config }) request.interceptors.response.use( response response.data, error { if (error.response error.response.status 401) { localStorage.removeItem(token) router.push(/login) } Message.error(error.response?.data?.message || 请求失败) return Promise.reject(error) } ) export default request这样做的好处是鉴权逻辑收敛在一个文件里后续新的 API 模块只需要引入request就自带 token。后端全局异常处理配上这个拦截器前后端对错误的约定就统一了。4.3 动物卡片组件与列表性能前台首页的动物列表我拆成了一个AnimalCard组件列表页只负责拉数据、循环渲染状态文案和数据格式封装在组件内部template div classanimal-card click$emit(detail) el-image :srcanimal.coverImage fitcover lazy / div classinfo h3{{ animal.name }}/h3 span classtag{{ statusText }}/span p{{ animal.breed }} · {{ animal.ageMonth }}个月/p /div /div /template script export default { name: AnimalCard, props: { animal: { type: Object, required: true } }, computed: { statusText() { const map { 0: 待领养, 1: 审核中, 2: 已找到家, 3: 寄养中, 4: 已下架 } return map[this.animal.status] } } } /script列表性能上注意两点一个是用el-image的lazy属性图片多的时候不会一次性全加载另一个是给v-for绑定稳定的animal.id作为 key千万不要用下标。4.4 表单校验比后端更早拦住无效申请领养申请表看似简单但志愿者最怕收到无效申请比如电话填 11 个 1、理由不到十个字、居住情况乱写。前端表单校验能在用户点击提交之前就把大部分低质量申请拦住。我用 Element UI 的rulesrules: { phone: [ { required: true, message: 请填写联系电话, trigger: blur }, { pattern: /^1[3-9]\d{9}$/, message: 手机号格式不正确, trigger: blur } ], reason: [ { required: true, message: 请填写申请理由, trigger: blur }, { min: 10, max: 500, message: 理由请在10到500字之间, trigger: blur } ] }提交按钮的点击事件里先validate再调接口同时用一个loading状态防止用户重复点击。前端校验不能替代后端校验但能显著减少无效申请还是很有必要。5. 完整部署流程从本地联调到云服务器上线5.1 环境版本对照与初始化数据库部署前先确认环境。我这次是JDK 8 Spring Boot 2.7 MySQL 8.0 Node 14 Vue 2这套组合兼容性最稳教程也最多。如果你用 JDK 17 和 Spring Boot 3需要注意包名从javax变成jakartaMyBatis 的 starter 也要换 3.x 版本。数据库初始化比较简单在 MySQL 里建一个库然后导入 SQL 脚本CREATE DATABASE adopt DEFAULT CHARACTER SET utf8mb4;utf8mb4很重要否则存表情符号或者生僻字可能报错。SQL 脚本里我放好了表结构和初始管理员账号导入后先SELECT * FROM user确认管理员存在。5.2 后端打包、前端构建与 Nginx 反向代理后端打包mvn clean package -DskipTests java -jar target/adopt-server.jar --spring.profiles.activeprod生产环境的配置我单独放在了application-prod.yml里面改成服务器数据库地址和上传路径。前端构建npm install npm run build构建完的dist目录上传到服务器然后配置 Nginx。这是整个部署里最需要小心的部分location /api/的proxy_pass结尾有没有斜杠行为完全不同server { listen 80; server_name your-domain.com; root /usr/share/nginx/html; index index.html; location / { 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; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }我特意没有给proxy_pass末尾加斜杠这样请求/api/animals会原样转发给后端http://127.0.0.1:8080/api/animals和后端的/api前缀对应。如果你看到proxy_pass写成http://127.0.0.1:8080/那/api前缀会被吞掉后端接口必须不带/api否则 404。5.3 systemd 守护进程与开机自启用java -jar直接跑后端关了终端进程就没了所以我加了一个 systemd 服务[Unit] Descriptionadopt-backend Afternetwork.target mysql.service [Service] Typesimple WorkingDirectory/opt/adopt ExecStart/usr/bin/java -jar /opt/adopt/adopt-server.jar --spring.profiles.activeprod Restartalways RestartSec5 Userdeploy [Install] WantedBymulti-user.target把文件放到/etc/systemd/system/adopt.service然后systemctl daemon-reload systemctl enable adopt systemctl start adopt这样后端崩溃会自动重启服务器重启也会自动拉起服务。日志用journalctl -u adopt -f查看排查问题很方便。6. 真实踩坑记录四个让我多花半晚上的问题6.1 前端列表一直转圈CORS、代理与预检请求第一次联调时前端页面打开很顺利但动物列表一直转圈。打开浏览器 Network 面板看到请求/api/animals被 CORS 拦截了。这是因为前端开发地址是localhost:5173后端是localhost:8080跨域了。解决办法有两个方向。开发环境最简单的是用 Vite 代理在vite.config.js里配置server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }这样浏览器永远请求同一个源代理再转发到后端不涉及跨域。生产环境用 Nginx 反向代理同样解决。如果确实想在后端开跨域要注意预检请求OPTIONS的处理最省事的是配一个全局 CORS 过滤器而不是每个 Controller 加CrossOrigin。6.2 上传图片刷新后 404路径映射的相对陷阱图片上传成功后页面里能立刻预览但一刷新就显示 404。排查链路是这样的上传接口返回了一个 URL/img/20240101-xxx.jpg页面直接用这个地址访问。开发环境里 IDEA 的运行目录下有这个文件能正常显示但后端静态资源映射没配好或者说映射的目录和实际保存目录不一致。最后我把上传路径改成配置项upload.path/data/adopt/upload并在WebMvcConfig里把/img/**映射到绝对路径问题才解决。图片这类静态资源永远不要依赖相对路径这是我在自己项目里踩过最深的坑之一。6.3 MySQL 8 连接失败驱动类名与连接参数后端启动报数据库连接失败第一次遇到的报错是Public Key Retrieval is not allowed。MySQL 8 默认认证插件和旧版不一样连接串里需要显式加上参数url: jdbc:mysql://localhost:3306/adopt?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue另外驱动的类名也要改成com.mysql.cj.jdbc.Driver老版本那种com.mysql.jdbc.Driver在 MySQL 8 下直接不行。这些参数我在官方文档里看得很清楚但实际部署时手一快就容易漏。6.4 前端路由 history 模式刷新 404try_files 兜底开发时用的 hash 模式没发现问题上线切成 history 模式后用户从首页点进详情正常但只要手动刷新/animal/3页面就 404。原因是 Nginx 找不到对应的真实文件animal/3默认返回 404。Nginx 配置里的try_files $uri $uri/ /index.html就是干这个的匹配不到静态文件时把请求交给前端入口index.html由前端路由接管。这个配置放在location /下是最容易被忽略但必须写的一行。整套系统从需求梳理到部署跑通我最大的体会是救助站的项目永远做不完功能永远可以往上加。但先把动物档案、领养状态、捐赠登记这三件事做扎实比加多少花哨功能都重要。如果后续要继续扩展可以考虑加领养回访提醒、志愿者排班表、捐赠明细导出报表。最后提个建议上线前一定要造一套完整的假数据把用户申请 - 管理员审核 - 动物状态变更这条链路走通再把页面细节慢慢打磨这样才是真正能用的系统。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
