戰(zhàn)：從零搭建桌游信息管理系統(tǒng))
去年幫一個(gè)學(xué)弟復(fù)盤他的畢業(yè)設(shè)計(jì)題目正好就是“基于SpringBoot的桌游信息管理系統(tǒng)”。乍一看這東西平平無奇無非是登錄、增刪改查、統(tǒng)計(jì)報(bào)表這幾板斧。但真正上手之后才發(fā)現(xiàn)桌游店的業(yè)務(wù)里藏著不少值得細(xì)摳的點(diǎn)桌游庫存怎么扣減、訂單狀態(tài)怎么流轉(zhuǎn)、會(huì)員余額和押金怎么處理、租借時(shí)長(zhǎng)怎么計(jì)費(fèi)。把這些邏輯理清楚項(xiàng)目做出來才有含金量而不是一個(gè)空殼CRUD。這篇文章打算把這個(gè)系統(tǒng)的設(shè)計(jì)思路、數(shù)據(jù)庫建模、后端實(shí)現(xiàn)、前端頁面、部署調(diào)試全過程拆開講一遍。適合三類人看正在做Java畢業(yè)設(shè)計(jì)、選題是管理系統(tǒng)的同學(xué)剛學(xué)完SpringBoot想找一個(gè)完整項(xiàng)目練手的初級(jí)開發(fā)者確實(shí)有桌游吧信息化需求、想自己搞個(gè)小工具的經(jīng)營(yíng)人員。我會(huì)盡量寫得能直接抄作業(yè)從環(huán)境搭建到核心代碼再到排查Bug的經(jīng)驗(yàn)全部攤開來說。1. 項(xiàng)目概覽與技術(shù)選型為什么大家都選SpringBoot1.1 桌游店管的是什么需求梳理做系統(tǒng)之前先別急著寫代碼得先弄明白“桌游信息管理系統(tǒng)”到底要管什么。我接觸過的桌游吧日常運(yùn)營(yíng)至少有這幾塊固定動(dòng)作第一桌游的商品化管理。店里一般有成百上千套桌游名字、類型、適合人數(shù)、單局時(shí)長(zhǎng)、每小時(shí)租金、庫存數(shù)量、損壞下架狀態(tài)這些信息靠Excel記錄特別容易亂需要一套能增刪改查和模糊搜索的商品模塊。第二會(huì)員和儲(chǔ)值管理。桌游吧大多靠辦卡鎖定回頭客會(huì)員的手機(jī)號(hào)、余額、積分、等級(jí)需要維護(hù)。這里有個(gè)常見需求是“桌游租借費(fèi)用從會(huì)員余額里扣”所以會(huì)員余額字段必須和訂單模塊聯(lián)動(dòng)。第三租借與訂單管理。這是整個(gè)系統(tǒng)的核心業(yè)務(wù)。顧客到店選一套桌游系統(tǒng)要生成一個(gè)租借訂單記錄桌游、時(shí)長(zhǎng)、金額、押金、開始時(shí)間、結(jié)束時(shí)間并實(shí)時(shí)更新桌游庫存。訂單不能只是新增、刪除還得有“租借中、已完成、已取消、逾期未還”這類狀態(tài)流轉(zhuǎn)。第四簡(jiǎn)單的統(tǒng)計(jì)報(bào)表。老板最關(guān)心的其實(shí)是“今天進(jìn)賬多少、哪幾款桌游最熱門、最近會(huì)員增長(zhǎng)情況”。所以系統(tǒng)最好帶一個(gè)數(shù)據(jù)看板用圖表把訂單金額趨勢(shì)、桌游熱度排行展示出來。這就是需求清單。管理系統(tǒng)的功能基本都由業(yè)務(wù)倒推出來千萬不要想到哪寫到哪否則后面改起來非常痛苦。1.2 技術(shù)棧選型SpringBoot MyBatis-Plus MySQL Thymeleaf這套系統(tǒng)的技術(shù)棧我很推薦一個(gè)成熟的組合SpringBoot 2.7.x MyBatis-Plus MySQL 5.7/8.0 Thymeleaf Bootstrap ECharts。原因很簡(jiǎn)單每一層都有明確替代方案但這個(gè)組合是綜合上手成本、資料豐富度、調(diào)試便利性之后最穩(wěn)妥的。SpringBoot的優(yōu)勢(shì)不用多吹內(nèi)嵌Tomcat、自動(dòng)裝配、約定大于配置能省掉傳統(tǒng)SSM里一長(zhǎng)串的XML配置。MyBatis-Plus相比原生MyBatis最大的價(jià)值是內(nèi)置了通用Mapper和通用Service單表CRUD幾乎不用手寫SQL分頁插件也用得順手。配合LambdaQueryWrapper條件查詢寫起來非常直觀對(duì)趕工期的項(xiàng)目來說極其友好。前端為什么選Thymeleaf而不是前后端分離的Vue核心原因是這套系統(tǒng)是單體應(yīng)用不需要單獨(dú)起后端接口服務(wù)。用Thymeleaf做服務(wù)端渲染頁面直接通過模板引擎拿到數(shù)據(jù)部署時(shí)一個(gè)jar包搞定不用處理跨域、不用配置Nginx轉(zhuǎn)發(fā)多個(gè)服務(wù)對(duì)畢業(yè)設(shè)計(jì)和中小型內(nèi)部管理系統(tǒng)來說交付和維護(hù)成本最低。如果你已經(jīng)熟練Vue也可以改成SpringBoot寫接口 Vue頁面但復(fù)雜度會(huì)明顯上升不是這個(gè)項(xiàng)目的最優(yōu)解。1.3 功能模塊全景圖把需求落到功能模塊上這套系統(tǒng)我建議這樣劃分管理員模塊登錄、退出、修改密碼、管理員信息維護(hù)。桌游分類模塊分類列表、新增、編輯、刪除用于給桌游打標(biāo)簽。桌游信息模塊桌游列表查詢、條件搜索、添加桌游、編輯、上下架、刪除封面圖上傳。會(huì)員管理模塊會(huì)員列表、新增會(huì)員、余額充值、積分調(diào)整、刪除/禁用。訂單管理模塊創(chuàng)建租借訂單、歸還結(jié)算、訂單狀態(tài)流轉(zhuǎn)、訂單條件查詢。統(tǒng)計(jì)看板模塊今日營(yíng)收、訂單數(shù)量、桌游熱度排行、近7日訂單金額趨勢(shì)。模塊之間不是孤立的。創(chuàng)建訂單要扣桌游庫存、算金額要讀桌游單價(jià)和時(shí)長(zhǎng)、支付要扣會(huì)員余額、歸還計(jì)算要更新訂單狀態(tài)和桌游庫存。這些都是跨表的業(yè)務(wù)操作必須放在Service層用事務(wù)串起來不能拆開來各寫各的。2. 數(shù)據(jù)庫設(shè)計(jì)先把地基砸實(shí)2.1 六張核心表怎么建數(shù)據(jù)庫設(shè)計(jì)是這套系統(tǒng)的地基。我見過太多人一上來先寫代碼結(jié)果表結(jié)構(gòu)建得七零八落后面業(yè)務(wù)邏輯越寫越擰巴。這里我直接給出一個(gè)可落地的建表思路。核心表分六張管理員表、桌游分類表、桌游信息表、會(huì)員表、租借訂單表、訂單明細(xì)表。考慮到畢設(shè)復(fù)雜度適中訂單明細(xì)表可以先不拆一張訂單對(duì)應(yīng)一套桌游即可如果后續(xù)要支持一個(gè)訂單租多套桌游再拆訂單明細(xì)表。桌游信息表是最核心的表字段設(shè)置如下CREATE TABLE board_game ( id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT 主鍵, game_name VARCHAR(100) NOT NULL COMMENT 桌游名稱, type_id BIGINT NOT NULL COMMENT 分類ID, min_players INT NOT NULL DEFAULT 2 COMMENT 最少游玩人數(shù), max_players INT NOT NULL DEFAULT 4 COMMENT 最多游玩人數(shù), play_duration DECIMAL(4,1) DEFAULT 1.0 COMMENT 單局預(yù)計(jì)時(shí)長(zhǎng)(小時(shí)), price DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT 每小時(shí)租金, stock INT NOT NULL DEFAULT 0 COMMENT 當(dāng)前庫存數(shù)量, status TINYINT NOT NULL DEFAULT 1 COMMENT 狀態(tài):1上架 0下架, cover_url VARCHAR(255) DEFAULT NULL COMMENT 封面圖地址, description TEXT COMMENT 桌游玩法簡(jiǎn)介, create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 創(chuàng)建時(shí)間, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新時(shí)間 ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT桌游信息表;租借訂單表設(shè)計(jì)的時(shí)候要特別注意不要直接用order做表名因?yàn)閛rder是SQL關(guān)鍵字容易埋坑。建議用rent_orderCREATE TABLE rent_order ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_no VARCHAR(32) NOT NULL UNIQUE COMMENT 訂單號(hào), member_id BIGINT NOT NULL COMMENT 會(huì)員ID, board_game_id BIGINT NOT NULL COMMENT 桌游ID, quantity INT NOT NULL DEFAULT 1 COMMENT 租借數(shù)量, total_amount DECIMAL(10,2) NOT NULL COMMENT 訂單總金額, deposit DECIMAL(10,2) DEFAULT 0.00 COMMENT 押金, start_time DATETIME NOT NULL COMMENT 租借開始時(shí)間, end_time DATETIME NOT NULL COMMENT 預(yù)計(jì)歸還時(shí)間, status TINYINT NOT NULL DEFAULT 0 COMMENT 狀態(tài):0待支付 1租借中 2已完成 3已取消, remark VARCHAR(255) COMMENT 備注, create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 創(chuàng)建時(shí)間 ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT租借訂單表;會(huì)員表和管理員表相對(duì)簡(jiǎn)單會(huì)員表需要包含member_no、name、phone、balance、points、level等字段。這里我特別加了一個(gè)member_no會(huì)員編號(hào)雖然手機(jī)號(hào)也能唯一標(biāo)識(shí)會(huì)員但單獨(dú)編號(hào)在后期對(duì)接小程序、會(huì)員卡時(shí)更方便。2.2 字段類型和狀態(tài)值的取舍建表時(shí)最容易被忽略的是字段類型的選擇。我舉兩個(gè)最常見的例子金額字段一定要用DECIMAL不能用FLOAT或DOUBLE。因?yàn)槎M(jìn)制浮點(diǎn)數(shù)在計(jì)算0.10.2這類場(chǎng)景會(huì)出現(xiàn)精度誤差而金額誤差是絕對(duì)不能接受的。DECIMAL(10,2)可以存最大10億的金額對(duì)于桌游吧來說完全足夠。狀態(tài)字段建議用TINYINT不要用VARCHAR存中文。比如訂單狀態(tài)用0、1、2、3表示在Java后端定義一個(gè)枚舉類代碼里只操作枚舉展示到頁面前再轉(zhuǎn)換成對(duì)應(yīng)的中文文案。這樣做的好處是數(shù)據(jù)庫體積小、查詢效率高、后端判斷邏輯不會(huì)因?yàn)橹杏⑽淖址町惓鰡栴}。雖然看起來多寫了幾行轉(zhuǎn)換代碼但項(xiàng)目的健壯性會(huì)明顯提升。2.3 外鍵到底建不建我的建議是不要建物理外鍵用邏輯外鍵。也就是在業(yè)務(wù)表里存關(guān)聯(lián)表的ID但不在數(shù)據(jù)庫層面強(qiáng)制約束。原因有幾點(diǎn)物理外鍵會(huì)讓刪除操作變得非常麻煩你想刪一個(gè)分類結(jié)果數(shù)據(jù)庫提示有桌游還在引用它必須先處理子表數(shù)據(jù)高并發(fā)場(chǎng)景下外鍵約束還會(huì)引入額外的鎖開銷而且大多數(shù)管理系統(tǒng)根本不依賴數(shù)據(jù)庫來保證完整性而是靠Service層代碼控制。既然不建物理外鍵那就要在代碼里兜底。比如刪除分類前先查詢?cè)摲诸愊率欠襁€有桌游有就禁止刪除創(chuàng)建訂單前校驗(yàn)會(huì)員和桌游是否存在校驗(yàn)庫存是否充足。這些邏輯放在Service層比依賴數(shù)據(jù)庫約束更靈活報(bào)錯(cuò)信息也能寫得更友好。3. 后端實(shí)現(xiàn)登錄、CRUD與庫存扣減的細(xì)節(jié)3.1 項(xiàng)目骨架與核心依賴配置后端代碼的包結(jié)構(gòu)我建議按功能模塊劃分而不是按技術(shù)類型劃分。按照controller、service、mapper這種分法到后期類一多就亂成一鍋粥。我習(xí)慣這樣組織com.example.boardgame ├── controller # 控制器只做參數(shù)接收和結(jié)果封裝 ├── service # 業(yè)務(wù)邏輯接口 ├── service.impl # 業(yè)務(wù)實(shí)現(xiàn)事務(wù)在這里 ├── mapper # MyBatis-Plus的Mapper接口 ├── entity # 數(shù)據(jù)庫實(shí)體類 ├── dto # 前端傳輸對(duì)象 ├── config # 配置類 ├── interceptor # 攔截器 └── common # 通用返回結(jié)果、異常處理、枚舉工程創(chuàng)建時(shí)pom.xml里最核心的依賴就這么幾個(gè)dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency這里有個(gè)細(xì)節(jié)如果你用的是SpringBoot 3.x依賴名稱和兼容性都有變化MySQL驅(qū)動(dòng)類名也從com.mysql.jdbc.Driver改成了com.mysql.cj.jdbc.Driver。我建議初學(xué)者鎖死SpringBoot 2.7.x版本相關(guān)資料最多、踩坑最容易被搜索引擎找到。3.2 登錄鑒權(quán)攔截器 Session登錄功能每個(gè)管理系統(tǒng)都有但實(shí)現(xiàn)方式有不少講究。最簡(jiǎn)單的方案是用Session保存登錄狀態(tài)配合Spring MVC攔截器統(tǒng)一校驗(yàn)。不用引入Spring Security或者JWT因?yàn)檫@套系統(tǒng)是服務(wù)端渲染的單體應(yīng)用用Session完全夠而且邏輯更直觀。攔截器代碼長(zhǎng)這樣Component public class LoginInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { HttpSession session request.getSession(); if (session.getAttribute(admin) ! null) { return true; } // 判斷是否為AJAX請(qǐng)求 String xrw request.getHeader(X-Requested-With); if (XMLHttpRequest.equals(xrw)) { response.setContentType(application/json;charsetutf-8); response.getWriter().write({\code\:401,\msg\:\登錄已過期請(qǐng)重新登錄\}); } else { response.sendRedirect(/login); } return false; } }然后注冊(cè)攔截器排除登錄接口和靜態(tài)資源路徑Configuration public class WebConfig implements WebMvcConfigurer { Resource private LoginInterceptor loginInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(loginInterceptor) .addPathPatterns(/**) .excludePathPatterns(/login, /css/**, /js/**, /images/**, /fonts/**); } }為什么要把AJAX請(qǐng)求和普通頁面請(qǐng)求分開處理因?yàn)轫撁嫣D(zhuǎn)和異步請(qǐng)求對(duì)未登錄狀態(tài)的處理方式不一樣。普通頁面直接重定向到登錄頁用戶能看到但AJAX請(qǐng)求如果也返回302前端拿到的是一個(gè)登錄頁的HTML解析數(shù)據(jù)就會(huì)報(bào)錯(cuò)。所以攔截器里要做一次區(qū)分。3.3 分頁查詢與通用增刪改查MyBatis-Plus最大的好處就是單表CRUD基本不用手寫SQL。實(shí)體類繼承BaseMapperService繼承IService就擁有了最基礎(chǔ)的增刪改查方法。但實(shí)際項(xiàng)目中肯定要帶條件查詢和分頁這就要用到它的分頁插件。分頁插件配置很簡(jiǎn)單Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }配置好之后Service層的分頁查詢可以這樣寫public PageResultBoardGame pageGames(int current, int size, String keyword, Long typeId) { PageBoardGame page new Page(current, size); LambdaQueryWrapperBoardGame wrapper new LambdaQueryWrapper(); wrapper.like(StringUtils.hasText(keyword), BoardGame::getGameName, keyword) .eq(typeId ! null, BoardGame::getTypeId, typeId) .orderByDesc(BoardGame::getCreateTime); PageBoardGame result boardGameMapper.selectPage(page, wrapper); return PageResult.of(result); }這里有兩個(gè)地方值得展開。第一個(gè)是LambdaQueryWrapper的條件寫法。.like(boolean condition, column, value)這種重載作用是當(dāng)condition為false時(shí)這個(gè)條件自動(dòng)跳過。這樣省掉了大量if判斷代碼看起來非常干凈。第二個(gè)是PageResult返回對(duì)象。Controller層不要直接把MyBatis-Plus的Page對(duì)象丟給前端因?yàn)槔锩姘艘恍┣岸瞬恍枰淖侄?。更合理的做法是封裝一個(gè)統(tǒng)一的PageResult包含total、current、size、records等字段這樣前端分頁組件取數(shù)才規(guī)范。這個(gè)習(xí)慣對(duì)以后寫接口很有幫助。3.4 桌游租借一次跨表的事務(wù)操作租借桌游是這個(gè)系統(tǒng)里最核心的業(yè)務(wù)鏈路也是最能體現(xiàn)事務(wù)能力的地方。完整邏輯是這樣的創(chuàng)建訂單時(shí)先從數(shù)據(jù)庫查出桌游信息校驗(yàn)狀態(tài)是否為上架校驗(yàn)庫存是否大于等于租借數(shù)量。然后根據(jù)桌游單價(jià)、租借小時(shí)數(shù)、數(shù)量計(jì)算出總金額檢查會(huì)員余額是否充足。都通過后生成訂單號(hào)插入訂單記錄扣減會(huì)員余額扣減桌游庫存這一切必須在一個(gè)事務(wù)里完成。庫存扣減建議不要在代碼里先查出來減完再寫回去而是用一條帶條件的UPDATE語句原子執(zhí)行Update(UPDATE board_game SET stock stock - #{num} WHERE id #{id} AND stock #{num}) int deductStock(Param(id) Long id, Param(num) Integer num);這條SQL的含義是“只有當(dāng)庫存大于等于租借數(shù)量時(shí)才扣減”并且是數(shù)據(jù)庫層面的原子操作。如果返回值是0說明庫存不足或者桌游不存在直接在Service層拋出業(yè)務(wù)異常并回滾事務(wù)。這種做法能避免兩個(gè)用戶同時(shí)下單時(shí)超賣的問題比先查再改安全得多。Service層的方法上必須加Transactional注解Transactional(rollbackFor Exception.class) public RentOrder createOrder(RentOrderCreateDTO dto) { // 1. 校驗(yàn)桌游狀態(tài)與庫存 // 2. 校驗(yàn)會(huì)員余額 // 3. 計(jì)算金額 // 4. 創(chuàng)建訂單 // 5. 扣減庫存 // 6. 扣減余額 }rollbackFor Exception.class一定要寫。Spring默認(rèn)只在拋出RuntimeException時(shí)回滾如果你拋的是普通Exception事務(wù)不會(huì)回滾到時(shí)候庫存扣了但訂單沒生成數(shù)據(jù)就亂了。這是我之前踩過的坑特別提醒一句。訂單狀態(tài)流轉(zhuǎn)也可以用枚舉管理。建議定義一個(gè)OrderStatusEnumGetter AllArgsConstructor public enum OrderStatusEnum { PENDING_PAY(0, 待支付), RENTING(1, 租借中), FINISHED(2, 已完成), CANCELLED(3, 已取消); private final Integer code; private final String desc; }所有訂單狀態(tài)修改都通過枚舉的code來操作前端拿到code后根據(jù)枚舉轉(zhuǎn)成中文。這樣代碼里不會(huì)出現(xiàn)魔法數(shù)字滿天飛的情況。4. 前端頁面從登錄頁到數(shù)據(jù)看板4.1 后臺(tái)布局與側(cè)邊欄導(dǎo)航前端我用的是Thymeleaf Bootstrap這套組合。后臺(tái)布局基本固定左側(cè)是菜單欄右側(cè)是內(nèi)容區(qū)頂部是當(dāng)前管理員信息和退出按鈕。Thymeleaf提供了強(qiáng)大的模板復(fù)用能力公共的側(cè)邊欄、頂欄、腳本引用都可以抽成fragment片段。公共片段文件一般是layout.html里面定義幾個(gè)th:fragment。各業(yè)務(wù)頁面只需要引入頁面內(nèi)容的片段并在對(duì)應(yīng)位置放自己的業(yè)務(wù)模塊。這樣做的好處是改菜單、改公共腳本只動(dòng)一個(gè)文件就夠了。側(cè)邊欄菜單的高亮狀態(tài)需要傳入當(dāng)前菜單標(biāo)識(shí)。我的做法是在Controller里往Model放一個(gè)navActive字段頁面根據(jù)這個(gè)字段判斷要激活哪個(gè)菜單。比如訪問桌游列表navActive等于game側(cè)邊欄里game對(duì)應(yīng)的a標(biāo)簽就自動(dòng)追加active樣式。別小看這個(gè)細(xì)節(jié)少了它用戶點(diǎn)來點(diǎn)去根本不知道自己在哪個(gè)模塊。4.2 表單校驗(yàn)和異步請(qǐng)求表單新增和編輯是管理系統(tǒng)最常見的交互。我只講兩個(gè)核心點(diǎn)。第一表單校驗(yàn)要兩層都做。前端校驗(yàn)用HTML自帶的required、maxlength、pattern屬性或者用jQuery Validation插件好處是響應(yīng)快輸入錯(cuò)誤立刻提示。但前端校驗(yàn)可以被繞過所以后端還需要再校驗(yàn)一次。后端校驗(yàn)最簡(jiǎn)單的方式是Controller里手動(dòng)判斷關(guān)鍵字段必要時(shí)用JSR-303注解比如NotNull、DecimalMin。第二數(shù)據(jù)提交方式。新增、編輯、刪除這些操作我建議用AJAX JSON格式交互而不是傳統(tǒng)的表單同步提交。原因很現(xiàn)實(shí)同步提交刷新的是整個(gè)頁面校驗(yàn)出錯(cuò)時(shí)用戶填了一半的數(shù)據(jù)全沒了體驗(yàn)很差。異步提交配合彈窗提示和layui或Bootstrap的模態(tài)框操作流順很多。而且統(tǒng)一返回Result對(duì)象后Controller的代碼也可以收斂得很干凈$.ajax({ url: /game/save, type: POST, contentType: application/json, data: JSON.stringify(formData), success: function(res) { if (res.code 200) { layer.msg(保存成功); // 刷新表格 } else { layer.msg(res.msg, {icon: 2}); } } });4.3 ECharts統(tǒng)計(jì)看板統(tǒng)計(jì)看板是一個(gè)很能提升系統(tǒng)檔次的模塊而且實(shí)現(xiàn)起來并不復(fù)雜。桌游管理系統(tǒng)看板我建議放三個(gè)核心圖近7日訂單金額趨勢(shì)用折線圖、桌游熱度排行用橫向柱狀圖、會(huì)員等級(jí)分布用餅圖。數(shù)據(jù)來源是后端統(tǒng)計(jì)分析接口。比如統(tǒng)計(jì)近7日營(yíng)收SQL可以按天分組SELECT DATE(create_time) AS day, SUM(total_amount) AS amount FROM rent_order WHERE status 2 AND create_time DATE_SUB(CURDATE(), INTERVAL 6 DAY) GROUP BY DATE(create_time) ORDER BY day;Controller把查詢結(jié)果轉(zhuǎn)成ECharts需要的格式返回前端通過Thymeleaf內(nèi)聯(lián)腳本接收并渲染。這里有個(gè)容易踩的坑時(shí)間格式化問題。傳給圖表的數(shù)據(jù)如果是標(biāo)準(zhǔn)的LocalDateTime對(duì)象默認(rèn)序列化出來可能是一長(zhǎng)串?dāng)?shù)字或帶T的格式建議在后端統(tǒng)一格式化成yyyy-MM-dd或yyyy-MM-dd HH:mm:ss字符串再返回省去前端處理麻煩。ECharts初始化的時(shí)機(jī)也要注意。頁面數(shù)據(jù)沒加載完或者容器寬度為0時(shí)就初始化圖表經(jīng)常變成一堆擁擠的圖形。建議在window.onload或$(document).ready之后再初始化同時(shí)給圖表容器設(shè)置固定高度。5. 從零搭建開發(fā)環(huán)境到服務(wù)器部署5.1 本機(jī)開發(fā)環(huán)境怎么配開發(fā)這套系統(tǒng)本機(jī)需要準(zhǔn)備這些軟件JDK 1.8、Maven 3.6、MySQL 5.7/8.0、IDEA。這幾個(gè)東西版本匹配很重要JDK推薦1.8對(duì)應(yīng)SpringBoot 2.7.x完全沒有問題。如果你裝了JDK 17甚至更高有些老版本的依賴可能會(huì)不兼容所以Java環(huán)境不是越高越好要看項(xiàng)目基于什么版本。MySQL安裝后要注意字符集設(shè)置。建庫時(shí)顯式指定utf8mb4CREATE DATABASE boardgame_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;utf8mb4兼容完整的UTF-8編碼能存emoji避免一些生僻字或特殊符號(hào)插入數(shù)據(jù)庫時(shí)報(bào)錯(cuò)。MySQL 8.0默認(rèn)字符集已經(jīng)是utf8mb4但保險(xiǎn)起見建庫時(shí)還是明確寫出來。IDEA建議直接安裝Ultimate版因?yàn)樯鐓^(qū)版不直接支持Spring Initializr創(chuàng)建項(xiàng)目但我一般建議直接到Spring官網(wǎng)的start.spring.io生成項(xiàng)目再導(dǎo)入這樣社區(qū)版也能用。導(dǎo)入項(xiàng)目后先讓Maven把依賴下載完再配置運(yùn)行環(huán)境。5.2 數(shù)據(jù)庫初始化和項(xiàng)目導(dǎo)入數(shù)據(jù)庫腳本文件可以直接用建表SQL。為了演示方便可以在腳本里預(yù)置幾套桌游數(shù)據(jù)和管理員賬號(hào)這樣項(xiàng)目一啟動(dòng)頁面就有內(nèi)容不用費(fèi)勁一條條新增。配置數(shù)據(jù)源時(shí)我把最常用的一套application.yml貼出來server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/boardgame_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: root password: 123456 thymeleaf: cache: false mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0這段配置里有幾個(gè)關(guān)鍵點(diǎn)我需要多說一句。連接串里的serverTimezoneAsia/Shanghai是必須寫的MySQL 8.0默認(rèn)時(shí)區(qū)設(shè)置經(jīng)常導(dǎo)致數(shù)據(jù)庫連接報(bào)錯(cuò)。allowPublicKeyRetrievaltrue也是用MySQL 8.0時(shí)經(jīng)常需要的參數(shù)否則會(huì)報(bào)Public Key Retrieval is not allowed。thymeleaf的cache: false很重要開發(fā)時(shí)改了模板不用重啟就能看到效果。mybatis-plus的log-impl輸出SQL日志排查問題時(shí)能直觀看到每條語句執(zhí)行情況。5.3 打包部署jar包與Nginx本地開發(fā)沒問題后部署到服務(wù)器是另一個(gè)常見環(huán)節(jié)。打包命令非常簡(jiǎn)單mvn clean package如果用的是IDEA也可以直接在Maven面板里雙擊package。打包完成后target目錄下會(huì)生成一個(gè)spring-boot-bootstrapped的jar包。這里有個(gè)常見的坑有些同學(xué)打包后運(yùn)行報(bào)“找不到主類”大概率是沒有配置spring-boot-maven-plugin的mainClass或者是項(xiàng)目里存在多個(gè)SpringBootApplication啟動(dòng)類。這個(gè)問題排查時(shí)去Maven插件配置里確認(rèn)一下即可。服務(wù)器上運(yùn)行jar包常規(guī)姿勢(shì)是用nohup后臺(tái)啟動(dòng)nohup java -jar boardgame-system.jar --server.port8080 app.log 21 這樣ssh斷開后程序也不會(huì)停。如果你想做得更專業(yè)可以用systemd寫一個(gè)服務(wù)文件支持開機(jī)自啟和自動(dòng)重啟。但對(duì)于畢業(yè)設(shè)計(jì)和中小項(xiàng)目nohup方案已經(jīng)夠用。端口和外部訪問這塊也要提前規(guī)劃。如果你的服務(wù)器上只有這一個(gè)應(yīng)用8080端口直接開放就行。但如果還有別的項(xiàng)目或者80端口被占用了建議用Nginx做反向代理把80端口轉(zhuǎn)發(fā)到8080順便還能代理靜態(tài)資源。生產(chǎn)環(huán)境我習(xí)慣把前端靜態(tài)資源和后端接口都通過一個(gè)域名入口進(jìn)來省得瀏覽器里帶端口號(hào)也方便以后上HTTPS。6. 常見問題排查與避坑手冊(cè)6.1 數(shù)據(jù)庫連接報(bào)錯(cuò)這一類報(bào)錯(cuò)在開發(fā)期出現(xiàn)頻率最高。我隨便列幾個(gè)最常見的場(chǎng)景啟動(dòng)時(shí)報(bào)Access denied for user rootlocalhost說明用戶名或密碼不對(duì)去application.yml里核對(duì)。報(bào)Unknown database boardgame_db說明數(shù)據(jù)庫沒建或者名字寫錯(cuò)。報(bào)Public Key Retrieval is not allowed這是MySQL 8.0的加密連接特性導(dǎo)致的在連接串加allowPublicKeyRetrievaltrue就能解決。報(bào)The server time zone value說明時(shí)區(qū)沒配置加上serverTimezoneAsia/Shanghai。這些報(bào)錯(cuò)信息其實(shí)已經(jīng)把問題原因說得很清楚但很多同學(xué)一看到一大段英文就慌。我建議遇到報(bào)錯(cuò)先看最下面幾行也就是Caused by開頭的部分那才是真正的根因。6.2 啟動(dòng)失敗的幾類原因啟動(dòng)失敗除了數(shù)據(jù)庫問題還有一類是端口被占用。SpringBoot默認(rèn)端口是8080如果你本機(jī)已經(jīng)跑了別的服務(wù)占用了8080啟動(dòng)日志會(huì)報(bào)Web server failed to start這時(shí)要么改server.port要么用命令查端口占用并殺掉對(duì)應(yīng)進(jìn)程。還有一類是依賴沖突或版本不對(duì)。比如SpringBoot 3.x的項(xiàng)目強(qiáng)行使用了為2.x寫的MyBatis-Plus配置類啟動(dòng)時(shí)會(huì)出現(xiàn)找不到類或者方法簽名不一致的問題。我的建議是一開始就鎖定SpringBoot 2.7.x和MyBatis-Plus 3.5.x的組合不要混用。版本不是越新越好穩(wěn)定的組合才能讓你把精力放在業(yè)務(wù)邏輯上。6.3 JSON序列化和時(shí)間格式的坑后端返回LocalDateTime類型數(shù)據(jù)時(shí)默認(rèn)序列化結(jié)果往往是“2024-03-18T10:24:30”這種帶T的格式前端展示起來很不好看。解決辦法有兩個(gè)。一是在實(shí)體類的日期字段上加注解JsonFormat(timezone GMT8, pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime createTime;timezone GMT8必須寫否則序列化出來可能和數(shù)據(jù)庫時(shí)間相差8小時(shí)。第二種是全局配置Jackson的ObjectMapper統(tǒng)一處理所有日期字段。兩種方案對(duì)比局部注解適合少量字段全局配置適合整個(gè)項(xiàng)目日期字段多的情況。我建議用全局配置省事且統(tǒng)一。6.4 給畢設(shè)和項(xiàng)目的三點(diǎn)建議做了這么多項(xiàng)目最后分享幾個(gè)掏心窩的建議。第一先花時(shí)間把數(shù)據(jù)庫設(shè)計(jì)好再動(dòng)代碼。我見過太多項(xiàng)目做著做著要加字段、改表名連帶著Service層邏輯全部重寫。設(shè)計(jì)階段多花一天開發(fā)階段能省一周。表關(guān)系、狀態(tài)枚舉、金額精度這些東西一定要在一開始就想清楚。第二Controller要保持薄。Controller只做參數(shù)接收、調(diào)用Service、返回結(jié)果業(yè)務(wù)邏輯不要寫在Controller里。很多人覺得這樣多寫一層很麻煩但項(xiàng)目一旦變大你就會(huì)發(fā)現(xiàn)這是唯一能保持代碼清爽的方式。我見過把庫存扣減寫在Controller里的項(xiàng)目后來光排查并發(fā)問題就花了兩周。第三項(xiàng)目要能在全新的環(huán)境里跑起來。交付項(xiàng)目時(shí)數(shù)據(jù)庫初始化腳本、配置說明、啟動(dòng)說明、部署文檔這幾樣缺一不可。我每次開發(fā)完都會(huì)在自己的電腦上用干凈的環(huán)境走一遍部署流程模擬第一次運(yùn)行的人會(huì)遇到什么問題。這個(gè)習(xí)慣幫我避免過很多次“在我電腦上明明好的”的尷尬。桌游信息管理系統(tǒng)這類項(xiàng)目技術(shù)點(diǎn)不算高深但它在業(yè)務(wù)鏈路上包含了登錄鑒權(quán)、分頁查詢、文件上傳、跨表事務(wù)、狀態(tài)機(jī)、數(shù)據(jù)統(tǒng)計(jì)等真實(shí)項(xiàng)目中幾乎必用的能力。把這套流程完整走一遍你對(duì)SpringBoot和MyBatis-Plus的理解會(huì)比看十遍教程都深刻。做的時(shí)候不用追求炫技先把核心鏈路跑通再一步步完善細(xì)節(jié)你會(huì)發(fā)現(xiàn)這個(gè)項(xiàng)目帶給你的收獲遠(yuǎn)比想象中多。 SpringBoot實(shí)戰(zhàn)：從零搭建桌游信息管理系統(tǒng)
去年幫一個(gè)學(xué)弟復(fù)盤他的畢業(yè)設(shè)計(jì)題目正好就是“基于SpringBoot的桌游信息管理系統(tǒng)”。乍一看這東西平平無奇無非是登錄、增刪改查、統(tǒng)計(jì)報(bào)表這幾板斧。但真正上手之后才發(fā)現(xiàn)桌游店的業(yè)務(wù)里藏著不少值得細(xì)摳的點(diǎn)桌游庫存怎么扣減、訂單狀態(tài)怎么流轉(zhuǎn)、會(huì)員余額和押金怎么處理、租借時(shí)長(zhǎng)怎么計(jì)費(fèi)。把這些邏輯理清楚項(xiàng)目做出來才有含金量而不是一個(gè)空殼CRUD。這篇文章打算把這個(gè)系統(tǒng)的設(shè)計(jì)思路、數(shù)據(jù)庫建模、后端實(shí)現(xiàn)、前端頁面、部署調(diào)試全過程拆開講一遍。適合三類人看正在做Java畢業(yè)設(shè)計(jì)、選題是管理系統(tǒng)的同學(xué)剛學(xué)完SpringBoot想找一個(gè)完整項(xiàng)目練手的初級(jí)開發(fā)者確實(shí)有桌游吧信息化需求、想自己搞個(gè)小工具的經(jīng)營(yíng)人員。我會(huì)盡量寫得能直接抄作業(yè)從環(huán)境搭建到核心代碼再到排查Bug的經(jīng)驗(yàn)全部攤開來說。1. 項(xiàng)目概覽與技術(shù)選型為什么大家都選SpringBoot1.1 桌游店管的是什么需求梳理做系統(tǒng)之前先別急著寫代碼得先弄明白“桌游信息管理系統(tǒng)”到底要管什么。我接觸過的桌游吧日常運(yùn)營(yíng)至少有這幾塊固定動(dòng)作第一桌游的商品化管理。店里一般有成百上千套桌游名字、類型、適合人數(shù)、單局時(shí)長(zhǎng)、每小時(shí)租金、庫存數(shù)量、損壞下架狀態(tài)這些信息靠Excel記錄特別容易亂需要一套能增刪改查和模糊搜索的商品模塊。第二會(huì)員和儲(chǔ)值管理。桌游吧大多靠辦卡鎖定回頭客會(huì)員的手機(jī)號(hào)、余額、積分、等級(jí)需要維護(hù)。這里有個(gè)常見需求是“桌游租借費(fèi)用從會(huì)員余額里扣”所以會(huì)員余額字段必須和訂單模塊聯(lián)動(dòng)。第三租借與訂單管理。這是整個(gè)系統(tǒng)的核心業(yè)務(wù)。顧客到店選一套桌游系統(tǒng)要生成一個(gè)租借訂單記錄桌游、時(shí)長(zhǎng)、金額、押金、開始時(shí)間、結(jié)束時(shí)間并實(shí)時(shí)更新桌游庫存。訂單不能只是新增、刪除還得有“租借中、已完成、已取消、逾期未還”這類狀態(tài)流轉(zhuǎn)。第四簡(jiǎn)單的統(tǒng)計(jì)報(bào)表。老板最關(guān)心的其實(shí)是“今天進(jìn)賬多少、哪幾款桌游最熱門、最近會(huì)員增長(zhǎng)情況”。所以系統(tǒng)最好帶一個(gè)數(shù)據(jù)看板用圖表把訂單金額趨勢(shì)、桌游熱度排行展示出來。這就是需求清單。管理系統(tǒng)的功能基本都由業(yè)務(wù)倒推出來千萬不要想到哪寫到哪否則后面改起來非常痛苦。1.2 技術(shù)棧選型SpringBoot MyBatis-Plus MySQL Thymeleaf這套系統(tǒng)的技術(shù)棧我很推薦一個(gè)成熟的組合SpringBoot 2.7.x MyBatis-Plus MySQL 5.7/8.0 Thymeleaf Bootstrap ECharts。原因很簡(jiǎn)單每一層都有明確替代方案但這個(gè)組合是綜合上手成本、資料豐富度、調(diào)試便利性之后最穩(wěn)妥的。SpringBoot的優(yōu)勢(shì)不用多吹內(nèi)嵌Tomcat、自動(dòng)裝配、約定大于配置能省掉傳統(tǒng)SSM里一長(zhǎng)串的XML配置。MyBatis-Plus相比原生MyBatis最大的價(jià)值是內(nèi)置了通用Mapper和通用Service單表CRUD幾乎不用手寫SQL分頁插件也用得順手。配合LambdaQueryWrapper條件查詢寫起來非常直觀對(duì)趕工期的項(xiàng)目來說極其友好。前端為什么選Thymeleaf而不是前后端分離的Vue核心原因是這套系統(tǒng)是單體應(yīng)用不需要單獨(dú)起后端接口服務(wù)。用Thymeleaf做服務(wù)端渲染頁面直接通過模板引擎拿到數(shù)據(jù)部署時(shí)一個(gè)jar包搞定不用處理跨域、不用配置Nginx轉(zhuǎn)發(fā)多個(gè)服務(wù)對(duì)畢業(yè)設(shè)計(jì)和中小型內(nèi)部管理系統(tǒng)來說交付和維護(hù)成本最低。如果你已經(jīng)熟練Vue也可以改成SpringBoot寫接口 Vue頁面但復(fù)雜度會(huì)明顯上升不是這個(gè)項(xiàng)目的最優(yōu)解。1.3 功能模塊全景圖把需求落到功能模塊上這套系統(tǒng)我建議這樣劃分管理員模塊登錄、退出、修改密碼、管理員信息維護(hù)。桌游分類模塊分類列表、新增、編輯、刪除用于給桌游打標(biāo)簽。桌游信息模塊桌游列表查詢、條件搜索、添加桌游、編輯、上下架、刪除封面圖上傳。會(huì)員管理模塊會(huì)員列表、新增會(huì)員、余額充值、積分調(diào)整、刪除/禁用。訂單管理模塊創(chuàng)建租借訂單、歸還結(jié)算、訂單狀態(tài)流轉(zhuǎn)、訂單條件查詢。統(tǒng)計(jì)看板模塊今日營(yíng)收、訂單數(shù)量、桌游熱度排行、近7日訂單金額趨勢(shì)。模塊之間不是孤立的。創(chuàng)建訂單要扣桌游庫存、算金額要讀桌游單價(jià)和時(shí)長(zhǎng)、支付要扣會(huì)員余額、歸還計(jì)算要更新訂單狀態(tài)和桌游庫存。這些都是跨表的業(yè)務(wù)操作必須放在Service層用事務(wù)串起來不能拆開來各寫各的。2. 數(shù)據(jù)庫設(shè)計(jì)先把地基砸實(shí)2.1 六張核心表怎么建數(shù)據(jù)庫設(shè)計(jì)是這套系統(tǒng)的地基。我見過太多人一上來先寫代碼結(jié)果表結(jié)構(gòu)建得七零八落后面業(yè)務(wù)邏輯越寫越擰巴。這里我直接給出一個(gè)可落地的建表思路。核心表分六張管理員表、桌游分類表、桌游信息表、會(huì)員表、租借訂單表、訂單明細(xì)表。考慮到畢設(shè)復(fù)雜度適中訂單明細(xì)表可以先不拆一張訂單對(duì)應(yīng)一套桌游即可如果后續(xù)要支持一個(gè)訂單租多套桌游再拆訂單明細(xì)表。桌游信息表是最核心的表字段設(shè)置如下CREATE TABLE board_game ( id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT 主鍵, game_name VARCHAR(100) NOT NULL COMMENT 桌游名稱, type_id BIGINT NOT NULL COMMENT 分類ID, min_players INT NOT NULL DEFAULT 2 COMMENT 最少游玩人數(shù), max_players INT NOT NULL DEFAULT 4 COMMENT 最多游玩人數(shù), play_duration DECIMAL(4,1) DEFAULT 1.0 COMMENT 單局預(yù)計(jì)時(shí)長(zhǎng)(小時(shí)), price DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT 每小時(shí)租金, stock INT NOT NULL DEFAULT 0 COMMENT 當(dāng)前庫存數(shù)量, status TINYINT NOT NULL DEFAULT 1 COMMENT 狀態(tài):1上架 0下架, cover_url VARCHAR(255) DEFAULT NULL COMMENT 封面圖地址, description TEXT COMMENT 桌游玩法簡(jiǎn)介, create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 創(chuàng)建時(shí)間, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新時(shí)間 ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT桌游信息表;租借訂單表設(shè)計(jì)的時(shí)候要特別注意不要直接用order做表名因?yàn)閛rder是SQL關(guān)鍵字容易埋坑。建議用rent_orderCREATE TABLE rent_order ( id BIGINT AUTO_INCREMENT PRIMARY KEY, order_no VARCHAR(32) NOT NULL UNIQUE COMMENT 訂單號(hào), member_id BIGINT NOT NULL COMMENT 會(huì)員ID, board_game_id BIGINT NOT NULL COMMENT 桌游ID, quantity INT NOT NULL DEFAULT 1 COMMENT 租借數(shù)量, total_amount DECIMAL(10,2) NOT NULL COMMENT 訂單總金額, deposit DECIMAL(10,2) DEFAULT 0.00 COMMENT 押金, start_time DATETIME NOT NULL COMMENT 租借開始時(shí)間, end_time DATETIME NOT NULL COMMENT 預(yù)計(jì)歸還時(shí)間, status TINYINT NOT NULL DEFAULT 0 COMMENT 狀態(tài):0待支付 1租借中 2已完成 3已取消, remark VARCHAR(255) COMMENT 備注, create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT 創(chuàng)建時(shí)間 ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT租借訂單表;會(huì)員表和管理員表相對(duì)簡(jiǎn)單會(huì)員表需要包含member_no、name、phone、balance、points、level等字段。這里我特別加了一個(gè)member_no會(huì)員編號(hào)雖然手機(jī)號(hào)也能唯一標(biāo)識(shí)會(huì)員但單獨(dú)編號(hào)在后期對(duì)接小程序、會(huì)員卡時(shí)更方便。2.2 字段類型和狀態(tài)值的取舍建表時(shí)最容易被忽略的是字段類型的選擇。我舉兩個(gè)最常見的例子金額字段一定要用DECIMAL不能用FLOAT或DOUBLE。因?yàn)槎M(jìn)制浮點(diǎn)數(shù)在計(jì)算0.10.2這類場(chǎng)景會(huì)出現(xiàn)精度誤差而金額誤差是絕對(duì)不能接受的。DECIMAL(10,2)可以存最大10億的金額對(duì)于桌游吧來說完全足夠。狀態(tài)字段建議用TINYINT不要用VARCHAR存中文。比如訂單狀態(tài)用0、1、2、3表示在Java后端定義一個(gè)枚舉類代碼里只操作枚舉展示到頁面前再轉(zhuǎn)換成對(duì)應(yīng)的中文文案。這樣做的好處是數(shù)據(jù)庫體積小、查詢效率高、后端判斷邏輯不會(huì)因?yàn)橹杏⑽淖址町惓鰡栴}。雖然看起來多寫了幾行轉(zhuǎn)換代碼但項(xiàng)目的健壯性會(huì)明顯提升。2.3 外鍵到底建不建我的建議是不要建物理外鍵用邏輯外鍵。也就是在業(yè)務(wù)表里存關(guān)聯(lián)表的ID但不在數(shù)據(jù)庫層面強(qiáng)制約束。原因有幾點(diǎn)物理外鍵會(huì)讓刪除操作變得非常麻煩你想刪一個(gè)分類結(jié)果數(shù)據(jù)庫提示有桌游還在引用它必須先處理子表數(shù)據(jù)高并發(fā)場(chǎng)景下外鍵約束還會(huì)引入額外的鎖開銷而且大多數(shù)管理系統(tǒng)根本不依賴數(shù)據(jù)庫來保證完整性而是靠Service層代碼控制。既然不建物理外鍵那就要在代碼里兜底。比如刪除分類前先查詢?cè)摲诸愊率欠襁€有桌游有就禁止刪除創(chuàng)建訂單前校驗(yàn)會(huì)員和桌游是否存在校驗(yàn)庫存是否充足。這些邏輯放在Service層比依賴數(shù)據(jù)庫約束更靈活報(bào)錯(cuò)信息也能寫得更友好。3. 后端實(shí)現(xiàn)登錄、CRUD與庫存扣減的細(xì)節(jié)3.1 項(xiàng)目骨架與核心依賴配置后端代碼的包結(jié)構(gòu)我建議按功能模塊劃分而不是按技術(shù)類型劃分。按照controller、service、mapper這種分法到后期類一多就亂成一鍋粥。我習(xí)慣這樣組織com.example.boardgame ├── controller # 控制器只做參數(shù)接收和結(jié)果封裝 ├── service # 業(yè)務(wù)邏輯接口 ├── service.impl # 業(yè)務(wù)實(shí)現(xiàn)事務(wù)在這里 ├── mapper # MyBatis-Plus的Mapper接口 ├── entity # 數(shù)據(jù)庫實(shí)體類 ├── dto # 前端傳輸對(duì)象 ├── config # 配置類 ├── interceptor # 攔截器 └── common # 通用返回結(jié)果、異常處理、枚舉工程創(chuàng)建時(shí)pom.xml里最核心的依賴就這么幾個(gè)dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency這里有個(gè)細(xì)節(jié)如果你用的是SpringBoot 3.x依賴名稱和兼容性都有變化MySQL驅(qū)動(dòng)類名也從com.mysql.jdbc.Driver改成了com.mysql.cj.jdbc.Driver。我建議初學(xué)者鎖死SpringBoot 2.7.x版本相關(guān)資料最多、踩坑最容易被搜索引擎找到。3.2 登錄鑒權(quán)攔截器 Session登錄功能每個(gè)管理系統(tǒng)都有但實(shí)現(xiàn)方式有不少講究。最簡(jiǎn)單的方案是用Session保存登錄狀態(tài)配合Spring MVC攔截器統(tǒng)一校驗(yàn)。不用引入Spring Security或者JWT因?yàn)檫@套系統(tǒng)是服務(wù)端渲染的單體應(yīng)用用Session完全夠而且邏輯更直觀。攔截器代碼長(zhǎng)這樣Component public class LoginInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { HttpSession session request.getSession(); if (session.getAttribute(admin) ! null) { return true; } // 判斷是否為AJAX請(qǐng)求 String xrw request.getHeader(X-Requested-With); if (XMLHttpRequest.equals(xrw)) { response.setContentType(application/json;charsetutf-8); response.getWriter().write({\code\:401,\msg\:\登錄已過期請(qǐng)重新登錄\}); } else { response.sendRedirect(/login); } return false; } }然后注冊(cè)攔截器排除登錄接口和靜態(tài)資源路徑Configuration public class WebConfig implements WebMvcConfigurer { Resource private LoginInterceptor loginInterceptor; Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(loginInterceptor) .addPathPatterns(/**) .excludePathPatterns(/login, /css/**, /js/**, /images/**, /fonts/**); } }為什么要把AJAX請(qǐng)求和普通頁面請(qǐng)求分開處理因?yàn)轫撁嫣D(zhuǎn)和異步請(qǐng)求對(duì)未登錄狀態(tài)的處理方式不一樣。普通頁面直接重定向到登錄頁用戶能看到但AJAX請(qǐng)求如果也返回302前端拿到的是一個(gè)登錄頁的HTML解析數(shù)據(jù)就會(huì)報(bào)錯(cuò)。所以攔截器里要做一次區(qū)分。3.3 分頁查詢與通用增刪改查MyBatis-Plus最大的好處就是單表CRUD基本不用手寫SQL。實(shí)體類繼承BaseMapperService繼承IService就擁有了最基礎(chǔ)的增刪改查方法。但實(shí)際項(xiàng)目中肯定要帶條件查詢和分頁這就要用到它的分頁插件。分頁插件配置很簡(jiǎn)單Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }配置好之后Service層的分頁查詢可以這樣寫public PageResultBoardGame pageGames(int current, int size, String keyword, Long typeId) { PageBoardGame page new Page(current, size); LambdaQueryWrapperBoardGame wrapper new LambdaQueryWrapper(); wrapper.like(StringUtils.hasText(keyword), BoardGame::getGameName, keyword) .eq(typeId ! null, BoardGame::getTypeId, typeId) .orderByDesc(BoardGame::getCreateTime); PageBoardGame result boardGameMapper.selectPage(page, wrapper); return PageResult.of(result); }這里有兩個(gè)地方值得展開。第一個(gè)是LambdaQueryWrapper的條件寫法。.like(boolean condition, column, value)這種重載作用是當(dāng)condition為false時(shí)這個(gè)條件自動(dòng)跳過。這樣省掉了大量if判斷代碼看起來非常干凈。第二個(gè)是PageResult返回對(duì)象。Controller層不要直接把MyBatis-Plus的Page對(duì)象丟給前端因?yàn)槔锩姘艘恍┣岸瞬恍枰淖侄?。更合理的做法是封裝一個(gè)統(tǒng)一的PageResult包含total、current、size、records等字段這樣前端分頁組件取數(shù)才規(guī)范。這個(gè)習(xí)慣對(duì)以后寫接口很有幫助。3.4 桌游租借一次跨表的事務(wù)操作租借桌游是這個(gè)系統(tǒng)里最核心的業(yè)務(wù)鏈路也是最能體現(xiàn)事務(wù)能力的地方。完整邏輯是這樣的創(chuàng)建訂單時(shí)先從數(shù)據(jù)庫查出桌游信息校驗(yàn)狀態(tài)是否為上架校驗(yàn)庫存是否大于等于租借數(shù)量。然后根據(jù)桌游單價(jià)、租借小時(shí)數(shù)、數(shù)量計(jì)算出總金額檢查會(huì)員余額是否充足。都通過后生成訂單號(hào)插入訂單記錄扣減會(huì)員余額扣減桌游庫存這一切必須在一個(gè)事務(wù)里完成。庫存扣減建議不要在代碼里先查出來減完再寫回去而是用一條帶條件的UPDATE語句原子執(zhí)行Update(UPDATE board_game SET stock stock - #{num} WHERE id #{id} AND stock #{num}) int deductStock(Param(id) Long id, Param(num) Integer num);這條SQL的含義是“只有當(dāng)庫存大于等于租借數(shù)量時(shí)才扣減”并且是數(shù)據(jù)庫層面的原子操作。如果返回值是0說明庫存不足或者桌游不存在直接在Service層拋出業(yè)務(wù)異常并回滾事務(wù)。這種做法能避免兩個(gè)用戶同時(shí)下單時(shí)超賣的問題比先查再改安全得多。Service層的方法上必須加Transactional注解Transactional(rollbackFor Exception.class) public RentOrder createOrder(RentOrderCreateDTO dto) { // 1. 校驗(yàn)桌游狀態(tài)與庫存 // 2. 校驗(yàn)會(huì)員余額 // 3. 計(jì)算金額 // 4. 創(chuàng)建訂單 // 5. 扣減庫存 // 6. 扣減余額 }rollbackFor Exception.class一定要寫。Spring默認(rèn)只在拋出RuntimeException時(shí)回滾如果你拋的是普通Exception事務(wù)不會(huì)回滾到時(shí)候庫存扣了但訂單沒生成數(shù)據(jù)就亂了。這是我之前踩過的坑特別提醒一句。訂單狀態(tài)流轉(zhuǎn)也可以用枚舉管理。建議定義一個(gè)OrderStatusEnumGetter AllArgsConstructor public enum OrderStatusEnum { PENDING_PAY(0, 待支付), RENTING(1, 租借中), FINISHED(2, 已完成), CANCELLED(3, 已取消); private final Integer code; private final String desc; }所有訂單狀態(tài)修改都通過枚舉的code來操作前端拿到code后根據(jù)枚舉轉(zhuǎn)成中文。這樣代碼里不會(huì)出現(xiàn)魔法數(shù)字滿天飛的情況。4. 前端頁面從登錄頁到數(shù)據(jù)看板4.1 后臺(tái)布局與側(cè)邊欄導(dǎo)航前端我用的是Thymeleaf Bootstrap這套組合。后臺(tái)布局基本固定左側(cè)是菜單欄右側(cè)是內(nèi)容區(qū)頂部是當(dāng)前管理員信息和退出按鈕。Thymeleaf提供了強(qiáng)大的模板復(fù)用能力公共的側(cè)邊欄、頂欄、腳本引用都可以抽成fragment片段。公共片段文件一般是layout.html里面定義幾個(gè)th:fragment。各業(yè)務(wù)頁面只需要引入頁面內(nèi)容的片段并在對(duì)應(yīng)位置放自己的業(yè)務(wù)模塊。這樣做的好處是改菜單、改公共腳本只動(dòng)一個(gè)文件就夠了。側(cè)邊欄菜單的高亮狀態(tài)需要傳入當(dāng)前菜單標(biāo)識(shí)。我的做法是在Controller里往Model放一個(gè)navActive字段頁面根據(jù)這個(gè)字段判斷要激活哪個(gè)菜單。比如訪問桌游列表navActive等于game側(cè)邊欄里game對(duì)應(yīng)的a標(biāo)簽就自動(dòng)追加active樣式。別小看這個(gè)細(xì)節(jié)少了它用戶點(diǎn)來點(diǎn)去根本不知道自己在哪個(gè)模塊。4.2 表單校驗(yàn)和異步請(qǐng)求表單新增和編輯是管理系統(tǒng)最常見的交互。我只講兩個(gè)核心點(diǎn)。第一表單校驗(yàn)要兩層都做。前端校驗(yàn)用HTML自帶的required、maxlength、pattern屬性或者用jQuery Validation插件好處是響應(yīng)快輸入錯(cuò)誤立刻提示。但前端校驗(yàn)可以被繞過所以后端還需要再校驗(yàn)一次。后端校驗(yàn)最簡(jiǎn)單的方式是Controller里手動(dòng)判斷關(guān)鍵字段必要時(shí)用JSR-303注解比如NotNull、DecimalMin。第二數(shù)據(jù)提交方式。新增、編輯、刪除這些操作我建議用AJAX JSON格式交互而不是傳統(tǒng)的表單同步提交。原因很現(xiàn)實(shí)同步提交刷新的是整個(gè)頁面校驗(yàn)出錯(cuò)時(shí)用戶填了一半的數(shù)據(jù)全沒了體驗(yàn)很差。異步提交配合彈窗提示和layui或Bootstrap的模態(tài)框操作流順很多。而且統(tǒng)一返回Result對(duì)象后Controller的代碼也可以收斂得很干凈$.ajax({ url: /game/save, type: POST, contentType: application/json, data: JSON.stringify(formData), success: function(res) { if (res.code 200) { layer.msg(保存成功); // 刷新表格 } else { layer.msg(res.msg, {icon: 2}); } } });4.3 ECharts統(tǒng)計(jì)看板統(tǒng)計(jì)看板是一個(gè)很能提升系統(tǒng)檔次的模塊而且實(shí)現(xiàn)起來并不復(fù)雜。桌游管理系統(tǒng)看板我建議放三個(gè)核心圖近7日訂單金額趨勢(shì)用折線圖、桌游熱度排行用橫向柱狀圖、會(huì)員等級(jí)分布用餅圖。數(shù)據(jù)來源是后端統(tǒng)計(jì)分析接口。比如統(tǒng)計(jì)近7日營(yíng)收SQL可以按天分組SELECT DATE(create_time) AS day, SUM(total_amount) AS amount FROM rent_order WHERE status 2 AND create_time DATE_SUB(CURDATE(), INTERVAL 6 DAY) GROUP BY DATE(create_time) ORDER BY day;Controller把查詢結(jié)果轉(zhuǎn)成ECharts需要的格式返回前端通過Thymeleaf內(nèi)聯(lián)腳本接收并渲染。這里有個(gè)容易踩的坑時(shí)間格式化問題。傳給圖表的數(shù)據(jù)如果是標(biāo)準(zhǔn)的LocalDateTime對(duì)象默認(rèn)序列化出來可能是一長(zhǎng)串?dāng)?shù)字或帶T的格式建議在后端統(tǒng)一格式化成yyyy-MM-dd或yyyy-MM-dd HH:mm:ss字符串再返回省去前端處理麻煩。ECharts初始化的時(shí)機(jī)也要注意。頁面數(shù)據(jù)沒加載完或者容器寬度為0時(shí)就初始化圖表經(jīng)常變成一堆擁擠的圖形。建議在window.onload或$(document).ready之后再初始化同時(shí)給圖表容器設(shè)置固定高度。5. 從零搭建開發(fā)環(huán)境到服務(wù)器部署5.1 本機(jī)開發(fā)環(huán)境怎么配開發(fā)這套系統(tǒng)本機(jī)需要準(zhǔn)備這些軟件JDK 1.8、Maven 3.6、MySQL 5.7/8.0、IDEA。這幾個(gè)東西版本匹配很重要JDK推薦1.8對(duì)應(yīng)SpringBoot 2.7.x完全沒有問題。如果你裝了JDK 17甚至更高有些老版本的依賴可能會(huì)不兼容所以Java環(huán)境不是越高越好要看項(xiàng)目基于什么版本。MySQL安裝后要注意字符集設(shè)置。建庫時(shí)顯式指定utf8mb4CREATE DATABASE boardgame_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;utf8mb4兼容完整的UTF-8編碼能存emoji避免一些生僻字或特殊符號(hào)插入數(shù)據(jù)庫時(shí)報(bào)錯(cuò)。MySQL 8.0默認(rèn)字符集已經(jīng)是utf8mb4但保險(xiǎn)起見建庫時(shí)還是明確寫出來。IDEA建議直接安裝Ultimate版因?yàn)樯鐓^(qū)版不直接支持Spring Initializr創(chuàng)建項(xiàng)目但我一般建議直接到Spring官網(wǎng)的start.spring.io生成項(xiàng)目再導(dǎo)入這樣社區(qū)版也能用。導(dǎo)入項(xiàng)目后先讓Maven把依賴下載完再配置運(yùn)行環(huán)境。5.2 數(shù)據(jù)庫初始化和項(xiàng)目導(dǎo)入數(shù)據(jù)庫腳本文件可以直接用建表SQL。為了演示方便可以在腳本里預(yù)置幾套桌游數(shù)據(jù)和管理員賬號(hào)這樣項(xiàng)目一啟動(dòng)頁面就有內(nèi)容不用費(fèi)勁一條條新增。配置數(shù)據(jù)源時(shí)我把最常用的一套application.yml貼出來server: port: 8080 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/boardgame_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalseallowPublicKeyRetrievaltrue username: root password: 123456 thymeleaf: cache: false mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0這段配置里有幾個(gè)關(guān)鍵點(diǎn)我需要多說一句。連接串里的serverTimezoneAsia/Shanghai是必須寫的MySQL 8.0默認(rèn)時(shí)區(qū)設(shè)置經(jīng)常導(dǎo)致數(shù)據(jù)庫連接報(bào)錯(cuò)。allowPublicKeyRetrievaltrue也是用MySQL 8.0時(shí)經(jīng)常需要的參數(shù)否則會(huì)報(bào)Public Key Retrieval is not allowed。thymeleaf的cache: false很重要開發(fā)時(shí)改了模板不用重啟就能看到效果。mybatis-plus的log-impl輸出SQL日志排查問題時(shí)能直觀看到每條語句執(zhí)行情況。5.3 打包部署jar包與Nginx本地開發(fā)沒問題后部署到服務(wù)器是另一個(gè)常見環(huán)節(jié)。打包命令非常簡(jiǎn)單mvn clean package如果用的是IDEA也可以直接在Maven面板里雙擊package。打包完成后target目錄下會(huì)生成一個(gè)spring-boot-bootstrapped的jar包。這里有個(gè)常見的坑有些同學(xué)打包后運(yùn)行報(bào)“找不到主類”大概率是沒有配置spring-boot-maven-plugin的mainClass或者是項(xiàng)目里存在多個(gè)SpringBootApplication啟動(dòng)類。這個(gè)問題排查時(shí)去Maven插件配置里確認(rèn)一下即可。服務(wù)器上運(yùn)行jar包常規(guī)姿勢(shì)是用nohup后臺(tái)啟動(dòng)nohup java -jar boardgame-system.jar --server.port8080 app.log 21 這樣ssh斷開后程序也不會(huì)停。如果你想做得更專業(yè)可以用systemd寫一個(gè)服務(wù)文件支持開機(jī)自啟和自動(dòng)重啟。但對(duì)于畢業(yè)設(shè)計(jì)和中小項(xiàng)目nohup方案已經(jīng)夠用。端口和外部訪問這塊也要提前規(guī)劃。如果你的服務(wù)器上只有這一個(gè)應(yīng)用8080端口直接開放就行。但如果還有別的項(xiàng)目或者80端口被占用了建議用Nginx做反向代理把80端口轉(zhuǎn)發(fā)到8080順便還能代理靜態(tài)資源。生產(chǎn)環(huán)境我習(xí)慣把前端靜態(tài)資源和后端接口都通過一個(gè)域名入口進(jìn)來省得瀏覽器里帶端口號(hào)也方便以后上HTTPS。6. 常見問題排查與避坑手冊(cè)6.1 數(shù)據(jù)庫連接報(bào)錯(cuò)這一類報(bào)錯(cuò)在開發(fā)期出現(xiàn)頻率最高。我隨便列幾個(gè)最常見的場(chǎng)景啟動(dòng)時(shí)報(bào)Access denied for user rootlocalhost說明用戶名或密碼不對(duì)去application.yml里核對(duì)。報(bào)Unknown database boardgame_db說明數(shù)據(jù)庫沒建或者名字寫錯(cuò)。報(bào)Public Key Retrieval is not allowed這是MySQL 8.0的加密連接特性導(dǎo)致的在連接串加allowPublicKeyRetrievaltrue就能解決。報(bào)The server time zone value說明時(shí)區(qū)沒配置加上serverTimezoneAsia/Shanghai。這些報(bào)錯(cuò)信息其實(shí)已經(jīng)把問題原因說得很清楚但很多同學(xué)一看到一大段英文就慌。我建議遇到報(bào)錯(cuò)先看最下面幾行也就是Caused by開頭的部分那才是真正的根因。6.2 啟動(dòng)失敗的幾類原因啟動(dòng)失敗除了數(shù)據(jù)庫問題還有一類是端口被占用。SpringBoot默認(rèn)端口是8080如果你本機(jī)已經(jīng)跑了別的服務(wù)占用了8080啟動(dòng)日志會(huì)報(bào)Web server failed to start這時(shí)要么改server.port要么用命令查端口占用并殺掉對(duì)應(yīng)進(jìn)程。還有一類是依賴沖突或版本不對(duì)。比如SpringBoot 3.x的項(xiàng)目強(qiáng)行使用了為2.x寫的MyBatis-Plus配置類啟動(dòng)時(shí)會(huì)出現(xiàn)找不到類或者方法簽名不一致的問題。我的建議是一開始就鎖定SpringBoot 2.7.x和MyBatis-Plus 3.5.x的組合不要混用。版本不是越新越好穩(wěn)定的組合才能讓你把精力放在業(yè)務(wù)邏輯上。6.3 JSON序列化和時(shí)間格式的坑后端返回LocalDateTime類型數(shù)據(jù)時(shí)默認(rèn)序列化結(jié)果往往是“2024-03-18T10:24:30”這種帶T的格式前端展示起來很不好看。解決辦法有兩個(gè)。一是在實(shí)體類的日期字段上加注解JsonFormat(timezone GMT8, pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime createTime;timezone GMT8必須寫否則序列化出來可能和數(shù)據(jù)庫時(shí)間相差8小時(shí)。第二種是全局配置Jackson的ObjectMapper統(tǒng)一處理所有日期字段。兩種方案對(duì)比局部注解適合少量字段全局配置適合整個(gè)項(xiàng)目日期字段多的情況。我建議用全局配置省事且統(tǒng)一。6.4 給畢設(shè)和項(xiàng)目的三點(diǎn)建議做了這么多項(xiàng)目最后分享幾個(gè)掏心窩的建議。第一先花時(shí)間把數(shù)據(jù)庫設(shè)計(jì)好再動(dòng)代碼。我見過太多項(xiàng)目做著做著要加字段、改表名連帶著Service層邏輯全部重寫。設(shè)計(jì)階段多花一天開發(fā)階段能省一周。表關(guān)系、狀態(tài)枚舉、金額精度這些東西一定要在一開始就想清楚。第二Controller要保持薄。Controller只做參數(shù)接收、調(diào)用Service、返回結(jié)果業(yè)務(wù)邏輯不要寫在Controller里。很多人覺得這樣多寫一層很麻煩但項(xiàng)目一旦變大你就會(huì)發(fā)現(xiàn)這是唯一能保持代碼清爽的方式。我見過把庫存扣減寫在Controller里的項(xiàng)目后來光排查并發(fā)問題就花了兩周。第三項(xiàng)目要能在全新的環(huán)境里跑起來。交付項(xiàng)目時(shí)數(shù)據(jù)庫初始化腳本、配置說明、啟動(dòng)說明、部署文檔這幾樣缺一不可。我每次開發(fā)完都會(huì)在自己的電腦上用干凈的環(huán)境走一遍部署流程模擬第一次運(yùn)行的人會(huì)遇到什么問題。這個(gè)習(xí)慣幫我避免過很多次“在我電腦上明明好的”的尷尬。桌游信息管理系統(tǒng)這類項(xiàng)目技術(shù)點(diǎn)不算高深但它在業(yè)務(wù)鏈路上包含了登錄鑒權(quán)、分頁查詢、文件上傳、跨表事務(wù)、狀態(tài)機(jī)、數(shù)據(jù)統(tǒng)計(jì)等真實(shí)項(xiàng)目中幾乎必用的能力。把這套流程完整走一遍你對(duì)SpringBoot和MyBatis-Plus的理解會(huì)比看十遍教程都深刻。做的時(shí)候不用追求炫技先把核心鏈路跑通再一步步完善細(xì)節(jié)你會(huì)發(fā)現(xiàn)這個(gè)項(xiàng)目帶給你的收獲遠(yuǎn)比想象中多。