1. Spring Security到底解决了什么问题先说个实际场景。你辛辛苦苦把接口写好上线第一天就被别人用脚本来刷数据或者一个普通用户直接调管理端接口把你数据库拖走。这时候你会意识到Java后端里认证和授权不是靠几个if判断就能糊弄过去的。Spring Security就是干这个的——它不只是一个登录拦截器而是一整套贯穿请求全生命周期的安全框架。很多人一看到Spring Security那套Filter链就头大觉得配置复杂、调试困难。但如果你愿意花点时间把它的执行顺序和核心抽象搞清楚你会发现它比你自己手写的拦截器要严谨得多。这套框架不仅能处理表单登录、HTTP Basic、OAuth2、JWT这些常见认证方式还能通过方法级注解做到接口粒度甚至数据行级的权限控制。对于Java开发者来说它几乎是后端安全领域的标配。这篇文章适合两类人一是刚接触Spring Security、被官方文档绕晕的初学者二是已经用过但遇到诡异问题、想知道底层原理的进阶者。我会按照架构思路 → 核心机制 → 实操配置 → 问题排查的顺序来讲尽量把我实际踩过的坑和验证过的方法都写清楚。2. 核心架构思路Filter Chain是怎么兜住所有请求的2.1 一张过滤器链就是一套安全流水线Spring Security最底层的执行模型是Servlet Filter这个得先说清楚。Java Web应用的请求进来后会先经过Tomcat等容器内的Filter链再进入DispatcherServlet。Spring Security做的事就是把一串内置的SecurityFilter注册到这条链上每个Filter只负责一个安全职责。打个比方这就好比进机场安检第一个窗口查你身份证有没有过期第二个窗口查你有没有带违禁品第三个窗口决定让你走普通通道还是VIP通道。每个环节独立但顺序不能乱。Spring Security的Filter链大致是这个顺序SecurityContextHolderFilter从Session或请求头里恢复当前用户上下文LogoutFilter处理退出登录UsernamePasswordAuthenticationFilter处理表单登录提交BasicAuthenticationFilter处理HTTP Basic认证ExceptionTranslationFilter捕获后续异常并转成401/403响应AuthorizationFilter做最终的授权裁决理解这条链的顺序特别重要。很多人排查问题一头雾水就是因为没搞清楚某个Filter是在哪个阶段生效的。比如你自定义了一个Filter想往SecurityContext里塞用户信息如果你的Filter排在AuthorizationFilter之后那授权时根本读不到你塞进去的用户。2.2 DelegatingFilterProxy与Spring容器解耦的秘密这里还有一个初学者容易懵的点为什么我们写的Spring Security配置会被Spring Boot自动装配关键在DelegatingFilterProxy。它本身是一个Servlet注册的Filter但真正干活的是Spring容器里的一个Bean名字叫springSecurityFilterChain。容器外的Filter系统不认识Spring Bean但DelegatingFilterProxy做了桥接这样Servlet容器和IoC容器就可以各自独立管理生命周期。你不需要记住所有Filter类名但一定要明白所有请求都会经过这整条链任何一个环节抛出异常后面的Filter就不会执行。这就是为什么有时候你配置了接口放行但请求还是被拦截——可能问题出在更前面的Filter比如CSRF过滤器。实操经验遇到我明明放行了但还被拦截的怪问题第一步不是怀疑配置而是先确认请求到底走到哪个Filter失败的。最简单的办法是在SecurityFilterChain配置里临时加一个日志Filter或者开启Spring Security的DEBUG日志级别能看到每个请求经过了哪些Filter。2.3 两份配置两个世界SecurityFilterChain与WebSecurity很多人被Spring Security新旧版本文档搞晕是因为配置方式经历了多次变化。Spring Security 5.7之前主流是继承WebSecurityConfigurerAdapter之后官方推荐用组件式配置定义一个SecurityFilterChain的Bean和一个UserDetailsService的Bean即可。我自己在升级项目时踩过不少坑。WebSecurityConfigurerAdapter这套旧写法网上资源多但和Spring Boot 3.x配合时问题很多尤其是Spring Security 6.0之后很多方法被标记废弃甚至移除。如果你是新项目直接用SecurityFilterChain EnableMethodSecurity这套组合如果是老项目升级则需要重构配置类不建议继续在新代码里沿用旧Adapter写法。举个简单的配置骨架Configuration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(auth - auth .requestMatchers(/api/public/**).permitAll() .requestMatchers(/api/admin/**).hasRole(ADMIN) .anyRequest().authenticated() ) .formLogin(withDefaults()) .httpBasic(withDefaults()); return http.build(); } Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }这套配置的逻辑非常直白public目录下开放admin目录下必须是ADMIN角色其他都要登录。formLogin和httpBasic同时开启是因为有些场景需要页面跳转有些场景需要接口认证。3. 认证机制深挖从用户名密码到SecurityContext的完整链路3.1 Authentication接口一个到处传递的通行证认证过程在Spring Security里可以概括成一句话把用户提交的凭证封装成Authentication对象由AuthenticationManager去验证这个对象验证通过后就把它存进SecurityContextHolder。Authentication接口里其实就三块核心内容当前用户是谁principal、有什么凭证credentials、有哪些权限authorities。用户名密码登录时前端传来的表单会被UsernamePasswordAuthenticationFilter封装成UsernamePasswordAuthenticationToken这个类就是Authentication的常见实现。我们要理解的关键点是Authentication对象在认证前只是一个未认证的凭据认证成功后它的authenticated属性变为true并且会被重新构建一次把敏感信息密码清空再塞进SecurityContext。所以你在后续代码里从SecurityContext拿到的User是不含密码的。3.2 ProviderManager与AuthenticationProvider的配合AuthenticationManager本身只是一个策略入口真正干活的是ProviderManager——它维护着一个AuthenticationProvider列表。每个Provider只负责一种认证方式DaoAuthenticationProvider处理数据库用户名密码JwtAuthenticationProvider处理JWTOAuth2LoginAuthenticationProvider处理OAuth2登录。这个设计初看觉得绕但它的价值在于系统可以同时支持多种登录方式互不干扰。实际项目里最常见的组合就是表单登录 微信扫码 JWT接口认证这种场景如果只写一个拦截器代码会越写越脏而Spring Security天然支持。具体到用户名密码登录DaoAuthenticationProvider的大致流程是从Authentication对象里取出用户名和密码调用UserDetailsService.loadUserByUsername()加载用户信息如果没有该用户抛出UsernameNotFoundException用PasswordEncoder.matches()比对密码是否一致校验用户状态是否锁定、是否禁用认证成功后构建一个新的Authentication对象其中principal是UserDetails对象有一个重要细节容易被忽略UserDetailsService只负责加载用户不负责验证密码。密码比对在Provider内部完成。这意味着你可以自己实现UserDetailsService去查数据库、查Redis甚至调远程接口只要返回UserDetails即可。3.3 PasswordEncoder密码存储的底线说到密码我必须多说几句。很多初学者还在用MD5加盐的方式存密码这在现在来看是很危险的做法。MD5/SHA系列本身就是为快速计算摘要设计的而暴力破解工具对这类算法的破解效率非常高。Spring Security官方推荐的BCrypt、scrypt、argon2才是正经方案它们都是故意设计成慢让每一次暴力尝试都要付出高昂时间成本。BCryptPasswordEncoder是用的最多的它的一个鲜明特点是每次加密同一个明文得到的密文都不一样因为内部自动带入了随机盐。所以校验时不能反过来加密比较而要调用matches(rawPassword, encodedPassword)方法它会从存储的密文里提取盐重新计算后比对。实操注意PasswordEncoder一旦上线尽量不要变更算法。如果有老库数据用的是MD5建议采用升级编码器方案新用户用BCrypt老用户登录时自动平滑升级为BCrypt。不要直接跑全量数据迁移容易出问题且回滚困难。4. 授权模型URL级、方法级与数据级权限4.1 URL级授权先认请求路径再定谁能访问认证解决你是谁授权解决你能干什么。Spring Security的URL授权在SecurityFilterChain里配置核心方法是authorizeHttpRequests。版本差异上Spring Security 6.0之前是antMatchers之后改成了requestMatchers老的写法在新版本里会报错。写授权规则时有一个铁律越具体的规则放前面越宽泛的放后面。因为规则是按顺序匹配的一旦匹配上就直接生效。看一个实际例子http.authorizeHttpRequests(auth - auth .requestMatchers(/api/auth/**, /, /index.html, /static/**).permitAll() .requestMatchers(/api/user/**).hasRole(USER) .requestMatchers(/api/admin/**).hasRole(ADMIN) .requestMatchers(/api/moderator/**).hasAnyRole(ADMIN, MODERATOR) .anyRequest().authenticated() );这里有一个关键区分hasRole和hasAuthority。hasRole(ADMIN)实际上检查的是ROLE_ADMIN这个权限标识它会自动补前缀ROLE_而hasAuthority(ROLE_ADMIN)检查的是原样字符串。如果你的权限数据里存的就是ROLE_ADMIN用哪个都行但如果存的是自定义权限编号如user:edit,那只能用hasAuthority。4.2 方法级安全用注解把权限收进业务代码URL授权解决的是入口拦截但有些接口内部的精细权限控制URL级别很难表达。比如一个订单删除接口普通用户只能删自己的订单管理员能删所有人订单。这种场景就该用方法级安全。开启方式很简单在配置类上加EnableMethodSecurity然后就可以在Service或Controller上用注解PreAuthorize(hasRole(ADMIN)) public void deleteOrder(Long orderId) { ... } PreAuthorize(hasPermission(#orderId, order, delete)) public void deleteOwnOrder(Long orderId) { ... }PreAuthorize里可以用Spring EL表达式引用方法参数用#开头甚至调用自定义Bean的方法。市面上很多高级权限需求——比如部门经理只能删除本部门数据——在PreAuthorize里都能比较优雅地表达。不过方法级安全也有性能代价每次调用都会走AOP代理。对于高频调用且权限明显无变化的场景建议配合缓存或者只在关键写操作上使用不要在列表查询这类读接口上做太复杂的权限表达式。4.3 动态权限与RBAC数据驱动才是企业级玩法大多数企业级系统的权限不是写死在配置里的而是动态配置的。用户在界面上勾选角色角色绑定菜单和按钮权限存在数据库里。这种场景下URL级和方法级的硬编码规则都不够灵活。方案有两种一种是自定义AuthorizationManager在授权阶段从数据库加载该用户的所有权限用PermissionEvaluator实现hasPermission的动态逻辑另一种更常见是结合Spring Security与自己的RBAC表在登录时把用户的所有权限加载进GrantedAuthority列表。需要注意动态加载权限不能每请求都查一次库否则性能会很差。我建议登录时把权限列表放进Redis带一个短TTL权限变更时主动删除Redis缓存让下次请求重新加载。5. 从零开始Spring Boot集成Spring Security实操记录5.1 引入依赖与第一版配置如果你用的是Spring Boot 3.x引入starter-security非常轻松dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency依赖引入后Spring Boot会启动默认安全配置所有接口都需要认证默认用户名为user密码是启动时打印在控制台的随机UUID。这不是bug是安全兜底策略。对于前后端分离项目建议一开始就写好JSON格式的401/403响应而不是默认的HTML错误页。分享一个实用配置http.exceptionHandling(ex - ex .authenticationEntryPoint((request, response, authException) - { response.setContentType(application/json;charsetUTF-8); response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); response.getWriter().write({\code\:401,\message\:\未登录或登录已过期\}); }) .accessDeniedHandler((request, response, accessDeniedException) - { response.setContentType(application/json;charsetUTF-8); response.setStatus(HttpServletResponse.SC_FORBIDDEN); response.getWriter().write({\code\:403,\message\:\没有权限访问\}); }) );这里的authenticationEntryPoint处理未认证场景accessDeniedHandler处理已认证但无权限场景。两者不要搞混否则会出现返回状态码错乱的问题。5.2 基于数据库的用户信息加载重新认识UserDetailsService实现数据库登录认证关键是自定义UserDetailsService。我不建议直接拿Spring Security自带的User实体那样会把业务用户和安全用户绑死。更合理的模式是业务User存业务信息另建一个SecurityUserDetails实现UserDetails接口作为适配层。下面是一个我实际项目中常用的写法Service public class UserDetailsServiceImpl implements UserDetailsService { private final UserMapper userMapper; private final RoleMapper roleMapper; public UserDetails loadUserByUsername(String username) { UserDO userDO userMapper.selectByUsername(username); if (userDO null) { throw new UsernameNotFoundException(用户不存在); } ListString roles roleMapper.selectRolesByUserId(userDO.getId()); return new SecurityUser(userDO, roles); } } public class SecurityUser implements UserDetails { private UserDO userDO; private ListString roles; public Collection? extends GrantedAuthority getAuthorities() { return roles.stream() .map(role - new SimpleGrantedAuthority(ROLE_ role)) .toList(); } public String getPassword() { return userDO.getPassword(); } public String getUsername() { return userDO.getUsername(); } public boolean isEnabled() { return userDO.getStatus() 1; } }注意getAuthorities()的写法我在这里把角色拼成了ROLE_前缀这样配置hasRole的时候就能直接匹配上。如果你不拼前缀那只能一直用hasAuthority(ADMIN)这种写法容易混乱。5.3 前后端分离下的JWT认证方案落地如果项目做的是前后端分离表单登录的Session方案体验很差。这时候JWT更合适。整套方案分为三个环节登录接口验证密码生成Token返回自定义JwtAuthenticationFilter从请求头提取Token并校验校验通过后构造Authentication对象放进SecurityContext放行请求核心过滤器实现套路比较固定Component public class JwtAuthenticationFilter extends OncePerRequestFilter { private final JwtTokenProvider tokenProvider; private final UserDetailsServiceImpl userDetailsService; protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String token resolveToken(request); if (token ! null tokenProvider.validateToken(token)) { String username tokenProvider.getUsername(token); UserDetails userDetails userDetailsService.loadUserByUsername(username); UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken(userDetails, null, userDetails.getAuthorities()); SecurityContextHolder.getContext().setAuthentication(authentication); } filterChain.doFilter(request, response); } }然后在SecurityFilterChain里把JwtAuthenticationFilter注册到UsernamePasswordAuthenticationFilter之前http.addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);这种做法的好处是Token校验逻辑独立不影响框架内其他认证方式。我实际用下来这个Filter必须在SecurityContextHolderFilter之后执行因为要先有了安全上下文后续授权过滤器才能读到Authentication对象。还有一个细节JWT Token里不要存敏感信息最多存userId、username、过期时间。每次请求都从Token里拿用户名去查库如果性能压力大可以只校验签名并把用户信息编码进claims但这样如果用户被禁用Token在有效期内还能继续使用需要自己权衡。6. 常见问题与排查技巧实录6.1 接口全部被拦截或白名单不生效现象配置了requestMatchers(/api/auth/**).permitAll()但请求还是跳登录页或者返回401。排查思路优先级永远是精确优先、顺序匹配。先把所有规则打印出来看看配错了没有logging: level: org.springframework.security: DEBUG另一个常见原因是Spring MVC和Security的路径匹配风格不同。Spring Security 6里的requestMatchers默认使用PathPatternParser如果你的Servlet Path设置有点特殊可能出现匹配不上的情况。这时候可以显式指定requestMatchers(/api/auth/**).permitAll()或者统一用MvcRequestMatcher来对齐Spring MVC的路径规则。还有个低级错误是写了两套SecurityFilterChain配置类后加载的配置覆盖了前面的。同一个项目只能有一个生效的SecurityFilterChain Bean除非用Order区分多个过滤链。6.2 前后端分离下POST请求返回403这是CSRF防护的锅。Spring Security默认开启CSRF防护它会要求所有非安全方法POST/PUT/DELETE携带一个CSRF Token。前后端分离项目用JWT方案时这个机制不但没用反而给自己添堵。解决方案很简单——关闭它http.csrf(csrf - csrf.disable());注意如果你做的是传统表单登录jsp页面建议保留CSRF防护这是防跨站请求伪造的关键防线。但如果是无状态API架构关闭CSRF是合理选择因为不存在基于Cookie的会话。6.3 自定义Filter里往SecurityContext塞用户但授权时还是匿名用户这个是很多同学都踩过的坑。原因通常是你的Filter在Spring Security过滤链之外执行了。Spring Security的过滤链有自己的顺序如果你直接把自己写的Filter注册到Servlet容器层面而不经过DelegatingFilterProxy那SecurityContextHolder可能还没建立或者你的Filter执行时机不对。解决方式把自己写的Filter作为Spring Bean然后在SecurityFilterChain里用addFilterBefore/addFilterAfter显式注册到链路中不要用Servlet的WebFilter注解去注册。另外要注意SecurityContext默认是用ThreadLocal保存的在异步处理、子线程里需要显式把SecurityContext传过去否则子线程里读不到登录用户。可以配置SecurityContextHolder策略为MODE_INHERITABLETHREADLOCAL或者自己写一个包装Executor传上下文。6.4 登录接口成功后返回401error日志却提示UserDaoAuthenticationProvider这个场景常见于改了数据库密码加密方式之后。如果你把数据库里老用户的密码从MD5硬换成了BCrypt密文但项目还在用自定义的比对逻辑那就会出现查到了用户但密码匹配失败的情况。如果UserDetailsService抛异常但不被感知也会表现为401。排查时先确认UserDetailsService有没有被调用可以在loadUserByUsername里打个日志。如果连日志都没有问题就在DAOProvider之前——可能是表单参数名不对或者认证入口没走到。6.5 速查表高频异常与解决方案异常现象根本原因解决方案白名单接口仍跳登录页规则顺序错误或配置未生效检查规则顺序开启DEBUG日志确认链路登录成功后所有接口403认证成功但角色不匹配检查GrantedAuthority是否带ROLE_前缀登录成功后sesseion失效SecurityContext未持久化确认SecurityContextPersistenceFilter未禁掉POST接口403CSRF防护拦截无状态API关闭CSRF密码框登录失败PasswordEncoder不一致确认配置的编码器与存储密文算法一致JWT接口匿名访问自定义Filter未注册进链路用addFilterBefore注册到正确位置Spring Boot 3.0报错使用了老版WebSecurityConfigurerAdapter重构为SecurityFilterChain组件式配置7. 总结一下我的实际体会做后端安全这块我最大的感受是Spring Security本身不难难的是理解它的分层思想和过滤器顺序。它把认证、授权、攻击防护拆成了一个个独立组件如果你硬要把所有逻辑塞在一个拦截器里那框架的优势就发挥不出来。建议新手学习时不要急着追求炫酷的JWT或OAuth2先做一次最简单的内存用户表单登录把认证链路跑通再逐步加数据库用户、密码加密、角色权限。每一步都配合DEBUG日志观察过滤器链的执行顺序踩几个坑之后你对整个框架的理解会突飞猛进。最后分享一个小技巧在调试Spring Security时你可以用一个简单的匿名请求比如curl不带任何Token然后用DEBUG日志看它经过哪些Filter、在哪个环节失败。这条链路会告诉你很多在文档里读不到的细节。安全框架的日常维护里最重要的不是写多少代码而是知道请求进来之后一步步发生什么——这个认知能帮你解决至少八成以上的疑难问题。