React + Spring 全栈实战：宠物领养匹配系统与 TTS 语音播报-北京尧图网络

简介PetMatch 是一套面向全栈开发学习者的宠物配对应用实战项目采用 React 前端与 Spring Boot 后端组合适合希望打通前后端技能、积累完整项目经验的开发者。项目围绕组件化 UI、状态与属性管理、React Router 路由以及 Spring Boot 自动配置、RESTful API、JPA 与 Hibernate 数据持久化、Spring Security 安全控制等知识点展开帮助读者理解现代 Web 应用从交互到数据处理的完整链路。资源包共 69 个文件约 2.72MB以 js、java、css 源码为主辅以 json 配置、html 页面、properties 配置及图片素材并包含 Maven 构建脚本与依赖 jar目录结构清晰便于按前端、后端、构建配置分模块研读。目前已有 111 人学习下载。对于想系统掌握 React 与 Spring 全栈协作、参考赛题级项目组织方式的读者这份代码具备较高的对照与复用价值。1. 从零搭一个宠物领养匹配系统React 前端 Spring 后端的 TTS Capstone 到底在做什么宠物领养这件事线下跑过的人都知道痛点在哪信息散落在各个群里、照片模糊、性格描述全靠志愿者手打领养人翻半天也找不到真正匹配的那只。所谓 petmatch本质就是把这套「人找宠、宠找人」的匹配逻辑做成一个可运行的全栈系统而 TTS Capstone 指的是一个完整的毕业设计级交付物——不是玩具 Demo而是前端能跑、后端能查、数据能落库、语音能播报的闭环。技术栈选 React Spring是这类项目里最常见也最稳的组合React 负责交互和状态Spring 负责业务和持久化两边通过 REST 接口解耦。这篇文章面向的是要独立完成一个全栈 Capstone 的开发者或者想拿一个真实场景练手 React 与 Spring 联调的人。我会把选型理由、最小可运行路径、参数配置和踩过的坑按顺序讲清楚你照着能复现也能判断这个方向值不值得投入。2. 技术选型与架构拆解为什么是 React 配 Spring而不是别的组合2.1 前端为什么锁定 React 而不是模板引擎宠物领养匹配的界面有一个绕不开的特征列表要筛选、卡片要联动、详情要弹层、收藏状态要即时反馈。如果用服务端模板渲染每次筛选都得整页刷新体验直接掉档。React 的组件化和状态管理正好吃这类场景——一个 PetCard 组件复用几十次筛选条件放在父组件的 state 里子组件只负责渲染数据流是单向的排查问题时不用满世界找谁改了 DOM。另一个现实原因是生态。做 Capstone 通常时间紧React 周边有现成的路由、表单、请求库不用自己造轮子。我一般会选 React 18 加函数组件加 Hooks不碰 class 组件因为 Hooks 把生命周期逻辑收进函数体配合 useEffect 处理请求副作用代码量比 class 少三分之一。2.2 后端为什么用 Spring Boot 而不是 Node 或 Python后端要处理的是领养申请的状态流转、宠物信息的增删改查、匹配算法的计算这些都需要强类型和事务保证。Spring Boot 的依赖注入和 JPA 让数据库操作变成声明式一个 Repository 接口就能完成大部分查询省掉手写 SQL 的重复劳动。更重要的是事务领养申请提交时要同时写申请记录、更新宠物状态、发通知这三步必须原子Spring 的 Transactional 一行注解就能兜住换成脚本语言得自己写补偿逻辑。选 Java 还有一个隐性好处Capstone 答辩时评审对 Spring 的工程规范认可度高分层清晰、异常处理统一代码看起来「像那么回事」。2.3 前后端分离的接口契约怎么定分离架构最容易翻车的地方是接口对不上。我的做法是先定契约再写代码用一张表把资源、方法、路径、请求体、响应体列清楚前后端各自照着实现。资源方法路径请求体关键字段响应关键字段宠物列表GET/api/petsspecies, size, pageid, name, breed, photoUrl宠物详情GET/api/pets/{id}无全字段领养状态提交申请POST/api/adoptionspetId, applicantName, contactapplicationId, status匹配推荐GET/api/matchpreferences排序后的宠物列表契约定完前端用 mock 数据先把界面跑通后端用 Postman 先把接口调通最后联调时基本只剩字段名拼写这种小问题。这个顺序能省掉大量「前端等后端、后端等前端」的扯皮时间。2.4 最小可运行骨架的搭建步骤先建后端。用 Spring Initializr 生成项目依赖勾选 Spring Web、Spring Data JPA、H2 DatabaseCapstone 阶段用内存库足够省去装 MySQL 的麻烦。# 生成后端骨架groupId 和 artifactId 按自己项目填 curl https://start.spring.io/starter.zip \ -d dependenciesweb,data-jpa,h2 \ -d typemaven-project \ -d javaVersion17 \ -o petmatch-backend.zip unzip petmatch-backend.zip -d petmatch-backend这段命令从官方脚手架拉一个带 Web、JPA、H2 的 Maven 项目。javaVersion 选 17 是因为 Spring Boot 3.x 最低要求 17别用 8否则启动直接报错。解压后进目录跑./mvnw spring-boot:run看到 Tomcat 在 8080 启动就算通了。再建前端。用 Vite 而不是 Create React App因为 Vite 冷启动快改代码热更新几乎无感。# 用 Vite 创建 React 项目 npm create vitelatest petmatch-frontend -- --template react cd petmatch-frontend npm install npm install axios react-router-domaxios 负责请求react-router-dom 负责页面跳转。装完跑npm run dev默认在 5173 端口。前后端端口不同联调时会遇到跨域这个坑在第 5 章细说。3. 后端核心实现实体建模、匹配逻辑与接口分层3.1 宠物与领养申请的实体设计实体设计决定了后面所有查询的难易。宠物表要存品种、体型、年龄、性格标签、照片地址、领养状态申请表要存申请人信息、目标宠物、申请时间、审批状态。两者是一对多一只宠物可以收到多份申请但同一时间只能被一个人领养成功。Entity Table(name pet) public class Pet { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; private String name; private String species; // 猫、狗、其他 private String breed; // 品种 private String size; // SMALL / MEDIUM / LARGE private Integer ageMonths; private String temperament; // 性格标签逗号分隔 private String photoUrl; private String status; // AVAILABLE / PENDING / ADOPTED // getter 和 setter 省略实际项目用 Lombok 的 Data 更省事 }status 字段是整个业务的核心状态机AVAILABLE 表示可领养PENDING 表示有人提交了申请正在审核ADOPTED 表示已被领养。任何更新操作都要先校验当前状态否则会出现两个人同时领养同一只宠物的并发问题。3.2 匹配算法的实现与权重参数匹配逻辑不需要机器学习用加权打分就够 Capstone 用而且可解释性强答辩时能讲清楚每一分怎么来的。核心思路是用户填偏好系统对每只可领养的宠物算一个匹配分按分排序返回。public double calculateMatchScore(Pet pet, MatchPreference pref) { double score 0.0; // 物种匹配权重最高不匹配直接大幅降分 if (pet.getSpecies().equals(pref.getSpecies())) { score 40; } else { score - 20; } // 体型匹配权重 25 if (pet.getSize().equals(pref.getSize())) { score 25; } // 年龄接近度越接近偏好年龄分越高权重 20 int ageDiff Math.abs(pet.getAgeMonths() - pref.getAgeMonths()); score Math.max(0, 20 - ageDiff * 0.5); // 性格标签命中每命中一个加 5 分上限 15 long hitCount Arrays.stream(pref.getTemperaments().split(,)) .filter(t - pet.getTemperament().contains(t)) .count(); score Math.min(15, hitCount * 5); return score; }权重不是拍脑袋定的。物种是领养决策里最硬的约束所以给 40 分且不匹配时倒扣体型关系到居住条件给 25年龄是软偏好用距离衰减性格是加分项封顶 15 防止标签多的宠物刷分。这套参数我调过几轮把物种权重从 30 提到 40 后推荐结果里跨物种的离谱推荐明显减少。你可以按自己数据分布改但记住一条硬约束用大权重加倒扣软偏好用衰减加分。3.3 Service 层的事务边界与状态校验领养申请提交是唯一需要事务的方法因为它要同时做三件事写申请记录、把宠物状态改成 PENDING、检查是否已有 PENDING 申请。Service public class AdoptionService { Transactional public AdoptionApplication submit(Long petId, AdoptionRequest req) { Pet pet petRepository.findById(petId) .orElseThrow(() - new RuntimeException(宠物不存在)); // 状态校验只有 AVAILABLE 才能被申请 if (!AVAILABLE.equals(pet.getStatus())) { throw new IllegalStateException(该宠物当前不可申请); } pet.setStatus(PENDING); petRepository.save(pet); AdoptionApplication app new AdoptionApplication(); app.setPetId(petId); app.setApplicantName(req.getApplicantName()); app.setContact(req.getContact()); app.setStatus(SUBMITTED); app.setCreatedAt(LocalDateTime.now()); return applicationRepository.save(app); } }Transactional 保证这三步要么全成功要么全回滚。状态校验放在最前面是因为并发场景下两个请求可能同时读到 AVAILABLE加锁或乐观锁能进一步兜底但 Capstone 阶段先做状态校验已经能挡住大部分误操作。注意异常类型业务异常用 IllegalStateException资源不存在用 RuntimeException前端根据 HTTP 状态码区分处理。3.4 Controller 层的接口暴露与统一响应Controller 只做参数接收和响应包装不写业务逻辑。统一响应格式能让前端处理更省心。RestController RequestMapping(/api) public class PetController { GetMapping(/pets) public ResponseEntityMapString, Object list( RequestParam(required false) String species, RequestParam(defaultValue 0) int page) { ListPet pets petService.findByFilter(species, page); MapString, Object body new HashMap(); body.put(code, 0); body.put(data, pets); body.put(total, pets.size()); return ResponseEntity.ok(body); } }响应统一用 code、data、total 三个字段前端拦截器里判断 code 是否为 0 就能决定走成功还是失败分支。分页参数用 page 加固定 size比传 offset 更不容易算错。4. 前端实现从列表渲染到语音播报的完整链路4.1 用 axios 封装请求层与错误拦截前端不要在每个组件里裸写 axios抽一个 request 模块统一处理 baseURL、超时和错误。import axios from axios; const request axios.create({ baseURL: http://localhost:8080/api, timeout: 8000, }); request.interceptors.response.use( (res) { if (res.data.code ! 0) { // 业务错误统一抛出组件里 catch 处理 return Promise.reject(new Error(res.data.message || 请求失败)); } return res.data.data; }, (err) { // 网络层错误比如后端没启动 console.error(网络异常, err.message); return Promise.reject(err); } ); export default request;baseURL 指向后端 8080timeout 设 8 秒超过就断避免用户干等。拦截器把业务错误和网络错误分开处理组件里只需要 try/catch 一次。这个封装在联调阶段能帮你快速定位是接口挂了还是逻辑错了。4.2 宠物列表的筛选与分页渲染列表页是用户停留最久的地方筛选要即时分页要顺滑。function PetList() { const [pets, setPets] useState([]); const [species, setSpecies] useState(); const [page, setPage] useState(0); useEffect(() { request.get(/pets, { params: { species, page } }) .then(setPets) .catch((e) alert(e.message)); }, [species, page]); // 筛选或翻页时重新请求 return ( div classNamepet-grid {pets.map((p) PetCard key{p.id} pet{p} /)} /div ); }useEffect 的依赖数组里放 species 和 page任何一个变都会触发重新请求这是 React 里做筛选的标准写法。注意别把 pets 放进依赖否则 setPets 会引发无限循环这是新手最常踩的坑。4.3 领养申请表单的校验与提交表单要做的校验分两层前端拦明显错误后端做最终校验。function AdoptionForm({ petId }) { const [form, setForm] useState({ applicantName: , contact: }); const handleSubmit async (e) { e.preventDefault(); if (!form.applicantName.trim()) { alert(请填写姓名); return; } if (!/^1\d{10}$/.test(form.contact)) { alert(联系方式格式不正确); return; } try { await request.post(/adoptions, { petId, ...form }); alert(申请已提交); } catch (err) { alert(err.message); } }; return ( form onSubmit{handleSubmit} input value{form.applicantName} onChange{(e) setForm({ ...form, applicantName: e.target.value })} / input value{form.contact} onChange{(e) setForm({ ...form, contact: e.target.value })} / button typesubmit提交申请/button /form ); }前端校验只是体验优化后端必须再校验一遍因为请求可以绕过前端直接发。联系方式用正则做基础格式检查别做太复杂的校验否则容易误伤。4.4 用 Web Speech API 做宠物信息语音播报TTS 是这个项目的亮点功能用浏览器原生的 SpeechSynthesis 就能实现不需要接第三方服务。function speakPetInfo(pet) { if (!window.speechSynthesis) { console.warn(当前浏览器不支持语音合成); return; } // 先取消正在播报的内容避免叠加 window.speechSynthesis.cancel(); const text ${pet.name}${pet.breed}${pet.ageMonths}个月大性格${pet.temperament}; const utterance new SpeechSynthesisUtterance(text); utterance.lang zh-CN; utterance.rate 1.0; // 语速0.1 到 10 utterance.pitch 1.0; // 音调0 到 2 utterance.volume 1.0; // 音量0 到 1 window.speechSynthesis.speak(utterance); }lang 设成 zh-CN 才会用中文语音rate 和 pitch 保持 1.0 最自然调太快听不清调太慢像机器人。cancel 那行很关键用户快速点多个宠物时不取消会排队播报体验很差。这个 API 在主流浏览器都支持但移动端有些环境会静默失败所以要做能力检测。5. 避坑与排查联调阶段最容易翻车的五个问题5.1 跨域请求被浏览器拦截现象前端控制台报 CORS policy 错误请求发不出去。原因前端跑在 5173后端在 8080浏览器同源策略默认拦截跨端口请求。解决在后端加全局 CORS 配置别在前端瞎折腾代理。Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) .allowedOrigins(http://localhost:5173) .allowedMethods(GET, POST, PUT, DELETE) .allowCredentials(true); } }allowedOrigins 写具体地址别图省事写星号带凭证的请求不允许通配。5.2 实体关联导致的 JSON 循环引用现象查宠物详情时接口返回 500日志里是 StackOverflowError。原因宠物和申请互相引用序列化时无限递归。解决在关联字段上加 JsonIgnore或者用 DTO 只返回需要的字段。Capstone 阶段用 DTO 更干净避免把实体直接暴露给前端。5.3 前端 useEffect 无限请求现象打开列表页Network 面板里请求刷屏。原因依赖数组里放了每次渲染都变的对象或数组。解决只放基本类型或者用 useMemo 缓存对象。排查时看请求是不是在 setState 之后又触发基本就能定位。5.4 语音播报在部分浏览器静默失败现象点了播报按钮没声音控制台也没报错。原因部分浏览器要求语音合成必须在用户交互事件里触发页面加载时自动播会被拦。解决把播报绑定到按钮点击别放在 useEffect 里自动执行。同时加能力检测不支持时给文字提示。5.5 领养状态并发更新导致数据错乱现象两个人同时申请同一只宠物两条申请都成功了。原因状态校验和更新之间有时间窗口两个请求都读到了 AVAILABLE。解决用乐观锁在 Pet 实体加 Version 字段更新时版本不匹配就抛异常前端提示「该宠物已被申请」。6. 进阶技巧把匹配分做成可解释的推荐理由Capstone 想拿高分光有功能不够得让推荐结果「说得清」。我一般会在返回匹配列表时把每一项的得分拆解也带上前端展示成「为什么推荐它」。public class MatchResult { private Pet pet; private double totalScore; private ListString reasons; // 人类可读的推荐理由 } // 在打分时同步收集理由 if (pet.getSpecies().equals(pref.getSpecies())) { score 40; reasons.add(物种符合你的偏好); } if (pet.getSize().equals(pref.getSize())) { score 25; reasons.add(体型匹配); }前端拿到 reasons 后渲染成标签用户一眼就知道这只宠物为什么排在前面。这个改动代码量很小但答辩演示时效果差别很大——评审能看到你不只是会调接口还考虑了结果的可解释性。验证匹配效果可以用一组固定偏好跑回归准备五只特征不同的宠物用同一份偏好请求看排序是否符合预期。如果物种匹配的宠物没排第一说明权重被其他项盖过了回去调参数。这个回归测试建议写成单元测试改权重后跑一遍防止调 A 坏 B。最后说个我自己的习惯每加一个功能先在纸上把数据流画一遍——用户点按钮触发哪个 state 变发什么请求后端改哪张表返回什么界面怎么变。这条链路想清楚了再写代码比边写边试快得多。全栈项目翻车大多不是技术难是链路没理清就动手。希望帮到你。本文还有配套的精品资源点击获取

React + Spring 全栈实战：宠物领养匹配系统与 TTS 语音播报

相关推荐

MATLAB模板匹配车牌识别：轻量确定性方案

MATLAB传递函数图绘制指南：从tf到bode与Simulink

eve-software-factory-template的Factory Brain揭秘：让每次AI运行都记住仓库教训的记忆设计

更多资讯

动态分析：让代码跑起来，定位覆盖率、性能与内存问题

C++23新特性实战：std::expected、std::print与deducing this的工程价值

掩码生成Transformer：少步数高效文本到图像生成实战

C++异常处理底层原理与实战避坑指南

Go网络编程实战：从连接超时排查到pprof性能调优

汇编实验五深度解析：段地址、栈操作与小端序实战指南

今日更新

小波包能量谱原理与MATLAB实现：从频带分解到故障特征提取

基于LSTM的网易云音乐评论情感分析：数据清洗与模型调优实战

Alpha-Beta剪枝与极大极小值算法：博弈树搜索原理与实战优化

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？