Struct SaTokenConfigBuilder 

pub struct SaTokenConfigBuilder { /* private fields */ }

配置构建器 | Configuration builder

Implementations

impl SaTokenConfigBuilder

pub fn token_name(self, name: impl Into<String>) -> Self

设置 Token 名称 | Set the token name

pub fn timeout(self, timeout: i64) -> Self

设置 Token 有效期（秒）| Set token lifetime in seconds

pub fn active_timeout(self, timeout: i64) -> Self

设置最低活跃频率（秒）| Set the minimum activity interval in seconds

pub fn dynamic_active_timeout(self, enabled: bool) -> Self

设置是否启用 per-token 动态 active_timeout Enable or disable per-token dynamic active_timeout

pub fn auto_renew(self, enabled: bool) -> Self

设置是否开启自动续签 | Enable or disable auto-renewal

pub fn renew_threshold(self, seconds: i64) -> Self

设置续签阈值（秒）。传入负值等价于关闭阈值（每次读取都续签）。 Set the renewal threshold in seconds. A negative value disables the threshold, restoring the legacy “renew on every read” behaviour.

pub fn is_concurrent(self, concurrent: bool) -> Self

设置是否允许并发登录 | Enable or disable concurrent logins

pub fn is_share(self, share: bool) -> Self

设置是否共享 token | Enable or disable shared tokens across concurrent logins

pub fn token_style(self, style: TokenStyle) -> Self

设置 Token 风格 | Set the token generation style

pub fn is_log(self, enabled: bool) -> Self

Emit operation logs at info level when true. 为 true 时在 info 级别输出操作日志。

pub fn is_read_header(self, enabled: bool) -> Self

Read token from headers (including Authorization fallback). 是否从请求头读取 token（含 Authorization 回退）。

pub fn is_read_cookie(self, enabled: bool) -> Self

Read token from cookies. 是否从 Cookie 读取 token。

pub fn is_read_body(self, enabled: bool) -> Self

Read token from query/param (is_read_body name kept for compatibility). 是否从 query/param 读取 token（字段名 is_read_body 保持兼容）。

pub fn token_prefix(self, prefix: impl Into<String>) -> Self

Custom token prefix; empty string is rejected at build time. 自定义 token 前缀；空字符串在构建时拒绝。

pub fn is_write_cookie(self, write: bool) -> Self

Opt-in cookie write for handlers using write_token_cookie (default false). Handler 调用 write_token_cookie 时是否真正写入 Cookie（默认 false）。

pub fn cookie_domain(self, domain: impl Into<String>) -> Self

Cookie Domain attribute. Cookie 的 Domain 属性。

pub fn cookie_path(self, path: impl Into<String>) -> Self

Cookie Path attribute. Cookie 的 Path 属性。

pub fn cookie_http_only(self, http_only: bool) -> Self

Cookie HttpOnly flag. Cookie 的 HttpOnly 标志。

pub fn cookie_secure(self, secure: bool) -> Self

Cookie Secure flag. Cookie 的 Secure 标志。

pub fn cookie_same_site(self, same_site: SameSite) -> Self

Cookie SameSite attribute. Cookie 的 SameSite 属性。

pub fn storage_key_prefix(self, prefix: impl Into<String>) -> Self

设置存储键前缀（默认 "sa:"）。 此前缀用于 Redis / 数据库等存储后端的键命名。

Set the storage key prefix (default "sa:"). Used when naming keys in Redis/DB backends.

pub fn key_layout(self, layout: SaKeyLayout) -> Self

设置存储键布局（A3-1）| Set the storage key layout (A3-1)

pub fn jwt_secret_key(self, key: impl Into<String>) -> Self

设置 JWT 密钥 | Set the JWT secret key

pub fn jwt_algorithm(self, algorithm: impl Into<String>) -> Self

设置 JWT 算法 | Set the JWT algorithm

pub fn jwt_issuer(self, issuer: impl Into<String>) -> Self

设置 JWT 签发者 | Set the JWT issuer

pub fn jwt_audience(self, audience: impl Into<String>) -> Self

设置 JWT 受众 | Set the JWT audience

pub fn jwt_fallback_on_error(self, fallback: bool) -> Self

设置 JWT 失败时是否回退 UUID | Enable or disable UUID fallback on JWT failure

pub fn enable_nonce(self, enable: bool) -> Self

启用防重放攻击（nonce 机制）| Enable anti-replay protection via nonce

pub fn nonce_timeout(self, timeout: i64) -> Self

设置 Nonce 有效期（秒）| Set the nonce lifetime in seconds

pub fn enable_refresh_token(self, enable: bool) -> Self

启用 Refresh Token | Enable refresh tokens

pub fn refresh_token_timeout(self, timeout: i64) -> Self

设置 Refresh Token 有效期（秒）| Set the refresh-token lifetime in seconds

pub fn max_login_count(self, count: i64) -> Self

设置同一账号最大登录数量 | Set max concurrent logins per account

pub fn overflow_logout_mode(self, mode: LogoutMode) -> Self

设置超出最大登录数时的下线模式 | Set the overflow logout mode

pub fn replaced_login_exit_mode(self, mode: ReplacedLoginExitMode) -> Self

设置非并发顶号退出策略 | Set the non-concurrent replace exit mode

pub fn replaced_range(self, range: ReplacedRange) -> Self

设置顶号范围 | Set the replace scope

pub fn right_now_create_token_session(self, enabled: bool) -> Self

