Spring Security 工具封装:SecurityUtils 获取当前登录用户

本文基于若依3.9.2、SpringBoot3版本。

image

Spring Security 工具封装:SecurityUtils 获取当前登录用户

com.ruoyi.common.utils.SecurityUtils 是若依对 Spring Security 的工具封装,方法分两组:一组从安全上下文里取当前登录用户,一组做密码加密与权限、角色判断。

这里只看第一组,主要有三个方面:取的值存在哪个对象上、它由谁在请求过程中写进去、取不到时为什么变成 401。

取值只依赖一个静态持有者

组内的方法层层调用,最终收敛到这两行代码:

/** 获取Authentication */
public static Authentication getAuthentication() {
    return SecurityContextHolder.getContext().getAuthentication();
}

/** 获取用户 */
public static LoginUser getLoginUser() {
    try {
        return (LoginUser) getAuthentication().getPrincipal();
    } catch (Exception e) {
        throw new ServiceException("获取用户信息异常", HttpStatus.UNAUTHORIZED);
    }
}

getAuthentication() 没有 try-catch,因为它不会失败:上下文为空时 SecurityContextHolder.getContext() 会新建一个空上下文并写回 ThreadLocal,接着 getAuthentication() 返回 null,两次调用都不抛异常。

getLoginUser() 不同,它在 null 上调用 getPrincipal(),空指针在这里抛出,然后被 catch 接住。

这两个方法穿过的对象构成一条链,每一层各管一件事:

对象 获取方式 在若依中的作用
SecurityContextHolder 静态方法 用 ThreadLocal 保存当前线程的 SecurityContext,线程之间互不影响
SecurityContext getContext() 一次请求的安全上下文,内部主要承载一个 Authentication
Authentication getAuthentication() 认证结果,含主体、凭证、权限集合、已认证标记
Principal getPrincipal() 认证主体。若依在这里放的是 LoginUser

最后一步的强转是 SecurityUtils 与若依自身的耦合点。getPrincipal() 声明为 Object,Spring Security 不规定里面放什么类型,由写入方决定。若依的写入方固定放 LoginUser,所以这里可以直接强转;换成别的认证方式时,这个强转会抛 ClassCastException,同样落进 catch 变成 401。

上下文由 JWT 过滤器写入

SecurityUtils 只负责读,写发生在 framework 模块的 JwtAuthenticationTokenFilter。它继承 OncePerRequestFilter,核心只有几行:

protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
        throws ServletException, IOException {
    LoginUser loginUser = tokenService.getLoginUser(request);
    if (StringUtils.isNotNull(loginUser) && StringUtils.isNull(SecurityUtils.getAuthentication())) {
        tokenService.verifyToken(loginUser);
        UsernamePasswordAuthenticationToken authenticationToken = new UsernamePasswordAuthenticationToken(loginUser, null, loginUser.getAuthorities());
        authenticationToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
        SecurityContextHolder.getContext().setAuthentication(authenticationToken);
    }
    chain.doFilter(request, response);
}

tokenService.getLoginUser(request) 从请求头取出 JWT,解出里面的 uuid,再用 login_tokens: 拼上 uuid 去 Redis 查 LoginUser。没带 token、token 解析失败、Redis 里查不到,三种情况都返回 null,后面的 if 不成立,上下文保持为空。

第二个判空写成 SecurityUtils.getAuthentication(),而不是 SecurityContextHolder.getContext().getAuthentication(),两者效果一样,工具类在这里只是一个更短的入口。这个判断防止同一次请求里重复设置认证信息。

UsernamePasswordAuthenticationToken 用的是三参数构造,依次是主体、凭证、权限集合。凭证传 null,因为走 token 认证没有密码参与;权限集合来自 loginUser.getAuthorities(),而 LoginUser 对这个方法的实现是直接返回 null:

@Override
public Collection<? extends GrantedAuthority> getAuthorities() {
    return null;
}

传 null 不会引发空指针。AbstractAuthenticationToken 的构造对 null 做了兜底,会替换成 AuthorityUtils.NO_AUTHORITIES 这个空集合。结果是令牌上的权限集合始终为空,Spring Security 原生的 hasAuthority 一类判断在该令牌上恒为 false。若依不用这套权限模型,判断依据是 LoginUser.permissions,这里的空集合不参与任何判断。

三参数构造还有一个作用:把令牌的 authenticated 标记置为 true。标记为已认证的令牌不会再交给 AuthenticationManager 校验,Spring Security 认为它的来源可信。setAuthentication 之后,令牌进入当前线程的 SecurityContext。

执行顺序上,这个过滤器通过 addFilterBefore 排在 UsernamePasswordAuthenticationFilter 之前,而 Controller 方法在 DispatcherServlet 里执行,所以业务代码运行时上下文已经写好。反过来说,请求没带有效 token、访问的又是匿名可达的接口(/login、@Anonymous 标注的方法)时,过滤器不写入认证信息,业务代码拿到的就是空上下文。

