實戰(zhàn)：從零搭建到避坑指南)
1. 為什么這套老三樣組合至今仍是后臺管理系統(tǒng)的首選后臺管理系統(tǒng)這個東西做過的人都知道需求翻來覆去就那些登錄鑒權(quán)、菜單權(quán)限、增刪改查、分頁列表、表單校驗、文件上傳。聽起來簡單但真要從零搭一個能用的架子坑一點都不少。我前后用不同技術(shù)棧搭過七八個后臺系統(tǒng)繞了一大圈最后還是回到了SpringBoot MyBatis Thymeleaf這套組合上。原因很直接這套組合的心智負(fù)擔(dān)最低。SpringBoot 把配置和依賴管理全包了MyBatis 讓你對 SQL 有完全的掌控權(quán)Thymeleaf 是服務(wù)端渲染頁面直接由后端吐出來不需要前后端分離那一套接口聯(lián)調(diào)、跨域處理、Token 傳遞的繁瑣流程。對于一個中小型后臺、內(nèi)部工具、或者個人項目來說這套方案的開發(fā)效率高得離譜。這篇文章我打算把整個搭建過程完整拆一遍從項目結(jié)構(gòu)設(shè)計、依賴選型、數(shù)據(jù)庫設(shè)計到核心的 CRUD 實現(xiàn)、分頁、權(quán)限攔截、模板布局再到實際開發(fā)中踩過的那些坑。適合有一定 Java 基礎(chǔ)、想快速上手一個完整后臺項目的朋友也適合那些做慣了前后端分離、想回頭看看服務(wù)端渲染方案到底香在哪的老手。文章里所有代碼和配置都是可以直接抄作業(yè)的我會把每個選擇背后的理由講清楚而不是甩一堆代碼讓你自己猜。先說清楚這套方案的定位它不適合高并發(fā)、大流量的 C 端產(chǎn)品也不適合需要復(fù)雜前端交互比如拖拽看板、實時協(xié)作的場景。但如果你要做的是一個幾十上百人用的內(nèi)部管理系統(tǒng)或者一個需要快速交付的 MVP那這套組合的性價比幾乎沒有對手。Thymeleaf 的模板復(fù)用能力配合 SpringBoot 的自動配置一個中等復(fù)雜度的后臺兩三天出原型完全不是問題。2. 項目整體架構(gòu)設(shè)計與技術(shù)選型拆解2.1 分層結(jié)構(gòu)怎么劃分才不混亂很多人搭后臺系統(tǒng)一開始圖省事Controller 里直接寫 SQL、拼 HTML寫著寫著代碼就爛成一鍋粥。我的習(xí)慣是從第一天就嚴(yán)格分層哪怕項目再小。標(biāo)準(zhǔn)的分層是這樣的Controller 層只負(fù)責(zé)接收請求參數(shù)、調(diào)用 Service、返回視圖或重定向不寫任何業(yè)務(wù)邏輯。Service 層業(yè)務(wù)邏輯的核心事務(wù)控制放在這一層調(diào)用 Mapper 完成數(shù)據(jù)操作。Mapper 層只做數(shù)據(jù)庫交互一個方法對應(yīng)一條 SQL保持純粹。Entity / DTOEntity 對應(yīng)數(shù)據(jù)庫表結(jié)構(gòu)DTO 用于接收前端參數(shù)和返回給頁面兩者不要混用。為什么要 Entity 和 DTO 分開因為數(shù)據(jù)庫字段和頁面需要的字段往往不一致。比如用戶表里有password字段但返回給頁面時絕對不能帶上再比如列表頁需要顯示角色名稱但用戶表里只存了role_id這時候就需要一個 DTO 來承載聯(lián)表查詢的結(jié)果。混用 Entity 會導(dǎo)致兩個問題一是敏感字段容易泄露到頁面二是表結(jié)構(gòu)一變頁面全崩。包結(jié)構(gòu)我一般這樣組織com.example.admin ├── controller // 控制器 ├── service // 業(yè)務(wù)接口 │ └── impl // 業(yè)務(wù)實現(xiàn) ├── mapper // MyBatis 接口 ├── entity // 數(shù)據(jù)庫實體 ├── dto // 數(shù)據(jù)傳輸對象 ├── config // 配置類 ├── interceptor // 攔截器 ├── common // 通用工具、常量、統(tǒng)一返回 └── AdminApplication // 啟動類這個結(jié)構(gòu)看起來平平無奇但它的好處是職責(zé)邊界清晰。新人接手時看到mapper就知道是數(shù)據(jù)庫操作看到interceptor就知道是攔截邏輯不用滿項目找。2.2 為什么選 Thymeleaf 而不是 JSP 或前后端分離這是最多人糾結(jié)的點。我逐個說下我的判斷。JSP 的問題JSP 本質(zhì)上是 Servlet 容器的一部分打包成可執(zhí)行 JAR 后運行會有各種路徑問題而且 JSP 的語法和 HTML 混在一起可讀性差現(xiàn)代 SpringBoot 項目基本已經(jīng)拋棄它了。Thymeleaf 是純 HTML 模板瀏覽器直接打開也能看到靜態(tài)效果前后端協(xié)作時前端可以先做好靜態(tài)頁面后端再往里填數(shù)據(jù)。前后端分離的問題分離方案Vue/React REST API當(dāng)然好但它引入了額外的復(fù)雜度——跨域配置、Token 管理、接口文檔維護、兩套代碼倉庫。對于一個后臺管理系統(tǒng)來說這些成本很多時候是浪費的。Thymeleaf 服務(wù)端渲染頁面直接由后端生成登錄狀態(tài)用 Session 管理簡單直接。Thymeleaf 的核心優(yōu)勢在于它的模板片段復(fù)用。后臺系統(tǒng)的頁面結(jié)構(gòu)高度相似——頂部導(dǎo)航、左側(cè)菜單、內(nèi)容區(qū)這些用 Thymeleaf 的th:fragment和th:replace抽成公共片段改一處全站生效。這個能力在 JSP 里也有jsp:include但 Thymeleaf 的語法更自然而且支持在瀏覽器里直接預(yù)覽。提示Thymeleaf 默認(rèn)會緩存模板開發(fā)階段一定要在配置文件里關(guān)掉緩存否則改完 HTML 刷新頁面看不到變化會浪費大量時間排查。2.3 依賴清單與版本選擇依賴這塊我不建議盲目追新后臺系統(tǒng)穩(wěn)定壓倒一切。下面是我實測比較穩(wěn)的一套組合依賴版本建議作用spring-boot-starter-web跟隨 SpringBoot 主版本W(wǎng)eb 支持spring-boot-starter-thymeleaf跟隨主版本模板引擎mybatis-spring-boot-starter2.3.xMyBatis 集成mysql-connector-j8.x數(shù)據(jù)庫驅(qū)動pagehelper-spring-boot-starter1.4.x分頁插件spring-boot-starter-validation跟隨主版本參數(shù)校驗lombok最新簡化實體類SpringBoot 主版本我建議用2.7.x或者3.x。2.7.x 的優(yōu)勢是生態(tài)成熟、資料多遇到問題一搜就有答案3.x 用了 Jakarta EE 命名空間javax.*全部變成jakarta.*如果你參考的教程比較老直接上 3.x 會有一堆包名對不上的問題。新手我建議從 2.7.x 起步把整個流程跑通了再考慮升級。PageHelper 這個分頁插件值得單獨說一句。MyBatis 本身不帶分頁功能你得自己寫LIMIT語句還要單獨寫一個COUNT查詢。PageHelper 的做法是在你執(zhí)行查詢前調(diào)用PageHelper.startPage(pageNum, pageSize)它會自動攔截下一條 SQL幫你拼上分頁和總數(shù)查詢。用起來非常省事但有個坑后面會講。3. 數(shù)據(jù)庫設(shè)計與核心表結(jié)構(gòu)落地3.1 后臺系統(tǒng)最少需要哪幾張表一個能跑起來的最小后臺我建議至少設(shè)計這幾張表用戶表、角色表、菜單表以及用戶角色關(guān)聯(lián)表、角色菜單關(guān)聯(lián)表。有人會問就做個簡單后臺搞這么復(fù)雜干嘛我的經(jīng)驗是權(quán)限這塊一開始不設(shè)計好后面加功能會非常痛苦。哪怕你現(xiàn)在只需要一個管理員賬號也建議把用戶和角色分開。因為業(yè)務(wù)一旦發(fā)展運營只能看訂單、財務(wù)只能看賬單這種需求一定會來。到時候你再去改表結(jié)構(gòu)、改代碼成本比一開始就設(shè)計好高得多。核心表結(jié)構(gòu)大致如下-- 用戶表 CREATE TABLE sys_user ( id BIGINT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL UNIQUE, password VARCHAR(100) NOT NULL, nickname VARCHAR(50), status TINYINT DEFAULT 1 COMMENT 1啟用 0禁用, create_time DATETIME DEFAULT CURRENT_TIMESTAMP ); -- 角色表 CREATE TABLE sys_role ( id BIGINT PRIMARY KEY AUTO_INCREMENT, role_name VARCHAR(50) NOT NULL, role_code VARCHAR(50) NOT NULL UNIQUE ); -- 用戶角色關(guān)聯(lián) CREATE TABLE sys_user_role ( user_id BIGINT NOT NULL, role_id BIGINT NOT NULL, PRIMARY KEY (user_id, role_id) ); -- 菜單表 CREATE TABLE sys_menu ( id BIGINT PRIMARY KEY AUTO_INCREMENT, parent_id BIGINT DEFAULT 0, menu_name VARCHAR(50) NOT NULL, url VARCHAR(200), icon VARCHAR(50), sort_order INT DEFAULT 0 ); -- 角色菜單關(guān)聯(lián) CREATE TABLE sys_role_menu ( role_id BIGINT NOT NULL, menu_id BIGINT NOT NULL, PRIMARY KEY (role_id, menu_id) );3.2 密碼存儲與字段設(shè)計的幾個關(guān)鍵決策密碼絕對不能明文存。這是底線沒有商量余地。我用的是 BCryptSpring Security 里有現(xiàn)成的BCryptPasswordEncoder但如果你不想引入整個 Spring Security它比較重可以單獨引入spring-security-crypto這個輕量包只為了用它的加密工具。BCrypt 的好處是它自帶鹽值每次加密同一個密碼得到的結(jié)果都不一樣但校驗時能正確匹配。這比 MD5 加固定鹽安全得多。字段長度給 100 是因為 BCrypt 生成的哈希串固定是 60 位留點余量。菜單表的parent_id設(shè)計成自關(guān)聯(lián)是為了支持多級菜單。后臺系統(tǒng)的菜單通常是樹形結(jié)構(gòu)——系統(tǒng)管理下面掛用戶管理角色管理菜單管理。用parent_id 0表示頂級菜單查詢時先查頂級再遞歸查子級或者一次性全查出來在內(nèi)存里組裝成樹。注意菜單的url字段要和 Controller 的映射路徑對應(yīng)上這是后面做權(quán)限攔截的基礎(chǔ)。如果 url 寫錯了攔截器就攔不住會出現(xiàn)菜單看不到但直接輸網(wǎng)址能訪問的漏洞。3.3 初始化數(shù)據(jù)的準(zhǔn)備表建好后得先塞一條管理員數(shù)據(jù)進去否則你連登錄都進不去。密碼字段要填 BCrypt 加密后的值不能直接寫明文。你可以寫一個臨時的測試方法用BCryptPasswordEncoder().encode(你的密碼)生成哈希串然后手動插進數(shù)據(jù)庫。初始化菜單數(shù)據(jù)時我建議先把所有菜單的parent_id都設(shè)成 0等系統(tǒng)跑起來、菜單能正常顯示了再慢慢調(diào)整層級關(guān)系。一上來就搞復(fù)雜的樹形結(jié)構(gòu)調(diào)試起來很費勁。4. 核心功能實現(xiàn)從登錄到增刪改查4.1 登錄鑒權(quán)與 Session 管理登錄邏輯本身不復(fù)雜接收用戶名密碼查庫比對成功就把用戶信息塞進 Session失敗就返回錯誤提示。但有幾個細(xì)節(jié)必須處理好。第一密碼比對要用加密工具的 matches 方法不能自己寫字符串比較。BCrypt 每次加密結(jié)果不同直接比較哈希串永遠(yuǎn)不相等。第二登錄失敗不要提示用戶名不存在或密碼錯誤統(tǒng)一提示用戶名或密碼錯誤。這是為了防止有人通過錯誤提示枚舉出系統(tǒng)里存在哪些用戶名。第三Session 里存什么。我一般存一個精簡的用戶對象id、username、nickname、角色列表、權(quán)限菜單列表。不要把整個 User 實體塞進去尤其是密碼字段萬一哪天不小心在頁面里輸出了 Session 內(nèi)容密碼就泄露了。登錄成功后跳轉(zhuǎn)到后臺首頁首頁需要展示當(dāng)前用戶的菜單。菜單的獲取邏輯是根據(jù)用戶 id 查角色根據(jù)角色查菜單去重后按sort_order排序再組裝成樹形結(jié)構(gòu)返回給頁面。4.2 攔截器實現(xiàn)權(quán)限控制攔截器是這套方案里權(quán)限控制的核心。思路很簡單寫一個HandlerInterceptor在preHandle方法里判斷當(dāng)前請求的路徑是否在用戶的權(quán)限菜單里不在就攔截。public class AuthInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { HttpSession session request.getSession(); Object user session.getAttribute(loginUser); if (user null) { response.sendRedirect(/login); return false; } return true; } }上面這個是最基礎(chǔ)的登錄攔截只判斷有沒有登錄。如果要做到菜單級權(quán)限還需要在 Session 里存一份當(dāng)前用戶可訪問的 url 集合preHandle里比對請求路徑。比對時要注意排除登錄頁、靜態(tài)資源、錯誤頁這些不需要權(quán)限的路徑否則會陷入死循環(huán)——攔截器攔截了登錄頁用戶永遠(yuǎn)登不進去。攔截器注冊時用addPathPatterns(/**)攔截所有請求再用excludePathPatterns排除掉白名單。白名單至少包括/login、/logout、/css/**、/js/**、/images/**、/error。實操心得靜態(tài)資源路徑一定要排除干凈。我踩過一次坑CSS 文件被攔截器攔下來重定向到登錄頁結(jié)果登錄頁樣式全丟排查了半天才發(fā)現(xiàn)是攔截器的問題。4.3 通用 CRUD 的模板化寫法后臺系統(tǒng)里 80% 的代碼都是增刪改查如果每個模塊都從頭寫一遍效率太低。我的做法是抽象出一套通用的寫法新模塊直接復(fù)制改改就行。以用戶管理為例一個完整的 CRUD 包含這幾個部分列表查詢帶分頁和條件搜索Controller 接收頁碼、每頁條數(shù)、搜索關(guān)鍵詞調(diào)用 ServiceService 里用 PageHelper 分頁返回一個PageInfo對象給頁面。頁面用 Thymeleaf 遍歷渲染表格底部渲染分頁條。新增和編輯這兩個功能通常共用一個表單頁面。新增時表單是空的編輯時表單回填數(shù)據(jù)。判斷依據(jù)是請求里有沒有 id 參數(shù)。Controller 里用GetMapping(/form)處理頁面跳轉(zhuǎn)用PostMapping(/save)處理提交。刪除一般用邏輯刪除而不是物理刪除也就是給表加一個deleted字段刪除時把它置為 1查詢時過濾掉。物理刪除一旦誤操作數(shù)據(jù)就找不回來了。邏輯刪除的代價是每條查詢都要帶WHERE deleted 0稍微麻煩點但安全。分頁這塊用 PageHelper 有個細(xì)節(jié)要注意PageHelper.startPage()必須緊挨著查詢語句調(diào)用中間不能插入其他數(shù)據(jù)庫操作否則分頁會作用到錯誤的 SQL 上。我見過有人把startPage寫在方法開頭中間查了別的表結(jié)果分頁參數(shù)跑偏了。4.4 Thymeleaf 模板布局與片段復(fù)用Thymeleaf 最實用的功能就是片段復(fù)用。后臺系統(tǒng)的頁面結(jié)構(gòu)高度一致把公共部分抽出來能省大量重復(fù)代碼。我一般會建一個layout.html里面定義好頭部、側(cè)邊欄、內(nèi)容區(qū)的骨架內(nèi)容區(qū)用一個th:fragment占位。其他頁面通過th:replace引入這個布局把自己的內(nèi)容填進去。!-- layout.html -- !DOCTYPE html html xmlns:thhttp://www.thymeleaf.org head meta charsetUTF-8 title th:text${pageTitle}后臺管理/title link relstylesheet th:href{/css/main.css} /head body div classheader th:replace~{fragments/header :: header}/div div classsidebar th:replace~{fragments/sidebar :: sidebar}/div div classcontent div th:replace${content}/div /div /body /html這種布局方式叫裝飾器模式Thymeleaf 官方推薦配合thymeleaf-layout-dialect使用但純用th:replace也能實現(xiàn)類似效果。新手我建議先用簡單的th:replace把公共片段抽出來等熟悉了再上布局方言。菜單渲染是個重點。側(cè)邊欄菜單是樹形結(jié)構(gòu)Thymeleaf 里用嵌套的th:each遍歷。一級菜單遍歷一次每個一級菜單下面再遍歷它的子菜單。判斷當(dāng)前訪問的 url 是否等于菜單 url相等就加個高亮樣式讓用戶知道自己在哪個頁面。5. 開發(fā)過程中最容易踩的坑與排查實錄5.1 常見問題速查表我把這些年踩過的坑整理成一張表遇到問題可以先對照排查問題現(xiàn)象可能原因解決方向頁面 404模板路徑不對 / Controller 映射不匹配檢查spring.thymeleaf.prefix配置和RequestMapping模板改了不生效模板緩存沒關(guān)配置spring.thymeleaf.cachefalse靜態(tài)資源 404攔截器攔截了靜態(tài)資源攔截器白名單加上/css/**等分頁總數(shù)不對PageHelper 調(diào)用位置錯誤startPage緊貼查詢語句中文亂碼數(shù)據(jù)庫連接沒指定編碼JDBC url 加characterEncodingutf8登錄后立刻掉線Session 超時太短配置server.servlet.session.timeout表單提交 400參數(shù)類型不匹配檢查 DTO 字段類型和表單 nameMyBatis 找不到 Mapper沒加MapperScan啟動類加注解指定包路徑5.2 幾個典型問題的深度排查問題一Thymeleaf 頁面報錯但看不出具體原因。Thymeleaf 的報錯信息有時候很含糊只說模板解析錯誤不告訴你是哪一行。這時候可以打開 DEBUG 日志在配置文件里把logging.level.org.thymeleaf設(shè)成 DEBUG它會打印出詳細(xì)的解析過程。另一個技巧是先把模板里的動態(tài)表達(dá)式一個個注釋掉定位到具體是哪段出的問題。問題二MyBatis 的駝峰映射失效。數(shù)據(jù)庫字段是create_time實體類屬性是createTime正常情況下 MyBatis 會自動映射但有時候查出來是 null。原因是駝峰映射沒開啟。在配置文件里加上mybatis.configuration.map-underscore-to-camel-casetrue就能解決。這個配置我建議一開始就加上能省很多事。問題三事務(wù)不生效。Service 方法上加了Transactional但數(shù)據(jù)沒回滾。最常見的原因是方法不是 public 的或者同類內(nèi)部方法調(diào)用A 方法調(diào) B 方法B 上有事務(wù)注解。Spring 的事務(wù)是基于代理的內(nèi)部調(diào)用不走代理事務(wù)自然不生效。解決辦法是把 B 方法抽到另一個 Service 里或者注入自己的代理對象。問題四分頁查詢后總數(shù)不對。PageHelper 返回的PageInfo里有個total字段正常情況下是總記錄數(shù)。但如果你的查詢語句里有GROUP BY或者復(fù)雜的子查詢PageHelper 自動生成的 count 語句可能算錯。這時候需要手動寫 count 查詢用PageInfo的構(gòu)造方法傳入自定義的總數(shù)。5.3 獨家避坑經(jīng)驗經(jīng)驗一開發(fā)階段一定要開 SQL 日志。在配置文件里把 MyBatis 的日志實現(xiàn)設(shè)成org.apache.ibatis.logging.stdout.StdOutImpl這樣每條執(zhí)行的 SQL 和參數(shù)都會打印到控制臺。排查問題時一眼就能看出 SQL 拼得對不對、參數(shù)傳得對不對。上線前記得關(guān)掉否則日志量太大。經(jīng)驗二表單提交前先做前端校驗后端也要再校驗一遍。前端校驗是為了用戶體驗后端校驗是為了安全。永遠(yuǎn)不要相信前端傳來的數(shù)據(jù)因為請求可以被偽造。用spring-boot-starter-validation的注解NotBlank、Size等在 DTO 上做校驗Controller 參數(shù)加Valid校驗失敗會自動返回錯誤信息。經(jīng)驗三刪除操作一定要加二次確認(rèn)。不管是前端彈窗確認(rèn)還是后端加邏輯刪除目的都是防止誤刪。我見過有人手滑點錯把整個用戶表清空了只能從備份恢復(fù)。邏輯刪除是最后的保險。經(jīng)驗四菜單權(quán)限和接口權(quán)限要分開控制。菜單權(quán)限控制的是用戶能看到哪些菜單接口權(quán)限控制的是用戶能調(diào)用哪些接口。只做菜單權(quán)限是不夠的因為用戶可以直接輸 url 訪問。兩者都要做才能形成完整的權(quán)限閉環(huán)。6. 項目擴展方向與個人實操體會這套基礎(chǔ)架子搭好之后能擴展的方向其實很多。比如加一個操作日志模塊用 AOP 攔截所有增刪改操作記錄操作人、操作時間、操作內(nèi)容出問題時能追溯。再比如加一個定時任務(wù)模塊用 Spring 的Scheduled處理一些周期性的數(shù)據(jù)統(tǒng)計。還有文件上傳、數(shù)據(jù)導(dǎo)出 Excel、郵件通知這些都是后臺系統(tǒng)的常見需求按需往上加就行。我個人在實際操作中的體會是后臺系統(tǒng)的難點從來不在技術(shù)本身而在需求的邊界。一開始想清楚哪些功能要做、哪些不做比悶頭寫代碼重要得多。我見過太多項目做著做著需求不斷膨脹最后變成一個四不像。所以我的建議是先用這套方案搭一個最小可用的版本把核心流程跑通然后再根據(jù)實際使用中的反饋逐步迭代。最后再分享一個小技巧Thymeleaf 的模板可以配置成從文件系統(tǒng)加載而不是 classpath這樣改完 HTML 不用重啟應(yīng)用刷新頁面就能看到效果。配置方式是設(shè)置spring.thymeleaf.prefixfile:./src/main/resources/templates/開發(fā)階段非常提效。上線時再改回 classpath 模式保證打包后的資源路徑正確。 SpringBoot + MyBatis + Thymeleaf 后臺管理系統(tǒng)實戰(zhàn)：從零搭建到避坑指南
1. 為什么這套老三樣組合至今仍是后臺管理系統(tǒng)的首選后臺管理系統(tǒng)這個東西做過的人都知道需求翻來覆去就那些登錄鑒權(quán)、菜單權(quán)限、增刪改查、分頁列表、表單校驗、文件上傳。聽起來簡單但真要從零搭一個能用的架子坑一點都不少。我前后用不同技術(shù)棧搭過七八個后臺系統(tǒng)繞了一大圈最后還是回到了SpringBoot MyBatis Thymeleaf這套組合上。原因很直接這套組合的心智負(fù)擔(dān)最低。SpringBoot 把配置和依賴管理全包了MyBatis 讓你對 SQL 有完全的掌控權(quán)Thymeleaf 是服務(wù)端渲染頁面直接由后端吐出來不需要前后端分離那一套接口聯(lián)調(diào)、跨域處理、Token 傳遞的繁瑣流程。對于一個中小型后臺、內(nèi)部工具、或者個人項目來說這套方案的開發(fā)效率高得離譜。這篇文章我打算把整個搭建過程完整拆一遍從項目結(jié)構(gòu)設(shè)計、依賴選型、數(shù)據(jù)庫設(shè)計到核心的 CRUD 實現(xiàn)、分頁、權(quán)限攔截、模板布局再到實際開發(fā)中踩過的那些坑。適合有一定 Java 基礎(chǔ)、想快速上手一個完整后臺項目的朋友也適合那些做慣了前后端分離、想回頭看看服務(wù)端渲染方案到底香在哪的老手。文章里所有代碼和配置都是可以直接抄作業(yè)的我會把每個選擇背后的理由講清楚而不是甩一堆代碼讓你自己猜。先說清楚這套方案的定位它不適合高并發(fā)、大流量的 C 端產(chǎn)品也不適合需要復(fù)雜前端交互比如拖拽看板、實時協(xié)作的場景。但如果你要做的是一個幾十上百人用的內(nèi)部管理系統(tǒng)或者一個需要快速交付的 MVP那這套組合的性價比幾乎沒有對手。Thymeleaf 的模板復(fù)用能力配合 SpringBoot 的自動配置一個中等復(fù)雜度的后臺兩三天出原型完全不是問題。2. 項目整體架構(gòu)設(shè)計與技術(shù)選型拆解2.1 分層結(jié)構(gòu)怎么劃分才不混亂很多人搭后臺系統(tǒng)一開始圖省事Controller 里直接寫 SQL、拼 HTML寫著寫著代碼就爛成一鍋粥。我的習(xí)慣是從第一天就嚴(yán)格分層哪怕項目再小。標(biāo)準(zhǔn)的分層是這樣的Controller 層只負(fù)責(zé)接收請求參數(shù)、調(diào)用 Service、返回視圖或重定向不寫任何業(yè)務(wù)邏輯。Service 層業(yè)務(wù)邏輯的核心事務(wù)控制放在這一層調(diào)用 Mapper 完成數(shù)據(jù)操作。Mapper 層只做數(shù)據(jù)庫交互一個方法對應(yīng)一條 SQL保持純粹。Entity / DTOEntity 對應(yīng)數(shù)據(jù)庫表結(jié)構(gòu)DTO 用于接收前端參數(shù)和返回給頁面兩者不要混用。為什么要 Entity 和 DTO 分開因為數(shù)據(jù)庫字段和頁面需要的字段往往不一致。比如用戶表里有password字段但返回給頁面時絕對不能帶上再比如列表頁需要顯示角色名稱但用戶表里只存了role_id這時候就需要一個 DTO 來承載聯(lián)表查詢的結(jié)果。混用 Entity 會導(dǎo)致兩個問題一是敏感字段容易泄露到頁面二是表結(jié)構(gòu)一變頁面全崩。包結(jié)構(gòu)我一般這樣組織com.example.admin ├── controller // 控制器 ├── service // 業(yè)務(wù)接口 │ └── impl // 業(yè)務(wù)實現(xiàn) ├── mapper // MyBatis 接口 ├── entity // 數(shù)據(jù)庫實體 ├── dto // 數(shù)據(jù)傳輸對象 ├── config // 配置類 ├── interceptor // 攔截器 ├── common // 通用工具、常量、統(tǒng)一返回 └── AdminApplication // 啟動類這個結(jié)構(gòu)看起來平平無奇但它的好處是職責(zé)邊界清晰。新人接手時看到mapper就知道是數(shù)據(jù)庫操作看到interceptor就知道是攔截邏輯不用滿項目找。2.2 為什么選 Thymeleaf 而不是 JSP 或前后端分離這是最多人糾結(jié)的點。我逐個說下我的判斷。JSP 的問題JSP 本質(zhì)上是 Servlet 容器的一部分打包成可執(zhí)行 JAR 后運行會有各種路徑問題而且 JSP 的語法和 HTML 混在一起可讀性差現(xiàn)代 SpringBoot 項目基本已經(jīng)拋棄它了。Thymeleaf 是純 HTML 模板瀏覽器直接打開也能看到靜態(tài)效果前后端協(xié)作時前端可以先做好靜態(tài)頁面后端再往里填數(shù)據(jù)。前后端分離的問題分離方案Vue/React REST API當(dāng)然好但它引入了額外的復(fù)雜度——跨域配置、Token 管理、接口文檔維護、兩套代碼倉庫。對于一個后臺管理系統(tǒng)來說這些成本很多時候是浪費的。Thymeleaf 服務(wù)端渲染頁面直接由后端生成登錄狀態(tài)用 Session 管理簡單直接。Thymeleaf 的核心優(yōu)勢在于它的模板片段復(fù)用。后臺系統(tǒng)的頁面結(jié)構(gòu)高度相似——頂部導(dǎo)航、左側(cè)菜單、內(nèi)容區(qū)這些用 Thymeleaf 的th:fragment和th:replace抽成公共片段改一處全站生效。這個能力在 JSP 里也有jsp:include但 Thymeleaf 的語法更自然而且支持在瀏覽器里直接預(yù)覽。提示Thymeleaf 默認(rèn)會緩存模板開發(fā)階段一定要在配置文件里關(guān)掉緩存否則改完 HTML 刷新頁面看不到變化會浪費大量時間排查。2.3 依賴清單與版本選擇依賴這塊我不建議盲目追新后臺系統(tǒng)穩(wěn)定壓倒一切。下面是我實測比較穩(wěn)的一套組合依賴版本建議作用spring-boot-starter-web跟隨 SpringBoot 主版本W(wǎng)eb 支持spring-boot-starter-thymeleaf跟隨主版本模板引擎mybatis-spring-boot-starter2.3.xMyBatis 集成mysql-connector-j8.x數(shù)據(jù)庫驅(qū)動pagehelper-spring-boot-starter1.4.x分頁插件spring-boot-starter-validation跟隨主版本參數(shù)校驗lombok最新簡化實體類SpringBoot 主版本我建議用2.7.x或者3.x。2.7.x 的優(yōu)勢是生態(tài)成熟、資料多遇到問題一搜就有答案3.x 用了 Jakarta EE 命名空間javax.*全部變成jakarta.*如果你參考的教程比較老直接上 3.x 會有一堆包名對不上的問題。新手我建議從 2.7.x 起步把整個流程跑通了再考慮升級。PageHelper 這個分頁插件值得單獨說一句。MyBatis 本身不帶分頁功能你得自己寫LIMIT語句還要單獨寫一個COUNT查詢。PageHelper 的做法是在你執(zhí)行查詢前調(diào)用PageHelper.startPage(pageNum, pageSize)它會自動攔截下一條 SQL幫你拼上分頁和總數(shù)查詢。用起來非常省事但有個坑后面會講。3. 數(shù)據(jù)庫設(shè)計與核心表結(jié)構(gòu)落地3.1 后臺系統(tǒng)最少需要哪幾張表一個能跑起來的最小后臺我建議至少設(shè)計這幾張表用戶表、角色表、菜單表以及用戶角色關(guān)聯(lián)表、角色菜單關(guān)聯(lián)表。有人會問就做個簡單后臺搞這么復(fù)雜干嘛我的經(jīng)驗是權(quán)限這塊一開始不設(shè)計好后面加功能會非常痛苦。哪怕你現(xiàn)在只需要一個管理員賬號也建議把用戶和角色分開。因為業(yè)務(wù)一旦發(fā)展運營只能看訂單、財務(wù)只能看賬單這種需求一定會來。到時候你再去改表結(jié)構(gòu)、改代碼成本比一開始就設(shè)計好高得多。核心表結(jié)構(gòu)大致如下-- 用戶表 CREATE TABLE sys_user ( id BIGINT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL UNIQUE, password VARCHAR(100) NOT NULL, nickname VARCHAR(50), status TINYINT DEFAULT 1 COMMENT 1啟用 0禁用, create_time DATETIME DEFAULT CURRENT_TIMESTAMP ); -- 角色表 CREATE TABLE sys_role ( id BIGINT PRIMARY KEY AUTO_INCREMENT, role_name VARCHAR(50) NOT NULL, role_code VARCHAR(50) NOT NULL UNIQUE ); -- 用戶角色關(guān)聯(lián) CREATE TABLE sys_user_role ( user_id BIGINT NOT NULL, role_id BIGINT NOT NULL, PRIMARY KEY (user_id, role_id) ); -- 菜單表 CREATE TABLE sys_menu ( id BIGINT PRIMARY KEY AUTO_INCREMENT, parent_id BIGINT DEFAULT 0, menu_name VARCHAR(50) NOT NULL, url VARCHAR(200), icon VARCHAR(50), sort_order INT DEFAULT 0 ); -- 角色菜單關(guān)聯(lián) CREATE TABLE sys_role_menu ( role_id BIGINT NOT NULL, menu_id BIGINT NOT NULL, PRIMARY KEY (role_id, menu_id) );3.2 密碼存儲與字段設(shè)計的幾個關(guān)鍵決策密碼絕對不能明文存。這是底線沒有商量余地。我用的是 BCryptSpring Security 里有現(xiàn)成的BCryptPasswordEncoder但如果你不想引入整個 Spring Security它比較重可以單獨引入spring-security-crypto這個輕量包只為了用它的加密工具。BCrypt 的好處是它自帶鹽值每次加密同一個密碼得到的結(jié)果都不一樣但校驗時能正確匹配。這比 MD5 加固定鹽安全得多。字段長度給 100 是因為 BCrypt 生成的哈希串固定是 60 位留點余量。菜單表的parent_id設(shè)計成自關(guān)聯(lián)是為了支持多級菜單。后臺系統(tǒng)的菜單通常是樹形結(jié)構(gòu)——系統(tǒng)管理下面掛用戶管理角色管理菜單管理。用parent_id 0表示頂級菜單查詢時先查頂級再遞歸查子級或者一次性全查出來在內(nèi)存里組裝成樹。注意菜單的url字段要和 Controller 的映射路徑對應(yīng)上這是后面做權(quán)限攔截的基礎(chǔ)。如果 url 寫錯了攔截器就攔不住會出現(xiàn)菜單看不到但直接輸網(wǎng)址能訪問的漏洞。3.3 初始化數(shù)據(jù)的準(zhǔn)備表建好后得先塞一條管理員數(shù)據(jù)進去否則你連登錄都進不去。密碼字段要填 BCrypt 加密后的值不能直接寫明文。你可以寫一個臨時的測試方法用BCryptPasswordEncoder().encode(你的密碼)生成哈希串然后手動插進數(shù)據(jù)庫。初始化菜單數(shù)據(jù)時我建議先把所有菜單的parent_id都設(shè)成 0等系統(tǒng)跑起來、菜單能正常顯示了再慢慢調(diào)整層級關(guān)系。一上來就搞復(fù)雜的樹形結(jié)構(gòu)調(diào)試起來很費勁。4. 核心功能實現(xiàn)從登錄到增刪改查4.1 登錄鑒權(quán)與 Session 管理登錄邏輯本身不復(fù)雜接收用戶名密碼查庫比對成功就把用戶信息塞進 Session失敗就返回錯誤提示。但有幾個細(xì)節(jié)必須處理好。第一密碼比對要用加密工具的 matches 方法不能自己寫字符串比較。BCrypt 每次加密結(jié)果不同直接比較哈希串永遠(yuǎn)不相等。第二登錄失敗不要提示用戶名不存在或密碼錯誤統(tǒng)一提示用戶名或密碼錯誤。這是為了防止有人通過錯誤提示枚舉出系統(tǒng)里存在哪些用戶名。第三Session 里存什么。我一般存一個精簡的用戶對象id、username、nickname、角色列表、權(quán)限菜單列表。不要把整個 User 實體塞進去尤其是密碼字段萬一哪天不小心在頁面里輸出了 Session 內(nèi)容密碼就泄露了。登錄成功后跳轉(zhuǎn)到后臺首頁首頁需要展示當(dāng)前用戶的菜單。菜單的獲取邏輯是根據(jù)用戶 id 查角色根據(jù)角色查菜單去重后按sort_order排序再組裝成樹形結(jié)構(gòu)返回給頁面。4.2 攔截器實現(xiàn)權(quán)限控制攔截器是這套方案里權(quán)限控制的核心。思路很簡單寫一個HandlerInterceptor在preHandle方法里判斷當(dāng)前請求的路徑是否在用戶的權(quán)限菜單里不在就攔截。public class AuthInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { HttpSession session request.getSession(); Object user session.getAttribute(loginUser); if (user null) { response.sendRedirect(/login); return false; } return true; } }上面這個是最基礎(chǔ)的登錄攔截只判斷有沒有登錄。如果要做到菜單級權(quán)限還需要在 Session 里存一份當(dāng)前用戶可訪問的 url 集合preHandle里比對請求路徑。比對時要注意排除登錄頁、靜態(tài)資源、錯誤頁這些不需要權(quán)限的路徑否則會陷入死循環(huán)——攔截器攔截了登錄頁用戶永遠(yuǎn)登不進去。攔截器注冊時用addPathPatterns(/**)攔截所有請求再用excludePathPatterns排除掉白名單。白名單至少包括/login、/logout、/css/**、/js/**、/images/**、/error。實操心得靜態(tài)資源路徑一定要排除干凈。我踩過一次坑CSS 文件被攔截器攔下來重定向到登錄頁結(jié)果登錄頁樣式全丟排查了半天才發(fā)現(xiàn)是攔截器的問題。4.3 通用 CRUD 的模板化寫法后臺系統(tǒng)里 80% 的代碼都是增刪改查如果每個模塊都從頭寫一遍效率太低。我的做法是抽象出一套通用的寫法新模塊直接復(fù)制改改就行。以用戶管理為例一個完整的 CRUD 包含這幾個部分列表查詢帶分頁和條件搜索Controller 接收頁碼、每頁條數(shù)、搜索關(guān)鍵詞調(diào)用 ServiceService 里用 PageHelper 分頁返回一個PageInfo對象給頁面。頁面用 Thymeleaf 遍歷渲染表格底部渲染分頁條。新增和編輯這兩個功能通常共用一個表單頁面。新增時表單是空的編輯時表單回填數(shù)據(jù)。判斷依據(jù)是請求里有沒有 id 參數(shù)。Controller 里用GetMapping(/form)處理頁面跳轉(zhuǎn)用PostMapping(/save)處理提交。刪除一般用邏輯刪除而不是物理刪除也就是給表加一個deleted字段刪除時把它置為 1查詢時過濾掉。物理刪除一旦誤操作數(shù)據(jù)就找不回來了。邏輯刪除的代價是每條查詢都要帶WHERE deleted 0稍微麻煩點但安全。分頁這塊用 PageHelper 有個細(xì)節(jié)要注意PageHelper.startPage()必須緊挨著查詢語句調(diào)用中間不能插入其他數(shù)據(jù)庫操作否則分頁會作用到錯誤的 SQL 上。我見過有人把startPage寫在方法開頭中間查了別的表結(jié)果分頁參數(shù)跑偏了。4.4 Thymeleaf 模板布局與片段復(fù)用Thymeleaf 最實用的功能就是片段復(fù)用。后臺系統(tǒng)的頁面結(jié)構(gòu)高度一致把公共部分抽出來能省大量重復(fù)代碼。我一般會建一個layout.html里面定義好頭部、側(cè)邊欄、內(nèi)容區(qū)的骨架內(nèi)容區(qū)用一個th:fragment占位。其他頁面通過th:replace引入這個布局把自己的內(nèi)容填進去。!-- layout.html -- !DOCTYPE html html xmlns:thhttp://www.thymeleaf.org head meta charsetUTF-8 title th:text${pageTitle}后臺管理/title link relstylesheet th:href{/css/main.css} /head body div classheader th:replace~{fragments/header :: header}/div div classsidebar th:replace~{fragments/sidebar :: sidebar}/div div classcontent div th:replace${content}/div /div /body /html這種布局方式叫裝飾器模式Thymeleaf 官方推薦配合thymeleaf-layout-dialect使用但純用th:replace也能實現(xiàn)類似效果。新手我建議先用簡單的th:replace把公共片段抽出來等熟悉了再上布局方言。菜單渲染是個重點。側(cè)邊欄菜單是樹形結(jié)構(gòu)Thymeleaf 里用嵌套的th:each遍歷。一級菜單遍歷一次每個一級菜單下面再遍歷它的子菜單。判斷當(dāng)前訪問的 url 是否等于菜單 url相等就加個高亮樣式讓用戶知道自己在哪個頁面。5. 開發(fā)過程中最容易踩的坑與排查實錄5.1 常見問題速查表我把這些年踩過的坑整理成一張表遇到問題可以先對照排查問題現(xiàn)象可能原因解決方向頁面 404模板路徑不對 / Controller 映射不匹配檢查spring.thymeleaf.prefix配置和RequestMapping模板改了不生效模板緩存沒關(guān)配置spring.thymeleaf.cachefalse靜態(tài)資源 404攔截器攔截了靜態(tài)資源攔截器白名單加上/css/**等分頁總數(shù)不對PageHelper 調(diào)用位置錯誤startPage緊貼查詢語句中文亂碼數(shù)據(jù)庫連接沒指定編碼JDBC url 加characterEncodingutf8登錄后立刻掉線Session 超時太短配置server.servlet.session.timeout表單提交 400參數(shù)類型不匹配檢查 DTO 字段類型和表單 nameMyBatis 找不到 Mapper沒加MapperScan啟動類加注解指定包路徑5.2 幾個典型問題的深度排查問題一Thymeleaf 頁面報錯但看不出具體原因。Thymeleaf 的報錯信息有時候很含糊只說模板解析錯誤不告訴你是哪一行。這時候可以打開 DEBUG 日志在配置文件里把logging.level.org.thymeleaf設(shè)成 DEBUG它會打印出詳細(xì)的解析過程。另一個技巧是先把模板里的動態(tài)表達(dá)式一個個注釋掉定位到具體是哪段出的問題。問題二MyBatis 的駝峰映射失效。數(shù)據(jù)庫字段是create_time實體類屬性是createTime正常情況下 MyBatis 會自動映射但有時候查出來是 null。原因是駝峰映射沒開啟。在配置文件里加上mybatis.configuration.map-underscore-to-camel-casetrue就能解決。這個配置我建議一開始就加上能省很多事。問題三事務(wù)不生效。Service 方法上加了Transactional但數(shù)據(jù)沒回滾。最常見的原因是方法不是 public 的或者同類內(nèi)部方法調(diào)用A 方法調(diào) B 方法B 上有事務(wù)注解。Spring 的事務(wù)是基于代理的內(nèi)部調(diào)用不走代理事務(wù)自然不生效。解決辦法是把 B 方法抽到另一個 Service 里或者注入自己的代理對象。問題四分頁查詢后總數(shù)不對。PageHelper 返回的PageInfo里有個total字段正常情況下是總記錄數(shù)。但如果你的查詢語句里有GROUP BY或者復(fù)雜的子查詢PageHelper 自動生成的 count 語句可能算錯。這時候需要手動寫 count 查詢用PageInfo的構(gòu)造方法傳入自定義的總數(shù)。5.3 獨家避坑經(jīng)驗經(jīng)驗一開發(fā)階段一定要開 SQL 日志。在配置文件里把 MyBatis 的日志實現(xiàn)設(shè)成org.apache.ibatis.logging.stdout.StdOutImpl這樣每條執(zhí)行的 SQL 和參數(shù)都會打印到控制臺。排查問題時一眼就能看出 SQL 拼得對不對、參數(shù)傳得對不對。上線前記得關(guān)掉否則日志量太大。經(jīng)驗二表單提交前先做前端校驗后端也要再校驗一遍。前端校驗是為了用戶體驗后端校驗是為了安全。永遠(yuǎn)不要相信前端傳來的數(shù)據(jù)因為請求可以被偽造。用spring-boot-starter-validation的注解NotBlank、Size等在 DTO 上做校驗Controller 參數(shù)加Valid校驗失敗會自動返回錯誤信息。經(jīng)驗三刪除操作一定要加二次確認(rèn)。不管是前端彈窗確認(rèn)還是后端加邏輯刪除目的都是防止誤刪。我見過有人手滑點錯把整個用戶表清空了只能從備份恢復(fù)。邏輯刪除是最后的保險。經(jīng)驗四菜單權(quán)限和接口權(quán)限要分開控制。菜單權(quán)限控制的是用戶能看到哪些菜單接口權(quán)限控制的是用戶能調(diào)用哪些接口。只做菜單權(quán)限是不夠的因為用戶可以直接輸 url 訪問。兩者都要做才能形成完整的權(quán)限閉環(huán)。6. 項目擴展方向與個人實操體會這套基礎(chǔ)架子搭好之后能擴展的方向其實很多。比如加一個操作日志模塊用 AOP 攔截所有增刪改操作記錄操作人、操作時間、操作內(nèi)容出問題時能追溯。再比如加一個定時任務(wù)模塊用 Spring 的Scheduled處理一些周期性的數(shù)據(jù)統(tǒng)計。還有文件上傳、數(shù)據(jù)導(dǎo)出 Excel、郵件通知這些都是后臺系統(tǒng)的常見需求按需往上加就行。我個人在實際操作中的體會是后臺系統(tǒng)的難點從來不在技術(shù)本身而在需求的邊界。一開始想清楚哪些功能要做、哪些不做比悶頭寫代碼重要得多。我見過太多項目做著做著需求不斷膨脹最后變成一個四不像。所以我的建議是先用這套方案搭一個最小可用的版本把核心流程跑通然后再根據(jù)實際使用中的反饋逐步迭代。最后再分享一個小技巧Thymeleaf 的模板可以配置成從文件系統(tǒng)加載而不是 classpath這樣改完 HTML 不用重啟應(yīng)用刷新頁面就能看到效果。配置方式是設(shè)置spring.thymeleaf.prefixfile:./src/main/resources/templates/開發(fā)階段非常提效。上線時再改回 classpath 模式保證打包后的資源路徑正確。