Struct StpUtil 

pub struct StpUtil;

StpUtil - 权限认证工具类

提供便捷的认证和授权操作方法，类似于 Java 版 sa-token 的 StpUtil

Implementations

impl StpUtil

pub fn init_manager(manager: SaTokenManager)

初始化全局 SaTokenManager（应用启动时调用一次）

示例

let manager = SaTokenConfig::builder()
    .storage(Arc::new(MemoryStorage::new()))
    .build();
StpUtil::init_manager(manager);

pub fn event_bus() -> &'static SaTokenEventBus

获取事件总线，用于注册监听器

示例

use sa_token_core::{StpUtil, SaTokenListener};
use async_trait::async_trait;
 
struct MyListener;
 
#[async_trait]
impl SaTokenListener for MyListener {
    async fn on_login(&self, login_id: &str, token: &str, login_type: &str) {
        println!("用户 {} 登录了", login_id);
    }
}
 
// 注册监听器
StpUtil::event_bus().register(Arc::new(MyListener)).await;

pub fn register_listener(listener: Arc<dyn SaTokenListener>)

注册事件监听器（便捷方法）

示例

StpUtil::register_listener(Arc::new(MyListener)).await;

pub async fn login(login_id: impl LoginId) -> SaTokenResult<TokenValue>

会话登录

示例

// 支持字符串 ID
let token = StpUtil::login("user_123").await?;
 
// 支持数字 ID
let token = StpUtil::login(10001).await?;
let token = StpUtil::login(10001_i64).await?;

pub async fn login_with_type( login_id: impl LoginId, _login_type: impl Into<String>, ) -> SaTokenResult<TokenValue>

pub async fn login_with_extra( login_id: impl LoginId, extra_data: Value, ) -> SaTokenResult<TokenValue>

登录并设置额外数据 | Login with extra data

参数 | Arguments

• login_id - 登录ID | Login ID
• extra_data - 额外数据 | Extra data

pub async fn login_with_manager( manager: &SaTokenManager, login_id: impl Into<String>, ) -> SaTokenResult<TokenValue>

会话登录（带 manager 参数的版本，向后兼容）

pub async fn logout(token: &TokenValue) -> SaTokenResult<()>

会话登出

pub async fn logout_with_manager( manager: &SaTokenManager, token: &TokenValue, ) -> SaTokenResult<()>

pub async fn kick_out(login_id: impl LoginId) -> SaTokenResult<()>

踢人下线（根据登录ID）

pub async fn kick_out_with_manager( manager: &SaTokenManager, login_id: &str, ) -> SaTokenResult<()>

pub async fn logout_by_login_id(login_id: impl LoginId) -> SaTokenResult<()>

强制登出（根据登录ID）

pub async fn logout_by_token(token: &TokenValue) -> SaTokenResult<()>

根据 token 登出（别名方法，更直观）

pub fn get_token_value() -> SaTokenResult<TokenValue>

获取当前请求的 token（无参数，从上下文获取）

示例

// 在请求处理函数中
let token = StpUtil::get_token_value()?;

pub async fn logout_current() -> SaTokenResult<()>

当前会话登出（无参数，从上下文获取 token）

示例

// 在请求处理函数中
StpUtil::logout_current().await?;

pub fn is_login_current() -> bool

检查当前会话是否登录（无参数，返回 bool）

示例

// 在请求处理函数中
if StpUtil::is_login_current() {
    println!("当前用户已登录");
}

pub fn check_login_current() -> SaTokenResult<()>

检查当前会话登录状态，未登录则抛出异常（无参数）

示例

// 在请求处理函数中
StpUtil::check_login_current()?;

pub async fn get_login_id_as_string() -> SaTokenResult<String>

获取当前会话的 login_id（String 类型，无参数）

示例

// 在请求处理函数中
let login_id = StpUtil::get_login_id_as_string().await?;

pub async fn get_login_id_as_long() -> SaTokenResult<i64>

获取当前会话的 login_id（i64 类型，无参数）

示例

// 在请求处理函数中
let user_id = StpUtil::get_login_id_as_long().await?;

pub fn get_token_info_current() -> SaTokenResult<Arc<TokenInfo>>

获取当前会话的 token 信息（无参数）

示例

// 在请求处理函数中
let token_info = StpUtil::get_token_info_current()?;
println!("Token 创建时间: {:?}", token_info.create_time);

pub async fn is_login(token: &TokenValue) -> bool

检查当前 token 是否已登录

pub async fn is_login_by_login_id(login_id: impl LoginId) -> bool

根据登录 ID 检查是否已登录

示例

let is_logged_in = StpUtil::is_login_by_login_id("user_123").await;
let is_logged_in = StpUtil::is_login_by_login_id(10001).await;

pub async fn is_login_with_manager( manager: &SaTokenManager, token: &TokenValue, ) -> bool

pub async fn check_login(token: &TokenValue) -> SaTokenResult<()>

检查当前 token 是否已登录，如果未登录则抛出异常

pub async fn get_token_info(token: &TokenValue) -> SaTokenResult<TokenInfo>

获取 token 信息

pub async fn get_login_id(token: &TokenValue) -> SaTokenResult<String>

获取当前 token 的登录ID

pub async fn get_login_id_or_default( token: &TokenValue, default: impl Into<String>, ) -> String

获取当前 token 的登录ID，如果未登录则返回默认值

pub async fn get_token_by_login_id( login_id: impl LoginId, ) -> SaTokenResult<TokenValue>

根据登录 ID 获取当前用户的 token

示例

let token = StpUtil::get_token_by_login_id("user_123").await?;
let token = StpUtil::get_token_by_login_id(10001).await?;

