做 Java 后端開發(fā)的多多少少都會(huì)跟 RuoYi 這套框架打交道尤其是 RuoYi-Vue 前后端分離版本。如果你在它上面做過二次開發(fā)大概率會(huì)在某個(gè)深夜對(duì)著“明明放行了為什么還是 401”這種問題撓頭。這時(shí)候你需要認(rèn)識(shí)一下PermitAllUrlProperties。這個(gè)類負(fù)責(zé)一件聽起來很小、但實(shí)際很關(guān)鍵的事在應(yīng)用啟動(dòng)時(shí)掃描所有 Controller 里標(biāo)注了Anonymous注解的接口把這些接口的 URL 收集成一張“匿名白名單”。后續(xù)請(qǐng)求進(jìn)來時(shí)只要命中這張名單就不需要解析 token、不需要登錄態(tài)直接放行。換句話說它決定了哪些接口可以“不穿衣服”跑在路上是若依匿名訪問機(jī)制的核心入口。這篇文章我會(huì)從若依的鑒權(quán)鏈路講起拆解PermitAllUrlProperties的源碼、運(yùn)行時(shí)機(jī)、實(shí)際用法再把我踩過的坑和排查思路一并整理出來適合正在做若依二開、或者想徹底理解若依接口鑒權(quán)機(jī)制的開發(fā)同學(xué)。1. 先從若依的鑒權(quán)鏈路說起這個(gè)類到底在解決什么問題1.1 登錄、Token 與動(dòng)態(tài)權(quán)限校驗(yàn)的基本流程RuoYi-Vue 的鑒權(quán)鏈路可以拆成三步登錄拿 token、請(qǐng)求帶 token、后端驗(yàn) token。用戶在登錄接口輸入用戶名密碼后端校驗(yàn)通過后生成一個(gè)隨機(jī) token把LoginUser對(duì)象和用戶權(quán)限信息緩存到 Redis 里token 本身返回給前端。前端每次請(qǐng)求在請(qǐng)求頭里帶上Authorization: Bearer token。后端收到請(qǐng)求后TokenFilter會(huì)從請(qǐng)求頭解析這個(gè) token再拿著 token 去 Redis 里換取LoginUser。換到了就把用戶的登錄狀態(tài)放進(jìn)SecurityContextHolder后續(xù)方法級(jí)權(quán)限注解PreAuthorize(ss.hasPermi(system:user:list))才能從當(dāng)前上下文里拿到用戶信息判斷這個(gè)用戶有沒有某個(gè)菜單或按鈕權(quán)限。如果換不到那就看這個(gè)接口是不是匿名接口如果是就走放行邏輯不是就直接返回 401。所以這里隱含了一個(gè)問題像/login、/captchaImage、/register這類接口用戶本來就沒登錄不可能帶 token后端必須把它們當(dāng)成“匿名可訪問”的接口單獨(dú)放行。若依的做法就是用Anonymous注解標(biāo)記這些接口再用PermitAllUrlProperties統(tǒng)一收集。1.2 為什么不在 SecurityConfig 里寫死而要引入 Anonymous 掃描機(jī)制很多剛接觸若依的同學(xué)會(huì)問Spring Security 不是有permitAll()嗎在SecurityConfig里把這些路徑一個(gè)個(gè)配進(jìn)去不就行了確實(shí)可以傳統(tǒng)單體版若依就是這么干的在SecurityConfig的authorizeRequests()里把/login、/captchaImage等地址permitAll()。但這種方式在前后端分離的 RuoYi-Vue 上有一個(gè)明顯的痛點(diǎn)接口數(shù)量一多集中式配置會(huì)變得很難維護(hù)。想象一下這個(gè)場(chǎng)景你負(fù)責(zé)的一個(gè)后臺(tái)管理系統(tǒng)有 200 個(gè)接口其中 15 個(gè)是公開的。如果全部集中在SecurityConfig里寫死每次新增公開接口都要去改這個(gè)類改著改著就漏了而且后來的人根本不知道某個(gè)接口是不是故意放行的。更麻煩的是不同業(yè)務(wù)模塊的開發(fā)者改同一個(gè)安全配置文件沖突是遲早的事。Anonymous這種設(shè)計(jì)把“是否匿名”的決策權(quán)下放到了接口方法本身屬于聲明式編程思路。開發(fā)者想開放哪個(gè)接口直接在方法上標(biāo)一個(gè)注解剩下的交給框架去掃描收集。新增接口時(shí)不需要碰全局安全配置改錯(cuò)了也只影響單個(gè)接口風(fēng)險(xiǎn)范圍小得多。兩種方式的差別用大白話講就是集中式寫死路徑像是學(xué)校門口門衛(wèi)手里的一沓紙質(zhì)名單每次有新人進(jìn)來就要改名單Anonymous像是給每間允許自由進(jìn)出的教室門上貼一個(gè)“無(wú)需刷卡”的標(biāo)志教室變了門衛(wèi)照常巡邏就行了。1.3 傳統(tǒng)若依和若依-Vue 在這個(gè)機(jī)制上的差異很多網(wǎng)上的教程混著講導(dǎo)致初學(xué)者容易懵。這里把兩個(gè)版本的區(qū)別說清楚。傳統(tǒng)單體版 RuoYi就是那個(gè)用 Thymeleaf 做頁(yè)面的版本使用的是直接配置 Spring Security 的方式它的匿名 URL 配置在SecurityConfig里寫死類名不一定叫PermitAllUrlProperties。而 RuoYi-Vue 前后端分離版因?yàn)橐肓烁?xì)粒度的接口權(quán)限模型才在ruoyi-framework模塊下單獨(dú)提供了PermitAllUrlProperties這個(gè)配置類配合Anonymous注解來管理匿名 URL。所以你如果是在 RuoYi-Vue 或它的衍生版本上做開發(fā)才會(huì)遇到PermitAllUrlProperties。如果你用的是傳統(tǒng)單體版搜Anonymous可能壓根搜不到就只能去SecurityConfig里找permitAll()的配置了。搞清這個(gè)前提看代碼時(shí)才不會(huì)張冠李戴。2. PermitAllUrlProperties 源碼拆解掃描、收集、匹配三步曲2.1 類的骨架InitializingBean 和 ApplicationStartedEvent 的作用PermitAllUrlProperties在若依-Vue 中位于com.ruoyi.framework.config包下完整實(shí)現(xiàn)大致是實(shí)現(xiàn)InitializingBean接口同時(shí)監(jiān)聽ApplicationStartedEvent事件。它有兩個(gè)核心時(shí)間點(diǎn)。第一個(gè)是afterPropertiesSet()這是InitializingBean接口的回調(diào)方法Spring 在完成 Bean 屬性注入后會(huì)執(zhí)行它。為什么若依不直接用PostConstruct因?yàn)檫@里需要確保RequestMappingHandlerMapping已經(jīng)初始化完畢能拿到容器里所有接口映射afterPropertiesSet在依賴注入完成后才調(diào)用正是干這件事的合適時(shí)機(jī)。第二個(gè)是onApplicationEvent(ApplicationStartedEvent event)應(yīng)用啟動(dòng)完成后觸發(fā)。這個(gè)時(shí)機(jī)比 Bean 初始化更晚一點(diǎn)此時(shí)所有接口已經(jīng)掃描完可以安心對(duì)白名單列表做排序和歸檔。類里面最關(guān)鍵的兩個(gè)成員變量一個(gè)是注入進(jìn)來的RequestMappingHandlerMapping它就是 Spring MVC 保存所有 URL 映射關(guān)系的地方另一個(gè)是內(nèi)部維護(hù)的ListAnonymousResource anonymousResources這個(gè)列表就是最終生成的匿名白名單。2.2 afterPropertiesSet 中如何掃描所有接口這是整個(gè)類最核心的邏輯。代碼大致長(zhǎng)這樣Override public void afterPropertiesSet() { requestMappingHandlerMapping.getHandlerMethods().forEach((key, value) - { SetString urls extractUrls(key); if (CollectionUtils.isEmpty(urls)) { return; } if (value.hasMethodAnnotation(Anonymous.class)) { for (String url : urls) { anonymousResources.add(new AnonymousResource(getPattern(url), false)); } } }); }requestMappingHandlerMapping.getHandlerMethods()返回一個(gè)MapRequestMappingInfo, HandlerMethod。RequestMappingInfo里保存的是這個(gè)接口的完整映射信息包括 URL pattern、請(qǐng)求方式、參數(shù)條件等HandlerMethod則是真正對(duì)應(yīng)的 Controller 方法。拿到HandlerMethod之后調(diào)用value.hasMethodAnnotation(Anonymous.class)判斷這個(gè)方法上有沒有標(biāo)Anonymous。這里有個(gè)細(xì)節(jié)要注意這個(gè)判斷只看方法本身如果Anonymous標(biāo)在了 Controller 類上這個(gè)分支是判斷不出來的。實(shí)際若依源碼里還會(huì)額外處理類級(jí)注解但不同版本實(shí)現(xiàn)有差異后面實(shí)操章節(jié)我再展開講。extractUrls說白了就是從RequestMappingInfo里把路徑取出來。Spring MVC 很貼心地幫我們處理好了類上RequestMapping與方法上GetMapping的路徑拼接所以這里拿到的 URL 是完整路徑不需要自己再去拼一次。真正有點(diǎn)技術(shù)含量的在getPattern方法。比如你寫的接口路徑是/system/user/{userId}運(yùn)行時(shí)真實(shí)請(qǐng)求可能是/system/user/1。如果白名單里存的是帶{userId}的模板后面的匹配邏輯就要額外處理變量。若依的做法是用正則把{xxx}統(tǒng)一替換成*這樣/system/user/{userId}就變成/system/user/*在matches時(shí)用 Ant 風(fēng)格的*通配符就能輕松匹配任意參數(shù)。2.3 啟動(dòng)后排序別讓通配符搶了精確路徑onApplicationEvent里的邏輯相對(duì)簡(jiǎn)單就是給anonymousResources列表按照 URL 長(zhǎng)度做降序排序代碼大致是Override public void onApplicationEvent(ApplicationStartedEvent event) { anonymousResources.sort(Comparator.comparingInt(resource - resource.getUrl().length()).reversed()); }為什么要排序因?yàn)閙atches匹配的時(shí)候是順序遍歷列表一旦某個(gè) URL 命中就直接返回 true。如果有兩條規(guī)則一條是/*一條是/system/config/list假設(shè)請(qǐng)求是/system/config/list要是先匹配了/*那精確路徑就被通配符吞掉了永遠(yuǎn)沒有機(jī)會(huì)走到第二層判斷。雖然很多匹配器內(nèi)部會(huì)做盡量匹配但若依這里用的是PatternMatchUtils.simpleMatch是“匹配到就返回”的邏輯所以順序直接影響結(jié)果。把長(zhǎng)的、精確的路徑排在前面是一種簡(jiǎn)單粗暴但非常有效的防誤判手段。這一點(diǎn)在實(shí)戰(zhàn)中特別容易被忽略。我有一次給某個(gè)模塊的所有接口統(tǒng)一加了Anonymous結(jié)果同模塊下一個(gè)更具體的接口怎么調(diào)都進(jìn)不了登錄態(tài)保護(hù)查了半天才發(fā)現(xiàn)是排序規(guī)則把精確路徑擠到了后面。后來養(yǎng)成了習(xí)慣凡是自己往白名單里加通配路徑都會(huì)特別留意它和已有規(guī)則之間的匹配優(yōu)先級(jí)。2.4 matches 的匹配規(guī)則為什么不是簡(jiǎn)單 equals最后是matches方法public boolean matches(String requestURI) { for (AnonymousResource resource : anonymousResources) { if (PatternMatchUtils.simpleMatch(resource.getUrl(), requestURI)) { return true; } } return false; }PatternMatchUtils.simpleMatch是 Spring 自帶的輕量路徑匹配工具支持*匹配任意字符但不支持**跨目錄匹配。若依在收集 URL 時(shí)已經(jīng)做了模板變量到*的轉(zhuǎn)換所以用這個(gè)工具類就夠了夠輕、夠快也不用引一整套AntPathMatcher進(jìn)來。AnonymousResource是若依自己定義的一個(gè)小類內(nèi)部有兩個(gè)字段url和isAuth。isAuth這個(gè)字段有點(diǎn)意思它表示這條匿名 URL 是否“即使帶著 token 也要繼續(xù)走鑒權(quán)流程”。默認(rèn)情況是false也就是不管帶不帶 token 都直接放行。在某些二次開發(fā)場(chǎng)景里你可能希望一個(gè)接口允許匿名訪問但如果用戶帶了 token又想順便識(shí)別出身份這個(gè)字段就能派上用場(chǎng)。3. 它是怎么被調(diào)起來的從 TokenFilter 到 SecurityContextHolder3.1 過濾器鏈中的關(guān)鍵一票PermitAllUrlProperties本身不會(huì)攔截任何請(qǐng)求它是一個(gè)被動(dòng)的“查詢服務(wù)”。真正在請(qǐng)求進(jìn)來時(shí)調(diào)用它的是TokenFilter這是若依-Vue 里繼承OncePerRequestFilter的一個(gè)過濾器。TokenFilter的執(zhí)行流程大概是這樣的請(qǐng)求進(jìn)來它先從 header 里解析 token如果 token 能換到LoginUser就把登錄態(tài)放進(jìn)SecurityContextHolder然后繼續(xù)走后續(xù)邏輯。如果 token 解析不出來或者根本沒帶 token它會(huì)調(diào)用permitAllUrlProperties.matches(request.getRequestURI())判斷當(dāng)前地址是不是匿名白名單里的接口。命中白名單就直接調(diào)filterChain.doFilter(request, response)放行不再?gòu)?qiáng)制要求登錄狀態(tài)。沒命中白名單就拋一個(gè)AuthenticationException由全局異常處理器轉(zhuǎn)成 401 返回給前端。所以PermitAllUrlProperties是整個(gè)鑒權(quán)鏈條里一個(gè)很關(guān)鍵的“閘口”。這個(gè)閘口一旦失效后果很極端要么所有帶Anonymous的接口全部變成需要登錄要么因?yàn)槟承┡渲缅e(cuò)誤導(dǎo)致整個(gè)過濾鏈被繞過白名單形同虛設(shè)。3.2 登錄用戶信息是在哪里寫入的熱搜里有個(gè)問題很有代表性“ruoyi在哪里寫入登錄用戶的信息”。如果你翻過TokenFilter源碼這個(gè)問題其實(shí)很好回答。在TokenFilter里拿到loginUser之后會(huì)執(zhí)行類似下面這段邏輯Authentication authentication new UsernamePasswordAuthenticationToken(loginUser, null, authorities); SecurityContextHolder.getContext().setAuthentication(authentication);SecurityContextHolder底層是ThreadLocal所以每個(gè)請(qǐng)求的登錄態(tài)是互相隔離的。一個(gè)請(qǐng)求從進(jìn)入到返回只要線程不切換、不走異步SecurityContextHolder里的Authentication就一直有效后面的PreAuthorize(ss.hasPermi(...))就是通過讀取這個(gè)上下文來判斷用戶身份的。但要注意如果接口走了匿名放行分支TokenFilter不會(huì)往SecurityContextHolder里寫任何東西上下文就是空的。這也就解釋了為什么Anonymous接口里如果再加PreAuthorize大概率會(huì)報(bào)“沒有用戶信息”的異常。3.3 Anonymous 與 PreAuthorize 的分工邊界很多初學(xué)者會(huì)把“匿名訪問”和“權(quán)限校驗(yàn)”混在一起以為兩個(gè)是互斥的其實(shí)它們是兩個(gè)不同維度的事。Anonymous解決的是“要不要登錄”的問題它控制的是請(qǐng)求能不能不帶 token 進(jìn)來。PreAuthorize解決的是“登錄了之后有沒有權(quán)限”的問題它控制的是某個(gè)用戶能不能訪問某個(gè)資源。一個(gè)內(nèi)部接口比如刪除用戶需要同時(shí)滿足“已登錄”和“有刪除權(quán)限”這種就應(yīng)該只寫PreAuthorize(ss.hasPermi(system:user:remove))不要寫Anonymous。一個(gè)公開的頁(yè)面接口比如獲取驗(yàn)證碼它需要“不登錄也能訪問”這種才寫Anonymous。一旦一個(gè)接口同時(shí)標(biāo)注了Anonymous和PreAuthorize語(yǔ)義就會(huì)變模糊Anonymous說你不需要登錄但PreAuthorize要求上下文里有用戶信息這本身就是自相矛盾的。所以我在工作中會(huì)跟團(tuán)隊(duì)強(qiáng)調(diào)拿到需求先判斷接口是“公開”還是“內(nèi)部”再?zèng)Q定用哪套機(jī)制兩個(gè)別混著寫。4. 實(shí)操如何用 PermitAllUrlProperties 開放一個(gè)匿名接口4.1 最小示例方法級(jí)別加 Anonymous在若依-Vue 中想讓某個(gè)接口支持匿名訪問最小操作就是在 Controller 方法上標(biāo)一個(gè)Anonymous注解Anonymous GetMapping(/demo/publicInfo) public AjaxResult publicInfo() { return AjaxResult.success(這是公開信息); }啟動(dòng)項(xiàng)目后直接用瀏覽器訪問/demo/publicInfo或者用 curl 不帶任何 header 請(qǐng)求都能正常返回 JSON不會(huì)彈出 401。如果這個(gè)接口在 Controller 類上還有一層RequestMapping(/api)那完整路徑就是/api/demo/publicInfoRequestMappingInfo會(huì)自動(dòng)拼接不需要你手動(dòng)處理前綴。還有一點(diǎn)要注意如果項(xiàng)目配置了server.servlet.context-path比如部署在/dev-api那訪問時(shí)的完整 URL 還要加上這層上下文路徑。TokenFilter里的request.getRequestURI()是包含 context-path 的所以白名單里的路徑也要跟著帶上前綴否則永遠(yuǎn)匹配不上。4.2 類級(jí)別加 Anonymous 的坑把Anonymous寫在 Controller 類上表示該類下所有方法都允許匿名訪問Anonymous RestController RequestMapping(/demo) public class DemoController { GetMapping(/a) public AjaxResult a() { ... } GetMapping(/b) public AjaxResult b() { ... } }這種寫法在需求上很常見比如對(duì)外數(shù)據(jù)同步接口、開放查詢接口等整組方法都不需要登錄態(tài)。但它有個(gè)隱患如果一個(gè)類里既有公開接口又有需要登錄的接口類級(jí)注解會(huì)讓后者的鑒權(quán)形同虛設(shè)等于你辛辛苦苦寫的PreAuthorize全部被忽略了。少數(shù)衍生版本對(duì)類級(jí)Anonymous的支持還不一致有些版本可能壓根沒有解析類上的注解導(dǎo)致“明明標(biāo)了卻還是 401”。我自己的經(jīng)驗(yàn)是盡量在方法級(jí)別加注解只有確認(rèn)整個(gè)類的所有方法都必須公開時(shí)才考慮類級(jí)寫法。畢竟方法級(jí)語(yǔ)義最清楚排錯(cuò)也最簡(jiǎn)單。4.3 有版本差異嗎RuoYi 傳統(tǒng)版、RuoYi-Vue、RuoYi-AI、Sa-Token 改造版這個(gè)問題我覺得值得單獨(dú)拿出來講因?yàn)樘嗳瞬冗^坑。如果你用的是傳統(tǒng)單體版 RuoYi沒有PermitAllUrlProperties這個(gè)類匿名配置直接在SecurityConfig里寫permitAll()。這個(gè)是第一代方案。如果你用的是 RuoYi-Vue 前后端分離版才是本文講的這套AnonymousPermitAllUrlProperties機(jī)制。這是第二代方案?，F(xiàn)在市面上還有很多衍生版本比如 RuoYi-AI、RuoYi-Vue-Pro以及各種基于 Sa-Token 改造的 SSO 版本。這些版本大多繼承或改寫了原來的鑒權(quán)邏輯。比如基于 Sa-Token 的若依可能用SaIgnore注解代替Anonymous同時(shí)把原來的TokenFilter換成了 Sa-Token 自己的過濾器。這時(shí)候你再翻代碼可能根本找不到PermitAllUrlProperties被調(diào)用的地方因?yàn)殍b權(quán)過濾器整條鏈都被替換掉了。還有若依-Vue-Pro 里開啟 BPM 工作流功能那是業(yè)務(wù)模塊的擴(kuò)展不影響這個(gè)配置類的定位但業(yè)務(wù)接口里哪些被放行、哪些沒被放行還是值得順著這套鏈路重新理一遍特別是工作流回調(diào)這類端口經(jīng)常出現(xiàn)匿名配置漏配或過寬的問題。4.4 動(dòng)態(tài)擴(kuò)展白名單的一個(gè)可行思路PermitAllUrlProperties是啟動(dòng)時(shí)一次性掃描的想加白名單就得改代碼重啟服務(wù)。但實(shí)際業(yè)務(wù)中經(jīng)常有這種需求運(yùn)營(yíng)后臺(tái)想臨時(shí)放行一個(gè)接口又不想發(fā)版重啟。這時(shí)候可以模仿這個(gè)類的設(shè)計(jì)自己做一套數(shù)據(jù)庫(kù)動(dòng)態(tài)白名單。大致思路是先建一張配置表字段包括 URL 模板、啟用狀態(tài)、備注。啟動(dòng)時(shí)把啟用的 URL 加載到內(nèi)存緩存里同時(shí)暴露一個(gè)刷新接口后臺(tái)改了配置之后調(diào)一下刷新接口或者用定時(shí)任務(wù)周期性加載。然后在TokenFilter的判空邏輯里把原來的單一判斷擴(kuò)展成多判斷。除了permitAllUrlProperties.matches(request.getRequestURI())再加一個(gè)dynamicAnonUrlService.matches(request.getRequestURI())兩者只要有一個(gè)命中就放行。代碼改動(dòng)不大但靈活性提升了一個(gè)量級(jí)。這里必須強(qiáng)調(diào)一個(gè)安全原則動(dòng)態(tài)白名單的入口一定要嚴(yán)格做權(quán)限控制不是誰(shuí)都能配置。我見過一個(gè)項(xiàng)目把動(dòng)態(tài)白名單管理接口放在了一個(gè)公開模塊里結(jié)果別人只要知道接口地址就能給自己加匿名權(quán)限等于把整個(gè)系統(tǒng)的安全防線給拆了。白名單這種東西寧可笨一點(diǎn)、慢一點(diǎn)也不要敞開口子。5. 常見問題與排查實(shí)錄5.1 加了 Anonymous 卻依然 401這是我在群里被問得最多的問題。我把排查思路整理成一個(gè)速查表遇到問題可以照著過一遍。可能原因排查方法解決思路注解標(biāo)在了類上但版本不支持解析查看框架版本源碼看afterPropertiesSet是否處理了類級(jí)注解改成方法級(jí)注解接口路徑與白名單不匹配確認(rèn)context-path是否包含在請(qǐng)求 URI 中在完整 URL 上做匹配必要時(shí)打印request.getRequestURI()注解加在了非 Controller 方法上確認(rèn)注解是不是標(biāo)在真正被 Spring MVC 映射的方法上只標(biāo)在 handler 方法上不要標(biāo)在普通私有方法過濾器鏈被其他框架替換查項(xiàng)目里有沒有引入 Sa-Token 等第三方鑒權(quán)框架統(tǒng)一用第三方的放行注解或調(diào)整過濾器順序項(xiàng)目上下文有多次轉(zhuǎn)發(fā)或重寫反向代理、網(wǎng)關(guān)層對(duì) URL 做了改寫在網(wǎng)關(guān)層同步放行規(guī)則或使用更寬松的通配符如果項(xiàng)目是若依-Vue 原生版本我建議先做一件事寫一個(gè)臨時(shí)接口在TokenFilter里加一行日志把每次請(qǐng)求的request.getRequestURI()和permitAllUrlProperties.matches()的結(jié)果打出來。不用猜日志會(huì)告訴你答案。5.2 路徑匹配不上或匹配了不該匹配的拿到白名單之后先留意*和**的區(qū)別。若依把{xxx}替換成的是*而 Spring 的PatternMatchUtils里*只能匹配路徑中一個(gè)層級(jí)不跨/。比如/system/user/*能匹配/system/user/1但匹配不了/system/user/1/2。如果你希望整個(gè)子目錄都匿名手寫的 URL 應(yīng)該用/system/user/**。還有一種常見情況是精確路徑和通配符互相干擾。例如你已經(jīng)有一條/system/**的通配規(guī)則又單獨(dú)放行了/system/user/list由于列表是按 URL 長(zhǎng)度降序排序的/system/user/list會(huì)更早被匹配所以結(jié)果反而是正常的。但如果通配路徑寫得太寬把本來要保護(hù)的接口也吞進(jìn)去這個(gè)問題就麻煩了。排查思路很簡(jiǎn)單把當(dāng)前系統(tǒng)的匿名白名單完整打印出來逐條看有沒有“看起來不該公開”的路徑。若依的anonymousResources是內(nèi)存列表你可以在onApplicationEvent或者matches方法里臨時(shí)加一行日志把列表內(nèi)容輸出到控制臺(tái)一目了然。5.3 多模塊項(xiàng)目里 Controller 掃描不全前后端分離的大型項(xiàng)目經(jīng)常拆成多個(gè) Maven 模塊。如果你的 Controller 不在啟動(dòng)類默認(rèn)掃描的包路徑下就不會(huì)被注冊(cè)到 Spring 容器里RequestMappingHandlerMapping自然拿不到這個(gè)接口Anonymous就算標(biāo)了也不會(huì)被掃描到。排查時(shí)先看啟動(dòng)類上的SpringBootApplication默認(rèn)掃描范圍再看有沒有自定義ComponentScan。如果業(yè)務(wù)模塊放在com.company.business這種和啟動(dòng)類不同根的包下就需要顯式擴(kuò)展掃描路徑。這是很基礎(chǔ)的問題但往往藏得很深因?yàn)榻涌诒旧硎悄茉L問的只是白名單掃描漏了表現(xiàn)就是“同一個(gè)Anonymous有的接口生效有的不生效”。5.4 接入 Sa-Token / SSO / BPM 后白名單失效如果你在若依上接入了 Sa-Token 或者做了 SSO 改造要意識(shí)到一個(gè)事實(shí)過濾器鏈變了原來的TokenFilter可能已經(jīng)被替換掉PermitAllUrlProperties也就變成了一個(gè)沒人調(diào)用的“僵尸配置類”。這時(shí)別去改PermitAllUrlProperties的源碼應(yīng)該找到新的鑒權(quán)過濾器里對(duì)應(yīng)放行的那個(gè)判斷邏輯看它有沒有兼容舊的Anonymous沒有的話就加入兼容處理或者干脆統(tǒng)一遷移到新注解。SSO 場(chǎng)景里特別要關(guān)注回調(diào)地址比如第三方系統(tǒng)登錄成功后跳回本系統(tǒng)的地址。這個(gè)回調(diào)通常要求匿名訪問但這種匿名應(yīng)該精確到具體的回調(diào)路徑而不是直接把/**整條放開。我見過一個(gè)項(xiàng)目為了調(diào)試方便把整個(gè)系統(tǒng)都設(shè)成了匿名上線后忘改回來相當(dāng)于所有接口都裸奔了一段時(shí)間還好是內(nèi)網(wǎng)系統(tǒng)否則后果不堪設(shè)想。5.5 如何寫一個(gè)簡(jiǎn)單的自動(dòng)化測(cè)試來守住這條鏈框架改來改去最容易出問題的環(huán)節(jié)就是匿名白名單。我建議在項(xiàng)目里針對(duì)這個(gè)點(diǎn)寫幾個(gè)接口測(cè)試守住底線。用 Spring Boot Test 配合 MockMvc最簡(jiǎn)單的一組用例是這樣SpringBootTest AutoConfigureMockMvc public class PermitAllUrlTest { Autowired private MockMvc mockMvc; Test public void anonymousUrlShouldPassWithoutToken() throws Exception { mockMvc.perform(get(/demo/publicInfo)) .andExpect(status().isOk()); } Test public void protectedUrlShouldRejectWithoutToken() throws Exception { mockMvc.perform(get(/system/user/list)) .andExpect(status().isUnauthorized()); } }第一條規(guī)定了白名單接口必須能匿名訪問第二條規(guī)定了受保護(hù)接口沒 token 時(shí)必須拒絕。這兩條用例只要跑通說明過濾鏈的基本行為沒問題。以后誰(shuí)在改造鑒權(quán)邏輯時(shí)誤刪了匿名判斷測(cè)試直接就會(huì)報(bào)紅避免問題流到生產(chǎn)環(huán)境。這里有個(gè)小技巧測(cè)試類盡量用AutoConfigureMockMvc它會(huì)自動(dòng)配好 Spring Security 的 Mock 環(huán)境不需要額外起真實(shí)端口跑起來很快。如果你改動(dòng)了過濾器鏈再補(bǔ)幾個(gè)“帶 token 訪問受保護(hù)接口”的用例整個(gè)鑒權(quán)鏈路就基本有保障了。5.6 最容易忽視的Anonymous 接口里的業(yè)務(wù)代碼前面講的都是框架層面的問題最后補(bǔ)一個(gè)業(yè)務(wù)層面的坑。有些接口標(biāo)了Anonymous但從 Redis 里拿用戶信息的代碼卻依然寫在業(yè)務(wù)方法里。匿名請(qǐng)求沒有登錄態(tài)LoginUser從SecurityContextHolder里取出來是 null然后業(yè)務(wù)代碼直接 NPE。這種問題框架層面沒有任何提示只有接口被匿名訪問時(shí)才會(huì)暴露。我的建議是凡是標(biāo)了Anonymous的接口業(yè)務(wù)邏輯里就不要再依賴任何用戶上下文。如果有部分邏輯需要當(dāng)前登錄用戶那就拆成兩個(gè)接口一個(gè)匿名版一個(gè)登錄版用不同的地址區(qū)分開。這樣既保證了匿名接口能正常調(diào)用也不會(huì)讓登錄態(tài)缺失的邏輯在不知不覺中出問題。6. 我在二次開發(fā)中最后想提醒的三件事6.1 別把匿名接口當(dāng)成“免檢通道”匿名接口不是說“寫個(gè)注解就完事了”它意味著這個(gè)接口會(huì)暴露給任何能訪問到你系統(tǒng)的人。登錄、驗(yàn)證碼這種接口放行沒問題但涉及用戶數(shù)據(jù)、系統(tǒng)配置、敏感操作的接口一定要慎之又慎。我見過一個(gè)項(xiàng)目把個(gè)人信息的查詢接口標(biāo)了Anonymous本意是讓小程序端不登錄也能查到基本信息結(jié)果接口返回的是完整手機(jī)號(hào)和身份證號(hào)等于把用戶隱私直接掛在公網(wǎng)上。白名單是用來解決“無(wú)法帶 token”的問題的不是用來繞過權(quán)限設(shè)計(jì)的。真正合理的做法是需要公開的數(shù)據(jù)只返回公開字段或者改成帶 token 的登錄查詢。6.2 上線前用全局搜索掃一遍所有 Anonymous這個(gè)習(xí)慣我保持了很長(zhǎng)時(shí)間樸素但非常有效。每次提測(cè)或者上線前在 IDE 里對(duì)Anonymous做一次全局搜索逐個(gè)確認(rèn)這些接口是否真的應(yīng)該匿名。尤其是項(xiàng)目經(jīng)歷過多次迭代之后往往會(huì)出現(xiàn)一種情況某個(gè)接口早期為了聯(lián)調(diào)方便加了Anonymous后面功能正式上線了注解卻一直沒刪。這種“歷史遺留匿名接口”是最危險(xiǎn)的因?yàn)樽龉δ荛_發(fā)的人已經(jīng)忘了它存在安全測(cè)試的人也沒注意到它就在角落里默默公開著。如果搜索出來的注解數(shù)量比較多建議在項(xiàng)目里單獨(dú)建一個(gè)文檔維護(hù)白名單清單把每個(gè)匿名接口的用途、開放時(shí)間、負(fù)責(zé)人記下來。流程聽起來繁瑣但真出了事這張表能幫你快速定位是誰(shuí)、什么時(shí)候、為什么開的這個(gè)口子。6.3 多租戶和 AI 衍生框架的匿名邊界要額外小心現(xiàn)在很多項(xiàng)目是基于若依做多租戶改造的或者接入了 AI 能力變成 RuoYi-AI 這類衍生框架。這些場(chǎng)景下匿名接口的邊界問題會(huì)被放大。多租戶項(xiàng)目里租戶信息通常是從 token 里解析tenantId拿到的。匿名請(qǐng)求沒有 token也就沒有租戶上下文業(yè)務(wù)代碼如果默認(rèn)“當(dāng)前租戶 0”或者“默認(rèn)租戶”就可能出現(xiàn) A 租戶的公開接口返回了 B 租戶的數(shù)據(jù)。遇到這種場(chǎng)景匿名接口要么不做租戶隔離要么在網(wǎng)關(guān)層根據(jù) IP、域名等外部標(biāo)識(shí)做租戶識(shí)別。接入 AI 功能的產(chǎn)品還容易踩另一個(gè)坑為了讓用戶先試后登把提問、對(duì)話這類接口全部匿名。這本身沒問題但要注意調(diào)用外部 AI 服務(wù)時(shí)成本是真實(shí)發(fā)生且不可控的。我的經(jīng)驗(yàn)是匿名接口必須配套限流和頻控哪怕只是最簡(jiǎn)單的 IP 維度限流也能在大流量沖擊時(shí)保住成本底線?；氐阶铋_始那個(gè)問題PermitAllUrlProperties表面上只是一個(gè)“掃描注解、收集 URL、匹配請(qǐng)求”的小工具但理解了它你其實(shí)就理解了若依整個(gè)鑒權(quán)鏈路的入口邏輯。我自己在做若依二次開發(fā)時(shí)最深的一個(gè)體會(huì)是白名單這種東西配置越分散、越隱蔽越容易出問題。尊重Anonymous加統(tǒng)一掃描這套模型把規(guī)則盡量收斂到一個(gè)清晰的清單里排錯(cuò)時(shí)才能真正做到心中有數(shù)。