管理模塊實(shí)戰(zhàn)：RBAC權(quán)限模型與Spring Security認(rèn)證鑒權(quán))
1. 系統(tǒng)管理模塊在后端項(xiàng)目里的真實(shí)定位做了這么多年后端我越來越確認(rèn)一件事系統(tǒng)管理模塊才是檢驗(yàn)后端工程師基本功的試金石。你們?cè)诤芏嗲昂蠖朔蛛x項(xiàng)目里看到的用戶管理、角色管理、菜單管理、部門管理、字典管理、操作日志和登錄日志表面看就是一組普通的增刪改查接口實(shí)際它們是整個(gè)系統(tǒng)的權(quán)限中樞和審計(jì)底座。這個(gè)模塊不炸業(yè)務(wù)模塊怎么做都還有補(bǔ)救空間這個(gè)模塊一旦權(quán)限失控后面接手的同事大概率只能推倒重來。這里先把概念收攏一下。系統(tǒng)管理模塊通常服務(wù)于兩類人一類是系統(tǒng)管理員負(fù)責(zé)維護(hù)組織架構(gòu)、賬號(hào)、角色、菜單、字典和參數(shù)另一類是普通用戶他們不直接感知這個(gè)模塊但每次登錄、每次點(diǎn)擊菜單、每次調(diào)用接口都在跟它打交道。前端需要從后端拿我有哪些菜單、我有哪些按鈕權(quán)限后端需要在這條鏈路的每一步?jīng)Q定這個(gè)請(qǐng)求放不放行。所以它不是一個(gè)普通 CRUD 模塊而是連接登錄體系、路由體系和接口安全體系的樞紐。先說一個(gè)最常見的認(rèn)知誤區(qū)很多人把系統(tǒng)管理模塊當(dāng)成先寫一批接口交差的腳手架代碼等業(yè)務(wù)模塊做起來之后權(quán)限需求一變才發(fā)現(xiàn)表結(jié)構(gòu)根本撐不住。比如想在用戶上掛多個(gè)部門想在角色里區(qū)分?jǐn)?shù)據(jù)范圍想對(duì)某個(gè)按鈕做臨時(shí)授權(quán)結(jié)果發(fā)現(xiàn)自己設(shè)計(jì)的用戶表只有單個(gè) role_id角色表沒有數(shù)據(jù)權(quán)限范圍字段菜單表里目錄和按鈕混在一張表卻沒有類型字段。這些問題不是功能開發(fā)問題是模型設(shè)計(jì)問題模型設(shè)計(jì)的坑到后期基本無(wú)解。1.1 為什么每個(gè)業(yè)務(wù)系統(tǒng)最后都會(huì)長(zhǎng)出一個(gè)系統(tǒng)管理模塊不需要什么高深理由只要有登錄和分工就必然有用戶、角色和菜單的需求。我見過最小的管理后臺(tái)只有一個(gè)管理員賬號(hào)直接在配置里寫死但后面業(yè)務(wù)發(fā)展起來運(yùn)營(yíng)要一個(gè)賬號(hào)、客服要一個(gè)賬號(hào)、財(cái)務(wù)要一個(gè)賬號(hào)還要限制各自的菜單和按鈕就只能回來補(bǔ)系統(tǒng)管理模塊。還有一個(gè)被忽略的理由是審計(jì)。線上出問題的時(shí)候你總得知道是哪個(gè)用戶在什么時(shí)間干了什么。所以操作日志和登錄日志不是可選項(xiàng)。尤其是涉及訂單、支付、審批這類敏感操作沒有日志就等于把腦袋伸出去讓別人砍。從前后端分離的視角再看一層前端路由和菜單不是寫死在代碼里的而是登錄后根據(jù)用戶的角色動(dòng)態(tài)生成。這就要求后端不僅返回 token還要返回用戶信息、角色集合和權(quán)限標(biāo)識(shí)集合。前端根據(jù)這些數(shù)據(jù)去渲染側(cè)邊欄攔截路由跳轉(zhuǎn)控制按鈕顯示。換句話說系統(tǒng)管理模塊輸出的是權(quán)限視圖整個(gè)前端的 UI 骨架都依賴它。1.2 模塊邊界怎么劃才不會(huì)把業(yè)務(wù)代碼拖下水我的做法是給系統(tǒng)管理模塊定三條硬邊界。第一它只放平臺(tái)級(jí)通用能力不摻業(yè)務(wù)字段。用戶表可以存歸屬部門但絕對(duì)不要把會(huì)員等級(jí)客戶來源這種業(yè)務(wù)字段堆進(jìn)來業(yè)務(wù)信息應(yīng)該放業(yè)務(wù)表里通過 userId 關(guān)聯(lián)。第二所有系統(tǒng)管理接口必須能設(shè)置權(quán)限標(biāo)識(shí)統(tǒng)一按 system:xxx:yyy 的格式命名比如 system:user:list、system:role:edit、system:menu:delete。第三系統(tǒng)管理模塊的代碼在物理上獨(dú)立成包接口路徑統(tǒng)一以 /system 開頭方便網(wǎng)關(guān)做路由隔離和統(tǒng)一日志。邊界劃清楚之后業(yè)務(wù)模塊做起來會(huì)非常舒服。業(yè)務(wù)表只關(guān)心自己的業(yè)務(wù)數(shù)據(jù)需要知道當(dāng)前用戶是誰(shuí)就去拿 SecurityContext 或者公共上下文里的 LoginUser需要判斷有沒有某個(gè)權(quán)限直接用 PreAuthorize 注解不用自己寫第二套鑒權(quán)邏輯。我自己見過最痛苦的項(xiàng)目是每個(gè) Controller 里都有一段復(fù)制粘貼的判斷用戶角色代碼業(yè)務(wù)一復(fù)雜那段邏輯改了五處只改了三處線上數(shù)據(jù)就是這么漏出去的。2. 先把RBAC這張底網(wǎng)織好表結(jié)構(gòu)設(shè)計(jì)經(jīng)驗(yàn)先講清楚 RBAC 的核心用戶與權(quán)限不直接掛鉤用戶先掛到角色上角色再擁有權(quán)限集合。為什么中間要多一層角色因?yàn)橹苯咏o用戶綁權(quán)限幾百個(gè)用戶時(shí)你還能忍幾千個(gè)用戶時(shí)就完全失控了。加一層角色新增一個(gè)人只需要給他分配角色調(diào)整權(quán)限只需要改角色用戶側(cè)無(wú)感生效。但要注意RBAC 落地的時(shí)候有兩個(gè)方向一種是用戶-角色-菜單/接口的粗粒度權(quán)限解決能進(jìn)哪個(gè)界面、能點(diǎn)哪個(gè)按鈕另一種是數(shù)據(jù)權(quán)限解決能看到哪些數(shù)據(jù)比如銷售只能看自己的訂單部門主管能看本部門的訂單。這兩種東西必須分開設(shè)計(jì)。表結(jié)構(gòu)上前者用菜單權(quán)限表后者通常用角色表上的 data_scope 字段再加自定義規(guī)則。2.1 五張核心表的字段與關(guān)聯(lián)我用得最多的是下面這套表組合它覆蓋了絕大多數(shù)管理后臺(tái)的需求表名作用關(guān)鍵字段sys_user系統(tǒng)用戶user_id, dept_id, username, password, status, del_flagsys_role角色role_id, role_name, role_key, data_scope, statussys_menu菜單/按鈕權(quán)限menu_id, parent_id, menu_type, perms, path, componentsys_user_role用戶-角色關(guān)聯(lián)user_id, role_idsys_role_menu角色-菜單關(guān)聯(lián)role_id, menu_idsys_user 最容易被忽略的是 dept_id。這個(gè)字段不只是一個(gè)組織歸屬的展示字段它是后面做數(shù)據(jù)權(quán)限過濾的錨點(diǎn)。比如銷售主管希望看到本部門及以下部門的數(shù)據(jù)程序在查詢業(yè)務(wù)表時(shí)就可以通過 dept_id 把數(shù)據(jù)范圍限定住。status 和 del_flag 一定要有前者控制賬號(hào)是否禁用后者做邏輯刪除。密碼字段只存 BCrypt 加密后的哈希串。sys_role 里除了 role_name最好加一個(gè) role_key 作為代碼層面的唯一標(biāo)識(shí)比如 admin、common。為什么不用 role_id因?yàn)閿?shù)據(jù)庫(kù)主鍵在遷移和合并環(huán)境時(shí)可能變化而 role_key 是業(yè)務(wù)常量可以在代碼里安全判斷。data_scope 字段表示數(shù)據(jù)權(quán)限范圍常見值有全部、本部門及以下、本部門、僅本人、自定義。自定義一般還要配一張 sys_role_dept 表來指定可見部門這個(gè)看項(xiàng)目規(guī)模決定要不要加。sys_menu 里的 menu_type 我習(xí)慣用 M(目錄)、C(菜單)、F(按鈕) 三種。目錄是頂級(jí)分組菜單是左側(cè)導(dǎo)航的葉子節(jié)點(diǎn)按鈕是頁(yè)面里的操作權(quán)限。perms 字段對(duì)目錄和菜單不一定必須但按鈕權(quán)限一定要寫比如 system:user:add。前端拿到這些 perms 集合后用指令判斷按鈕要不要渲染后端用同樣的字符串做接口鑒權(quán)。sys_user_role 和 sys_role_menu 就是兩張純關(guān)聯(lián)表各帶主鍵或聯(lián)合主鍵。不要嫌多表查詢麻煩權(quán)限體系一旦出現(xiàn)一個(gè)用戶多個(gè)角色、一個(gè)角色多個(gè)菜單的情況關(guān)聯(lián)表是最容易擴(kuò)展和維護(hù)的。2.2 部門、字典、日志這類輔助表的設(shè)計(jì)細(xì)節(jié)部門表 sys_dept 是樹形結(jié)構(gòu)parent_id 指向上級(jí)部門根節(jié)點(diǎn)可以設(shè) parent_id 0。我有一個(gè)強(qiáng)烈建議一定要加 ancestors 字段例如當(dāng)前部門 id12上級(jí)是 3那 ancestors 就存 0,3。這個(gè)字段用來查詢本部門及以下所有部門時(shí)非常方便直接構(gòu)造 dept_id in (子部門列表)不用遞歸。字典表要分成 sys_dict_type 和 sys_dict_data 兩張前者定義字典類型比如 order_status后者存具體字典項(xiàng)比如 status0 表示待支付、status1 表示已支付。把業(yè)務(wù)里的枚舉值抽成字典好處是前端下拉框直接從后端拿運(yùn)營(yíng)可以自己維護(hù)不用每次加枚舉都發(fā)版本。代價(jià)是查詢多一層緩存這個(gè)可以通過本地緩存或者 Redis 解決。日志表至少兩張sys_oper_log 記錄操作日志sys_login_log 記錄登錄日志。操作日志字段包括操作人、操作模塊、請(qǐng)求方法、請(qǐng)求路徑、請(qǐng)求參數(shù)、返回結(jié)果、耗時(shí)、IP、操作時(shí)間。注意不要把請(qǐng)求體原樣存巨大字段遇到文件上傳一定要截?cái)唷５卿浫罩局辽僖杏脩裘?、登錄狀態(tài)、IP、瀏覽器 User-Agent、登錄時(shí)間。日志表的寫入場(chǎng)景是高并發(fā)、低價(jià)值所以不要和業(yè)務(wù)接口放在同一個(gè)事務(wù)里要么單獨(dú)線程池要么直接異步落庫(kù)。3. 認(rèn)證與鑒權(quán)鏈路JWT Spring Security 的串法表結(jié)構(gòu)定了之后真正難的部分在認(rèn)證鑒權(quán)。這里我用 Java 技術(shù)棧的 Spring Boot 3 Spring Security JWT Redis 來拆解這套組合在目前前后端分離項(xiàng)目里非常常見。為什么不自己在攔截器里手動(dòng)解析 token因?yàn)檎J(rèn)證流程的邊界情況很多token 過期、刷新、用戶被禁用、權(quán)限變更、并發(fā)登錄、CSRF、跨域預(yù)檢Spring Security 的過濾器鏈把這些能力標(biāo)準(zhǔn)化了你只需要按自己的業(yè)務(wù)去填充。3.1 登錄接口里到底要做幾件事很多人寫登錄接口只做了三件事查用戶、比密碼、發(fā) token。但實(shí)際生產(chǎn)環(huán)境里登錄接口至少要按這個(gè)順序做完整校驗(yàn)驗(yàn)證碼。驗(yàn)證碼存在 Rediskey 用 uuid創(chuàng)建時(shí)設(shè)置過期時(shí)間校驗(yàn)后立刻刪除防止暴力重放。根據(jù)用戶名查詢用戶。這里要注意查詢時(shí)把密碼字段帶出來因?yàn)楹竺嬉容^哈希值但返回給前端時(shí)永遠(yuǎn)不要序列化密碼字段。檢查用戶狀態(tài)和角色狀態(tài)。status 為 1 的賬號(hào)直接拒絕登錄并記錄登錄日志。用 BCryptPasswordEncoder 的 matches 方法校驗(yàn)密碼。不要用 MD5不要自己發(fā)明加鹽邏輯。登錄成功后生成 JWT。JWT 里只放 userId 和一個(gè) tokenId不要塞用戶角色和權(quán)限列表因?yàn)?JWT 是簽名但未加密的而且權(quán)限數(shù)據(jù)放在 token 里無(wú)法實(shí)時(shí)更新。把 LoginUser 對(duì)象包含用戶基本信息、角色集合、權(quán)限標(biāo)識(shí)集合存入 Rediskey 可以用 login_token:userId:tokenId指定過期時(shí)間。返回結(jié)果里攜帶 token 和用戶信息。前端把 token 存起來每次請(qǐng)求自動(dòng)放到 Authorization 頭。登錄失敗也需要寫 log 嗎需要。登錄失敗日志對(duì)安全審計(jì)特別重要連續(xù)失敗次數(shù)還可以作為賬號(hào)鎖定的判斷依據(jù)。我一般會(huì)用 Redis 記錄失敗次數(shù)比如 1 小時(shí)內(nèi)失敗 5 次鎖定 15 分鐘。3.2 接口級(jí)鑒權(quán)為什么必須靠權(quán)限標(biāo)識(shí)前后端分離項(xiàng)目里最大的安全誤區(qū)是以為前端隱藏了菜單和按鈕用戶就看不到那些功能了。實(shí)際上接口才是數(shù)據(jù)的真正入口任何人只要拿到一個(gè) token就可以繞過前端直接請(qǐng)求接口。所以每個(gè)敏感接口都必須由后端鑒權(quán)。Spring Security 里我習(xí)慣配合自定義注解。先定義一個(gè) PermissionService從 SecurityContext 中取當(dāng)前登錄用戶的權(quán)限集合判斷是否包含某個(gè)權(quán)限標(biāo)識(shí)Service(ss) public class PermissionService { public boolean hasPermi(String permission) { if (StringUtils.isEmpty(permission)) { return false; } LoginUser loginUser SecurityUtils.getLoginUser(); if (loginUser null) { return false; } // 超級(jí)管理員直接放行 if (loginUser.isAdmin()) { return true; } return loginUser.getPermissions().contains(permission); } }Controller 里這樣用PreAuthorize(ss.hasPermi(system:user:list)) GetMapping(/list) public TableDataInfo list(SysUser user) { ... }這樣配置的好處是權(quán)限標(biāo)識(shí)和表里的 sys_menu.perms 字段完全對(duì)得上。菜單管理界面上每加一個(gè)按鈕權(quán)限標(biāo)識(shí)后端接口只要用同一串字符串做注解前端按鈕也用同一串字符串做 v-hasPermi 判斷三個(gè)地方一套數(shù)據(jù)不會(huì)出現(xiàn)前端按鈕看不到但接口能調(diào)的錯(cuò)位。3.3 Redis 在認(rèn)證鏈路中的角色Redis 在體系里做了三件事。第一存驗(yàn)證碼和登錄失敗次數(shù)第二存用戶登錄態(tài)實(shí)現(xiàn)真正可注銷、可踢人、可續(xù)期的會(huì)話第三緩存用戶的權(quán)限集合。為什么要存權(quán)限而不是每次鑒權(quán)都查數(shù)據(jù)庫(kù)查一次權(quán)限集合要關(guān)聯(lián)用戶表、角色表、菜單表一個(gè)請(qǐng)求里可能有好幾個(gè)接口要做 PreAuthorize 判斷次次查數(shù)據(jù)庫(kù)性能頂不住。重點(diǎn)是權(quán)限變更后的緩存同步。系統(tǒng)管理員改了某個(gè)角色的菜單如果緩存里的舊權(quán)限不清理用戶在有效期內(nèi)依然能調(diào)用已經(jīng)收回的接口這是權(quán)限系統(tǒng)的硬傷。我的做法是更新角色菜單的時(shí)候刪除該角色關(guān)聯(lián)的所有用戶的 LoginUser 緩存更新用戶角色的分配時(shí)刪除該用戶的緩存。用戶下一個(gè)請(qǐng)求進(jìn)來解析 token 時(shí)發(fā)現(xiàn)緩存不存在就重新從數(shù)據(jù)庫(kù)加載權(quán)限并寫入 Redis。這一步的核心代碼如下// 角色菜單變更后 userOnlineService.removeUserCacheByRoleId(roleId); // 用戶角色重新分配后 userOnlineService.removeUserCacheByUserId(userId);如果項(xiàng)目里已經(jīng)用上了消息隊(duì)列也可以用事件發(fā)布通知所有實(shí)例清緩存沒有消息隊(duì)列就靠 Redis key 刪除后自動(dòng)重新加載來兜底。這里要特別注意分布式環(huán)境下的延遲問題權(quán)限變更后未必立刻在所有實(shí)例生效但通常一兩秒內(nèi)能收斂。4. 用戶、角色、菜單接口的分層落地Controller-Service-Mapper 實(shí)際寫法系統(tǒng)管理模塊的接口特別適合展示一套規(guī)整的三層結(jié)構(gòu)因?yàn)檫壿嫴粡?fù)雜但邊界必須清晰。我自己總結(jié)的規(guī)則是Controller 只做參數(shù)接收和結(jié)果封裝Service 做業(yè)務(wù)規(guī)則和事務(wù)控制Mapper 只做 SQL 查詢。事務(wù)、異常、唯一性校驗(yàn)這類問題不在 Controller 里寫。4.1 用戶管理分頁(yè)、新增、分配角色、重置密碼用戶管理的核心接口就六個(gè)分頁(yè)查詢、根據(jù)用戶編號(hào)查詢?cè)斍?、新增用戶、修改用戶、刪除用戶、重置密碼。分頁(yè)查詢一般配合 PageHelperGetMapping(/list) public TableDataInfo list(SysUser user) { startPage(); ListSysUser list userService.selectUserList(user); return getDataTable(list); }startPage 是 PageHelper 的靜態(tài)方法它通過攔截器把下一條 SQL 包成分頁(yè)查詢返回的 list 實(shí)際是 Page 對(duì)象再由 getDataTable 把 total 和 rows 封裝成前端需要的結(jié)構(gòu)。這里有一個(gè)坑startPage 和它作用的那條 SQL 之間不能夾著其他 SQL 操作一旦中間有別的查詢PageHelper 會(huì)把分頁(yè)參數(shù)作用到錯(cuò)誤的 SQL 上。新增用戶時(shí)最重要的一步是唯一性校驗(yàn)。username 必須唯一但如果你做了邏輯刪除就有一個(gè)經(jīng)典坑刪除的用戶還占著 username再新增同名用戶時(shí)唯一索引直接報(bào)錯(cuò)。解決思路我放到第 5 章展開。新增用戶還需要給一個(gè)初始密碼通常用一個(gè)默認(rèn)值 123456并且把 isNeedUpdatePwd 這類字段標(biāo)記為 true前端檢測(cè)到該字段就彈窗要求改密。分配角色是用戶管理里另一個(gè)容易做錯(cuò)的地方。前端提交的 userIds 和 roleIds 是一對(duì)多關(guān)系Service 里必須在事務(wù)內(nèi)先刪除 sys_user_role 里該用戶的全部記錄再批量插入新的關(guān)聯(lián)記錄。不要只做增刪差量雖然效率高但業(yè)務(wù)場(chǎng)景下全刪全插最可靠而且這個(gè)表數(shù)據(jù)量一般不大沒必要做復(fù)雜 diff。4.2 角色管理分配菜單與同步更新角色管理的重點(diǎn)是角色-菜單關(guān)系。新增角色時(shí)前端會(huì)傳來一個(gè)菜單 id 的樹形勾選列表注意這個(gè)列表里一般既包含父級(jí)目錄也包含子菜單和按鈕不要只存葉子節(jié)點(diǎn)。為什么因?yàn)榍岸藙?dòng)態(tài)路由要判斷當(dāng)前角色有沒有某個(gè)目錄或菜單的可見權(quán)如果目錄沒被勾選子菜單即使有權(quán)限也無(wú)法在側(cè)邊欄展示。所以插入 sys_role_menu 的時(shí)候全部按提交的 menuIds 插入即可。修改角色時(shí)則要先更新 sys_role 基礎(chǔ)信息再刪除原有的角色菜單關(guān)聯(lián)再重新插入新的關(guān)聯(lián)。這兩個(gè)操作必須放在同一個(gè)事務(wù)里否則中途異常會(huì)出現(xiàn)角色信息是新的、菜單權(quán)限是舊的這種臟數(shù)據(jù)。刪除角色前必須檢查 sys_user_role 里是否還有用戶引用。如果有前端要給出明確提示該角色已分配給 N 個(gè)用戶請(qǐng)先解除分配后再刪除。否則直接刪除角色會(huì)導(dǎo)致這些用戶的權(quán)限集合變成幽靈數(shù)據(jù)登錄后菜單無(wú)法正常加載。多表操作建議寫成下面這種事務(wù)控制方式Transactional(rollbackFor Exception.class) public void updateRole(SysRole role) { // 1. 更新角色表 roleMapper.updateRole(role); // 2. 刪除舊的菜單關(guān)聯(lián) roleMenuMapper.deleteRoleMenuByRoleId(role.getRoleId()); // 3. 插入新的菜單關(guān)聯(lián) insertRoleMenu(role); }4.3 菜單管理樹形結(jié)構(gòu)、動(dòng)態(tài)路由與按鈕權(quán)限菜單管理的查詢接口返回的不是平鋪列表而是樹形結(jié)構(gòu)。前端拿到樹之后做兩件事一是管理界面的樹形表格二是登錄后根據(jù)角色可訪問菜單構(gòu)建動(dòng)態(tài)路由。后端這邊的核心是遞歸構(gòu)建樹public ListSysMenu buildMenuTree(ListSysMenu menus) { // 先按 parentId 分組再?gòu)母?jié)點(diǎn)開始組裝 children }遞歸本身不難難點(diǎn)在數(shù)據(jù)校驗(yàn)。比如 parentId 不能指向自身不能形成環(huán)否則前端渲染路由時(shí)會(huì)死循環(huán)。我見過一個(gè)項(xiàng)目在菜單表里把 A 菜單的 parentId 配成了 BB 的 parentId 又配成了 A前端頁(yè)面直接卡死。所以新增菜單時(shí)建議做一次父節(jié)點(diǎn)鏈檢測(cè)確保新菜單的父節(jié)點(diǎn)不能是自己的子節(jié)點(diǎn)。按鈕權(quán)限這塊要跟菜單類型聯(lián)動(dòng)。如果 menu_typeF那 component 和 path 都可以不填只填 perms 和菜單名稱如果 menu_typeC則必須填 component對(duì)應(yīng)前端頁(yè)面的組件路徑。后端接口在返回路由給前端時(shí)通常會(huì)把按鈕類型的菜單過濾掉因?yàn)樗鼈儾粎⑴c路由只參與權(quán)限標(biāo)識(shí)集。5. 上線前最容易翻車的細(xì)節(jié)跨域、邏輯刪除、權(quán)限緩存一致性5.1 三個(gè)真實(shí)踩過坑唯一索引、樹形遞歸、跨域第一個(gè)坑是邏輯刪除和唯一索引打架。MySQL 的表結(jié)構(gòu)里 username 上建了唯一索引用戶刪除時(shí)我們把 del_flag 從 0 改成 1數(shù)據(jù)還在索引還占著導(dǎo)致新用戶無(wú)法使用同一個(gè)用戶名。常規(guī)解法有幾種刪除時(shí)把 username 改名比如 username_del_{id}或者索引字段改成 (username, del_flag)但邏輯刪除的字段是 0 和 1刪除多條同樣 username 的記錄會(huì)重復(fù)沖突比較穩(wěn)的方案是數(shù)據(jù)庫(kù)表去掉唯一索引把唯一性校驗(yàn)完全放在 Service 層配合分布式鎖避免并發(fā)創(chuàng)建同名用戶。第二個(gè)坑是樹形遞歸的效率和深度問題。部門表、菜單表的深度通常不會(huì)太大但如果不加控制遞歸查詢會(huì)變成多次全表查詢。更常見的是刪除父節(jié)點(diǎn)時(shí)沒有校驗(yàn)子節(jié)點(diǎn)導(dǎo)致留下一堆孤兒節(jié)點(diǎn)。所以我在刪除接口里都會(huì)先查子節(jié)點(diǎn)數(shù)量大于 0 就拒絕刪除把原因?qū)懬宄嬖V前端。第三個(gè)坑是跨域配置。前后端分離項(xiàng)目里前端和后端端口不同最常見的做法是后端允許所有來源跨域。但如果開啟了 allowCredentials(true) 用來傳遞 cookie那么 allowedOrigins 就不能配成 *瀏覽器會(huì)直接報(bào)錯(cuò)。正確寫法是允許具體的前端域名或者用 allowedOriginPatterns。另外Spring Security 的攔截鏈里必須對(duì) CORS 預(yù)檢請(qǐng)求 OPTIONS 放行否則前端會(huì)發(fā)現(xiàn)后端明明配了跨域但還是請(qǐng)求失敗。5.2 性能與安全自查清單上線前我會(huì)按下面這份清單過一遍系統(tǒng)管理模塊檢查項(xiàng)說明密碼存儲(chǔ)確認(rèn)沒有明文密碼BCrypt 成本因子不低于 10越權(quán)訪問普通用戶 token 不能訪問 system:user:list 等管理接口邏輯刪除范圍所有管理表都有 del_flag所有查詢 SQL 都帶 del_flag0權(quán)限緩存一致性角色菜單修改后用戶權(quán)限緩存能及時(shí)失效分頁(yè) SQL 參數(shù)排序字段不能直接拼用戶輸入需要白名單校驗(yàn)操作日志脫敏密碼、token、身份證字段在日志里要過濾文件上傳接口上傳接口必須有獨(dú)立權(quán)限標(biāo)識(shí)防止匿名上傳超管賬號(hào)管理超級(jí)管理員數(shù)量嚴(yán)格控制使用獨(dú)立強(qiáng)密碼管理這些條目看起來瑣碎但權(quán)限類事故十有八九都出在這些地方。特別是在權(quán)限緩存一致性上我建議每次發(fā)布涉及權(quán)限的變更后主動(dòng)清空一遍登錄用戶緩存寧可讓用戶重新登錄也不要讓舊權(quán)限殘留在線。6. 實(shí)測(cè)下來的一點(diǎn)體會(huì)與可擴(kuò)展方向先說體會(huì)。系統(tǒng)管理模塊是一個(gè)典型的不需要重復(fù)造輪子、但必須看懂輪子的模塊。用開源框架作為起點(diǎn)是高效的比如可以參考若依這類前后端分離項(xiàng)目代碼完整、權(quán)限鏈路清晰能直接拿來改。但我建議至少把表結(jié)構(gòu)、認(rèn)證流程、權(quán)限判斷這三塊吃透否則遇到定制需求只能瞎加字段、繞開原有設(shè)計(jì)最后越改越亂。我自己的經(jīng)驗(yàn)是能不動(dòng)的地方盡量不動(dòng)要?jiǎng)拥臅r(shí)候先畫清楚改動(dòng)鏈路只改業(yè)務(wù)側(cè)不動(dòng)權(quán)限模型。再說兩個(gè)來自實(shí)測(cè)項(xiàng)目的對(duì)比。一個(gè)項(xiàng)目是內(nèi)部管理系統(tǒng)用戶量小我按標(biāo)準(zhǔn) RBAC 實(shí)現(xiàn)沒有做數(shù)據(jù)權(quán)限只靠菜單控制完全夠用另一個(gè)項(xiàng)目是給第三方客戶用的運(yùn)營(yíng)平臺(tái)用戶量幾千部門層級(jí)四層我加了數(shù)據(jù)權(quán)限角色表里新增 data_scope 字段并在業(yè)務(wù)查詢里拼接部門條件。同樣一個(gè)訂單查詢接口有數(shù)據(jù)權(quán)限版本和無(wú)數(shù)據(jù)權(quán)限版本表面看只差了一個(gè) where 子句實(shí)際上統(tǒng)計(jì)邏輯完全不同。數(shù)據(jù)權(quán)限的 SQL 拼接需要在 Service 層做統(tǒng)一封裝不要散到各個(gè) Mapper 里否則每個(gè)業(yè)務(wù)查詢都要自己寫一遍維護(hù)成本極高。然后是擴(kuò)展方向。第一個(gè)方向是數(shù)據(jù)權(quán)限細(xì)化在 sys_role 里加 data_scope 字段配合部門表在業(yè)務(wù)查詢時(shí)自動(dòng)追加 SQL 過濾條件。第二個(gè)方向是多租戶系統(tǒng)管理這需要在所有表加 tenant_id在登錄認(rèn)證時(shí)解析租戶上下文業(yè)務(wù)接口的查詢默認(rèn)帶上租戶過濾。多租戶這塊我建議最好在項(xiàng)目一開始就決定做不做不要在跑了一年后拖到高峰期再改造。改造的關(guān)鍵不僅在表加 tenant_id更在認(rèn)證環(huán)節(jié)登錄時(shí)要根據(jù)用戶的租戶編碼確認(rèn)身份Redis 緩存 key 也要帶 tenantId否則兩個(gè)租戶下同名的用戶名會(huì)互相覆蓋緩存。第三個(gè)方向是把操作日志跟消息中間件打通操作日志只負(fù)責(zé)往隊(duì)列里丟消費(fèi)端負(fù)責(zé)落庫(kù)和告警既不影響主流程性能也能做實(shí)時(shí)風(fēng)險(xiǎn)預(yù)警。最后分享一個(gè)實(shí)際操作中的小技巧新項(xiàng)目從零搭建時(shí)可以先把用戶、角色、菜單、部門、字典、日志這六個(gè)子模塊的接口和權(quán)限標(biāo)識(shí)梳理成一張清單再開始寫代碼。這張清單既是開發(fā)計(jì)劃也是后面聯(lián)調(diào)時(shí)給前端同事的接口契約更是上線前安全測(cè)試的檢查依據(jù)。代碼可以抄、框架可以選但權(quán)限模型必須自己想清楚。系統(tǒng)管理模塊這一章看似平淡往后幾乎每一個(gè)業(yè)務(wù)需求都會(huì)踩在它上面值得你多花幾天把它釘牢。 系統(tǒng)管理模塊實(shí)戰(zhàn)：RBAC權(quán)限模型與Spring Security認(rèn)證鑒權(quán)
1. 系統(tǒng)管理模塊在后端項(xiàng)目里的真實(shí)定位做了這么多年后端我越來越確認(rèn)一件事系統(tǒng)管理模塊才是檢驗(yàn)后端工程師基本功的試金石。你們?cè)诤芏嗲昂蠖朔蛛x項(xiàng)目里看到的用戶管理、角色管理、菜單管理、部門管理、字典管理、操作日志和登錄日志表面看就是一組普通的增刪改查接口實(shí)際它們是整個(gè)系統(tǒng)的權(quán)限中樞和審計(jì)底座。這個(gè)模塊不炸業(yè)務(wù)模塊怎么做都還有補(bǔ)救空間這個(gè)模塊一旦權(quán)限失控后面接手的同事大概率只能推倒重來。這里先把概念收攏一下。系統(tǒng)管理模塊通常服務(wù)于兩類人一類是系統(tǒng)管理員負(fù)責(zé)維護(hù)組織架構(gòu)、賬號(hào)、角色、菜單、字典和參數(shù)另一類是普通用戶他們不直接感知這個(gè)模塊但每次登錄、每次點(diǎn)擊菜單、每次調(diào)用接口都在跟它打交道。前端需要從后端拿我有哪些菜單、我有哪些按鈕權(quán)限后端需要在這條鏈路的每一步?jīng)Q定這個(gè)請(qǐng)求放不放行。所以它不是一個(gè)普通 CRUD 模塊而是連接登錄體系、路由體系和接口安全體系的樞紐。先說一個(gè)最常見的認(rèn)知誤區(qū)很多人把系統(tǒng)管理模塊當(dāng)成先寫一批接口交差的腳手架代碼等業(yè)務(wù)模塊做起來之后權(quán)限需求一變才發(fā)現(xiàn)表結(jié)構(gòu)根本撐不住。比如想在用戶上掛多個(gè)部門想在角色里區(qū)分?jǐn)?shù)據(jù)范圍想對(duì)某個(gè)按鈕做臨時(shí)授權(quán)結(jié)果發(fā)現(xiàn)自己設(shè)計(jì)的用戶表只有單個(gè) role_id角色表沒有數(shù)據(jù)權(quán)限范圍字段菜單表里目錄和按鈕混在一張表卻沒有類型字段。這些問題不是功能開發(fā)問題是模型設(shè)計(jì)問題模型設(shè)計(jì)的坑到后期基本無(wú)解。1.1 為什么每個(gè)業(yè)務(wù)系統(tǒng)最后都會(huì)長(zhǎng)出一個(gè)系統(tǒng)管理模塊不需要什么高深理由只要有登錄和分工就必然有用戶、角色和菜單的需求。我見過最小的管理后臺(tái)只有一個(gè)管理員賬號(hào)直接在配置里寫死但后面業(yè)務(wù)發(fā)展起來運(yùn)營(yíng)要一個(gè)賬號(hào)、客服要一個(gè)賬號(hào)、財(cái)務(wù)要一個(gè)賬號(hào)還要限制各自的菜單和按鈕就只能回來補(bǔ)系統(tǒng)管理模塊。還有一個(gè)被忽略的理由是審計(jì)。線上出問題的時(shí)候你總得知道是哪個(gè)用戶在什么時(shí)間干了什么。所以操作日志和登錄日志不是可選項(xiàng)。尤其是涉及訂單、支付、審批這類敏感操作沒有日志就等于把腦袋伸出去讓別人砍。從前后端分離的視角再看一層前端路由和菜單不是寫死在代碼里的而是登錄后根據(jù)用戶的角色動(dòng)態(tài)生成。這就要求后端不僅返回 token還要返回用戶信息、角色集合和權(quán)限標(biāo)識(shí)集合。前端根據(jù)這些數(shù)據(jù)去渲染側(cè)邊欄攔截路由跳轉(zhuǎn)控制按鈕顯示。換句話說系統(tǒng)管理模塊輸出的是權(quán)限視圖整個(gè)前端的 UI 骨架都依賴它。1.2 模塊邊界怎么劃才不會(huì)把業(yè)務(wù)代碼拖下水我的做法是給系統(tǒng)管理模塊定三條硬邊界。第一它只放平臺(tái)級(jí)通用能力不摻業(yè)務(wù)字段。用戶表可以存歸屬部門但絕對(duì)不要把會(huì)員等級(jí)客戶來源這種業(yè)務(wù)字段堆進(jìn)來業(yè)務(wù)信息應(yīng)該放業(yè)務(wù)表里通過 userId 關(guān)聯(lián)。第二所有系統(tǒng)管理接口必須能設(shè)置權(quán)限標(biāo)識(shí)統(tǒng)一按 system:xxx:yyy 的格式命名比如 system:user:list、system:role:edit、system:menu:delete。第三系統(tǒng)管理模塊的代碼在物理上獨(dú)立成包接口路徑統(tǒng)一以 /system 開頭方便網(wǎng)關(guān)做路由隔離和統(tǒng)一日志。邊界劃清楚之后業(yè)務(wù)模塊做起來會(huì)非常舒服。業(yè)務(wù)表只關(guān)心自己的業(yè)務(wù)數(shù)據(jù)需要知道當(dāng)前用戶是誰(shuí)就去拿 SecurityContext 或者公共上下文里的 LoginUser需要判斷有沒有某個(gè)權(quán)限直接用 PreAuthorize 注解不用自己寫第二套鑒權(quán)邏輯。我自己見過最痛苦的項(xiàng)目是每個(gè) Controller 里都有一段復(fù)制粘貼的判斷用戶角色代碼業(yè)務(wù)一復(fù)雜那段邏輯改了五處只改了三處線上數(shù)據(jù)就是這么漏出去的。2. 先把RBAC這張底網(wǎng)織好表結(jié)構(gòu)設(shè)計(jì)經(jīng)驗(yàn)先講清楚 RBAC 的核心用戶與權(quán)限不直接掛鉤用戶先掛到角色上角色再擁有權(quán)限集合。為什么中間要多一層角色因?yàn)橹苯咏o用戶綁權(quán)限幾百個(gè)用戶時(shí)你還能忍幾千個(gè)用戶時(shí)就完全失控了。加一層角色新增一個(gè)人只需要給他分配角色調(diào)整權(quán)限只需要改角色用戶側(cè)無(wú)感生效。但要注意RBAC 落地的時(shí)候有兩個(gè)方向一種是用戶-角色-菜單/接口的粗粒度權(quán)限解決能進(jìn)哪個(gè)界面、能點(diǎn)哪個(gè)按鈕另一種是數(shù)據(jù)權(quán)限解決能看到哪些數(shù)據(jù)比如銷售只能看自己的訂單部門主管能看本部門的訂單。這兩種東西必須分開設(shè)計(jì)。表結(jié)構(gòu)上前者用菜單權(quán)限表后者通常用角色表上的 data_scope 字段再加自定義規(guī)則。2.1 五張核心表的字段與關(guān)聯(lián)我用得最多的是下面這套表組合它覆蓋了絕大多數(shù)管理后臺(tái)的需求表名作用關(guān)鍵字段sys_user系統(tǒng)用戶user_id, dept_id, username, password, status, del_flagsys_role角色role_id, role_name, role_key, data_scope, statussys_menu菜單/按鈕權(quán)限menu_id, parent_id, menu_type, perms, path, componentsys_user_role用戶-角色關(guān)聯(lián)user_id, role_idsys_role_menu角色-菜單關(guān)聯(lián)role_id, menu_idsys_user 最容易被忽略的是 dept_id。這個(gè)字段不只是一個(gè)組織歸屬的展示字段它是后面做數(shù)據(jù)權(quán)限過濾的錨點(diǎn)。比如銷售主管希望看到本部門及以下部門的數(shù)據(jù)程序在查詢業(yè)務(wù)表時(shí)就可以通過 dept_id 把數(shù)據(jù)范圍限定住。status 和 del_flag 一定要有前者控制賬號(hào)是否禁用后者做邏輯刪除。密碼字段只存 BCrypt 加密后的哈希串。sys_role 里除了 role_name最好加一個(gè) role_key 作為代碼層面的唯一標(biāo)識(shí)比如 admin、common。為什么不用 role_id因?yàn)閿?shù)據(jù)庫(kù)主鍵在遷移和合并環(huán)境時(shí)可能變化而 role_key 是業(yè)務(wù)常量可以在代碼里安全判斷。data_scope 字段表示數(shù)據(jù)權(quán)限范圍常見值有全部、本部門及以下、本部門、僅本人、自定義。自定義一般還要配一張 sys_role_dept 表來指定可見部門這個(gè)看項(xiàng)目規(guī)模決定要不要加。sys_menu 里的 menu_type 我習(xí)慣用 M(目錄)、C(菜單)、F(按鈕) 三種。目錄是頂級(jí)分組菜單是左側(cè)導(dǎo)航的葉子節(jié)點(diǎn)按鈕是頁(yè)面里的操作權(quán)限。perms 字段對(duì)目錄和菜單不一定必須但按鈕權(quán)限一定要寫比如 system:user:add。前端拿到這些 perms 集合后用指令判斷按鈕要不要渲染后端用同樣的字符串做接口鑒權(quán)。sys_user_role 和 sys_role_menu 就是兩張純關(guān)聯(lián)表各帶主鍵或聯(lián)合主鍵。不要嫌多表查詢麻煩權(quán)限體系一旦出現(xiàn)一個(gè)用戶多個(gè)角色、一個(gè)角色多個(gè)菜單的情況關(guān)聯(lián)表是最容易擴(kuò)展和維護(hù)的。2.2 部門、字典、日志這類輔助表的設(shè)計(jì)細(xì)節(jié)部門表 sys_dept 是樹形結(jié)構(gòu)parent_id 指向上級(jí)部門根節(jié)點(diǎn)可以設(shè) parent_id 0。我有一個(gè)強(qiáng)烈建議一定要加 ancestors 字段例如當(dāng)前部門 id12上級(jí)是 3那 ancestors 就存 0,3。這個(gè)字段用來查詢本部門及以下所有部門時(shí)非常方便直接構(gòu)造 dept_id in (子部門列表)不用遞歸。字典表要分成 sys_dict_type 和 sys_dict_data 兩張前者定義字典類型比如 order_status后者存具體字典項(xiàng)比如 status0 表示待支付、status1 表示已支付。把業(yè)務(wù)里的枚舉值抽成字典好處是前端下拉框直接從后端拿運(yùn)營(yíng)可以自己維護(hù)不用每次加枚舉都發(fā)版本。代價(jià)是查詢多一層緩存這個(gè)可以通過本地緩存或者 Redis 解決。日志表至少兩張sys_oper_log 記錄操作日志sys_login_log 記錄登錄日志。操作日志字段包括操作人、操作模塊、請(qǐng)求方法、請(qǐng)求路徑、請(qǐng)求參數(shù)、返回結(jié)果、耗時(shí)、IP、操作時(shí)間。注意不要把請(qǐng)求體原樣存巨大字段遇到文件上傳一定要截?cái)唷５卿浫罩局辽僖杏脩裘?、登錄狀態(tài)、IP、瀏覽器 User-Agent、登錄時(shí)間。日志表的寫入場(chǎng)景是高并發(fā)、低價(jià)值所以不要和業(yè)務(wù)接口放在同一個(gè)事務(wù)里要么單獨(dú)線程池要么直接異步落庫(kù)。3. 認(rèn)證與鑒權(quán)鏈路JWT Spring Security 的串法表結(jié)構(gòu)定了之后真正難的部分在認(rèn)證鑒權(quán)。這里我用 Java 技術(shù)棧的 Spring Boot 3 Spring Security JWT Redis 來拆解這套組合在目前前后端分離項(xiàng)目里非常常見。為什么不自己在攔截器里手動(dòng)解析 token因?yàn)檎J(rèn)證流程的邊界情況很多token 過期、刷新、用戶被禁用、權(quán)限變更、并發(fā)登錄、CSRF、跨域預(yù)檢Spring Security 的過濾器鏈把這些能力標(biāo)準(zhǔn)化了你只需要按自己的業(yè)務(wù)去填充。3.1 登錄接口里到底要做幾件事很多人寫登錄接口只做了三件事查用戶、比密碼、發(fā) token。但實(shí)際生產(chǎn)環(huán)境里登錄接口至少要按這個(gè)順序做完整校驗(yàn)驗(yàn)證碼。驗(yàn)證碼存在 Rediskey 用 uuid創(chuàng)建時(shí)設(shè)置過期時(shí)間校驗(yàn)后立刻刪除防止暴力重放。根據(jù)用戶名查詢用戶。這里要注意查詢時(shí)把密碼字段帶出來因?yàn)楹竺嬉容^哈希值但返回給前端時(shí)永遠(yuǎn)不要序列化密碼字段。檢查用戶狀態(tài)和角色狀態(tài)。status 為 1 的賬號(hào)直接拒絕登錄并記錄登錄日志。用 BCryptPasswordEncoder 的 matches 方法校驗(yàn)密碼。不要用 MD5不要自己發(fā)明加鹽邏輯。登錄成功后生成 JWT。JWT 里只放 userId 和一個(gè) tokenId不要塞用戶角色和權(quán)限列表因?yàn)?JWT 是簽名但未加密的而且權(quán)限數(shù)據(jù)放在 token 里無(wú)法實(shí)時(shí)更新。把 LoginUser 對(duì)象包含用戶基本信息、角色集合、權(quán)限標(biāo)識(shí)集合存入 Rediskey 可以用 login_token:userId:tokenId指定過期時(shí)間。返回結(jié)果里攜帶 token 和用戶信息。前端把 token 存起來每次請(qǐng)求自動(dòng)放到 Authorization 頭。登錄失敗也需要寫 log 嗎需要。登錄失敗日志對(duì)安全審計(jì)特別重要連續(xù)失敗次數(shù)還可以作為賬號(hào)鎖定的判斷依據(jù)。我一般會(huì)用 Redis 記錄失敗次數(shù)比如 1 小時(shí)內(nèi)失敗 5 次鎖定 15 分鐘。3.2 接口級(jí)鑒權(quán)為什么必須靠權(quán)限標(biāo)識(shí)前后端分離項(xiàng)目里最大的安全誤區(qū)是以為前端隱藏了菜單和按鈕用戶就看不到那些功能了。實(shí)際上接口才是數(shù)據(jù)的真正入口任何人只要拿到一個(gè) token就可以繞過前端直接請(qǐng)求接口。所以每個(gè)敏感接口都必須由后端鑒權(quán)。Spring Security 里我習(xí)慣配合自定義注解。先定義一個(gè) PermissionService從 SecurityContext 中取當(dāng)前登錄用戶的權(quán)限集合判斷是否包含某個(gè)權(quán)限標(biāo)識(shí)Service(ss) public class PermissionService { public boolean hasPermi(String permission) { if (StringUtils.isEmpty(permission)) { return false; } LoginUser loginUser SecurityUtils.getLoginUser(); if (loginUser null) { return false; } // 超級(jí)管理員直接放行 if (loginUser.isAdmin()) { return true; } return loginUser.getPermissions().contains(permission); } }Controller 里這樣用PreAuthorize(ss.hasPermi(system:user:list)) GetMapping(/list) public TableDataInfo list(SysUser user) { ... }這樣配置的好處是權(quán)限標(biāo)識(shí)和表里的 sys_menu.perms 字段完全對(duì)得上。菜單管理界面上每加一個(gè)按鈕權(quán)限標(biāo)識(shí)后端接口只要用同一串字符串做注解前端按鈕也用同一串字符串做 v-hasPermi 判斷三個(gè)地方一套數(shù)據(jù)不會(huì)出現(xiàn)前端按鈕看不到但接口能調(diào)的錯(cuò)位。3.3 Redis 在認(rèn)證鏈路中的角色Redis 在體系里做了三件事。第一存驗(yàn)證碼和登錄失敗次數(shù)第二存用戶登錄態(tài)實(shí)現(xiàn)真正可注銷、可踢人、可續(xù)期的會(huì)話第三緩存用戶的權(quán)限集合。為什么要存權(quán)限而不是每次鑒權(quán)都查數(shù)據(jù)庫(kù)查一次權(quán)限集合要關(guān)聯(lián)用戶表、角色表、菜單表一個(gè)請(qǐng)求里可能有好幾個(gè)接口要做 PreAuthorize 判斷次次查數(shù)據(jù)庫(kù)性能頂不住。重點(diǎn)是權(quán)限變更后的緩存同步。系統(tǒng)管理員改了某個(gè)角色的菜單如果緩存里的舊權(quán)限不清理用戶在有效期內(nèi)依然能調(diào)用已經(jīng)收回的接口這是權(quán)限系統(tǒng)的硬傷。我的做法是更新角色菜單的時(shí)候刪除該角色關(guān)聯(lián)的所有用戶的 LoginUser 緩存更新用戶角色的分配時(shí)刪除該用戶的緩存。用戶下一個(gè)請(qǐng)求進(jìn)來解析 token 時(shí)發(fā)現(xiàn)緩存不存在就重新從數(shù)據(jù)庫(kù)加載權(quán)限并寫入 Redis。這一步的核心代碼如下// 角色菜單變更后 userOnlineService.removeUserCacheByRoleId(roleId); // 用戶角色重新分配后 userOnlineService.removeUserCacheByUserId(userId);如果項(xiàng)目里已經(jīng)用上了消息隊(duì)列也可以用事件發(fā)布通知所有實(shí)例清緩存沒有消息隊(duì)列就靠 Redis key 刪除后自動(dòng)重新加載來兜底。這里要特別注意分布式環(huán)境下的延遲問題權(quán)限變更后未必立刻在所有實(shí)例生效但通常一兩秒內(nèi)能收斂。4. 用戶、角色、菜單接口的分層落地Controller-Service-Mapper 實(shí)際寫法系統(tǒng)管理模塊的接口特別適合展示一套規(guī)整的三層結(jié)構(gòu)因?yàn)檫壿嫴粡?fù)雜但邊界必須清晰。我自己總結(jié)的規(guī)則是Controller 只做參數(shù)接收和結(jié)果封裝Service 做業(yè)務(wù)規(guī)則和事務(wù)控制Mapper 只做 SQL 查詢。事務(wù)、異常、唯一性校驗(yàn)這類問題不在 Controller 里寫。4.1 用戶管理分頁(yè)、新增、分配角色、重置密碼用戶管理的核心接口就六個(gè)分頁(yè)查詢、根據(jù)用戶編號(hào)查詢?cè)斍?、新增用戶、修改用戶、刪除用戶、重置密碼。分頁(yè)查詢一般配合 PageHelperGetMapping(/list) public TableDataInfo list(SysUser user) { startPage(); ListSysUser list userService.selectUserList(user); return getDataTable(list); }startPage 是 PageHelper 的靜態(tài)方法它通過攔截器把下一條 SQL 包成分頁(yè)查詢返回的 list 實(shí)際是 Page 對(duì)象再由 getDataTable 把 total 和 rows 封裝成前端需要的結(jié)構(gòu)。這里有一個(gè)坑startPage 和它作用的那條 SQL 之間不能夾著其他 SQL 操作一旦中間有別的查詢PageHelper 會(huì)把分頁(yè)參數(shù)作用到錯(cuò)誤的 SQL 上。新增用戶時(shí)最重要的一步是唯一性校驗(yàn)。username 必須唯一但如果你做了邏輯刪除就有一個(gè)經(jīng)典坑刪除的用戶還占著 username再新增同名用戶時(shí)唯一索引直接報(bào)錯(cuò)。解決思路我放到第 5 章展開。新增用戶還需要給一個(gè)初始密碼通常用一個(gè)默認(rèn)值 123456并且把 isNeedUpdatePwd 這類字段標(biāo)記為 true前端檢測(cè)到該字段就彈窗要求改密。分配角色是用戶管理里另一個(gè)容易做錯(cuò)的地方。前端提交的 userIds 和 roleIds 是一對(duì)多關(guān)系Service 里必須在事務(wù)內(nèi)先刪除 sys_user_role 里該用戶的全部記錄再批量插入新的關(guān)聯(lián)記錄。不要只做增刪差量雖然效率高但業(yè)務(wù)場(chǎng)景下全刪全插最可靠而且這個(gè)表數(shù)據(jù)量一般不大沒必要做復(fù)雜 diff。4.2 角色管理分配菜單與同步更新角色管理的重點(diǎn)是角色-菜單關(guān)系。新增角色時(shí)前端會(huì)傳來一個(gè)菜單 id 的樹形勾選列表注意這個(gè)列表里一般既包含父級(jí)目錄也包含子菜單和按鈕不要只存葉子節(jié)點(diǎn)。為什么因?yàn)榍岸藙?dòng)態(tài)路由要判斷當(dāng)前角色有沒有某個(gè)目錄或菜單的可見權(quán)如果目錄沒被勾選子菜單即使有權(quán)限也無(wú)法在側(cè)邊欄展示。所以插入 sys_role_menu 的時(shí)候全部按提交的 menuIds 插入即可。修改角色時(shí)則要先更新 sys_role 基礎(chǔ)信息再刪除原有的角色菜單關(guān)聯(lián)再重新插入新的關(guān)聯(lián)。這兩個(gè)操作必須放在同一個(gè)事務(wù)里否則中途異常會(huì)出現(xiàn)角色信息是新的、菜單權(quán)限是舊的這種臟數(shù)據(jù)。刪除角色前必須檢查 sys_user_role 里是否還有用戶引用。如果有前端要給出明確提示該角色已分配給 N 個(gè)用戶請(qǐng)先解除分配后再刪除。否則直接刪除角色會(huì)導(dǎo)致這些用戶的權(quán)限集合變成幽靈數(shù)據(jù)登錄后菜單無(wú)法正常加載。多表操作建議寫成下面這種事務(wù)控制方式Transactional(rollbackFor Exception.class) public void updateRole(SysRole role) { // 1. 更新角色表 roleMapper.updateRole(role); // 2. 刪除舊的菜單關(guān)聯(lián) roleMenuMapper.deleteRoleMenuByRoleId(role.getRoleId()); // 3. 插入新的菜單關(guān)聯(lián) insertRoleMenu(role); }4.3 菜單管理樹形結(jié)構(gòu)、動(dòng)態(tài)路由與按鈕權(quán)限菜單管理的查詢接口返回的不是平鋪列表而是樹形結(jié)構(gòu)。前端拿到樹之后做兩件事一是管理界面的樹形表格二是登錄后根據(jù)角色可訪問菜單構(gòu)建動(dòng)態(tài)路由。后端這邊的核心是遞歸構(gòu)建樹public ListSysMenu buildMenuTree(ListSysMenu menus) { // 先按 parentId 分組再?gòu)母?jié)點(diǎn)開始組裝 children }遞歸本身不難難點(diǎn)在數(shù)據(jù)校驗(yàn)。比如 parentId 不能指向自身不能形成環(huán)否則前端渲染路由時(shí)會(huì)死循環(huán)。我見過一個(gè)項(xiàng)目在菜單表里把 A 菜單的 parentId 配成了 BB 的 parentId 又配成了 A前端頁(yè)面直接卡死。所以新增菜單時(shí)建議做一次父節(jié)點(diǎn)鏈檢測(cè)確保新菜單的父節(jié)點(diǎn)不能是自己的子節(jié)點(diǎn)。按鈕權(quán)限這塊要跟菜單類型聯(lián)動(dòng)。如果 menu_typeF那 component 和 path 都可以不填只填 perms 和菜單名稱如果 menu_typeC則必須填 component對(duì)應(yīng)前端頁(yè)面的組件路徑。后端接口在返回路由給前端時(shí)通常會(huì)把按鈕類型的菜單過濾掉因?yàn)樗鼈儾粎⑴c路由只參與權(quán)限標(biāo)識(shí)集。5. 上線前最容易翻車的細(xì)節(jié)跨域、邏輯刪除、權(quán)限緩存一致性5.1 三個(gè)真實(shí)踩過坑唯一索引、樹形遞歸、跨域第一個(gè)坑是邏輯刪除和唯一索引打架。MySQL 的表結(jié)構(gòu)里 username 上建了唯一索引用戶刪除時(shí)我們把 del_flag 從 0 改成 1數(shù)據(jù)還在索引還占著導(dǎo)致新用戶無(wú)法使用同一個(gè)用戶名。常規(guī)解法有幾種刪除時(shí)把 username 改名比如 username_del_{id}或者索引字段改成 (username, del_flag)但邏輯刪除的字段是 0 和 1刪除多條同樣 username 的記錄會(huì)重復(fù)沖突比較穩(wěn)的方案是數(shù)據(jù)庫(kù)表去掉唯一索引把唯一性校驗(yàn)完全放在 Service 層配合分布式鎖避免并發(fā)創(chuàng)建同名用戶。第二個(gè)坑是樹形遞歸的效率和深度問題。部門表、菜單表的深度通常不會(huì)太大但如果不加控制遞歸查詢會(huì)變成多次全表查詢。更常見的是刪除父節(jié)點(diǎn)時(shí)沒有校驗(yàn)子節(jié)點(diǎn)導(dǎo)致留下一堆孤兒節(jié)點(diǎn)。所以我在刪除接口里都會(huì)先查子節(jié)點(diǎn)數(shù)量大于 0 就拒絕刪除把原因?qū)懬宄嬖V前端。第三個(gè)坑是跨域配置。前后端分離項(xiàng)目里前端和后端端口不同最常見的做法是后端允許所有來源跨域。但如果開啟了 allowCredentials(true) 用來傳遞 cookie那么 allowedOrigins 就不能配成 *瀏覽器會(huì)直接報(bào)錯(cuò)。正確寫法是允許具體的前端域名或者用 allowedOriginPatterns。另外Spring Security 的攔截鏈里必須對(duì) CORS 預(yù)檢請(qǐng)求 OPTIONS 放行否則前端會(huì)發(fā)現(xiàn)后端明明配了跨域但還是請(qǐng)求失敗。5.2 性能與安全自查清單上線前我會(huì)按下面這份清單過一遍系統(tǒng)管理模塊檢查項(xiàng)說明密碼存儲(chǔ)確認(rèn)沒有明文密碼BCrypt 成本因子不低于 10越權(quán)訪問普通用戶 token 不能訪問 system:user:list 等管理接口邏輯刪除范圍所有管理表都有 del_flag所有查詢 SQL 都帶 del_flag0權(quán)限緩存一致性角色菜單修改后用戶權(quán)限緩存能及時(shí)失效分頁(yè) SQL 參數(shù)排序字段不能直接拼用戶輸入需要白名單校驗(yàn)操作日志脫敏密碼、token、身份證字段在日志里要過濾文件上傳接口上傳接口必須有獨(dú)立權(quán)限標(biāo)識(shí)防止匿名上傳超管賬號(hào)管理超級(jí)管理員數(shù)量嚴(yán)格控制使用獨(dú)立強(qiáng)密碼管理這些條目看起來瑣碎但權(quán)限類事故十有八九都出在這些地方。特別是在權(quán)限緩存一致性上我建議每次發(fā)布涉及權(quán)限的變更后主動(dòng)清空一遍登錄用戶緩存寧可讓用戶重新登錄也不要讓舊權(quán)限殘留在線。6. 實(shí)測(cè)下來的一點(diǎn)體會(huì)與可擴(kuò)展方向先說體會(huì)。系統(tǒng)管理模塊是一個(gè)典型的不需要重復(fù)造輪子、但必須看懂輪子的模塊。用開源框架作為起點(diǎn)是高效的比如可以參考若依這類前后端分離項(xiàng)目代碼完整、權(quán)限鏈路清晰能直接拿來改。但我建議至少把表結(jié)構(gòu)、認(rèn)證流程、權(quán)限判斷這三塊吃透否則遇到定制需求只能瞎加字段、繞開原有設(shè)計(jì)最后越改越亂。我自己的經(jīng)驗(yàn)是能不動(dòng)的地方盡量不動(dòng)要?jiǎng)拥臅r(shí)候先畫清楚改動(dòng)鏈路只改業(yè)務(wù)側(cè)不動(dòng)權(quán)限模型。再說兩個(gè)來自實(shí)測(cè)項(xiàng)目的對(duì)比。一個(gè)項(xiàng)目是內(nèi)部管理系統(tǒng)用戶量小我按標(biāo)準(zhǔn) RBAC 實(shí)現(xiàn)沒有做數(shù)據(jù)權(quán)限只靠菜單控制完全夠用另一個(gè)項(xiàng)目是給第三方客戶用的運(yùn)營(yíng)平臺(tái)用戶量幾千部門層級(jí)四層我加了數(shù)據(jù)權(quán)限角色表里新增 data_scope 字段并在業(yè)務(wù)查詢里拼接部門條件。同樣一個(gè)訂單查詢接口有數(shù)據(jù)權(quán)限版本和無(wú)數(shù)據(jù)權(quán)限版本表面看只差了一個(gè) where 子句實(shí)際上統(tǒng)計(jì)邏輯完全不同。數(shù)據(jù)權(quán)限的 SQL 拼接需要在 Service 層做統(tǒng)一封裝不要散到各個(gè) Mapper 里否則每個(gè)業(yè)務(wù)查詢都要自己寫一遍維護(hù)成本極高。然后是擴(kuò)展方向。第一個(gè)方向是數(shù)據(jù)權(quán)限細(xì)化在 sys_role 里加 data_scope 字段配合部門表在業(yè)務(wù)查詢時(shí)自動(dòng)追加 SQL 過濾條件。第二個(gè)方向是多租戶系統(tǒng)管理這需要在所有表加 tenant_id在登錄認(rèn)證時(shí)解析租戶上下文業(yè)務(wù)接口的查詢默認(rèn)帶上租戶過濾。多租戶這塊我建議最好在項(xiàng)目一開始就決定做不做不要在跑了一年后拖到高峰期再改造。改造的關(guān)鍵不僅在表加 tenant_id更在認(rèn)證環(huán)節(jié)登錄時(shí)要根據(jù)用戶的租戶編碼確認(rèn)身份Redis 緩存 key 也要帶 tenantId否則兩個(gè)租戶下同名的用戶名會(huì)互相覆蓋緩存。第三個(gè)方向是把操作日志跟消息中間件打通操作日志只負(fù)責(zé)往隊(duì)列里丟消費(fèi)端負(fù)責(zé)落庫(kù)和告警既不影響主流程性能也能做實(shí)時(shí)風(fēng)險(xiǎn)預(yù)警。最后分享一個(gè)實(shí)際操作中的小技巧新項(xiàng)目從零搭建時(shí)可以先把用戶、角色、菜單、部門、字典、日志這六個(gè)子模塊的接口和權(quán)限標(biāo)識(shí)梳理成一張清單再開始寫代碼。這張清單既是開發(fā)計(jì)劃也是后面聯(lián)調(diào)時(shí)給前端同事的接口契約更是上線前安全測(cè)試的檢查依據(jù)。代碼可以抄、框架可以選但權(quán)限模型必須自己想清楚。系統(tǒng)管理模塊這一章看似平淡往后幾乎每一個(gè)業(yè)務(wù)需求都會(huì)踩在它上面值得你多花幾天把它釘牢。