身份认证与应用安全 / 系统课时
检查用户是否拥有指定角色
检查用户是否拥有指定角色
接口只允许管理员、运营或审计人员访问时,不需要手工遍历角色列表。Sa-Token 提供布尔判断和异常式校验两组角色 API,本节用单角色、全部满足和任一满足三种条件完成授权判断,并说明未登录与角色不足的处理边界。
学习目标
- 使用
hasRole判断当前账号是否拥有指定角色 - 使用
hasRoleAnd、hasRoleOr表达多个角色的“全部”与“任一”条件 - 在需要阻断请求时改用
checkRole、checkRoleAnd、checkRoleOr
判断和校验解决不同问题
StpUtil.hasRole("admin") 返回布尔值,适合页面分支、可选功能或业务代码自行决定后续动作。当前账号未登录时,角色判断结果为 false。
StpUtil.checkRole("admin") 则用于“没有该角色就不能继续”的接口保护。角色不满足时会抛出 NotRoleException,后续代码不会执行。若接口还需要明确区分“未登录”和“已登录但无角色”,可以先调用 StpUtil.checkLogin(),再做角色校验。
用角色 API 表达授权条件
下面是片段示例,放入已经完成 Sa-Token 登录认证和 StpInterface#getRoleList 配置的 Spring Boot 项目即可使用。四个接口分别展示布尔判断、单角色阻断、任一角色通过和全部角色通过。
import cn.dev33.satoken.stp.StpUtil;
import cn.dev33.satoken.util.SaResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/role")
public class RoleCheckController {
@GetMapping("/admin")
public SaResult isAdmin() {
// 只需要分支判断时使用布尔 API,不主动抛出角色异常。
return SaResult.data(StpUtil.hasRole("admin"));
}
@GetMapping("/admin-only")
public SaResult adminOnly() {
StpUtil.checkLogin();
StpUtil.checkRole("admin");
return SaResult.ok("authorized");
}
@GetMapping("/ops-or-auditor")
public SaResult opsOrAuditor() {
StpUtil.checkLogin();
// 任一角色满足即可继续;全部满足应改用 checkRoleAnd。
StpUtil.checkRoleOr("ops", "auditor");
return SaResult.ok("authorized");
}
@GetMapping("/admin-and-auditor")
public SaResult adminAndAuditor() {
StpUtil.checkLogin();
StpUtil.checkRoleAnd("admin", "auditor");
return SaResult.ok("authorized");
}
}预期结果
/role/admin:当前账号含有 admin 时 data 为 true,否则为 false
/role/admin-only:已登录且含有 admin 时返回 authorized,否则角色校验失败
/role/ops-or-auditor:含有 ops 或 auditor 任一角色时通过
/role/admin-and-auditor:同时含有 admin 与 auditor 时才通过实际 HTTP 状态码和错误响应体取决于项目如何把 NotLoginException、NotRoleException 映射到统一异常响应,Sa-Token 的角色校验本身只负责通过或抛出对应异常。
多个角色条件不要写反
多个角色判断最容易出错的是把“任一满足”和“全部满足”写反。可以直接按业务语义选择 API:
| 业务条件 | 返回布尔值 | 不满足时抛异常 |
|---|---|---|
拥有 admin |
hasRole("admin") |
checkRole("admin") |
同时拥有 admin、auditor |
hasRoleAnd("admin", "auditor") |
checkRoleAnd("admin", "auditor") |
拥有 ops、auditor 任意一个 |
hasRoleOr("ops", "auditor") |
checkRoleOr("ops", "auditor") |
不要用多个独立 hasRole 再手工拼复杂条件,除非业务确实需要额外分支。直接使用 And、Or API 能让授权意图更明确,也减少逻辑运算符写错的机会。
角色结果来自 StpInterface
这些 API 不会自己推断数据库里的角色。它们最终依赖 StpInterface#getRoleList 返回的角色标识集合,因此代码里的 admin、ops、auditor 必须和项目存储的角色码完全对应。
如果 getRoleList 使用了缓存,后台修改用户角色后还要按缓存策略主动失效;否则 hasRole 和 checkRole 会继续针对旧角色列表做判断。接口层的角色 API 写对,只解决“如何检查”,授权数据是否新鲜仍由数据加载层负责。
当授权逻辑只是判断角色时,优先使用角色 API;如果真正控制的是“订单删除”“报表导出”这类细粒度能力,则应把能力建模成权限码,再使用权限检查,避免角色名称逐渐演变成难以维护的业务权限集合。