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) -> Result<TokenValue, SaTokenError>

会话登录

示例

// 支持字符串 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>, ) -> Result<TokenValue, SaTokenError>

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

登录并设置额外数据 | 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>, ) -> Result<TokenValue, SaTokenError>

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

pub async fn logout(token: &TokenValue) -> Result<(), SaTokenError>

会话登出

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

pub async fn kick_out(login_id: impl LoginId) -> Result<(), SaTokenError>

踢人下线（根据登录ID）

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

pub async fn logout_by_login_id( login_id: impl LoginId, ) -> Result<(), SaTokenError>

强制登出（根据登录ID）

pub async fn logout_by_token(token: &TokenValue) -> Result<(), SaTokenError>

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

pub fn get_token_value() -> Result<TokenValue, SaTokenError>

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

示例

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

pub async fn logout_current() -> Result<(), SaTokenError>

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

示例

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

pub fn is_login_current() -> bool

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

示例

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

pub fn check_login_current() -> Result<(), SaTokenError>

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

示例

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

pub async fn get_login_id_as_string() -> Result<String, SaTokenError>

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

示例

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

pub async fn get_login_id_as_long() -> Result<i64, SaTokenError>

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

示例

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

pub fn get_token_info_current() -> Result<Arc<TokenInfo>, SaTokenError>

获取当前会话的 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) -> Result<(), SaTokenError>

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

pub async fn get_token_info( token: &TokenValue, ) -> Result<TokenInfo, SaTokenError>

获取 token 信息

pub async fn get_login_id(token: &TokenValue) -> Result<String, SaTokenError>

获取当前 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, ) -> Result<TokenValue, SaTokenError>

根据登录 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, ) -> Result<Vec<TokenValue>, SaTokenError>

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

示例

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

pub async fn get_session( login_id: impl LoginId, ) -> Result<SaSession, SaTokenError>

获取当前登录账号的 Session

pub async fn save_session(session: &SaSession) -> Result<(), SaTokenError>

保存 Session

pub async fn delete_session(login_id: impl LoginId) -> Result<(), SaTokenError>

删除 Session

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

where T: Serialize,

在 Session 中设置值

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

where T: DeserializeOwned,

从 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>, ) -> Result<(), SaTokenError>

为用户添加权限

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

为用户添加单个权限

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

移除用户的某个权限

pub async fn clear_permissions( login_id: impl LoginId, ) -> Result<(), SaTokenError>

清除用户的所有权限

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, ) -> Result<(), SaTokenError>

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

impl StpUtil

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

为用户设置角色

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

为用户添加单个角色

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

移除用户的某个角色

pub async fn clear_roles(login_id: impl LoginId) -> Result<(), SaTokenError>

清除用户的所有角色

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, ) -> Result<(), SaTokenError>

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

impl StpUtil

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

where T: LoginId,

批量踢人下线

pub async fn get_token_timeout( token: &TokenValue, ) -> Result<Option<i64>, SaTokenError>

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

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

续期 token（重置过期时间）

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

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

参数 | Arguments

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

pub async fn get_extra_data( token: &TokenValue, ) -> Result<Option<Value>, SaTokenError>

获取 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?;