pub async fn get_all_tokens_by_login_id( login_id: impl LoginId, ) -> SaTokenResult<Vec<TokenValue>>

根据登录 ID 获取所有在线的 token 列表（支持多设备登录）

示例

let tokens = StpUtil::get_all_tokens_by_login_id("user_123").await?;

pub async fn get_session(login_id: impl LoginId) -> SaTokenResult<SaSession>

获取当前登录账号的 Session

pub async fn save_session(session: &SaSession) -> SaTokenResult<()>

保存 Session

pub async fn delete_session(login_id: impl LoginId) -> SaTokenResult<()>

删除 Session

pub async fn set_session_value<T: Serialize>( login_id: impl LoginId, key: &str, value: T, ) -> SaTokenResult<()>

在 Session 中设置值

pub async fn get_session_value<T: DeserializeOwned>( login_id: impl LoginId, key: &str, ) -> SaTokenResult<Option<T>>

从 Session 中获取值

pub fn create_token(token_value: impl Into<String>) -> TokenValue

创建一个新的 token（但不登录）

pub fn is_valid_token_format(token: &str) -> bool

检查 token 格式是否有效（仅检查格式，不检查是否存在于存储中）

impl StpUtil

pub async fn set_permissions( login_id: impl LoginId, permissions: Vec<String>, ) -> SaTokenResult<()>

为用户添加权限

pub async fn add_permission( login_id: impl LoginId, permission: impl Into<String>, ) -> SaTokenResult<()>

为用户添加单个权限

pub async fn remove_permission( login_id: impl LoginId, permission: &str, ) -> SaTokenResult<()>

移除用户的某个权限

pub async fn clear_permissions(login_id: impl LoginId) -> SaTokenResult<()>

清除用户的所有权限

pub async fn get_permissions(login_id: impl LoginId) -> Vec<String>

获取用户的所有权限

pub async fn has_permission(login_id: impl LoginId, permission: &str) -> bool

检查用户是否拥有指定权限

pub async fn has_all_permissions( login_id: impl LoginId, permissions: &[&str], ) -> bool

检查用户是否拥有所有指定权限（AND 逻辑）

pub async fn has_permissions_and( login_id: impl LoginId, permissions: &[&str], ) -> bool

检查用户是否拥有所有指定权限（别名，AND 逻辑）

pub async fn has_any_permission( login_id: impl LoginId, permissions: &[&str], ) -> bool

检查用户是否拥有任一指定权限（OR 逻辑）

pub async fn has_permissions_or( login_id: impl LoginId, permissions: &[&str], ) -> bool

检查用户是否拥有任一指定权限（别名，OR 逻辑）

pub async fn check_permission( login_id: impl LoginId, permission: &str, ) -> SaTokenResult<()>

检查权限，如果没有则抛出异常

impl StpUtil

pub async fn set_roles( login_id: impl LoginId, roles: Vec<String>, ) -> SaTokenResult<()>

为用户设置角色

pub async fn add_role( login_id: impl LoginId, role: impl Into<String>, ) -> SaTokenResult<()>

为用户添加单个角色

pub async fn remove_role( login_id: impl LoginId, role: &str, ) -> SaTokenResult<()>

移除用户的某个角色

pub async fn clear_roles(login_id: impl LoginId) -> SaTokenResult<()>

清除用户的所有角色

pub async fn get_roles(login_id: impl LoginId) -> Vec<String>

获取用户的所有角色

pub async fn has_role(login_id: impl LoginId, role: &str) -> bool

检查用户是否拥有指定角色

pub async fn has_all_roles(login_id: impl LoginId, roles: &[&str]) -> bool

检查用户是否拥有所有指定角色（AND 逻辑）

pub async fn has_roles_and(login_id: impl LoginId, roles: &[&str]) -> bool

检查用户是否拥有所有指定角色（别名，AND 逻辑）

pub async fn has_any_role(login_id: impl LoginId, roles: &[&str]) -> bool

检查用户是否拥有任一指定角色（OR 逻辑）

pub async fn has_roles_or(login_id: impl LoginId, roles: &[&str]) -> bool

检查用户是否拥有任一指定角色（别名，OR 逻辑）

pub async fn check_role(login_id: impl LoginId, role: &str) -> SaTokenResult<()>

检查角色，如果没有则抛出异常

impl StpUtil

pub async fn kick_out_batch<T: LoginId>( login_ids: &[T], ) -> SaTokenResult<Vec<Result<(), SaTokenError>>>

批量踢人下线

pub async fn get_token_timeout(token: &TokenValue) -> SaTokenResult<Option<i64>>

获取 token 剩余有效时间（秒）

pub async fn renew_timeout( token: &TokenValue, timeout_seconds: i64, ) -> SaTokenResult<()>

续期 token（重置过期时间）

pub async fn set_extra_data( token: &TokenValue, extra_data: Value, ) -> SaTokenResult<()>

设置 Token 的额外数据 | Set extra data for token

参数 | Arguments

• token - Token值 | Token value
• extra_data - 额外数据 | Extra data

pub async fn get_extra_data(token: &TokenValue) -> SaTokenResult<Option<Value>>

获取 Token 的额外数据 | Get extra data from token

参数 | Arguments

• token - Token值 | Token value

pub fn builder(login_id: impl LoginId) -> TokenBuilder

创建 Token 构建器，用于链式调用 | Create token builder for chain calls

示例 | Example

use serde_json::json;
 
// 链式调用示例
let token = StpUtil::builder("user_123")
    .extra_data(json!({"ip": "192.168.1.1"}))
    .device("pc")
    .login_type("admin")
    .login()
    .await?;