做 Java 后端開(kāi)發(fā)的人應(yīng)該都見(jiàn)過(guò)或者寫(xiě)過(guò)寵物領(lǐng)養(yǎng)救助平臺(tái)這類項(xiàng)目?；?Java Spring Boot 的寵物領(lǐng)養(yǎng)救助系統(tǒng)核心是把寵物發(fā)布、領(lǐng)養(yǎng)申請(qǐng)、救助登記、后臺(tái)審核這些事串成一條完整業(yè)務(wù)鏈而不是簡(jiǎn)單堆幾個(gè)增刪改查頁(yè)面。這套項(xiàng)目對(duì)剛接觸 Spring Boot 的人特別合適也能幫準(zhǔn)備做課程設(shè)計(jì)或畢業(yè)設(shè)計(jì)的人少走彎路。我陸續(xù)看過(guò)幾套類似源碼很多代碼思路大同小異這篇文章把這類項(xiàng)目從需求、表結(jié)構(gòu)、后端實(shí)現(xiàn)到部署排查一條線講清楚。如果你手頭已經(jīng)有一套源碼文檔運(yùn)行視頻講解視頻配合這篇來(lái)理解效果會(huì)好很多。1. 先搞清楚平臺(tái)要給誰(shuí)用需求拆解與模塊設(shè)計(jì)很多同學(xué)拿到這種項(xiàng)目第一反應(yīng)就是趕緊把數(shù)據(jù)庫(kù)導(dǎo)進(jìn)去、把后端跑起來(lái)結(jié)果看頁(yè)面時(shí)才發(fā)現(xiàn)“不知道這個(gè)按鈕對(duì)應(yīng)哪段代碼”。所以我不建議急著啟動(dòng)先把需求盤(pán)一遍。所謂寵物領(lǐng)養(yǎng)救助平臺(tái)表面上是在做寵物信息管理實(shí)際上是在做兩條業(yè)務(wù)線。第一條是領(lǐng)養(yǎng)線機(jī)構(gòu)或個(gè)人發(fā)布待領(lǐng)養(yǎng)寵物普通用戶瀏覽、申請(qǐng)、等待審核審核通過(guò)后完成領(lǐng)養(yǎng)。第二條是救助線發(fā)現(xiàn)流浪或受傷寵物的人發(fā)布求助信息救助站或志愿者接單平臺(tái)記錄救助進(jìn)度和結(jié)果。兩條線都會(huì)落到用戶、寵物、申請(qǐng)、救助記錄這些核心數(shù)據(jù)上所以數(shù)據(jù)庫(kù)設(shè)計(jì)必須圍繞這幾類實(shí)體展開(kāi)。1.1 三類用戶畫(huà)像與業(yè)務(wù)場(chǎng)景最常見(jiàn)的用戶角色有三種。普通用戶是平臺(tái)的主要使用者主要做四件事注冊(cè)登錄、瀏覽寵物、提交領(lǐng)養(yǎng)申請(qǐng)、查看自己的申請(qǐng)進(jìn)度。救助站管理員是內(nèi)容維護(hù)者負(fù)責(zé)發(fā)布待領(lǐng)養(yǎng)寵物、上傳寵物照片、審核領(lǐng)養(yǎng)申請(qǐng)、登記救助記錄。平臺(tái)超級(jí)管理員則負(fù)責(zé)用戶管理、內(nèi)容下架、統(tǒng)計(jì)報(bào)表等更高權(quán)限的操作。舉一個(gè)典型場(chǎng)景某用戶在馬路上發(fā)現(xiàn)一只被遺棄的小貓先拍照發(fā)布一條救助信息救助站接手后給小貓做體檢再把小貓的檔案生成寵物信息并標(biāo)記為“待領(lǐng)養(yǎng)”。這時(shí)另一位用戶看到小貓信息覺(jué)得合適就提交領(lǐng)養(yǎng)申請(qǐng)。管理員在后臺(tái)看到這條申請(qǐng)核對(duì)養(yǎng)寵條件和家庭情況審核通過(guò)后寵物狀態(tài)自動(dòng)變成“已領(lǐng)養(yǎng)”。這個(gè)過(guò)程中救助信息、寵物信息、申請(qǐng)記錄是分離的但又通過(guò)用戶和寵物建立關(guān)聯(lián)。這套流程想通了代碼結(jié)構(gòu)也就不容易跑偏。1.2 功能模塊到底要拆成幾塊按業(yè)務(wù)場(chǎng)景拆整個(gè)系統(tǒng)可以分成五個(gè)核心模塊用戶認(rèn)證模塊注冊(cè)、登錄、個(gè)人資料、JWT Token 管理。寵物信息模塊寵物列表、詳情、分類篩選、發(fā)布、圖片上傳、狀態(tài)管理。領(lǐng)養(yǎng)申請(qǐng)模塊提交申請(qǐng)、取消申請(qǐng)、后臺(tái)審核、領(lǐng)養(yǎng)記錄查詢。救助模塊發(fā)布求助、救助進(jìn)度更新、救助記錄展示。后臺(tái)管理模塊用戶管理、寵物審核、申請(qǐng)審核、救助信息管理、數(shù)據(jù)統(tǒng)計(jì)。救助模塊容易被人忽略很多實(shí)現(xiàn)只是把它做成了靜態(tài)新聞公告。實(shí)際上救助記錄和領(lǐng)養(yǎng)申請(qǐng)是兩套完全不同的狀態(tài)流救助記錄關(guān)注“是否已有人接手、救助進(jìn)展到哪一步”領(lǐng)養(yǎng)申請(qǐng)關(guān)注“是否通過(guò)審核、寵物是否完成領(lǐng)養(yǎng)”。如果強(qiáng)行合在同一張表里后面寫(xiě)狀態(tài)判斷時(shí)會(huì)很痛苦。1.3 為什么采用 Spring Boot 單體分層架構(gòu)第一次接觸這類項(xiàng)目的人常問(wèn)既然技術(shù)棧里有 Spring Boot、MyBatis、Redis、Vue為什么不做成微服務(wù)我的看法是這種校園項(xiàng)目、課程設(shè)計(jì)或者中小型平臺(tái)用單體分層架構(gòu)是性價(jià)比最高的選擇。微服務(wù)的好處是模塊隔離和獨(dú)立擴(kuò)展但代價(jià)是服務(wù)注冊(cè)、配置中心、分布式事務(wù)、鏈路追蹤這些額外復(fù)雜度。寵物領(lǐng)養(yǎng)平臺(tái)的用戶量、業(yè)務(wù)復(fù)雜度完全沒(méi)到需要拆分的地步單體應(yīng)用部署簡(jiǎn)單、調(diào)試方便一個(gè) Spring Boot 進(jìn)程就能把后端全部跑起來(lái)。再加上 Spring Boot 本身自帶自動(dòng)配置、內(nèi)嵌 Tomcat、眾多 Starter配合 MyBatis-Plus 做數(shù)據(jù)訪問(wèn)幾天時(shí)間就能把骨架搭完。分層結(jié)構(gòu)也足夠清晰Controller 接收請(qǐng)求Service 處理業(yè)務(wù)Mapper 訪問(wèn)數(shù)據(jù)庫(kù)Entity 映射表結(jié)構(gòu)。先用單體把業(yè)務(wù)邏輯想清楚比一上來(lái)就追新架構(gòu)靠譜得多。2. 數(shù)據(jù)庫(kù)設(shè)計(jì)狀態(tài)字段定好了后面少寫(xiě)很多改動(dòng)表結(jié)構(gòu)設(shè)計(jì)是這類項(xiàng)目最容易決定后期工作量的地方。我每次拿到一套源碼不會(huì)先看代碼而是先打開(kāi) SQL 文件看三張核心表寵物表、領(lǐng)養(yǎng)申請(qǐng)表、用戶表。這幾張表的結(jié)構(gòu)設(shè)計(jì)基本能反映整個(gè)項(xiàng)目的質(zhì)量。2.1 核心表結(jié)構(gòu)與字段說(shuō)明一套完整但不過(guò)度設(shè)計(jì)的表結(jié)構(gòu)通常包括下面這些表表名主要作用關(guān)鍵字段user普通用戶和管理員id, username, password, phone, avatar, user_type, statuspet寵物信息id, pet_name, breed, age, sex, city, cover_image, description, publisher_id, statusadoption_application領(lǐng)養(yǎng)申請(qǐng)id, pet_id, user_id, applicant_name, phone, address, reason, status, audit_remarkrescue_record救助記錄id, title, address, description, images, contact_phone, status, create_timeadmin管理員賬號(hào)id, username, password, rolenotice平臺(tái)公告id, title, content, create_time寵物表里的 publisher_id 關(guān)聯(lián) user 表表示這條寵物信息是誰(shuí)發(fā)布的。adoption_application 表通過(guò) pet_id 和 user_id 把申請(qǐng)人和寵物關(guān)聯(lián)起來(lái)后臺(tái)審核時(shí)只要依據(jù)這兩個(gè)外鍵關(guān)系去更新?tīng)顟B(tài)即可。表字段不一定要多豪華重點(diǎn)是能支撐狀態(tài)流轉(zhuǎn)并且保證之后加字段不傷筋動(dòng)骨。2.2 狀態(tài)字段與業(yè)務(wù)狀態(tài)流轉(zhuǎn)狀態(tài)字段是整個(gè)項(xiàng)目里最容易寫(xiě)錯(cuò)邏輯的地方。我會(huì)在數(shù)據(jù)庫(kù)里把狀態(tài)都定義成 tinyint并用注釋寫(xiě)明含義避免代碼里到處是魔法數(shù)字。寵物表的狀態(tài)建議這樣設(shè)計(jì)status含義0待審核1待領(lǐng)養(yǎng)2已領(lǐng)養(yǎng)3已下架領(lǐng)養(yǎng)申請(qǐng)表的狀態(tài)建議這樣設(shè)計(jì)status含義0待審核1已通過(guò)2已拒絕狀態(tài)流轉(zhuǎn)的核心規(guī)則是管理員審核通過(guò)寵物發(fā)布后寵物從 0 變?yōu)?1用戶提交領(lǐng)養(yǎng)申請(qǐng)后申請(qǐng)記錄為 0管理員審核申請(qǐng)通過(guò)后申請(qǐng)變?yōu)?1同時(shí)寵物表從 1 變?yōu)?2如果審核拒絕申請(qǐng)變?yōu)?2寵物繼續(xù)保持在 1等待下一位申請(qǐng)者。這里有一個(gè)很常見(jiàn)的坑同一只寵物可能有多條待審核申請(qǐng)如果管理員通過(guò)了其中一條另外幾條申請(qǐng)應(yīng)該自動(dòng)變成已拒絕或已取消否則就會(huì)造成同一只寵物被“重復(fù)領(lǐng)養(yǎng)”。很多初級(jí)項(xiàng)目沒(méi)有處理這個(gè)邏輯導(dǎo)致寵物狀態(tài)已經(jīng)變成 2其他申請(qǐng)還是待審核狀態(tài)。處理方式很簡(jiǎn)單在領(lǐng)養(yǎng)申請(qǐng)審核通過(guò)的代碼里額外更新同寵物下所有狀態(tài)為 0 的申請(qǐng)。2.3 外鍵、索引與刪除策略的取舍很多教材里強(qiáng)調(diào)外鍵約束但真實(shí)項(xiàng)目里我一般不建議加物理外鍵。物理外鍵會(huì)讓插入、刪除順序變得很?chē)?yán)格比如先刪寵物還是先刪申請(qǐng)一旦順序反了就會(huì)報(bào)錯(cuò)而且系統(tǒng)后期拆分或遷移數(shù)據(jù)時(shí)物理外鍵還會(huì)成為負(fù)擔(dān)。正確做法是在 Java 代碼里通過(guò) Service 層保證數(shù)據(jù)一致性只在表字段上建普通索引。需要重點(diǎn)關(guān)注的索引有三個(gè)pet 表的 status 和 city 聯(lián)合索引adoption_application 表的 pet_id 和 user_id 聯(lián)合索引rescue_record 表的 status 索引。這些字段都是查詢和篩選的高頻條件。刪除策略上不太建議直接物理刪除寵物信息。用戶已經(jīng)提交過(guò)申請(qǐng)且申請(qǐng)記錄里關(guān)聯(lián)了寵物 id如果寵物被物理刪除后臺(tái)查看歷史申請(qǐng)時(shí)會(huì)變成空數(shù)據(jù)。更好的做法是用邏輯刪除給表加一個(gè) deleted 字段查詢時(shí)統(tǒng)一過(guò)濾。或者更簡(jiǎn)單一點(diǎn)直接用 status3已下架來(lái)替代刪除既保留數(shù)據(jù)又方便用戶申訴和后臺(tái)追蹤。3. 后端功能實(shí)現(xiàn)從登錄到領(lǐng)養(yǎng)審核的完整鏈路后端代碼看起來(lái)模塊很多但真正撐起業(yè)務(wù)核心的只有幾個(gè)部分統(tǒng)一返回結(jié)構(gòu)、登錄鑒權(quán)、文件上傳、領(lǐng)養(yǎng)審核、列表查詢。把這五塊吃透項(xiàng)目的骨架就明白了。3.1 統(tǒng)一返回體、異常處理與分層約定前后端聯(lián)調(diào)最容易出現(xiàn)的問(wèn)題就是接口返回格式不統(tǒng)一。今天返回{data: xxx}明天返回{result: xxx}前端寫(xiě)起來(lái)非常痛苦。所以項(xiàng)目里必須有一個(gè)統(tǒng)一返回體。Data public class ResultT { private Integer code; private String msg; private T data; public static T ResultT ok(T data) { ResultT r new Result(); r.code 200; r.msg ok; r.data data; return r; } public static T ResultT fail(Integer code, String msg) { ResultT r new Result(); r.code code; r.msg msg; return r; } }配合一個(gè)全局異常處理器可以把業(yè)務(wù)異常和技術(shù)異常統(tǒng)一攔截。比如用戶提交領(lǐng)養(yǎng)申請(qǐng)時(shí)寵物已經(jīng)不存在Service 層直接拋出BusinessException由RestControllerAdvice統(tǒng)一轉(zhuǎn)成Result.fail(400, e.getMessage())。這樣 Controller 層就不用每個(gè)方法都寫(xiě) try-catch代碼會(huì)干凈很多。分層時(shí)記住一條紅線Controller 不寫(xiě)業(yè)務(wù)邏輯只做參數(shù)接收和結(jié)果轉(zhuǎn)換Service 不做 SQL 拼接只調(diào) Mapper 方法復(fù)雜查詢才在 Mapper XML 里寫(xiě) SQL。3.2 JWT 登錄鑒權(quán)與密碼處理HTTP 接口本身是無(wú)狀態(tài)的登錄之后怎么知道調(diào)用者是誰(shuí)主流做法就是 JWT。用戶登錄成功后后端生成一個(gè) token 返回給前端前端在后續(xù)請(qǐng)求的 Header 里帶上Authorization: token后端通過(guò)攔截器解析 token 得到用戶 id 和角色。String token Jwts.builder() .setSubject(user.getId().toString()) .claim(username, user.getUsername()) .setExpiration(new Date(System.currentTimeMillis() 1000 * 60 * 60 * 24 * 7)) .signWith(SignatureAlgorithm.HS256, secretKey) .compact();攔截器里需要做三件事讀取 Header 里的 token解析 token 是否過(guò)期把解析出的用戶信息放到當(dāng)前請(qǐng)求上下文中。注意放行登錄、注冊(cè)、寵物列表這些公開(kāi)接口不要一棍子把所有接口都攔掉否則前端在未登錄狀態(tài)連首頁(yè)都打不開(kāi)。密碼處理這塊不管項(xiàng)目復(fù)雜度多高都不要存明文。至少要用 MD5 加鹽更好的是用 BCrypt。加鹽的目的是防止彩虹表直接反推BCrypt 則自帶鹽值和強(qiáng)度參數(shù)安全性更高。3.3 寵物發(fā)布、圖片上傳與靜態(tài)資源映射寵物信息里圖片是剛需上傳接口要解決的問(wèn)題有三個(gè)文件存到哪里、怎么防止文件名沖突、前端怎么訪問(wèn)到這張圖。我比較推薦的做法是把文件保存到本機(jī)某個(gè)業(yè)務(wù)目錄比如項(xiàng)目根目錄下的upload/文件夾文件名用 UUID 重命名數(shù)據(jù)庫(kù)只存相對(duì)路徑。這樣數(shù)據(jù)庫(kù)和磁盤(pán)文件不會(huì)因?yàn)橹孛ハ喔采w而且未來(lái)如果要遷移到云存儲(chǔ)只需要改動(dòng)上傳方法數(shù)據(jù)庫(kù)字段不用變。PostMapping(/upload) public ResultString upload(RequestParam(file) MultipartFile file) { if (file.isEmpty()) { return Result.fail(400, 文件不能為空); } String originalFilename file.getOriginalFilename(); String suffix originalFilename ! null ? originalFilename.substring(originalFilename.lastIndexOf(.)) : .jpg; String fileName UUID.randomUUID() suffix; Path targetPath Paths.get(uploadDir).resolve(fileName); file.transferTo(targetPath); return Result.ok(/uploads/ fileName); }上傳之后還要配置靜態(tài)資源映射否則/uploads/xxx.jpg會(huì)直接 404。Configuration public class WebMvcConfig implements WebMvcConfigurer { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/uploads/**) .addResourceLocations(file: uploadDir /); } }這里有個(gè)細(xì)節(jié)uploadDir最好用絕對(duì)路徑并且提前創(chuàng)建目錄。很多人用相對(duì)路徑結(jié)果在 IDE 里啟動(dòng)正常打成 jar 包后路徑就變了圖片全部丟失。3.4 領(lǐng)養(yǎng)申請(qǐng)與后臺(tái)審核的事務(wù)實(shí)現(xiàn)領(lǐng)養(yǎng)審核是整個(gè)系統(tǒng)里最需要寫(xiě)事務(wù)的地方。它的核心邏輯是更新申請(qǐng)的審核狀態(tài)如果審核通過(guò)還要同步更新寵物狀態(tài)。這兩步必須在一個(gè)事務(wù)里完成否則可能出現(xiàn)申請(qǐng)已通過(guò)但寵物還是待領(lǐng)養(yǎng)的情況。Transactional(rollbackFor Exception.class) public void auditAdoption(Long applicationId, Integer auditStatus, String remark) { AdoptionApplication app adoptionApplicationMapper.selectById(applicationId); if (app null || app.getStatus() ! 0) { throw new BusinessException(申請(qǐng)不存在或已處理); } app.setStatus(auditStatus); app.setAuditRemark(remark); app.setAuditTime(LocalDateTime.now()); adoptionApplicationMapper.updateById(app); if (auditStatus 1) { Pet pet petMapper.selectById(app.getPetId()); pet.setStatus(2); petMapper.updateById(pet); // 同一寵物其他待審核申請(qǐng)自動(dòng)置為已拒絕 LambdaUpdateWrapperAdoptionApplication updateWrapper new LambdaUpdateWrapper(); updateWrapper.eq(AdoptionApplication::getPetId, app.getPetId()) .eq(AdoptionApplication::getStatus, 0) .set(AdoptionApplication::getStatus, 2) .set(AdoptionApplication::getAuditRemark, 該寵物已被領(lǐng)養(yǎng)); adoptionApplicationMapper.update(null, updateWrapper); } }為什么老項(xiàng)目會(huì)在這里出問(wèn)題最常見(jiàn)的原因是把Transactional加在 Controller 方法上或者在同類的另一個(gè)方法里直接調(diào)用結(jié)果事務(wù)沒(méi)有生效。正確玩法是把事務(wù)加在 Service 實(shí)現(xiàn)類的 public 方法上并且保證異常能被 Spring 捕獲。如果方法內(nèi)部自己 try-catch 把異常吞掉Spring 是不會(huì)回滾的。3.5 列表篩選和分頁(yè)查詢的常規(guī)寫(xiě)法寵物列表頁(yè)是用戶第一眼看到的東西接口要支持分頁(yè)還要支持按城市、品種、狀態(tài)篩選。用 MyBatis-Plus 的LambdaQueryWrapper可以寫(xiě)得很清晰不需要在 XML 里拼 SQL。PagePet page petMapper.selectPage( new Page(pageNum, pageSize), new LambdaQueryWrapperPet() .eq(StringUtils.isNotBlank(city), Pet::getCity, city) .like(StringUtils.isNotBlank(breed), Pet::getBreed, breed) .eq(Pet::getStatus, 1) .orderByDesc(Pet::getCreateTime) );使用 LambdaQueryWrapper 的好處有兩個(gè)一是字段名用方法引用不會(huì)寫(xiě)錯(cuò)列名二是條件對(duì)象是StringUtils.isNotBlank當(dāng)參數(shù)為空時(shí)這段條件自動(dòng)拼不上避免了 SQL 注入風(fēng)險(xiǎn)。分頁(yè)對(duì)象自帶 total、current、pages 這些字段前端直接展示即可。特別注意如果有多個(gè)篩選條件一定不要在 Java 代碼里字符串拼接 SQL這是項(xiàng)目里的高危行為。4. 前端頁(yè)面與接口聯(lián)調(diào)別只盯著后端代碼很多人的注意力全放在后端結(jié)果啟動(dòng)項(xiàng)目后發(fā)現(xiàn)頁(yè)面白屏、接口 404。前端和后端是配合關(guān)系哪怕源碼里已經(jīng)有現(xiàn)成頁(yè)面也得知道每個(gè)頁(yè)面在調(diào)哪個(gè)接口。4.1 用戶端和管理端的頁(yè)面劃分用戶端重點(diǎn)看六個(gè)頁(yè)面首頁(yè)寵物列表、寵物詳情頁(yè)、領(lǐng)養(yǎng)申請(qǐng)頁(yè)、救助信息發(fā)布頁(yè)、個(gè)人中心、登錄注冊(cè)頁(yè)。管理端重點(diǎn)看寵物管理、領(lǐng)養(yǎng)審核、救助管理、用戶管理、數(shù)據(jù)統(tǒng)計(jì)。每個(gè)管理頁(yè)面背后基本都是一個(gè)分頁(yè)列表接口加上一個(gè)新增加、修改、刪除接口。如果前端是 Vue 單頁(yè)應(yīng)用核心在路由配置和請(qǐng)求封裝。路由對(duì)應(yīng)頁(yè)面請(qǐng)求封裝統(tǒng)一處理 token 注入和返回體解析。如果前端是簡(jiǎn)單模板頁(yè)面那更要注意表單提交的字段名和后端實(shí)體字段是否一致。不一致是最常見(jiàn)的聯(lián)調(diào)問(wèn)題比如后端字段叫phone前端提交的是tel后臺(tái)直接收到 null。4.2 接口路徑和返回格式約定接口設(shè)計(jì)建議統(tǒng)一 RESTful 風(fēng)格方便前后端記憶方法路徑說(shuō)明POST/api/user/register用戶注冊(cè)POST/api/user/login用戶登錄GET/api/pet/list寵物分頁(yè)列表GET/api/pet/detail/{id}寵物詳情POST/api/adoption/apply提交領(lǐng)養(yǎng)申請(qǐng)POST/api/admin/adoption/audit審核領(lǐng)養(yǎng)申請(qǐng)GET/api/rescue/list救助列表POST/api/upload圖片上傳鑒權(quán)規(guī)則上普通用戶接口要求帶 token管理員接口還要校驗(yàn)角色。攔截器在進(jìn)入 Controller 之前把角色信息解析出來(lái)如果普通用戶訪問(wèn) admin 接口直接返回 403。這樣權(quán)限判斷不會(huì)散落到每個(gè)業(yè)務(wù)方法里。4.3 聯(lián)調(diào)時(shí)最容易出問(wèn)題的幾個(gè)位置第一個(gè)是跨域。前端跑在 5173 或 8081后端跑在 8080瀏覽器默認(rèn)會(huì)攔截跨域請(qǐng)求。后端需要配置 CorsFilter 或者實(shí)現(xiàn)WebMvcConfigurer的addCorsMappings。第二個(gè)是日期格式。Java 的LocalDateTime默認(rèn)序列化出來(lái)是一串?dāng)?shù)組前端根本沒(méi)法用要配置 Jackson 的日期格式。第三個(gè)是文件路徑。前端拿到的圖片地址是不是完整 URL能不能直接放進(jìn) img 標(biāo)簽這些都要提前約定好。5. 本地部署運(yùn)行拿到源碼后從0跑起來(lái)的完整步驟我不建議拿到項(xiàng)目就直接點(diǎn)啟動(dòng)按鈕因?yàn)榇蟾怕蕰?huì)因?yàn)榄h(huán)境問(wèn)題報(bào)一堆錯(cuò)。先按順序做好環(huán)境確認(rèn)和配置修改整個(gè)過(guò)程會(huì)順暢很多。5.1 環(huán)境版本與安裝注意點(diǎn)不同源碼用到的基礎(chǔ)版本差異很大先看項(xiàng)目的 pom.xml 和前端 package.json 再動(dòng)手組件推薦版本說(shuō)明JDK1.8 或 11Spring Boot 2.x 用 1.8 最穩(wěn)Maven3.6 以上管理后端依賴MySQL5.7 或 8.05.7 兼容性最好Redis5.0 以上如果項(xiàng)目引用了 Redis 依賴才需要Node.js14 或 16前端 Vue 項(xiàng)目構(gòu)建用IDEIntelliJ IDEA直接導(dǎo)入 Maven 工程有個(gè)小技巧啟動(dòng)前先檢查 pom.xml 里是否引用了 Redis、RabbitMQ 這類中間件如果引用了本地環(huán)境沒(méi)有啟動(dòng)對(duì)應(yīng)服務(wù)后端會(huì)直接啟動(dòng)失敗。確認(rèn)依賴都齊全后再進(jìn)入下一步。5.2 修改配置文件的核心地方后端核心配置集中在 application.yml主要改數(shù)據(jù)庫(kù)連接和文件上傳路徑。server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/pet_adoption?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver servlet: multipart: max-file-size: 10MB max-request-size: 20MB mybatis-plus: mapper-locations: classpath*:mapper/**/*.xml configuration: map-underscore-to-camel-case: true這里要注意三個(gè)細(xì)節(jié)。serverTimezoneAsia/Shanghai不寫(xiě)MySQL 8 下經(jīng)常報(bào)時(shí)間連接錯(cuò)誤。map-underscore-to-camel-case必須開(kāi)否則數(shù)據(jù)庫(kù)里的create_time映射不到 Java 的createTime。文件上傳大小限制默認(rèn)只有 1MB寵物圖片稍微大一點(diǎn)就會(huì)被攔所以手動(dòng)放大到 10MB。前端項(xiàng)目的接口地址也要看一眼如果寫(xiě)死了localhost:8080本地運(yùn)行沒(méi)問(wèn)題如果寫(xiě)的是測(cè)試服務(wù)器地址必須改成后端實(shí)際地址。5.3 啟動(dòng)驗(yàn)證順序按照下面的順序操作基本不會(huì)出現(xiàn)“卡住看不懂”的情況。第一步用 Navicat 或命令行創(chuàng)建數(shù)據(jù)庫(kù)然后把項(xiàng)目提供的 SQL 文件導(dǎo)入。導(dǎo)入后點(diǎn)開(kāi) pet 表看一眼確認(rèn)有數(shù)據(jù)還是空表。第二步修改 application.yml 里的賬號(hào)密碼保證能連上剛才創(chuàng)建的庫(kù)。第三步如果 pom.xml 里有 Redis啟動(dòng)本地 Redis 服務(wù)。第四步運(yùn)行 Spring Boot 啟動(dòng)類看到 “Started Application in x seconds” 才說(shuō)明后端起來(lái)了。第五步啟動(dòng)前端執(zhí)行 npm install 和 npm run serve瀏覽器打開(kāi)頁(yè)面。第六步隨便注冊(cè)一個(gè)賬號(hào)走一遍發(fā)布寵物到申請(qǐng)領(lǐng)養(yǎng)的流程確認(rèn)狀態(tài)流轉(zhuǎn)正常。這一步不要省。很多項(xiàng)目表面能啟動(dòng)但實(shí)際業(yè)務(wù)鏈路是斷的早期發(fā)現(xiàn)總比寫(xiě)代碼寫(xiě)到一半再排查強(qiáng)。6. 常見(jiàn)問(wèn)題排查與避坑實(shí)錄這部分是我覺(jué)得最值錢(qián)的內(nèi)容。項(xiàng)目運(yùn)行不起來(lái)、頁(yè)面數(shù)據(jù)不對(duì)90% 的原因就集中在下面這些點(diǎn)。6.1 高頻報(bào)錯(cuò)速查表現(xiàn)象可能原因處理方法Application 啟動(dòng)時(shí)報(bào)數(shù)據(jù)源錯(cuò)誤數(shù)據(jù)庫(kù)沒(méi)建、賬號(hào)密碼錯(cuò)、URL 寫(xiě)錯(cuò)先確認(rèn)數(shù)據(jù)庫(kù)連接是否能 ping 通再檢查 yml 配置訪問(wèn)頁(yè)面白屏 404前端接口地址寫(xiě)錯(cuò)、后端 context-path 不一致查看瀏覽器 Network確認(rèn)請(qǐng)求有沒(méi)有發(fā)到后端圖片上傳后訪問(wèn) 404沒(méi)有配置靜態(tài)資源映射或 uploadDir 路徑不對(duì)檢查addResourceHandlers是否生效接口報(bào) 401 或 403token 沒(méi)傳、token 過(guò)期、角色權(quán)限不足查看請(qǐng)求 Header 是否有 AuthorizationInvalid bound statementMapper 接口和 XML 文件沒(méi)對(duì)應(yīng)上檢查mapper-locations和 namespace時(shí)間字段返回?cái)?shù)字?jǐn)?shù)組LocalDateTime 序列化問(wèn)題配置 Jackson JavaTimeModule 和日期格式Redis連接失敗Redis 服務(wù)未啟動(dòng)或地址配置錯(cuò)誤啟動(dòng) Redis確認(rèn)端口中文亂碼數(shù)據(jù)庫(kù)字符集不是 utf8mb4重新建庫(kù)時(shí)指定 utf8mb46.2 一套通用的排查思路遇到問(wèn)題不要只盯著瀏覽器報(bào)錯(cuò)我自己通常按這三步走。第一步看控制臺(tái)日志。后端啟動(dòng)失敗時(shí)先看第一個(gè)異常類型而不是最后一行看不懂的 Caused by 開(kāi)端。日志最前面的異常類名幾乎能直接指向問(wèn)題方向比如ClassNotFoundException就是缺依賴CannotCreateTransactionException就是數(shù)據(jù)庫(kù)連接出問(wèn)題。第二步確認(rèn)基礎(chǔ)環(huán)境。數(shù)據(jù)庫(kù)能不能連上、端口有沒(méi)有被占用、前端代理有沒(méi)有配置這些問(wèn)題用最快的手動(dòng)操作驗(yàn)證一遍比花半小時(shí)看代碼更有效。第三步還原操作路徑。把出問(wèn)題的接口調(diào)用鏈走一遍看是前端沒(méi)發(fā)請(qǐng)求還是后端收到了但返回異常還是數(shù)據(jù)庫(kù)里數(shù)據(jù)狀態(tài)不對(duì)。前端 Network 面板、后端日志、數(shù)據(jù)庫(kù)三個(gè)對(duì)照著看很快就能定位。6.3 幾個(gè)項(xiàng)目里容易忽略的細(xì)節(jié)事務(wù)異常被吞掉是最隱蔽的坑。Service 方法加了Transactional里面卻自己 try-catch 了異常代碼看起來(lái)不報(bào)錯(cuò)但數(shù)據(jù)寫(xiě)到一半就斷了最難受。事務(wù)方法里的異常一定要往上拋交給全局異常處理器處理。文件上傳路徑不要用相對(duì)路徑。相對(duì)路徑在 IDE 里跑和打成 jar 跑工作目錄不一樣圖片一會(huì)兒有、一會(huì)兒沒(méi)有。建議代碼里用配置屬性動(dòng)態(tài)指定絕對(duì)路徑或者臨時(shí)用System.getProperty(user.dir)拼一個(gè)項(xiàng)目運(yùn)行目錄。領(lǐng)養(yǎng)申請(qǐng)并發(fā)的問(wèn)題建議盡早考慮。同一只寵物如果被兩個(gè)人同時(shí)提交申請(qǐng)并且管理員同時(shí)審核可能出現(xiàn)兩個(gè)審核操作都把寵物狀態(tài)改成 2 的臟讀。嚴(yán)謹(jǐn)一點(diǎn)的做法是在審核方法里用樂(lè)觀鎖比如在 pet 表加 version 字段更新時(shí)校驗(yàn)版本號(hào)或者最簡(jiǎn)單地在審核前用select ... for update鎖住寵物記錄。7. 二次開(kāi)發(fā)擴(kuò)展讓系統(tǒng)從“能跑”變成“好用”能把一套現(xiàn)成的寵物領(lǐng)養(yǎng)救助平臺(tái)跑起來(lái)只能算完成了第一步。真正拉開(kāi)差距的是你在這個(gè)基礎(chǔ)上加了什么、改了什么。7.1 建議優(yōu)先加的功能如果要在這個(gè)項(xiàng)目上做二次開(kāi)發(fā)我強(qiáng)烈建議先加寵物健康檔案。寵物領(lǐng)養(yǎng)不是商品交易領(lǐng)養(yǎng)人很關(guān)心寵物疫苗、驅(qū)蟲(chóng)、絕育情況。新建一張 pet_health_record 表關(guān)聯(lián) pet_id記錄疫苗名稱、接種時(shí)間、下次接種日期頁(yè)面放在寵物詳情里會(huì)讓系統(tǒng)完整度立刻上一個(gè)檔次。第二個(gè)建議加領(lǐng)養(yǎng)回訪。很多救助站會(huì)要求領(lǐng)養(yǎng)人定期反饋寵物近況用一個(gè)回訪任務(wù)表加上定時(shí)任務(wù)到時(shí)間自動(dòng)生成回訪工單管理員跟進(jìn)后記錄結(jié)果。這個(gè)功能很貼合實(shí)際業(yè)務(wù)也是面試時(shí)能拿出來(lái)講的亮點(diǎn)。第三個(gè)建議加在線協(xié)商功能。用戶在提交申請(qǐng)前常想和救助站溝通一下寵物性格、領(lǐng)養(yǎng)條件用 WebSocket 做一個(gè)簡(jiǎn)單聊天室比反復(fù)刷新列表和打電話體驗(yàn)好得多。7.2 代碼層可以做的優(yōu)化業(yè)務(wù)之外代碼層有幾個(gè)值得優(yōu)化的點(diǎn)。列表接口可以把寵物信息和圖片分離減少大字段查詢熱點(diǎn)數(shù)據(jù)用 Redis 做緩存比如首頁(yè)推薦寵物列表一分鐘更新一次就夠了接口返回值不要直接返回?cái)?shù)據(jù)庫(kù)實(shí)體因?yàn)閷?shí)體里的密碼、手機(jī)號(hào)等敏感字段可能被前端看到建議補(bǔ)一層 DTO。數(shù)據(jù)庫(kù)這塊可以把救助記錄的類型、寵物品種這些重復(fù)性高的字段改成字典表減少維護(hù)成本。接口層可以補(bǔ)充參數(shù)校驗(yàn)注解比如手機(jī)號(hào)格式、申請(qǐng)理由長(zhǎng)度避免前端繞過(guò)頁(yè)面直接調(diào)接口。7.3 關(guān)于學(xué)習(xí)這類項(xiàng)目的一點(diǎn)個(gè)人體會(huì)我拿到一套新項(xiàng)目習(xí)慣是“倒著學(xué)”。先看 SQL 文件里的表結(jié)構(gòu)把狀態(tài)字段和關(guān)聯(lián)字段畫(huà)出來(lái)再打開(kāi)講解視頻按模塊跳著看重點(diǎn)看領(lǐng)養(yǎng)審核、文件上傳、權(quán)限攔截這幾個(gè)核心環(huán)節(jié)最后自己動(dòng)手改一個(gè)小需求比如給寵物表加一個(gè)“是否已絕育”字段從前端表單到后端接口到數(shù)據(jù)庫(kù)全鏈路改一遍。這樣做的好處是你不是被動(dòng)地把代碼看了一遍而是真正理解了每個(gè)模塊的來(lái)龍去脈。后面再遇到類似的項(xiàng)目哪怕表名不同核心邏輯也都能一眼看穿。這套寵物領(lǐng)養(yǎng)救助平臺(tái)系統(tǒng)價(jià)值不只是“能跑”。你看懂了狀態(tài)流轉(zhuǎn)、事務(wù)控制、文件上傳、權(quán)限攔截這幾個(gè)關(guān)鍵點(diǎn)再去做任何后臺(tái)管理系統(tǒng)都會(huì)順手很多。最后提醒一句拿到配套的文檔和講解視頻后先定位目錄再動(dòng)手改代碼這個(gè)順序能幫你省下大把試錯(cuò)時(shí)間。