1. 项目概述为什么这个组合在真实业务中跑得稳、改得快、查得清SpringBoot Spring Security Swagger 这套技术栈不是教科书里凑出来的“理想搭配”而是我在过去三年带过的7个中型后台系统里被反复验证过最省心的认证权限底座。它解决的从来不是“能不能登录”这种基础问题而是“用户输错三次密码后要不要锁账户”“管理员临时给某人开三天导出权限怎么不留后门”“前端同事改个按钮颜色后端接口文档要不要同步更新”这些每天都在发生的现实摩擦。关键词里那个“跳转自定义登录界面”表面看只是换个HTML页面背后其实是把Spring Security默认的/login重定向链路整个掰开揉碎——你得知道它在哪拦截请求、在哪判断未认证、在哪触发跳转否则改完页面发现404或者登录成功后又弹回登录页这种问题我见过太多次。这套方案适合两类人一类是刚从单体应用转型做前后端分离的Java后端需要一套不绕弯子、能直接抄作业的权限骨架另一类是前端团队开始用Vue/React独立开发但后端还卡在Shiro或手写Filter的老项目急需一个能快速对接、文档自动同步、权限规则可配置的升级路径。它不追求炫技但每个环节都经得起压测和审计——比如登录失败日志会精确到IP用户名时间戳Swagger生成的接口文档里所有带PreAuthorize(hasRole(ADMIN))的方法都会自动标红并注明所需角色连测试同学都能看懂权限边界。2. 整体架构设计与技术选型逻辑为什么不是Spring Cloud Security或JWT单独上阵2.1 为什么坚持用Spring Security而非自己封装Filter链有人问“Security太重我直接写个LoginFilter不更轻量”——这话在单接口场景下成立但放到真实业务里就露馅了。我拿最近一个电商后台举例用户登录后要同时校验手机是否实名、账号是否被冻结、当前IP是否在白名单、当天登录次数是否超限。如果用自定义Filter这四个校验得串成一条if-else长链任何一个环节抛异常整个流程就断了而且没法复用已有的RememberMe、CSRF防护、密码加密策略。而Spring Security的AuthenticationManager天然支持Provider链式调用DaoAuthenticationProvider查库、CustomLockProvider校验锁定状态、IpWhitelistProvider过滤IP每个Provider只管自己那块失败时还能统一返回401或423Locked。更关键的是它的FilterChainProxy会按顺序加载这些Filter像组装乐高一样插拔——你要加短信验证码校验新增一个SmsCodeAuthenticationFilter就行不用动原有逻辑。我试过把Security换成纯Filter方案在支付回调接口里补了个防重放校验结果导致登录页的CSRF token失效排查了两天才发现是Filter顺序冲突。Security的标准化流程本质是用约定代替猜测省下的调试时间够你多写三个业务接口。2.2 为什么选择Session机制而非JWT做主认证方案热搜词里常看到“JWT无状态、适合分布式”但真实项目里JWT的坑比糖多。去年有个物流系统用JWT上线后发现三个致命问题一是token过期时间设成2小时客服人员下班前没操作token一过期就得重新登录客户投诉率飙升二是黑名单管理成本高员工离职后要遍历所有Redis里的token做失效处理运维半夜被报警电话叫醒三是前端把token存在localStorageXSS攻击一打一个准。而Spring Security默认的HttpSession方案天然解决这些问题session超时由容器控制如Tomcat的maxInactiveInterval注销时调用session.invalidate()立刻失效cookie的HttpOnly属性防XSS。当然我们做了增强——用Redis集中存储sessionspring-session-data-redis既保留session的易管理性又支持水平扩展。至于JWT我们只在特定场景用比如生成临时下载链接的签名token有效期5分钟用HMAC-SHA256签发完全不走用户会话体系。这种混合模式比纯JWT或纯Session都更贴近业务实际。2.3 为什么Swagger必须集成进认证流而不是独立部署很多团队把Swagger放在测试环境单独跑结果出现“文档里写的接口能调通生产环境死活403”的尴尬。根源在于没让Swagger页面本身参与认证流程。我们的做法是把Swagger的静态资源路径/swagger-ui/、/v3/api-docs/明确配置进Security的permitAll白名单但要求访问者必须已通过登录认证——也就是说你得先登录系统才能看到Swagger页面。这样做的好处是双重的一是前端调用接口时浏览器自动携带JSESSIONID cookie和业务请求完全一致避免了“文档测试通过代码调不通”的割裂二是Swagger生成的Try it out按钮会自动注入当前用户的认证上下文测试时不用手动填Header。更重要的是我们在Swagger配置里加了权限分组普通用户只能看到user-api分组管理员能看到admin-api分组这个分组逻辑和PreAuthorize注解完全同步。当产品经理说“这个导出接口只给财务组开”你改一行PreAuthorize(hasRole(FINANCE))Swagger文档里对应接口立刻变灰不可点连文档都不用人工更新。3. 核心细节解析与实操要点从登录流程拆解到界面定制的每一步3.1 Spring Security认证流程的七个关键节点及拦截点理解登录跳转必须吃透Security的认证生命周期。这不是黑盒而是有迹可循的七步流水线请求进入用户访问/dashboardSecurity的FilterChainProxy捕获请求匿名检查AnonymousAuthenticationFilter判断是否已认证未认证则创建AnonymousAuthenticationToken权限决策FilterSecurityInterceptor调用AccessDecisionManager检查/dashboard是否需要ROLE_USER权限拒绝响应因未认证且需权限ExceptionTranslationFilter捕获AccessDeniedException触发AuthenticationEntryPoint跳转触发默认LoginUrlAuthenticationEntryPoint将请求重定向至/login登录页渲染/login被ViewControllerRegistry映射到login.html此时Security已准备好CSRF token表单提交用户提交表单UsernamePasswordAuthenticationFilter拦截/loginPOST请求调用AuthenticationManager完成认证关键在于第4步和第5步——很多人以为改loginPage(/my-login)就能换页面却忘了AuthenticationEntryPoint才是跳转的总开关。如果你在配置里写了.formLogin().loginPage(/my-login)但没配.exceptionHandling().authenticationEntryPoint(...)那么当用户直接访问受保护URL时依然会跳转到默认/login。我踩过的坑是在WebSecurityConfigurerAdapter的configure(HttpSecurity http)方法里把formLogin()配置放在authorizeRequests()之后导致跳转规则没生效。正确顺序必须是先定义authorizeRequests()设置权限规则再用formLogin()配置登录行为最后用exceptionHandling()兜底。3.2 自定义登录界面的三大避坑实践自定义登录页不是简单复制login.html这里有三个硬性约束提示CSRF token必须显式注入否则表单提交必403提示登录失败时Security会把错误信息存入SPRING_SECURITY_LAST_EXCEPTION必须用Thymeleaf的#errors对象取值提示密码输入框的name属性必须为password用户名必须为username这是UsernamePasswordAuthenticationFilter的硬编码约定我们用Thymeleaf实现登录页核心片段如下form th:action{/login} methodpost input typehidden th:name${_csrf.parameterName} th:value${_csrf.token} / div classform-group label用户名/label input typetext nameusername classform-control th:classappend${#fields.hasErrors(username)} ? is-invalid / div classinvalid-feedback th:if${#fields.hasErrors(username)} th:errors*{username}用户名错误/div /div div classform-group label密码/label input typepassword namepassword classform-control / /div div classalert alert-danger rolealert th:if${param.error} 用户名或密码错误请重试 /div button typesubmit classbtn btn-primary登录/button /form注意两个细节一是th:name${_csrf.parameterName}动态获取CSRF参数名默认_csrf避免硬编码二是th:if${param.error}判断URL参数error是否存在这是Security在认证失败后自动重定向/login?error的机制。很多新手用#session去取错误信息结果永远为空——因为错误信息不在session里而在重定向的query参数中。3.3 权限控制粒度的三层设计URL级、方法级、数据级权限不是非黑即白我们按风险等级分三层实施URL级用http.authorizeRequests()控制粗粒度访问比如/admin/**必须ROLE_ADMIN/api/user/**必须ROLE_USER。这里有个经验静态资源路径/static/**、/images/**一定要放在authorizeRequests()最前面用permitAll()放行否则CSS/JS加载失败导致页面错乱。方法级在Service层方法上用PreAuthorize(hasRole(ADMIN) and #userId authentication.principal.id)实现“管理员只能删自己的数据”。这里authentication.principal.id是当前登录用户的IDSecurity自动注入不用手动从session取。数据级对高危操作如删除订单在Mapper XML里加动态SQLdelete iddeleteOrder DELETE FROM orders WHERE id #{id} AND user_id #{principal.id} AND status ! SHIPPED /delete#{principal.id}由Security的EnableGlobalMethodSecurity(prePostEnabled true)解析确保SQL层面就过滤掉越权数据。这种三层防御让权限漏洞几乎不可能发生。去年审计时安全团队用Burp Suite尝试修改URL参数越权访问第一层URL拦截就返回403他们改用合法token调用API第二层方法注解又拦截最后直接连数据库执行SQL第三层数据过滤仍生效。三道防线缺一不可。4. 实操过程与核心环节实现从零搭建可运行的认证系统4.1 依赖配置与版本兼容性清单Maven依赖看似简单版本冲突却是高频故障源。我们锁定以下组合经Spring Boot 2.7.x实测properties spring-boot.version2.7.18/spring-boot.version spring-security.version5.7.11/spring-security.version springdoc-openapi.version1.6.14/springdoc-openapi.version /properties dependencies !-- Spring Boot Web核心 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId version${spring-boot.version}/version /dependency !-- Spring Security注意不引入starter-security避免自动配置干扰-- dependency groupIdorg.springframework.security/groupId artifactIdspring-security-web/artifactId version${spring-security.version}/version /dependency dependency groupIdorg.springframework.security/groupId artifactIdspring-security-config/artifactId version${spring-security.version}/version /dependency !-- Swagger替代品springdoc-openapi比旧版Swagger更适配Security-- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-ui/artifactId version${springdoc-openapi.version}/version /dependency !-- Thymeleaf模板引擎 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency /dependencies关键点说明不使用spring-boot-starter-security它会自动配置WebSecurityConfiguration和我们手动配置的SecurityConfig冲突导致自定义登录页失效。springdoc-openapi替代Swagger旧版Swaggerspringfox与Spring Security 5.7存在兼容问题EnableSwagger2注解会导致FilterChainProxy初始化失败。springdoc基于OpenAPI 3规范原生支持Security的PreAuthorize注解解析。Thymeleaf必须显式声明Spring Boot 2.7默认不启用Thymeleaf需添加依赖并配置spring.thymeleaf.enabledtrue。4.2 Security配置类的完整实现与参数详解SecurityConfig.java是整个认证体系的中枢以下是精简后的核心代码已移除无关日志和注释Configuration EnableWebSecurity EnableGlobalMethodSecurity(prePostEnabled true, securedEnabled true) public class SecurityConfig { Bean public PasswordEncoder passwordEncoder() { // 使用BCrypt强哈希强度12耗时约300ms平衡安全与性能 return new BCryptPasswordEncoder(12); } Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf(csrf - csrf .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())) // 允许JS读取CSRF cookie .and() .sessionManagement(session - session .sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED) // 仅在需要时创建session .invalidSessionUrl(/login?invalid-sessiontrue)) // session失效跳转页 .and() .authorizeHttpRequests(authz - authz .requestMatchers(/static/**, /images/**, /css/**, /js/**).permitAll() // 静态资源放行 .requestMatchers(/login, /register, /error).permitAll() // 登录相关页面放行 .requestMatchers(/swagger-ui/**, /v3/api-docs/**).permitAll() // Swagger资源放行 .requestMatchers(/admin/**).hasRole(ADMIN) // 管理员路径 .requestMatchers(/api/**).authenticated() // API需认证 .anyRequest().authenticated()) // 其他请求均需认证 .formLogin(form - form .loginPage(/login) // 自定义登录页路径 .loginProcessingUrl(/login) // 表单提交目标URL .defaultSuccessUrl(/dashboard, true) // 登录成功后跳转true忽略原请求 .failureUrl(/login?errortrue) // 认证失败跳转 .usernameParameter(username) // 用户名参数名 .passwordParameter(password) // 密码参数名 .permitAll()) .logout(logout - logout .logoutUrl(/logout) .logoutSuccessUrl(/login?logouttrue) .invalidateHttpSession(true) .deleteCookies(JSESSIONID)) .exceptionHandling(exception - exception .accessDeniedPage(/403) // 权限不足页面 .authenticationEntryPoint(new LoginUrlAuthenticationEntryPoint(/login))); // 未认证跳转入口 return http.build(); } Bean public UserDetailsService userDetailsService() { // 内存用户示例实际项目替换为JdbcUserDetailsManager或自定义UserDetailsService UserDetails admin User.builder() .username(admin) .password($2a$12$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
1. 项目概述为什么这个组合在真实业务中跑得稳、改得快、查得清SpringBoot Spring Security Swagger 这套技术栈不是教科书里凑出来的“理想搭配”而是我在过去三年带过的7个中型后台系统里被反复验证过最省心的认证权限底座。它解决的从来不是“能不能登录”这种基础问题而是“用户输错三次密码后要不要锁账户”“管理员临时给某人开三天导出权限怎么不留后门”“前端同事改个按钮颜色后端接口文档要不要同步更新”这些每天都在发生的现实摩擦。关键词里那个“跳转自定义登录界面”表面看只是换个HTML页面背后其实是把Spring Security默认的/login重定向链路整个掰开揉碎——你得知道它在哪拦截请求、在哪判断未认证、在哪触发跳转否则改完页面发现404或者登录成功后又弹回登录页这种问题我见过太多次。这套方案适合两类人一类是刚从单体应用转型做前后端分离的Java后端需要一套不绕弯子、能直接抄作业的权限骨架另一类是前端团队开始用Vue/React独立开发但后端还卡在Shiro或手写Filter的老项目急需一个能快速对接、文档自动同步、权限规则可配置的升级路径。它不追求炫技但每个环节都经得起压测和审计——比如登录失败日志会精确到IP用户名时间戳Swagger生成的接口文档里所有带PreAuthorize(hasRole(ADMIN))的方法都会自动标红并注明所需角色连测试同学都能看懂权限边界。2. 整体架构设计与技术选型逻辑为什么不是Spring Cloud Security或JWT单独上阵2.1 为什么坚持用Spring Security而非自己封装Filter链有人问“Security太重我直接写个LoginFilter不更轻量”——这话在单接口场景下成立但放到真实业务里就露馅了。我拿最近一个电商后台举例用户登录后要同时校验手机是否实名、账号是否被冻结、当前IP是否在白名单、当天登录次数是否超限。如果用自定义Filter这四个校验得串成一条if-else长链任何一个环节抛异常整个流程就断了而且没法复用已有的RememberMe、CSRF防护、密码加密策略。而Spring Security的AuthenticationManager天然支持Provider链式调用DaoAuthenticationProvider查库、CustomLockProvider校验锁定状态、IpWhitelistProvider过滤IP每个Provider只管自己那块失败时还能统一返回401或423Locked。更关键的是它的FilterChainProxy会按顺序加载这些Filter像组装乐高一样插拔——你要加短信验证码校验新增一个SmsCodeAuthenticationFilter就行不用动原有逻辑。我试过把Security换成纯Filter方案在支付回调接口里补了个防重放校验结果导致登录页的CSRF token失效排查了两天才发现是Filter顺序冲突。Security的标准化流程本质是用约定代替猜测省下的调试时间够你多写三个业务接口。2.2 为什么选择Session机制而非JWT做主认证方案热搜词里常看到“JWT无状态、适合分布式”但真实项目里JWT的坑比糖多。去年有个物流系统用JWT上线后发现三个致命问题一是token过期时间设成2小时客服人员下班前没操作token一过期就得重新登录客户投诉率飙升二是黑名单管理成本高员工离职后要遍历所有Redis里的token做失效处理运维半夜被报警电话叫醒三是前端把token存在localStorageXSS攻击一打一个准。而Spring Security默认的HttpSession方案天然解决这些问题session超时由容器控制如Tomcat的maxInactiveInterval注销时调用session.invalidate()立刻失效cookie的HttpOnly属性防XSS。当然我们做了增强——用Redis集中存储sessionspring-session-data-redis既保留session的易管理性又支持水平扩展。至于JWT我们只在特定场景用比如生成临时下载链接的签名token有效期5分钟用HMAC-SHA256签发完全不走用户会话体系。这种混合模式比纯JWT或纯Session都更贴近业务实际。2.3 为什么Swagger必须集成进认证流而不是独立部署很多团队把Swagger放在测试环境单独跑结果出现“文档里写的接口能调通生产环境死活403”的尴尬。根源在于没让Swagger页面本身参与认证流程。我们的做法是把Swagger的静态资源路径/swagger-ui/、/v3/api-docs/明确配置进Security的permitAll白名单但要求访问者必须已通过登录认证——也就是说你得先登录系统才能看到Swagger页面。这样做的好处是双重的一是前端调用接口时浏览器自动携带JSESSIONID cookie和业务请求完全一致避免了“文档测试通过代码调不通”的割裂二是Swagger生成的Try it out按钮会自动注入当前用户的认证上下文测试时不用手动填Header。更重要的是我们在Swagger配置里加了权限分组普通用户只能看到user-api分组管理员能看到admin-api分组这个分组逻辑和PreAuthorize注解完全同步。当产品经理说“这个导出接口只给财务组开”你改一行PreAuthorize(hasRole(FINANCE))Swagger文档里对应接口立刻变灰不可点连文档都不用人工更新。3. 核心细节解析与实操要点从登录流程拆解到界面定制的每一步3.1 Spring Security认证流程的七个关键节点及拦截点理解登录跳转必须吃透Security的认证生命周期。这不是黑盒而是有迹可循的七步流水线请求进入用户访问/dashboardSecurity的FilterChainProxy捕获请求匿名检查AnonymousAuthenticationFilter判断是否已认证未认证则创建AnonymousAuthenticationToken权限决策FilterSecurityInterceptor调用AccessDecisionManager检查/dashboard是否需要ROLE_USER权限拒绝响应因未认证且需权限ExceptionTranslationFilter捕获AccessDeniedException触发AuthenticationEntryPoint跳转触发默认LoginUrlAuthenticationEntryPoint将请求重定向至/login登录页渲染/login被ViewControllerRegistry映射到login.html此时Security已准备好CSRF token表单提交用户提交表单UsernamePasswordAuthenticationFilter拦截/loginPOST请求调用AuthenticationManager完成认证关键在于第4步和第5步——很多人以为改loginPage(/my-login)就能换页面却忘了AuthenticationEntryPoint才是跳转的总开关。如果你在配置里写了.formLogin().loginPage(/my-login)但没配.exceptionHandling().authenticationEntryPoint(...)那么当用户直接访问受保护URL时依然会跳转到默认/login。我踩过的坑是在WebSecurityConfigurerAdapter的configure(HttpSecurity http)方法里把formLogin()配置放在authorizeRequests()之后导致跳转规则没生效。正确顺序必须是先定义authorizeRequests()设置权限规则再用formLogin()配置登录行为最后用exceptionHandling()兜底。3.2 自定义登录界面的三大避坑实践自定义登录页不是简单复制login.html这里有三个硬性约束提示CSRF token必须显式注入否则表单提交必403提示登录失败时Security会把错误信息存入SPRING_SECURITY_LAST_EXCEPTION必须用Thymeleaf的#errors对象取值提示密码输入框的name属性必须为password用户名必须为username这是UsernamePasswordAuthenticationFilter的硬编码约定我们用Thymeleaf实现登录页核心片段如下form th:action{/login} methodpost input typehidden th:name${_csrf.parameterName} th:value${_csrf.token} / div classform-group label用户名/label input typetext nameusername classform-control th:classappend${#fields.hasErrors(username)} ? is-invalid / div classinvalid-feedback th:if${#fields.hasErrors(username)} th:errors*{username}用户名错误/div /div div classform-group label密码/label input typepassword namepassword classform-control / /div div classalert alert-danger rolealert th:if${param.error} 用户名或密码错误请重试 /div button typesubmit classbtn btn-primary登录/button /form注意两个细节一是th:name${_csrf.parameterName}动态获取CSRF参数名默认_csrf避免硬编码二是th:if${param.error}判断URL参数error是否存在这是Security在认证失败后自动重定向/login?error的机制。很多新手用#session去取错误信息结果永远为空——因为错误信息不在session里而在重定向的query参数中。3.3 权限控制粒度的三层设计URL级、方法级、数据级权限不是非黑即白我们按风险等级分三层实施URL级用http.authorizeRequests()控制粗粒度访问比如/admin/**必须ROLE_ADMIN/api/user/**必须ROLE_USER。这里有个经验静态资源路径/static/**、/images/**一定要放在authorizeRequests()最前面用permitAll()放行否则CSS/JS加载失败导致页面错乱。方法级在Service层方法上用PreAuthorize(hasRole(ADMIN) and #userId authentication.principal.id)实现“管理员只能删自己的数据”。这里authentication.principal.id是当前登录用户的IDSecurity自动注入不用手动从session取。数据级对高危操作如删除订单在Mapper XML里加动态SQLdelete iddeleteOrder DELETE FROM orders WHERE id #{id} AND user_id #{principal.id} AND status ! SHIPPED /delete#{principal.id}由Security的EnableGlobalMethodSecurity(prePostEnabled true)解析确保SQL层面就过滤掉越权数据。这种三层防御让权限漏洞几乎不可能发生。去年审计时安全团队用Burp Suite尝试修改URL参数越权访问第一层URL拦截就返回403他们改用合法token调用API第二层方法注解又拦截最后直接连数据库执行SQL第三层数据过滤仍生效。三道防线缺一不可。4. 实操过程与核心环节实现从零搭建可运行的认证系统4.1 依赖配置与版本兼容性清单Maven依赖看似简单版本冲突却是高频故障源。我们锁定以下组合经Spring Boot 2.7.x实测properties spring-boot.version2.7.18/spring-boot.version spring-security.version5.7.11/spring-security.version springdoc-openapi.version1.6.14/springdoc-openapi.version /properties dependencies !-- Spring Boot Web核心 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId version${spring-boot.version}/version /dependency !-- Spring Security注意不引入starter-security避免自动配置干扰-- dependency groupIdorg.springframework.security/groupId artifactIdspring-security-web/artifactId version${spring-security.version}/version /dependency dependency groupIdorg.springframework.security/groupId artifactIdspring-security-config/artifactId version${spring-security.version}/version /dependency !-- Swagger替代品springdoc-openapi比旧版Swagger更适配Security-- dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-ui/artifactId version${springdoc-openapi.version}/version /dependency !-- Thymeleaf模板引擎 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-thymeleaf/artifactId /dependency /dependencies关键点说明不使用spring-boot-starter-security它会自动配置WebSecurityConfiguration和我们手动配置的SecurityConfig冲突导致自定义登录页失效。springdoc-openapi替代Swagger旧版Swaggerspringfox与Spring Security 5.7存在兼容问题EnableSwagger2注解会导致FilterChainProxy初始化失败。springdoc基于OpenAPI 3规范原生支持Security的PreAuthorize注解解析。Thymeleaf必须显式声明Spring Boot 2.7默认不启用Thymeleaf需添加依赖并配置spring.thymeleaf.enabledtrue。4.2 Security配置类的完整实现与参数详解SecurityConfig.java是整个认证体系的中枢以下是精简后的核心代码已移除无关日志和注释Configuration EnableWebSecurity EnableGlobalMethodSecurity(prePostEnabled true, securedEnabled true) public class SecurityConfig { Bean public PasswordEncoder passwordEncoder() { // 使用BCrypt强哈希强度12耗时约300ms平衡安全与性能 return new BCryptPasswordEncoder(12); } Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf(csrf - csrf .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())) // 允许JS读取CSRF cookie .and() .sessionManagement(session - session .sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED) // 仅在需要时创建session .invalidSessionUrl(/login?invalid-sessiontrue)) // session失效跳转页 .and() .authorizeHttpRequests(authz - authz .requestMatchers(/static/**, /images/**, /css/**, /js/**).permitAll() // 静态资源放行 .requestMatchers(/login, /register, /error).permitAll() // 登录相关页面放行 .requestMatchers(/swagger-ui/**, /v3/api-docs/**).permitAll() // Swagger资源放行 .requestMatchers(/admin/**).hasRole(ADMIN) // 管理员路径 .requestMatchers(/api/**).authenticated() // API需认证 .anyRequest().authenticated()) // 其他请求均需认证 .formLogin(form - form .loginPage(/login) // 自定义登录页路径 .loginProcessingUrl(/login) // 表单提交目标URL .defaultSuccessUrl(/dashboard, true) // 登录成功后跳转true忽略原请求 .failureUrl(/login?errortrue) // 认证失败跳转 .usernameParameter(username) // 用户名参数名 .passwordParameter(password) // 密码参数名 .permitAll()) .logout(logout - logout .logoutUrl(/logout) .logoutSuccessUrl(/login?logouttrue) .invalidateHttpSession(true) .deleteCookies(JSESSIONID)) .exceptionHandling(exception - exception .accessDeniedPage(/403) // 权限不足页面 .authenticationEntryPoint(new LoginUrlAuthenticationEntryPoint(/login))); // 未认证跳转入口 return http.build(); } Bean public UserDetailsService userDetailsService() { // 内存用户示例实际项目替换为JdbcUserDetailsManager或自定义UserDetailsService UserDetails admin User.builder() .username(admin) .password($2a$12$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
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