请求结束时上下文被清空

SecurityContext 挂在 ThreadLocal 上,而 Web 容器的线程是复用的。如果没人清理,上一个请求的用户会残留到下一个请求里。

清理由过滤链上的 SecurityContextHolderFilter 完成,它把 chain.doFilter 包在 try/finally 中,finally 里调 SecurityContextHolder.clearContext(),正常返回和抛异常两条路径都会执行。

若依把 session 策略设为 SessionCreationPolicy.STATELESS,安全上下文不写入 HttpSession,请求结束就丢弃。用户的身份本身存在 Redis,下一个请求到来时由 JWT 过滤器重新查出来、重新写入。所以每次请求里 SecurityUtils 读到的 LoginUser 都是本次查出来的对象,多个请求之间不共享同一个实例。

这个清理只作用于处理请求的那个线程。@Async 方法、AsyncManager 提交的任务跑在别的线程上,ThreadLocal 不跟着过去,在异步任务里直接调 SecurityUtils.getLoginUser() 会拿到空上下文并抛 401。若依的处理方式是在请求线程里先把要用的值取出来,作为参数传进异步任务:

LoginUser loginUser = SecurityUtils.getLoginUser();
SysOperLog operLog = new SysOperLog();
if (loginUser != null) {
    operLog.setOperName(loginUser.getUsername());
}
AsyncManager.me().execute(AsyncFactory.recordOper(operLog));

operLog 是普通对象,异步线程只访问它,不再访问安全上下文。这里的 loginUser != null 实际不会成立,getLoginUser() 要么返回对象,要么抛异常,没有返回 null 的分支。判断留着不影响结果,但也不起作用。

派生方法把异常统一成 401

getUserId()、getDeptId()、getUsername() 三个方法同构,都是先取 LoginUser,再取其中一个属性:

/** 用户ID */
public static Long getUserId() {
    try {
        return getLoginUser().getUserId();
    } catch (Exception e) {
        throw new ServiceException("获取用户ID异常", HttpStatus.UNAUTHORIZED);
    }
}

区别只在方法名、getter 与提示文字,错误码统一是 HttpStatus.UNAUTHORIZED,值为 401。

两层 try-catch 是叠加的。getUserId() 捕获到的异常,可能正是 getLoginUser() 抛出的 ServiceException("获取用户信息异常"),它被重新包装成 ServiceException("获取用户ID异常")。新异常没有把原异常作为 cause 传进去,也没有打印,抛出去后原始异常就丢了,只剩最外层的提示文字和新的堆栈。排查时看到「获取用户ID异常」,光靠提示文字无法知道根因是上下文为空。

401 的两条来源

ServiceException 是 RuntimeException 的子类,带一个可选的 code 字段。它在业务代码里抛出后,由 @RestControllerAdvice 标注的 GlobalExceptionHandler 接住:

@ExceptionHandler(ServiceException.class)
public AjaxResult handleServiceException(ServiceException e, HttpServletRequest request) {
    log.error(e.getMessage(), e);
    Integer code = e.getCode();
    return StringUtils.isNotNull(code) ? AjaxResult.error(code, e.getMessage()) : AjaxResult.error(e.getMessage());
}

code 非空时走 AjaxResult.error(code, msg),响应体是 {"code":401,"msg":"获取用户信息异常"}。这个方法没有 @ResponseStatus,HTTP 状态码仍是 200,401 只存在于响应体的 code 字段里。

前端在响应拦截器里读这个字段:

const code = res.data.code || 200
if (code === 401) {
  if (!isRelogin.show) {
    isRelogin.show = true
    MessageBox.confirm('登录状态已过期,您可以继续留在该页面,或者重新登录', '系统提示', {
      confirmButtonText: '重新登录',
      cancelButtonText: '取消',
      type: 'warning'
    }).then(() => {
      isRelogin.show = false
      store.dispatch('LogOut').then(() => {
        location.href = '/index'
      })
    }).catch(() => {
      isRelogin.show = false
    })
  }
  return Promise.reject('无效的会话,或者会话已过期,请重新登录。')
}

isRelogin.show 防止多个并发请求同时弹出多个确认框。确认后调用登出接口并跳回首页;取消则停在当前页,后续请求继续拿到 401。

另一条 401 不经过 SecurityUtils。请求没带 token 或 token 失效时,anyRequest().authenticated() 授权规则先拦下请求,ExceptionTranslationFilter 把认证异常交给 AuthenticationEntryPointImpl:

public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException e) {
    int code = HttpStatus.UNAUTHORIZED;
    String msg = StringUtils.format("请求访问:{},认证失败,无法访问系统资源", request.getRequestURI());
    ServletUtils.renderString(response, JSON.toJSONString(AjaxResult.error(code, msg)));
}