设置登录时是否立即创建 Token-Session Enable or disable creating a Token-Session immediately on login

pub fn token_session_check_login(self, enabled: bool) -> Self

设置获取 Token-Session 时是否校验登录态 Enable or disable login check when fetching a Token-Session

pub fn logout_range(self, range: LogoutRange) -> Self

设置默认 logout 范围 | Set the default logout range

pub fn is_logout_keep_token_session(self, keep: bool) -> Self

设置 logout 时是否保留 Token-Session Enable or disable keeping the Token-Session on logout

pub fn grant_cache_ttl(self, seconds: i64) -> Self

设置权限/角色缓存 TTL（秒）。<= 0 关闭缓存。 Sets the permission/role cache TTL in seconds; <= 0 disables it.

pub fn grant_cache_max_entries(self, max: usize) -> Self

设置缓存条目上限（跨全部分片的总量）。 Sets the total cache capacity across all shards.

pub fn grant_cache_single_flight(self, enabled: bool) -> Self

开关单飞（并发未命中合并为一次底层加载）。 Toggles single-flight loading for concurrent cache misses.

pub fn grant_request_scope(self, enabled: bool) -> Self

开关请求级授权快照。 Toggles the per-request authorization snapshot.

pub fn grant_write_policy(self, policy: GrantWritePolicy) -> Self

设置只读 StpInterface 下的写策略。 Sets the write policy used with a read-only StpInterface.

pub fn role_wildcard(self, enabled: bool) -> Self

Toggle role wildcard matching (default: exact). 开关角色通配符匹配（默认精确匹配）。

pub fn context_auto_create(self, enable: bool) -> Self

设置 context_auto_create Set whether with_current_mut should auto-create an empty context.

pub fn http_basic(self, account: impl Into<String>) -> Self

HTTP Basic account (user:password) HTTP Basic 账号（user:password）

pub fn same_token_timeout(self, timeout: i64) -> Self

Same-Token TTL in seconds Same-Token 有效期（秒）

pub fn same_token_header(self, name: impl Into<String>) -> Self

Same-Token header name Same-Token 请求头名

pub fn max_try_times(self, n: i32) -> Self

Max attempts when allocating a unique login / temp token (-1 = no retry). 分配唯一登录/临时 token 的最大尝试次数（-1 表示不重试）。

pub fn sign_secret_key(self, key: impl Into<String>) -> Self

HMAC secret for RequestSign via StpUtil (independent from JWT). StpUtil 使用的 HMAC 密钥（与 JWT 密钥分离）。

pub fn sign_window_secs(self, secs: i64) -> Self

Timestamp window in seconds for RequestSign. RequestSign 的时间窗（秒）。

pub fn serializer(self, serializer: SharedSerializer) -> Self

设置存储层序列化器（默认 JSON） Set the storage serializer (JSON by default)

pub fn storage(self, storage: Arc<dyn SaStorage>) -> Self

设置存储适配器 | Set the storage adapter

pub fn event_bus(self, bus: SaTokenEventBus) -> Self

注入共享事件总线；未设置时 Manager::new 内部创建默认 bus

Injects a shared event bus; if not set, Manager::new creates a default bus internally.

pub fn register_listener(self, listener: Arc<dyn SaTokenListener>) -> Self

注册事件监听器（可多次调用以注册多个）。 Register an event listener (call multiple times for multiple listeners).

示例 | Example

use std::sync::Arc;
use sa_token_core::{SaTokenConfig, SaTokenListener};

struct MyListener;
impl SaTokenListener for MyListener { /* ... */ }

let manager = SaTokenConfig::builder()
    .storage(Arc::new(MemoryStorage::new()))
    .register_listener(Arc::new(MyListener))
    .build();

pub fn build(self) -> SaTokenManager

构建 SaTokenManager（需先设置 storage）。

自动完成：

1. 创建 SaTokenManager
2. 注册所有事件监听器
3. 初始化 StpUtil

Build a SaTokenManager (storage must be set first).

Automatically:

1. Creates SaTokenManager
2. Registers all event listeners
3. Initializes StpUtil

Panics

未设置 storage 时 panic。 Panics if storage was not set.

示例 | Example

use std::sync::Arc;
use sa_token_core::SaTokenConfig;
use sa_token_storage_memory::MemoryStorage;

// 一行完成初始化 | Complete initialization in one line
SaTokenConfig::builder()
    .storage(Arc::new(MemoryStorage::new()))
    .timeout(7200)
    .register_listener(Arc::new(MyListener))
    .build();

pub fn try_build(self) -> SaTokenResult<SaTokenManager>

Build Manager; JWT misconfig returns Err instead of panicking later. 构造 Manager；JWT 配错在此处返回 Err，而不是延后 panic。

pub fn build_manager_only(self) -> SaTokenManager

仅构造 Manager：注册监听器 / 注入 EventBus，不写入全局 StpUtil。 Construct Manager only: listeners + event bus; do not touch global StpUtil.

pub fn build_config(self) -> SaTokenConfig

仅构建配置（不创建 Manager） Build the config only (without creating a Manager)

pub fn try_build_config(self) -> SaTokenResult<SaTokenConfig>

Build config after JWT validation (does not construct Manager). 校验 JWT 后只构建配置（不构造 Manager）。

Trait Implementations

impl Debug for SaTokenConfigBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SaTokenConfigBuilder

fn default() -> SaTokenConfigBuilder

Returns the “default value” for a type.