Spring Security 新版本配置這幾年讓不少從 Spring Boot 2 時代過來的開發(fā)者在升級時栽了跟頭。以前老項目里最常見的寫法就是讓配置類繼承WebSecurityConfigurerAdapter然后重寫configure(HttpSecurity http)里面用antMatchers(...).permitAll()一把梭從 Spring Security 5.7 開始這種寫法就不斷告警到 Spring Security 6 直接移除。你現(xiàn)在打開新項目會發(fā)現(xiàn)整個配置思路已經(jīng)換成了組件化寫法不再有 Adapter不再有.and()鏈?zhǔn)狡唇佣峭ㄟ^HttpSecurity上的方法組合出一個SecurityFilterChainBean。這篇內(nèi)容就是針對 Spring Security 新版本配置的一線實操總結(jié)包含我升級過程中踩過的坑、調(diào)整過的方案以及現(xiàn)在最常用的配置骨架。適合正準(zhǔn)備從舊版遷移或者剛接觸 Spring Boot 3 Spring Security 6 的朋友參考讀完拿去做項目改造基本夠用。1. 先盤清楚新版本配置到底改了什么1.1 從 WebSecurityConfigurerAdapter 到組件化配置先說一個很多人沒想明白的問題為什么 Spring Security 一定要把WebSecurityConfigurerAdapter干掉舊版里一次只允許一個配置適配器生效。項目稍大一點你想對不同的 URL 目錄應(yīng)用不同規(guī)則只能靠多個WebSecurityConfigurerAdapter的Order去控制。用起來很繞而且擴展點都藏在重寫方法里新手看半天也不知道哪個方法被哪個框架回調(diào)了。新版本的做法是把“適配器”這個概念徹底去掉改成直接暴露SecurityFilterChain和過濾器鏈注冊機制。本質(zhì)上你現(xiàn)在要做的事情和以前是一樣的核心還是構(gòu)建一條過濾器鏈。只是注冊方式從“繼承 重寫”變成了“聲明 Bean 方法調(diào)用”。下面是一份最精簡的新版核心配置你對比一下舊寫法就能看出差別Configuration EnableWebSecurity public class SecurityConfig { Bean SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(auth - auth .requestMatchers(/public/**).permitAll() .anyRequest().authenticated() ) .formLogin(Customizer.withDefaults()); return http.build(); } }注意三點配置類不需要繼承任何類Configuration加上一個返回SecurityFilterChain的Bean方法就行。authorizeHttpRequests替代了舊的authorizeRequests里面用的是requestMatchers舊版antMatchers和mvcMatchers已經(jīng)淡出。方法內(nèi)部直接用 lambda 配置不需要.and()來回切換上下文。1.2 為什么.and()沒了以及 Lambda DSL 的好處很多舊代碼里能看到一大串.and().and().and()結(jié)構(gòu)例如http.authorizeRequests() .antMatchers(/public/**).permitAll() .and() .formLogin() .loginPage(/login) .and() .logout() .logoutUrl(/logout);這種寫法的問題在于.and()只是把對象切回HttpSecurity一旦中間某一步傳錯了配置器編譯器基本幫不上忙。新版本的 Lambda DSL 會讓每個配置模塊的上下文保持清晰配置formLogin、csrf、sessionManagement時各自獨立成塊代碼可讀性高了一個量級IDE 自動補全也更友好。不過這里要提醒一句網(wǎng)上不少老教程雖然標(biāo)題是“新版本”代碼卻還停留在.and()時代甚至把authorizeRequests和authorizeHttpRequests混在一起寫。這種代碼在新版里會直接編譯失敗提示找不到antMatchers()。我看到太多帖子把這種情況歸結(jié)為“Spring Security 太難了”其實只是 API 換了個位置。1.3 默認(rèn)策略收緊CSRF、CORS、Session 策略的變化新版本除了 API 換了寫法還有一個容易忽略的點默認(rèn)策略比舊版嚴(yán)格了很多。CSRF跨站請求偽造防護默認(rèn)開啟。如果你的服務(wù)是前后端分離的無狀態(tài)接口且不使用瀏覽器 Cookie 做身份憑證就需要顯式關(guān)閉 CSRF否則所有 POST、PUT、DELETE 請求都會被攔截。默認(rèn)登錄頁/login依然自帶但如果你希望做完全自定義的 JSON 登錄需要把默認(rèn)的formLogin關(guān)掉并添加自己的認(rèn)證過濾器。在 Spring Security 6 里對無狀態(tài)場景的推薦方式是配置SessionCreationPolicy.STATELESS避免框架默認(rèn)創(chuàng)建 Session。這里的核心認(rèn)知是新版本希望開發(fā)者在寫每一行配置前主動想清楚自己的應(yīng)用形態(tài)是“傳統(tǒng)服務(wù)端渲染頁面”還是“前后端分離接口服務(wù)”。如果是前者很多默認(rèn)行為可以直接用如果是后者你要顯式關(guān)掉 CSRF、配置 CORS并且不要讓框架維護 Session。我在項目里給團隊定了個很簡單的小口訣csrf要看憑證存放位置session要看服務(wù)端要不要維護狀態(tài)cors要看瀏覽器接口是否跨域。這三個前提搞不清楚配置文檔抄得再多也會埋坑。2. 搭建新版核心配置一個可以落地的 SecurityFilterChain2.1 最簡配置怎么寫才安全網(wǎng)上能找到的新版“最簡配置”基本上都是這種風(fēng)格http.csrf(csrf - csrf.disable()) .authorizeHttpRequests(auth - auth .anyRequest().permitAll());這段代碼的問題是它把認(rèn)證和授權(quán)全關(guān)了算什么安全配置適合新建一個臨時測試工程第一次確認(rèn) Spring Boot 能跑起來但如果你直接把它當(dāng)成項目骨架那還不如不加 Security 依賴。我建議的最小可用配置是這樣的保留密碼加密校驗?zāi)芰δJ(rèn)所有請求都必須經(jīng)過認(rèn)證只放開健康檢查和登錄入口然后根據(jù)實際需求逐步加規(guī)則。這樣配置上線后即使忘了某個細(xì)節(jié)沒有一個大口子直接暴露在外面。Configuration EnableWebSecurity public class SecurityConfig { Bean SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http .csrf(csrf - csrf.disable()) .authorizeHttpRequests(auth - auth .requestMatchers(/health, /error, /api/auth/login).permitAll() .anyRequest().authenticated() ) .sessionManagement(session - session .sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .httpBasic(Customizer.withDefaults()); return http.build(); } }把一個請求“先全攔住再按需放行”作為底線比一開始就permitAll()一大片安全得多。后面要接 Swagger 文檔、靜態(tài)資源或者前端頁面再單獨把對應(yīng)路徑加進permitAll列表里風(fēng)險就可控了。2.2 內(nèi)存用戶與密碼解析器組合沒有接數(shù)據(jù)庫之前最快的用戶配置方式是InMemoryUserDetailsManager。但這里有幾個細(xì)節(jié)必須注意。首先是密碼絕對不能存明文。Spring Security 新版本里默認(rèn)的PasswordEncoder是一個DelegatingPasswordEncoder它會把密碼按{id}密文格式存儲例如{bcrypt}$2a$10$xxxx。你在代碼里創(chuàng)建內(nèi)存用戶時一定要先調(diào)用passwordEncoder.encode(明文)。Bean UserDetailsService userDetailsService(PasswordEncoder passwordEncoder) { UserDetails admin User.builder() .username(admin) .password(passwordEncoder.encode(Admin123)) .roles(ADMIN, USER) .build(); UserDetails viewer User.builder() .username(viewer) .password(passwordEncoder.encode(Viewer123)) .roles(USER) .build(); return new InMemoryUserDetailsManager(admin, viewer); } Bean PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); }這里有一個很常見的報錯你只自定義了UserDetailsService但忘了聲明PasswordEncoder啟動時會報There is no PasswordEncoder mapped for the id null。這個問題的根源是默認(rèn)的密碼解析器拿到一個沒有{id}前綴的密碼不敢確定該用哪種算法去解密所以直接報錯。新版本里我建議統(tǒng)一用一個BCryptPasswordEncoder作為全局密碼編碼器配合DelegatingPasswordEncoder的靈活性。如果你有舊系統(tǒng)的MD5、SHA-256等歷史密碼需要兼容可以在PasswordEncoderFactories.createDelegatingPasswordEncoder()基礎(chǔ)上擴展但新密碼一律用 bcrypt。這樣既保證兼容又不會把新數(shù)據(jù)存成弱算法。2.3 基于數(shù)據(jù)庫的真實用戶服務(wù)內(nèi)存用戶只適合原型階段真實項目還是要接入數(shù)據(jù)庫。新版 Spring Security 里定義一個UserDetailsServiceBean框架就會在認(rèn)證流程中自動使用它Service public class DbUserDetailsService implements UserDetailsService { private final UserRepository userRepository; public DbUserDetailsService(UserRepository userRepository) { this.userRepository userRepository; } Override public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException { User user userRepository.findByUsername(username) .orElseThrow(() - new UsernameNotFoundException(user not found: username)); return org.springframework.security.core.userdetails.User.builder() .username(user.getUsername()) .password(user.getPassword()) .roles(user.getRoles().split(,)) .disabled(!user.isEnabled()) .build(); } }記得把數(shù)據(jù)庫用戶表里的password字段存成加密后的結(jié)果不是明文。很多團隊喜歡把roles字段用逗號分隔拼在一個字段里這種方式在用戶量不大、角色關(guān)系不復(fù)雜的系統(tǒng)里確實省事但查詢時要注意做權(quán)限變更后的緩存刷新否則用戶改了角色要等登錄態(tài)過期才生效。如果你需要把“數(shù)據(jù)庫密碼校驗失敗”“用戶被鎖定”等不同異常區(qū)分開處理可以自定義AuthenticationProvider在里面注入UserDetailsService和PasswordEncoder。但在大多數(shù)場景下DaoAuthenticationProvider已經(jīng)內(nèi)置了這些功能直接讓框架自動裝配即可。從配置角度來說新版代碼里并不需要手動寫一堆 Provider 邏輯。只有當(dāng)你需要接入第三方登錄、短信驗證碼或者動態(tài) token 時才需要自定義AuthenticationProvider并注冊到AuthenticationManager中。2.4 多過濾器鏈讓管理后臺和用戶接口走不同規(guī)則這是新版本里值得充分利用的能力你可以聲明多個SecurityFilterChainBean并通過Order控制優(yōu)先級。舊版里要實現(xiàn)“同一個應(yīng)用用戶端接口和管理后臺接口使用不同安全規(guī)則”要借助多個 Adapter 的 Order很容易踩坑。新版里干脆把每條過濾器鏈的匹配規(guī)則直接寫在requestMatchers上Configuration EnableWebSecurity public class MultiChainSecurityConfig { Bean Order(1) SecurityFilterChain adminSecurityFilterChain(HttpSecurity http) throws Exception { http .securityMatcher(/admin/**) .csrf(csrf - csrf.disable()) .authorizeHttpRequests(auth - auth .requestMatchers(/admin/login).permitAll() .anyRequest().hasRole(ADMIN) ) .formLogin(Customizer.withDefaults()); return http.build(); } Bean Order(2) SecurityFilterChain apiSecurityFilterChain(HttpSecurity http) throws Exception { http .securityMatcher(/api/**) .csrf(csrf - csrf.disable()) .authorizeHttpRequests(auth - auth .requestMatchers(/api/auth/login, /api/public/**).permitAll() .anyRequest().authenticated() ) .sessionManagement(session - session .sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .httpBasic(Customizer.withDefaults()); return http.build(); } }這里最容易犯的錯誤是securityMatcher的作用范圍沒有覆蓋所有請求導(dǎo)致某些路徑落到了最底層的默認(rèn)過濾器鏈上結(jié)果被 401 或 403 攔下來。如果你同時聲明了多條過濾器鏈最好再加一個兜底的默認(rèn)鏈確保所有未匹配的請求有明確的安全策略。我在生產(chǎn)項目里就親眼看過一次這種配置事故用戶端接口和管理端接口分了兩條鏈結(jié)果OPTIONS預(yù)檢請求沒匹配到任何配置被默認(rèn)規(guī)則直接擋掉前端控制臺全是跨域報錯排查半天才定位到規(guī)則重疊的問題。3. 新版本實際操作過程登錄、鑒權(quán)、OAuth2 那些容易踩坑的地方3.1 前后端分離下的 JSON 登錄接口怎么接很多團隊從舊版過渡時問得最多的一句話是能不能不用默認(rèn)的表單登錄頁自己寫一個/auth/login接口接收 JSON 用戶名密碼默認(rèn)的UsernamePasswordAuthenticationFilter只會從請求參數(shù)里獲取用戶名和密碼不會解析 JSON。所以你需要做兩件事關(guān)閉默認(rèn)的表單登錄過濾器。在過濾器鏈合適的位置添加一個自定義 JSON 登錄過濾器或者直接繞過過濾器鏈在業(yè)務(wù) Controller 里手動調(diào)用AuthenticationManager。我更推薦后一種“手動認(rèn)證”方案。在 Controller 里注入AuthenticationManager寫一個登錄方法PostMapping(/auth/login) public ResponseEntityLoginResponse login(RequestBody LoginRequest request) { Authentication authentication authenticationManager.authenticate( new UsernamePasswordAuthenticationToken(request.username(), request.password()) ); SecurityContextHolder.getContext().setAuthentication(authentication); // 然后按自己項目的規(guī)范生成 token 返回給前端 }這樣的好處是登錄邏輯完全可控路徑可以自己定義返回結(jié)構(gòu)也能統(tǒng)一。得到Authentication對象后因為是無狀態(tài)應(yīng)用通常會把用戶信息和過期時間封裝成 Token。配置方面只需要確保/auth/login路徑被permitAll放行并且框架不會因為沒經(jīng)過UsernamePasswordAuthenticationFilter而拒絕你的業(yè)務(wù)請求。一個小細(xì)節(jié)手動認(rèn)證時如果沒有調(diào)用SecurityContextHolder.getContext().setAuthentication(...)后續(xù)一旦走到任何依賴當(dāng)前登錄用戶的方法級權(quán)限處理都會拿不到用戶信息。即使你是用 Token 方案也應(yīng)該在校驗 Token 后設(shè)置一次 SecurityContext保證AuthenticationPrincipal等注解能正常工作。3.2 方法級鑒權(quán)PreAuthorize 和 EnableMethodSecurity 怎么配新版 Spring Security 中方法級安全已經(jīng)獨立成一個專門的注解配置類上要加EnableMethodSecurity而不是舊的EnableGlobalMethodSecurity。這個細(xì)節(jié)很容易被忽略因為很多舊教程標(biāo)題寫著 Spring Security 6代碼里卻還在用EnableGlobalMethodSecurity跑起來也不報錯但方法上的PreAuthorize就是不生效。正確姿勢是在通過Configuration配置的類上加注解Configuration EnableWebSecurity EnableMethodSecurity public class SecurityConfig { // ... }之后在 Controller 或 Service 方法上使用PreAuthorize(hasRole(ADMIN)) GetMapping(/admin/users) public ListUserVO listUsers() { return userService.listAll(); } PreAuthorize(hasAuthority(user:update)) PutMapping(/users/{id}) public void updateUser(PathVariable Long id, RequestBody UserUpdateRequest request) { userService.update(id, request); }區(qū)分hasRole和hasAuthority也很重要。如果你在用戶服務(wù)里給用戶設(shè)置的是roles(ADMIN)那么框架會默認(rèn)給它加ROLE_前綴方法注解里就要寫hasRole(ADMIN)。如果你設(shè)置的是authorities(user:update)這種細(xì)粒度權(quán)限碼就要寫hasAuthority(user:update)。兩者混放在實際項目里非常常見運維排查權(quán)限問題時很多“為什么用戶明明有權(quán)限但接口返回 403”的案例最后都查到是角色前綴沒對上。EnableMethodSecurity里還有幾個可以開關(guān)的選項比如jsr250Enabled true可以啟用RolesAllowedprePostEnabled默認(rèn)也是開啟的。日常項目直接用默認(rèn)配置就好不用刻意把每個注解體系都打開。3.3 Spring Boot 3 整合 OAuth2 資源服務(wù)器時別再糾結(jié) hasScope熱詞里提到“spring security oauth2 沒有 hasScope 方法了嗎”這個問題我在很多群里被問過。其實你去翻官方文檔或源碼會發(fā)現(xiàn)oauth2ResourceServer()配置器上并沒有一個叫hasScope的全局方法。很多老文章里的寫法是從舊的授權(quán)服務(wù)器擴展點直接抄過來的到了新版本自然編譯不過。正確做法是JWT 方式接入資源服務(wù)器時在authorizeHttpRequests里判斷 Scope。http.oauth2ResourceServer(oauth2 - oauth2 .jwt(jwt - jwt .jwtAuthenticationConverter(jwtAuthenticationConverter()) )) .authorizeHttpRequests(auth - auth .requestMatchers(/api/orders/**).hasAuthority(SCOPE_order:read) .anyRequest().authenticated() );因為在 Spring Security 的默認(rèn)實現(xiàn)中從 JWT 的scope或scp聲明解析出來的權(quán)限會以SCOPE_作為前綴變成一個個 authority。你在授權(quán)規(guī)則里直接用hasAuthority(SCOPE_order:read)判斷即可?？吹絊COPE_前綴就明白這是從 JWT Scope 映射出來的權(quán)限而不是數(shù)據(jù)庫里給用戶單獨配置的權(quán)限。如果你的授權(quán)服務(wù)器在 JWT 里存放的是自定義字段比如roles: [admin]那你需要提供一個JwtAuthenticationConverter的 Bean把這個字段解析成ROLE_admin權(quán)限否則 Spring Security 默認(rèn)只會處理scope/scp字段。之前有朋友接到一個第三方單點登錄系統(tǒng)JWT 里權(quán)限字段叫authorities結(jié)果在網(wǎng)關(guān)層全部 403最后就是自定義了一個轉(zhuǎn)換器才解決。**自定義轉(zhuǎn)換器的實現(xiàn)很簡單Bean JwtAuthenticationConverter jwtAuthenticationConverter() { JwtGrantedAuthoritiesConverter converter new JwtGrantedAuthoritiesConverter(); converter.setJwtClaimName(authorities); converter.setAuthorityPrefix(ROLE_); JwtAuthenticationConverter jwtAuthenticationConverter new JwtAuthenticationConverter(); jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(converter); return jwtAuthenticationConverter; }這段代碼的作用就是把 JWT 中名為authorities的聲明取出并統(tǒng)一加上ROLE_前綴。這樣你在PreAuthorize(hasRole(ADMIN))里寫的角色才能匹配上。3.4 登錄狀態(tài)與跨域CORS 到底該配在哪一端前后端分離開發(fā)時跨域問題經(jīng)常被丟給后端。新版 Spring Security 里如果你只依賴 Spring MVC 的CrossOrigin或全局CorsFilter同時又用了 Spring Security有時候 CORS 會被過濾器鏈的優(yōu)先級擋住。建議在 Security 配置里統(tǒng)一管理Bean SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http .cors(cors - cors.configurationSource(corsConfigurationSource())) // 其他配置 return http.build(); } Bean CorsConfigurationSource corsConfigurationSource() { CorsConfiguration config new CorsConfiguration(); config.setAllowedOriginPatterns(List.of(http://localhost:8080, https://*.example.com)); config.setAllowedMethods(List.of(GET, POST, PUT, DELETE, OPTIONS)); config.setAllowedHeaders(List.of(*)); config.setAllowCredentials(true); config.setMaxAge(3600L); UrlBasedCorsConfigurationSource source new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration(/**, config); return source; }這段配置里我用了setAllowedOriginPatterns而不是setAllowedOrigins。原因是當(dāng)allowCredentials為 true 時setAllowedOrigins不支持通配符*如果你允許前端帶上 Cookie 或 Authorization 頭就必須用精確源或者AllowedOriginPatterns。很多初學(xué)者會在這里遇到“貌似 CORS 配置了但還是報跨域錯誤”的情況基本都是因為這個細(xì)節(jié)?？缬蝾A(yù)檢請求OPTIONS是由 CORS 機制處理的配置了上面的CorsConfigurationSource后Spring Security 會正確放行預(yù)檢不需要你在authorizeHttpRequests里單獨把OPTIONS全部permitAll。如果你看到接口單獨用 Postman 調(diào)沒問題瀏覽器一調(diào)就掛十有八九是 CORS 配置沒生效或沒走到 Security 的 CORS 過濾器前而不是后端業(yè)務(wù)接口拒絕跨域。4. 新版本配置實戰(zhàn)排坑我至少遇到過這些異常4.1 啟動 500 報錯無法獲取 AuthenticationManager在 Spring Security 6 中如果你在 Controller 里直接注入AuthenticationManager而項目里又沒有顯式聲明這個 Bean啟動可能會失敗。常見報錯提示找不到AuthenticationManager。解決辦法是在配置類中顯式暴露它Configuration public class AuthManagerConfig { private final AuthenticationConfiguration authenticationConfiguration; public AuthManagerConfig(AuthenticationConfiguration authenticationConfiguration) { this.authenticationConfiguration authenticationConfiguration; } Bean AuthenticationManager authenticationManager() throws Exception { return authenticationConfiguration.getAuthenticationManager(); } }AuthenticationConfiguration會自動感知你在項目中配置的UserDetailsService、PasswordEncoder以及自定義的AuthenticationProvider最終生成的AuthenticationManager就能用于手動認(rèn)證。不要自己在配置類里 new 一個ProviderManager那樣反而容易漏掉全局的 UserDetailsService。4.2 登錄成功后一直拿不到用戶信息經(jīng)常遇到的現(xiàn)象是調(diào)用登錄接口成功Token 也正常返回了但下一個接口把 Token 帶過去后端處理時Authentication為 null。這種情況一般不是過濾器鏈寫錯而是沒有在每次請求到達 Controller 之前根據(jù) Token 還原登錄態(tài)。你需要一個自定義過濾器放在UsernamePasswordAuthenticationFilter之前讀取 TokenComponent public class JwtAuthenticationFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String token resolveToken(request); if (token ! null SecurityContextHolder.getContext().getAuthentication() null) { // 這里解析 token得到用戶身份 // 構(gòu)造 UsernamePasswordAuthenticationToken并 setAuthenticated(true) SecurityContextHolder.getContext().setAuthentication(authentication); } filterChain.doFilter(request, response); } }然后在 Security 配置中注冊http.addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);很多項目在接入 Token 登錄時登錄接口自己寫了一套簽發(fā)邏輯卻漏掉了“每次請求都解析 Token 并恢復(fù) SecurityContext”這個環(huán)節(jié)。只要漏了這一層后續(xù)所有靠 SecurityContext 判斷用戶身份的邏輯全部失效。記住自動登錄狀態(tài)恢復(fù)的本質(zhì)就是在過濾器里替框架把“用戶憑證”找回來。4.3 授權(quán)規(guī)則順序?qū)е碌?403authorizeHttpRequests里的規(guī)則是按從上到下順序匹配的先匹配到的規(guī)則先生效。常見的錯誤是把anyRequest().authenticated()寫在中間結(jié)果后面的permitAll()全部不生效。比較穩(wěn)妥的順序是先放行完全公開的接口和靜態(tài)資源再做方法級之外的粗粒度角色判斷最后用anyRequest()兜底。http.authorizeHttpRequests(auth - auth .requestMatchers(/public/**, /assets/**, /error).permitAll() .requestMatchers(/admin/**).hasRole(ADMIN) .anyRequest().authenticated() );我一直跟團隊強調(diào)授權(quán)規(guī)則不要寫得太多太細(xì)。系統(tǒng)復(fù)雜到一定規(guī)模后把所有權(quán)限判斷都堆在安全配置類里面很難維護。建議在配置類里只做“公共接口放行”和“大塊 URL 目錄的角色隔離”真正細(xì)粒度的數(shù)據(jù)權(quán)限放到 Service 層用PreAuthorize去處理這樣定位問題會快很多。4.4 常用問題與排查路徑速查現(xiàn)象優(yōu)先排查點常見原因接口返回 401Token 過濾器是否執(zhí)行、permitAll路徑是否正確Token 解析失敗或未放行公開接口接口返回 403用戶權(quán)限前綴、角色是否匹配沒有ROLE_前綴或規(guī)則順序不對登錄接口一直走默認(rèn)登錄頁是否關(guān)閉了formLogin自定義 JSON 登錄還需關(guān)閉默認(rèn)表單密碼錯誤但沒提示PasswordEncoder是否統(tǒng)一多個密碼編碼器或存了明文跨域請求報錯CORS 配置、OPTIONS預(yù)檢沒有走 Security 的 CorsConfigurationSourceSecurityContext 為空過濾器順序自定義過濾器沒有注冊或順序顛倒PreAuthorize不生效配置類是否加了EnableMethodSecurity使用了舊注解每次排查這些問題時我習(xí)慣先看一眼請求到底經(jīng)過了哪些過濾器?？梢栽谌罩炯墑e里把org.springframework.security調(diào)成DEBUG過濾鏈的執(zhí)行情況會被完整打印出來。實際追蹤一遍過濾器執(zhí)行順序比自己憑空猜配置位置高效得多。我處理的絕大多數(shù) Security 疑難雜癥都是靠這個手段定位到具體過濾器節(jié)點的。5. 最后說幾句配置思路上的體會從WebSecurityConfigurerAdapter到SecurityFilterChain表面上是換了一套 API背后其實是 Spring Security 團隊推動了很多年的設(shè)計目標(biāo)讓安全配置顯式化、模塊化避免代碼被隱藏的繼承邏輯控制。我在實際項目里最深的體會是配置類不要寫成一個巨無霸。無論SecurityFilterChain還是各種Bean都按模塊拆開比如密碼策略一個類、CORS 一個類、OAuth2 一個類。新版組件化配置本身就適合這種做法但很多人還是習(xí)慣把代碼全堆在一個SecurityConfig里半年后沒人能改得動。另一個很實用的做法是每次升級 Spring Boot 版本前先用 Spring Security 官方遷移文檔對照一遍自己項目里用到的 API因為很多“新版本不再支持”的提示并不會在啟動時立刻報錯而是跑到某個接口時才出現(xiàn)詭異問題。依賴管理盡量用 Spring Boot 的 BOM 統(tǒng)一控制版本不要單獨指定某個 Spring Security 版本跟 Boot 大版本錯位。最后分享一個小技巧如果你在用 Spring Boot 3.x并且項目里引入了EnableWebSecurity但沒有任何SecurityFilterChainBean系統(tǒng)會使用默認(rèn)的BackButton...這類自動兜底配置。很多人想先快速跑通業(yè)務(wù)就隨手加一行EnableWebSecurity結(jié)果所有請求都被默認(rèn)認(rèn)證攔住了還以為是自己路徑寫錯。實際上你不做任何 Security 配置時 Spring Boot 也會給應(yīng)用加上默認(rèn)賬號密碼地址就在啟動日志里自動生成的那個Using generated security password。這個默認(rèn)賬號密碼不是隨便生成的而是框架給你留的最后一道保險。搞清楚這套邏輯你對新版本配置的掌握就能比網(wǎng)上大多數(shù)照抄教程的開發(fā)者更扎實。