做過(guò)后臺(tái)管理系統(tǒng)的人大概都遇到過(guò)一個(gè)岔路口一個(gè)只有十來(lái)個(gè)人用的內(nèi)部工具需求三天兩頭改前端要做的其實(shí)就是列表、表單、彈窗、刪除確認(rèn)這幾件事這時(shí)候如果上來(lái)就搞前后端分離光是接口聯(lián)調(diào)、跨域、權(quán)限透?jìng)?、部署兩套產(chǎn)物就能耗掉大半工期。我前陣子接手的一個(gè)運(yùn)維臺(tái)賬系統(tǒng)就是這么個(gè)場(chǎng)景十來(lái)個(gè)頁(yè)面二十多張表交付周期四周最后定下來(lái)的技術(shù)組合就是標(biāo)題里這四樣SpringBoot 打底、MyBatis-Plus 干數(shù)據(jù)層、Thymeleaf 渲染頁(yè)面、AdminLTE 套殼。整套東西跑起來(lái)增刪改查這類活兒的開發(fā)節(jié)奏會(huì)非?？煲粋€(gè)標(biāo)準(zhǔn)模塊從建表到頁(yè)面能點(diǎn)熟練的話兩三個(gè)小時(shí)就能出一版。這篇內(nèi)容想聊的就是這套組合在真實(shí)項(xiàng)目里的落地細(xì)節(jié)不是官方文檔的復(fù)述。適合的人大概有三類剛接觸 SpringBoot 想做點(diǎn)完整東西練手的手上有個(gè)內(nèi)部系統(tǒng)要快速交付、不想被前端工程化拖住的以及已經(jīng)會(huì)用這套棧但總在分頁(yè)、表單回顯、靜態(tài)資源這些地方反復(fù)卡殼的。我會(huì)把依賴版本的坑、MyBatis-Plus 分頁(yè)插件的正確姿勢(shì)、AdminLTE 接 Thymeleaf 的布局復(fù)用方式、還有增刪改查四個(gè)動(dòng)作里那些文檔不會(huì)寫的細(xì)節(jié)一條一條攤開講。中間穿插的配置和代碼都是可以直接抄去改的遇到需要取舍的地方我會(huì)說(shuō)清楚為什么這么選。1. 先想清楚這套四件套各自的邊界在哪1.1 服務(wù)端渲染在內(nèi)部系統(tǒng)里的性價(jià)比賬選型這件事最怕的是拿互聯(lián)網(wǎng) C 端的標(biāo)準(zhǔn)去套內(nèi)部管理系統(tǒng)。C 端產(chǎn)品用戶量大、交互復(fù)雜、首屏性能敏感前后端分離帶來(lái)的收益能覆蓋掉工程復(fù)雜度。但內(nèi)部臺(tái)賬、審批、配置管理這類系統(tǒng)頁(yè)面數(shù)量有限、交互模式高度重復(fù)、用戶就那幾十個(gè)首屏慢個(gè)三百毫秒沒(méi)人在意反而更在意這個(gè)字段能不能加一列這個(gè)查詢條件能不能多一個(gè)這種需求變更的速度。服務(wù)端渲染在這個(gè)場(chǎng)景下的優(yōu)勢(shì)很直接一個(gè) Controller 方法配一個(gè)模板數(shù)據(jù)從數(shù)據(jù)庫(kù)到頁(yè)面是一條直線沒(méi)有中間層。改一個(gè)字段動(dòng)的是實(shí)體類、Mapper 不用動(dòng)、模板加一行、Controller 加一個(gè)取值五分鐘的事。換成前后端分離同樣的改動(dòng)要?jiǎng)?DTO、接口、前端 model、前端表單、可能還有類型定義五個(gè)文件起步還得等前端同學(xué)排期。代價(jià)也要說(shuō)清楚。Thymeleaf 的模板語(yǔ)法是在 HTML 屬性上做文章邏輯復(fù)雜了會(huì)很難看超過(guò)三層的條件嵌套基本就沒(méi)法維護(hù)了局部刷新能力弱想要個(gè)下拉聯(lián)動(dòng)、表格無(wú)刷新編輯就得自己寫零散的 JSSEO 完全談不上不過(guò)內(nèi)部系統(tǒng)也不需要。我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單如果這個(gè)系統(tǒng)的主要使用者是公司內(nèi)部員工、頁(yè)面總數(shù)在五十個(gè)以內(nèi)、沒(méi)有復(fù)雜的前端狀態(tài)管理需求這套組合就是劃算的如果要做的是面向外部用戶的產(chǎn)品或者有大量實(shí)時(shí)交互那就老老實(shí)實(shí)上分離架構(gòu)。1.2 四個(gè)組件各管一段別讓職責(zé)串味實(shí)際寫代碼時(shí)最常見(jiàn)的混亂是把本該在 Service 層的邏輯塞進(jìn) Controller或者把查詢條件拼裝散落在模板里。這套棧里四樣?xùn)|西的職責(zé)其實(shí)很清晰組件負(fù)責(zé)的事不該干的事SpringBoot容器、依賴注入、配置、事務(wù)邊界不寫業(yè)務(wù)規(guī)則MyBatis-Plus單表 CRUD、條件構(gòu)造、分頁(yè)、邏輯刪除不處理展示格式、不做權(quán)限判斷Thymeleaf數(shù)據(jù)渲染、條件展示、循環(huán)、格式化不拼查詢條件、不做業(yè)務(wù)計(jì)算AdminLTE頁(yè)面骨架、樣式、常用交互組件不承載業(yè)務(wù)邏輯一個(gè)典型的分層寫法是Controller 只做參數(shù)接收、調(diào)用 Service、往 Model 里塞數(shù)據(jù)、返回視圖名Service 管事務(wù)和業(yè)務(wù)規(guī)則比如用戶名不能重復(fù)刪除前要檢查有沒(méi)有關(guān)聯(lián)數(shù)據(jù)Mapper 只管數(shù)據(jù)訪問(wèn)。Thymeleaf 模板里只做展示判斷比如狀態(tài)字段是 0 還是 1 決定顯示什么顏色的標(biāo)簽。這個(gè)邊界守住了后面加需求才不會(huì)牽一發(fā)動(dòng)全身。1.3 什么時(shí)候該果斷放棄這套方案我不太喜歡某某技術(shù)已死這種論調(diào)但確實(shí)有幾類需求不適合硬套。一是需要大量圖表實(shí)時(shí)刷新的看板Thymeleaf 渲染完就定死了后續(xù)全靠手寫 JS 輪詢不如直接上圖表庫(kù)配接口二是移動(dòng)端適配要求高的場(chǎng)景AdminLTE 是桌面優(yōu)先的布局雖然響應(yīng)式做了但在手機(jī)上體驗(yàn)一般三是需要多人協(xié)同編輯同一份數(shù)據(jù)的場(chǎng)景服務(wù)端渲染那套表單提交模型處理不了沖突合并。碰到這三類趁早換方案別等到寫了一半再返工。2. 骨架搭建依賴順序和版本對(duì)齊比想象中重要2.1 pom 里的依賴清單版本別隨手寫新建工程的時(shí)候最容易出事的就是版本。SpringBoot 版本、MyBatis-Plus 版本、Thymeleaf 版本三者之間有隱性約束尤其是 MyBatis-Plus它跟 SpringBoot 的適配是按大版本對(duì)應(yīng)的3.5.x 系列對(duì) SpringBoot 2.x 和 3.x 的支持情況不一樣。我的做法是先用 Spring Initializr 生成一個(gè)干凈的骨架選定 SpringBoot 版本然后把 MyBatis-Plus 的版本號(hào)顯式寫上不依賴父 POM 的默認(rèn)管理。dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-validation/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.5/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies這里有兩個(gè)細(xì)節(jié)值得單獨(dú)拎出來(lái)。第一spring-boot-starter-validation必須單獨(dú)引入SpringBoot 2.3 之后校驗(yàn)相關(guān)的包已經(jīng)從 web starter 里剝離了不引這個(gè)Valid注解會(huì)靜默失效——注意是靜默不報(bào)錯(cuò)表單提交什么校驗(yàn)都不觸發(fā)很容易查半天。第二MySQL 驅(qū)動(dòng)在較新的 SpringBoot 里坐標(biāo)改成了com.mysql:mysql-connector-j老項(xiàng)目里常見(jiàn)的mysql:mysql-connector-java雖然還能用但會(huì)有告警新項(xiàng)目直接寫新的。如果你用的是 SpringBoot 3.xMyBatis-Plus 的 starter 也要換成mybatis-plus-spring-boot3-starter這個(gè)坐標(biāo)差異在官方文檔里不算顯眼但包名不一樣直接復(fù)制 2.x 的配置會(huì)啟動(dòng)失敗報(bào)找不到自動(dòng)配置類。2.2 application.yml 里必須動(dòng)的那幾項(xiàng)配置文件這塊默認(rèn)值大多能用但有四項(xiàng)我每次都會(huì)改server: port: 8080 servlet: encoding: charset: UTF-8 force: true spring: thymeleaf: cache: false prefix: classpath:/templates/ suffix: .html mode: HTML datasource: url: jdbc:mysql://127.0.0.1:3306/demo_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: demo password: demo123 driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: id-type: auto logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0 mapper-locations: classpath*:/mapper/**/*.xmlthymeleaf.cache在開發(fā)期一定要關(guān)掉這個(gè)后面還會(huì)展開講它是最容易讓人懷疑人生的一個(gè)配置。map-underscore-to-camel-case默認(rèn)是 true但顯式寫出來(lái)能避免接手別人項(xiàng)目時(shí)的困惑。log-impl打開 SQL 打印調(diào)試期非常有用上線前記得關(guān)掉不然日志量會(huì)很嚇人。serverTimezone這個(gè)參數(shù)不能省省了在寫入LocalDateTime的時(shí)候可能差八小時(shí)而且是那種數(shù)據(jù)看著對(duì)、時(shí)間就是不對(duì)的詭異問(wèn)題。數(shù)據(jù)源連接串里的allowPublicKeyRetrievaltrue是配合較新版本 MySQL 的認(rèn)證插件用的不加的話在某些環(huán)境下會(huì)報(bào)公鑰檢索失敗。這個(gè)參數(shù)涉及安全邊界只在本地和內(nèi)網(wǎng)開發(fā)環(huán)境用生產(chǎn)環(huán)境按各自的數(shù)據(jù)庫(kù)規(guī)范走。3. MyBatis-Plus 數(shù)據(jù)層從實(shí)體映射到分頁(yè)查詢的完整鏈路3.1 實(shí)體類和表結(jié)構(gòu)的映射約定MyBatis-Plus 默認(rèn)有一套約定類名轉(zhuǎn)下劃線對(duì)應(yīng)表名字段名轉(zhuǎn)下劃線對(duì)應(yīng)列名。遵守約定能省掉大量注解。我在項(xiàng)目里通常就三條規(guī)則表名統(tǒng)一加業(yè)務(wù)前綴比如sys_user、biz_order主鍵統(tǒng)一叫id且自增每張表都帶create_time、update_time、deleted三個(gè)公共字段。Data TableName(sys_user) public class SysUser { TableId(type IdType.AUTO) private Long id; private String username; private String realName; private String phone; private Integer status; TableField(fill FieldFill.INSERT) private LocalDateTime createTime; TableField(fill FieldFill.INSERT_UPDATE) private LocalDateTime updateTime; TableLogic private Integer deleted; }TableLogic這個(gè)注解是邏輯刪除的核心。加上它之后所有通過(guò) MyBatis-Plus 生成的刪除語(yǔ)句都會(huì)自動(dòng)變成UPDATE ... SET deleted 1查詢語(yǔ)句會(huì)自動(dòng)追加deleted 0。這個(gè)機(jī)制的好處是業(yè)務(wù)代碼里完全感知不到刪除的實(shí)現(xiàn)方式壞處是有幾個(gè)場(chǎng)景會(huì)失效手寫 XML 里的 SQL 不會(huì)自動(dòng)加條件需要自己補(bǔ)update語(yǔ)句也不會(huì)自動(dòng)過(guò)濾已刪除數(shù)據(jù)還有就是唯一索引要重新設(shè)計(jì)——如果username建了唯一索引刪掉一個(gè)用戶之后想再建同名用戶就會(huì)沖突因?yàn)槟菞l軟刪除的記錄還在表里。軟刪除的唯一索引問(wèn)題常見(jiàn)的解法是把deleted字段設(shè)計(jì)成刪除時(shí)寫入主鍵 ID而不是固定寫 1這樣聯(lián)合唯一索引(username, deleted)就能保證只有一條未刪除記錄。不過(guò)這樣配置就復(fù)雜一些小項(xiàng)目里我一般直接放棄用戶名唯一索引改在 Service 層做查重判斷簡(jiǎn)單夠用。自動(dòng)填充需要配一個(gè)處理器Component public class MetaHandler implements MetaObjectHandler { Override public void insertFill(MetaObject metaObject) { this.strictInsertFill(metaObject, createTime, LocalDateTime.class, LocalDateTime.now()); this.strictInsertFill(metaObject, updateTime, LocalDateTime.class, LocalDateTime.now()); } Override public void updateFill(MetaObject metaObject) { this.strictUpdateFill(metaObject, updateTime, LocalDateTime.class, LocalDateTime.now()); } }注意strictUpdateFill只對(duì)TableField(fill FieldFill.INSERT_UPDATE)標(biāo)注的字段生效如果實(shí)體類漏了這個(gè)注解填充不會(huì)執(zhí)行而且不會(huì)報(bào)錯(cuò)。3.2 分頁(yè)插件必須先注冊(cè)否則分頁(yè)永遠(yuǎn)返回全量這是我見(jiàn)過(guò)最多人踩的坑。MyBatis-Plus 從 3.4 開始分頁(yè)功能必須手動(dòng)注冊(cè)攔截器不注冊(cè)的話Page對(duì)象傳進(jìn)去也不報(bào)錯(cuò)但total永遠(yuǎn)是 0、records永遠(yuǎn)是全表數(shù)據(jù)。很多人第一次遇到會(huì)以為是Page參數(shù)位置傳錯(cuò)了查半天。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); PaginationInnerInterceptor pagination new PaginationInnerInterceptor(DbType.MYSQL); pagination.setMaxLimit(500L); pagination.setOverflow(false); interceptor.addInnerInterceptor(pagination); return interceptor; } }setMaxLimit(500L)是個(gè)保護(hù)措施防止前端傳個(gè)size999999把數(shù)據(jù)庫(kù)拖死。setOverflow(false)的意思是頁(yè)碼超出范圍時(shí)返回空列表而不是回到第一頁(yè)這個(gè)選擇看業(yè)務(wù)習(xí)慣我傾向于 false因?yàn)榛氐降谝豁?yè)會(huì)讓用戶以為自己點(diǎn)錯(cuò)了。分頁(yè)查詢配合條件構(gòu)造器的典型寫法public IPageSysUser pageQuery(UserQuery query, long current, long size) { PageSysUser page new Page(current, size); LambdaQueryWrapperSysUser wrapper new LambdaQueryWrapper(); wrapper.like(StringUtils.hasText(query.getUsername()), SysUser::getUsername, query.getUsername()) .eq(query.getStatus() ! null, SysUser::getStatus, query.getStatus()) .ge(query.getBeginTime() ! null, SysUser::getCreateTime, query.getBeginTime()) .le(query.getEndTime() ! null, SysUser::getCreateTime, query.getEndTime()) .orderByDesc(SysUser::getId); return this.page(page, wrapper); }LambdaQueryWrapper比QueryWrapper好在字段名是方法引用改字段名的時(shí)候編譯器會(huì)報(bào)錯(cuò)字符串寫法的QueryWrapper只能等到運(yùn)行時(shí)才發(fā)現(xiàn)列名寫錯(cuò)了。條件構(gòu)造器里每個(gè)方法都有個(gè)重載版本第一個(gè)參數(shù)是布爾值用來(lái)控制這個(gè)條件是否生效這個(gè)特性在寫動(dòng)態(tài)查詢時(shí)極其好用能避免大量 if 判斷。3.3 多條件搜索的拼接邏輯應(yīng)該放在哪條件拼接的位置有兩派做法放 Controller 里用參數(shù)逐個(gè)判斷或者放 Service 里封裝成一個(gè)方法。我傾向后者Controller 就負(fù)責(zé)把請(qǐng)求參數(shù)打包成一個(gè)查詢對(duì)象傳下去。這樣做的另一個(gè)好處是查詢參數(shù)可以做成一個(gè)獨(dú)立的類字段上直接掛校驗(yàn)注解和日期格式注解。Data public class UserQuery { private String username; private Integer status; DateTimeFormat(pattern yyyy-MM-dd) private LocalDate beginTime; DateTimeFormat(pattern yyyy-MM-dd) private LocalDate endTime; }DateTimeFormat這個(gè)注解是給表單綁定用的處理的是從頁(yè)面提交上來(lái)的字符串到日期對(duì)象的轉(zhuǎn)換。如果是 JSON 接口用的是JsonFormat兩個(gè)注解長(zhǎng)得像但作用域完全不同混用會(huì)導(dǎo)致日期綁不上、拋 400 錯(cuò)誤。這個(gè)區(qū)別我在帶新人的時(shí)候解釋過(guò)很多遍本質(zhì)上就是數(shù)據(jù)來(lái)源不同表單走的是 Spring 的ConversionServiceJSON 走的是 Jackson。4. AdminLTE 接 Thymeleaf靜態(tài)資源、布局復(fù)用和腳本順序4.1 靜態(tài)資源目錄怎么擺路徑怎么寫才不打架AdminLTE 是一套基于 Bootstrap 的后臺(tái)模板下載下來(lái)是個(gè)完整的前端工程里面有dist、plugins兩個(gè)主要目錄。放進(jìn) SpringBoot 項(xiàng)目的正確位置是src/main/resources/static/放進(jìn)去之后通過(guò)/dist/css/adminlte.min.css這樣的路徑就能訪問(wèn)。目錄結(jié)構(gòu)我一般是這么組織的resources/ static/ dist/ AdminLTE 的 css、js plugins/ 各種插件fontawesome、jquery、bootstrap uploads/ 用戶上傳的圖片運(yùn)行時(shí)生成 templates/ layout/ 公共片段 user/ 業(yè)務(wù)頁(yè)面 login.html有個(gè)細(xì)節(jié)很容易被忽略SpringBoot 的靜態(tài)資源默認(rèn)映射到/**如果模板里寫的是link th:href{/dist/css/adminlte.min.css}加了{(lán)}語(yǔ)法之后SpringBoot 會(huì)自動(dòng)處理上下文路徑。如果你的應(yīng)用部署在非根路徑下比如server.servlet.context-path/admin不用{}寫死的相對(duì)路徑全部會(huì) 404。這個(gè)坑在本地開發(fā)時(shí)完全發(fā)現(xiàn)不了因?yàn)楸镜啬J(rèn)是根路徑。上傳目錄的問(wèn)題要單獨(dú)說(shuō)一下。static/uploads這個(gè)位置在打成 jar 包之后是只讀的往里寫文件會(huì)失敗。生產(chǎn)環(huán)境應(yīng)該把上傳路徑配成一個(gè)外部目錄通過(guò)WebMvcConfigurer加資源映射Configuration public class WebConfig implements WebMvcConfigurer { Value(${app.upload-path}) private String uploadPath; Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/uploads/**) .addResourceLocations(file: uploadPath); } }這樣頁(yè)面里引用/uploads/xxx.png就能拿到外部目錄里的文件開發(fā)和生產(chǎn)的路徑差異用配置文件隔離。4.2 用 fragment 做布局復(fù)用別引額外的方言包Thymeleaf 復(fù)用頁(yè)面的方式有好幾種官方推薦的thymeleaf-layout-dialect用起來(lái)確實(shí)優(yōu)雅但它多一個(gè)依賴語(yǔ)法也自成一套團(tuán)隊(duì)里如果新人多學(xué)習(xí)成本不太劃算。我一般用原生的 fragment 組合來(lái)實(shí)現(xiàn)。先定義公共片段!-- templates/layout/common.html -- !DOCTYPE html html xmlns:thhttp://www.thymeleaf.org head th:fragmenthead(title) meta charsetutf-8 title th:text${title}頁(yè)面標(biāo)題/title link th:href{/plugins/fontawesome-free/css/all.min.css} relstylesheet link th:href{/dist/css/adminlte.min.css} relstylesheet /head body nav th:fragmentnavbar classmain-header navbar navbar-expand navbar-white navbar-light ul classnavbar-nav li classnav-item a classnav-link>!DOCTYPE html html xmlns:thhttp://www.thymeleaf.org head th:replace~{layout/common :: head(用戶管理)}/head body classhold-transition sidebar-mini layout-fixed div classwrapper nav th:replace~{layout/common :: navbar}/nav aside th:replace~{layout/common :: sidebar}/aside div classcontent-wrapper section classcontent-header div classcontainer-fluid h1用戶管理/h1 /div /section section classcontent div classcontainer-fluid !-- 業(yè)務(wù)內(nèi)容 -- /div /section /div footer th:replace~{layout/common :: footer}/footer /div /body /htmlth:replace和th:insert的區(qū)別要說(shuō)一下replace是用片段整體替換掉當(dāng)前標(biāo)簽insert是把片段塞進(jìn)當(dāng)前標(biāo)簽內(nèi)部。用replace的時(shí)候當(dāng)前標(biāo)簽本身會(huì)被丟掉所以寫法上要保證被替換的標(biāo)簽類型跟片段的根標(biāo)簽一致。側(cè)邊欄的菜單高亮靠當(dāng)前路徑判斷a th:href{/user/list} classnav-link th:classappend${#httpServletRequest.requestURI.startsWith(/user)} ? active#httpServletRequest這個(gè)對(duì)象在 Thymeleaf 3 里默認(rèn)是可用的不過(guò)在嚴(yán)格的安全配置下可能取不到取不到就退回用手動(dòng)傳一個(gè)activeMenu變量的方式穩(wěn)一些。4.3 腳本加載順序不對(duì)頁(yè)面會(huì)靜默失靈AdminLTE 依賴 jQuery、Bootstrap、popper這幾個(gè)的順序不能亂。正確的寫法是 jQuery 在最前然后 bootstrap 的 bundle 版本自帶 popper最后才是 adminlte 的主腳本script th:src{/plugins/jquery/jquery.min.js}/script script th:src{/plugins/bootstrap/js/bootstrap.bundle.min.js}/script script th:src{/dist/js/adminlte.min.js}/script順序錯(cuò)了的典型現(xiàn)象是折疊菜單點(diǎn)不開、下拉框點(diǎn)一下閃一下就關(guān)、彈窗出不來(lái)?？刂婆_(tái)可能只有一條$ is not defined或者干脆什么都沒(méi)有。我遇到過(guò)最隱蔽的一次是有人把 adminlte.min.js 放到了head里頁(yè)面骨架還沒(méi)渲染完腳本就執(zhí)行了界面看著正常但所有交互事件都沒(méi)綁上。所以腳本統(tǒng)一放/body前這是硬規(guī)矩。還有個(gè)版本匹配的坑AdminLTE 3 基于 Bootstrap 4AdminLTE 4 基于 Bootstrap 5。如果從網(wǎng)上復(fù)制了個(gè) AdminLTE 3 的頁(yè)面模板又去引了 Bootstrap 5 的 CSS會(huì)出現(xiàn)間距全亂、圓角對(duì)不上、按鈕顏色偏色這類看著像但又不太像的問(wèn)題。這種情況我的建議是一旦確定用哪個(gè)版本把整套靜態(tài)資源一次性拷全不要東拼西湊。5. 增刪改查四個(gè)動(dòng)作真正花時(shí)間的都在細(xì)節(jié)里5.1 列表頁(yè)分頁(yè)、搜索條件回填與參數(shù)保持列表頁(yè)看著最簡(jiǎn)單實(shí)際上坑最多。分頁(yè)組件要跟搜索條件共存翻到第二頁(yè)的時(shí)候搜索條件不能丟這個(gè)是最基本的要求。我的做法是 Controller 接收查詢對(duì)象和分頁(yè)參數(shù)把所有條件重新塞回 ModelGetMapping(/list) public String list(UserQuery query, RequestParam(defaultValue 1) long current, RequestParam(defaultValue 10) long size, Model model) { IPageSysUser page userService.pageQuery(query, current, size); model.addAttribute(page, page); model.addAttribute(query, query); return user/list; }模板里的分頁(yè)鏈接必須帶上搜索條件nav ul classpagination pagination-sm li classpage-item th:classappend${page.current 1} ? disabled a classpage-link th:href{/user/list(current${page.current - 1}, size${page.size}, username${query.username}, status${query.status})}上一頁(yè)/a /li li classpage-item th:eachi : ${#numbers.sequence(1, page.pages)} th:classappend${i page.current} ? active a classpage-link th:href{/user/list(current${i}, size${page.size}, username${query.username}, status${query.status})} th:text${i}1/a /li li classpage-item th:classappend${page.current page.pages} ? disabled a classpage-link th:href{/user/list(current${page.current 1}, size${page.size}, username${query.username}, status${query.status})}下一頁(yè)/a /li /ul /nav{...}語(yǔ)法里括號(hào)內(nèi)的參數(shù)會(huì)自動(dòng)做 URL 編碼不用手動(dòng)處理中文。這是 Thymeleaf 一個(gè)很實(shí)用的特性用字符串拼接的方式拼 URL 反而容易出問(wèn)題。頁(yè)碼直接用#numbers.sequence全展開在數(shù)據(jù)量小的內(nèi)部系統(tǒng)里夠用。如果分頁(yè)超過(guò)二十頁(yè)這個(gè)寫法會(huì)把頁(yè)碼撐爆需要做滑動(dòng)窗口那就得寫個(gè)小工具方法或者在 Controller 里算好beginPage和endPage傳給模板。內(nèi)部系統(tǒng)我一般不管頁(yè)面撐開了用戶自己會(huì)縮小范圍。搜索表單的回填也要注意th:value里如果原值是 null渲染出來(lái)是空字符串不會(huì)報(bào)錯(cuò)但下拉框要注意選中狀態(tài)select namestatus classform-control option value全部狀態(tài)/option option value1 th:selected${query.status 1}啟用/option option value0 th:selected${query.status 0}停用/option /select這里有個(gè)類型陷阱query.status是Integer如果表單里value1Thymeleaf 在比較時(shí)做的是對(duì)象比較Integer(1) 1在 Thymeleaf 的表達(dá)式引擎里通常能自動(dòng)拆箱成立但如果 status 是String類型就會(huì)失敗。我在項(xiàng)目里統(tǒng)一用Integer接狀態(tài)值避免這個(gè)歧義。5.2 新增和編輯表單復(fù)用、校驗(yàn)失敗回顯與查重時(shí)機(jī)新增和編輯的頁(yè)面高度相似字段完全一樣區(qū)別只是有沒(méi)有初始值。復(fù)用同一個(gè)模板是標(biāo)準(zhǔn)做法用一個(gè)id是否為空來(lái)判斷GetMapping(/form) public String form(RequestParam(required false) Long id, Model model) { SysUser user id null ? new SysUser() : userService.getById(id); model.addAttribute(user, user); return user/form; }模板里所有th:value都綁到user對(duì)象的字段上新增時(shí)是空對(duì)象自然是空值。保存用兩個(gè)方法分別處理新增和修改不要試圖用一個(gè)方法通用因?yàn)樾ｒ?yàn)規(guī)則不一樣新增要查重修改要排除自己。校驗(yàn)這塊PostMapping(/save) public String save(Valid ModelAttribute(user) SysUser user, BindingResult bindingResult, RedirectAttributes ra) { if (userService.existsUsername(user.getUsername(), user.getId())) { bindingResult.rejectValue(username, duplicate, 該登錄名已被占用); } if (bindingResult.hasErrors()) { return user/form; } userService.saveOrUpdate(user); ra.addFlashAttribute(msg, 保存成功); return redirect:/user/list; }ModelAttribute(user)里的名字很關(guān)鍵它決定了模板里用${user}能不能取到值。如果校驗(yàn)失敗返回表單頁(yè)Model 里必須有這個(gè)對(duì)象ModelAttribute會(huì)自動(dòng)把它塞進(jìn)去。這一點(diǎn)如果漏了表現(xiàn)就是校驗(yàn)失敗跳回表單頁(yè)結(jié)果所有已填內(nèi)容全空用戶得重新填一遍體驗(yàn)極差。RedirectAttributes的addFlashAttribute是重定向后傳遞提示消息的標(biāo)準(zhǔn)做法數(shù)據(jù)存在 session 里跳轉(zhuǎn)后讀一次就沒(méi)了。如果用addAttribute參數(shù)會(huì)拼到 URL 上中文還得編碼很難看。表單模板里的錯(cuò)誤提示div classform-group label登錄名 span classtext-danger*/span/label input typetext classform-control th:classappend${#fields.hasErrors(user.username)} ? is-invalid th:field*{username} div classinvalid-feedback th:if${#fields.hasErrors(user.username)} th:errors*{username}錯(cuò)誤信息/div /divth:field*{username}會(huì)自動(dòng)生成id、name、value三個(gè)屬性比手寫th:value更省事而且跟#fields的錯(cuò)誤機(jī)制是配套的。用th:field的時(shí)候注意必須在form上掛th:object否則*{}語(yǔ)法找不到上下文。查重的時(shí)機(jī)也有講究。放在 Service 里做也行但那樣校驗(yàn)失敗的信息拿不到BindingResult只能拋異常或者返回錯(cuò)誤碼頁(yè)面回顯就得另想辦法。放在 Controller 里配合bindingResult.rejectValue是這套棧下最順手的做法錯(cuò)誤信息能直接出現(xiàn)在對(duì)應(yīng)字段下面。5.3 刪除單條、批量與邏輯刪除的取舍刪除功能最容易被輕視。一個(gè)GetMapping(/delete/{id})寫完就完事了看著能跑但這是典型的錯(cuò)誤做法——GET 請(qǐng)求被瀏覽器預(yù)加載、被爬蟲抓取、被用戶誤刷新都能觸發(fā)刪除。刪必須用 POST。PostMapping(/delete) public String delete(RequestParam Long id, RedirectAttributes ra) { userService.removeById(id); ra.addFlashAttribute(msg, 刪除成功); return redirect:/user/list; } PostMapping(/batchDelete) public String batchDelete(RequestParam(ids) ListLong ids, RedirectAttributes ra) { userService.removeByIds(ids); ra.addFlashAttribute(msg, 已刪除 ids.size() 條); return redirect:/user/list; }前端確認(rèn)用 AdminLTE 自帶的模態(tài)框或者confirm批量刪除要注意一個(gè)細(xì)節(jié)如果用戶一條都沒(méi)勾選就點(diǎn)刪除ids參數(shù)是空的Spring 綁定ListLong會(huì)直接拋 400。穩(wěn)妥的寫法是RequestParam(value ids, required false)進(jìn)來(lái)先判空if (CollectionUtils.isEmpty(ids)) { ra.addFlashAttribute(msg, 請(qǐng)先選擇要?jiǎng)h除的記錄); return redirect:/user/list; }邏輯刪除的取舍前面提過(guò)一部分這里補(bǔ)充一個(gè)實(shí)際場(chǎng)景如果業(yè)務(wù)上需要回收站功能邏輯刪除是必須的如果數(shù)據(jù)完全不敏感物理刪除反而干凈因?yàn)檐泟h除的記錄日積月累會(huì)讓表越來(lái)越大查詢還得帶條件。我的經(jīng)驗(yàn)是涉及人員、訂單、財(cái)務(wù)這類數(shù)據(jù)的表用邏輯刪除配置項(xiàng)、日志這類表直接物理刪?；熘脹](méi)問(wèn)題加不加TableLogic是按實(shí)體類控制的。6. 聯(lián)調(diào)階段最容易卡住的幾個(gè)現(xiàn)象與排查順序6.1 模板改了頁(yè)面不變先看緩存開關(guān)這個(gè)現(xiàn)象我第一次遇到時(shí)懷疑過(guò) IDE 沒(méi)保存、懷疑過(guò)瀏覽器緩存、懷疑過(guò) SpringBoot 沒(méi)熱加載折騰了快一個(gè)小時(shí)最后發(fā)現(xiàn)就是spring.thymeleaf.cachetrue。開發(fā)環(huán)境必須設(shè)成 false這個(gè)配置默認(rèn)值在 SpringBoot 里是 true。即使關(guān)了緩存如果你改了模板但沒(méi)重新編譯而項(xiàng)目又是從target/classes里讀模板的那還是看不到變化。IDEA 里的做法是 Build 一次或者用spring-boot-devtools配合自動(dòng)編譯。我用 devtools 的時(shí)候會(huì)把spring.thymeleaf.prefix指向file:src/main/resources/templates/直接從源碼目錄讀改完刷新就生效省掉編譯這一步spring: thymeleaf: prefix: file:src/main/resources/templates/ cache: false這個(gè)配置只能用在開發(fā)環(huán)境生產(chǎn)環(huán)境必須走 classpath。另外一個(gè)容易混淆的點(diǎn)改了 Java 代碼之后模板的變動(dòng)可能被編譯覆蓋。排查順序我一般是配置文件有沒(méi)有生效 → 模板路徑對(duì)不對(duì) → 編譯產(chǎn)物是不是最新的從外往里查比一上來(lái)就打斷點(diǎn)快。6.2 日期和數(shù)字的格式化Thymeleaf 里要靠工具類LocalDateTime直接輸出到頁(yè)面會(huì)是2024-03-15T10:23:45中間帶個(gè) T很難看。格式化的寫法td th:text${#temporals.format(user.createTime, yyyy-MM-dd HH:mm)}時(shí)間/td#temporals是 Thymeleaf 3 內(nèi)置的處理 Java 8 時(shí)間類型的工具需要thymeleaf-extras-java8time依賴不過(guò) SpringBoot 的 starter 里已經(jīng)包含了不用單獨(dú)引。如果是Date類型用的是#dates.format兩個(gè)工具類不能混用混了會(huì)報(bào)找不到方法。空值處理是另一個(gè)高頻問(wèn)題。${user.realName}如果是 null頁(yè)面直接不渲染內(nèi)容不會(huì)報(bào)錯(cuò)但#temporals.format(null, ...)會(huì)拋異常。穩(wěn)妥的寫法是td th:text${user.createTime ! null} ? ${#temporals.format(user.createTime, yyyy-MM-dd HH:mm)} : --/td金額類的字段用#numbers.formatDecimal(amount, 1, 2)保留兩位小數(shù)注意第一個(gè)參數(shù)是整數(shù)最少位數(shù)不是總位數(shù)這個(gè)參數(shù)含義經(jīng)常被搞反。6.3 靜態(tài)資源 404 與中文亂碼的分層排查靜態(tài)資源 404 的排查我有一套固定順序。先看 URL 對(duì)不對(duì)瀏覽器 F12 的網(wǎng)絡(luò)面板里能看到實(shí)際請(qǐng)求的路徑如果路徑里帶了../或者重復(fù)的/static/說(shuō)明模板里的路徑寫錯(cuò)了——{}語(yǔ)法不需要你手寫/static它對(duì)應(yīng)的就是static目錄的根。再看 Spring Security 有沒(méi)有攔截如果項(xiàng)目集成了安全框架靜態(tài)資源默認(rèn)是要放行的配置里漏了requestMatchers(/dist/**, /plugins/**).permitAll()就會(huì)全 404。最后看打包方式j(luò)ar 包里的static目錄是通過(guò) classpath 訪問(wèn)的如果資源放的目錄名不是static比如放成了public或者resources那 SpringBoot 也能識(shí)別但目錄名拼錯(cuò)就完了。中文亂碼分兩種。一種是請(qǐng)求參數(shù)亂碼表單提交的中文到后端變成問(wèn)號(hào)這是編碼配置問(wèn)題server.servlet.encoding.forcetrue加上頁(yè)面的charsetutf-8基本能解決。另一種是響應(yīng)內(nèi)容亂碼頁(yè)面上中文變成方塊或者亂碼通常是模板文件本身的編碼不對(duì)IDEA 里在文件右下角能看到當(dāng)前編碼確認(rèn)是 UTF-8 就行。還有一種最隱蔽的數(shù)據(jù)庫(kù)連接的characterEncoding寫成了utf8但表是utf8mb4存表情符號(hào)的時(shí)候報(bào)錯(cuò)或者截?cái)噙@個(gè)只能從建表語(yǔ)句開始統(tǒng)一。6.4 表單提交后提示信息不顯示addFlashAttribute存進(jìn)去的消息在頁(yè)面里要用${msg}取。取不到的情況一般是重定向的地址跟存放的會(huì)話不一致或者頁(yè)面模板里漏了判斷div classalert alert-success alert-dismissible th:if${msg ! null} button typebutton classclose>