这条路径上请求根本到不了 Controller。两条路径的 code 相同,msg 不同:认证入口带的文案里有请求 URI,SecurityUtils 抛出的是固定文字。前端对两者做同样处理。

若依中的调用位置

取值方法在若依里有三类调用点,分别在 Controller、Service 与权限校验的 Bean 中。

Controller 层通过 BaseController 转调:

public LoginUser getLoginUser() {
    return SecurityUtils.getLoginUser();
}

public Long getUserId() {
    return getLoginUser().getUserId();
}

public String getUsername() {
    return getLoginUser().getUsername();
}

子类继承 BaseController 后直接写 getLoginUser(),方法体里看不出背后是静态工具类,实际是父类同名方法转调。SysProfileController 的个人信息、修改密码、更换头像几个接口都用这种方式拿当前用户。

Service 层用 isAdmin() 做分支:

public void checkRoleDataScope(Long... roleIds) {
    if (!SecurityUtils.isAdmin()) {
        for (Long roleId : roleIds) {
            SysRole role = new SysRole();
            role.setRoleId(roleId);
            List<SysRole> roles = SpringUtils.getAopProxy(this).selectRoleList(role);
            if (StringUtils.isEmpty(roles)) {
                throw new ServiceException("没有权限访问角色数据!");
            }
        }
    }
}

超级管理员跳过数据权限校验,普通用户逐条查。SysUserServiceImpl、SysDeptServiceImpl 里的同类校验方法结构一致。isAdmin() 内部调的是 isAdmin(getUserId()),userId 等于 1 即视为管理员。

权限校验走 PermissionService,Bean 名 ss。它的 hasPermi、hasAnyPermi、hasRole、hasAnyRoles 四个方法结构一致,都是先取当前用户,再比对集合,取用户与判空的部分如下:

LoginUser loginUser = SecurityUtils.getLoginUser();
if (StringUtils.isNull(loginUser) || CollectionUtils.isEmpty(loginUser.getPermissions())) {
    return false;
}

if 里的两个条件只有后一半会成立。getLoginUser() 要么返回对象、要么抛异常,StringUtils.isNull(loginUser) 恒为 false,真正起作用的是权限集合是否为空。hasRole、hasAnyRoles 判断的是 loginUser.getUser().getRoles() 是否为空,写法相同,同样带着这个不会成立的条件。@PreAuthorize 里的 SpEL 由 Spring Security 求值,最终落到这个 Bean 上。

思考

静态方法还是注入 Bean:SecurityUtils 没有 @Component,方法全为 static,好处是任何位置都能直接调,Controller 基类、Service 实现、AOP 切面、静态工具类内部都不需要注入。若改成 Bean,DictUtils 这类静态工具类就只能像取 RedisCache 那样通过 SpringUtils.getBean 拿,绕一层。代价是静态方法无法替换实现,单元测试要么真实准备 SecurityContextHolder(手动 setContext 一个带 LoginUser 的 Authentication),要么放弃对这段逻辑的隔离测试。若依选了静态,把测试成本放到使用方,对框架自身是划算的:方法体只有几行,可测的价值本来就低,真正需要隔离的是调用它的业务逻辑。

取值失败为什么一律转 401:上下文为空、主体为 null、强转类型不对、属性为 null,这几种情况成因完全不同,返回给上层的却是同一个 code。好处是调用方只面对一种语义「当前没有可用的登录用户」,业务代码不必区分;坏处是编程错误被伪装成登录过期,例如写入方换成了别的 UserDetails 实现,前端只会弹「登录状态已过期」,日志里也只有一句「获取用户信息异常」。GlobalExceptionHandler 用 log.error(e.getMessage(), e) 打出完整堆栈,就是为这种情况留的定位手段。

getLoginUser() 不返回 null 的取舍:方法要么给出用户,要么抛异常,调用方不必判空,也不会出现拿到半可用结果继续往下走的情况。代价有两处。一是判空代码在框架自己的实现里反复出现,LogAspect 的 if (loginUser != null)、PermissionService 四个判断方法里的 StringUtils.isNull(loginUser) 都不会成立,读代码时容易误以为存在返回 null 的分支;这些位置想表达的是「查不到用户就当作没有权限」,false 本来是个合理答案,而 getLoginUser() 只给异常,判空于是写不出来。二是真正需要「可能没有登录用户」的场景不好表达,比如一个允许匿名访问、登录后要额外返回个人数据的接口,只能 try-catch 兜住 401 再继续,或者改用不带异常的 getAuthentication() 判断上下文是否为空。后者更清晰,SecurityUtils 也把 getAuthentication() 公开出来了。

posted @ 2026-11-15 19:42  咖啡八杯  阅读(7)  评论(0)    收藏  举报