sa-token

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sa-Token 核心权限认证框架

Sa-Token Core Permission Authentication Framework

基于 Sa-Token v1.45.0 | 官方文档：https://sa-token.cc | GitHub：https://github.com/dromara/sa-token

Sa-Token 是一个轻量级 Java 权限认证框架，核心包零依赖，提供了完整的鉴权体系。

StpUtil

是其核心门面工具类。

Based on Sa-Token v1.45.0 | Official documentation: https://sa-token.cc | GitHub: https://github.com/dromara/sa-token

Sa-Token is a lightweight Java permission authentication framework. Its core package is dependency-free and provides a complete access-control system.

StpUtil

is its core facade utility class.

Capability Boundaries

✅ Strong Suits

✅ Best-Fit Capabilities

登录认证 —
```
StpUtil.login()
```
会话登录、记住我模式、指定设备类型、登录扩展参数

会话校验 —

StpUtil.isLogin()

checkLogin()

getLoginId()

全套查询 API

Token 管理 — 获取 token 值/名称/信息、根据 token 反查账号、token 有效期双策略（timeout + active-timeout）
权限/角色认证 — 实现 StpInterface 定义权限加载器、checkPermission/checkRole 系列 API、权限通配符
```
*
```

注解鉴权 —

@SaCheckLogin

、

@SaCheckPermission

、

@SaCheckRole

、

@SaIgnore

、

@SaCheckOr

路由拦截鉴权 — SaInterceptor + SaRouter 匹配链、stop/back/free 退出机制、多条件匹配
Session 会话 — Account-Session / Token-Session / Custom-Session 三种模型
踢人下线 — 强制注销、踢下线、顶下线三种操作
框架配置 — application.yml 全配置项、代码配置方式
前后端分离 — Cookie 模式 vs Header 模式，小程序/APP 无 Cookie 适配
Token 自定义 — 6 种内置风格、自定义生成策略、Bearer 提交前缀
同端互斥登录 — 同一设备类型仅允许一个在线

Login Authentication —
```
StpUtil.login()
```
supports session login, remember-me mode, specified device types, and extended login parameters
Session Validation — a complete suite of query APIs, including
```
StpUtil.isLogin()
```
/
```
checkLogin()
```
/
```
getLoginId()
```
Token Management — retrieve Token values, names, and information; look up accounts by Token; dual Token expiration strategies (timeout + active-timeout)
Permission/Role Authentication — implement StpInterface to define a permission loader, the checkPermission/checkRole API family, and the permission wildcard
```
*
```

Annotation-Based Authorization —

@SaCheckLogin

@SaCheckPermission

@SaCheckRole

@SaIgnore

@SaCheckOr

Route-Interceptor Authorization — SaInterceptor + SaRouter matching chains, stop/back/free exit mechanisms, and multi-condition matching
Session Management — three models: Account-Session / Token-Session / Custom-Session
Forced Logout — three operations: forced session termination, kickout, and replacement of an existing online session
Framework Configuration — all application.yml options and code-based configuration methods
Frontend-Backend Separation — Cookie mode vs. Header mode, with adaptation for mini programs and apps that do not support Cookies
Token Customization — six built-in styles, custom generation strategies, and Bearer submission prefixes
Mutually Exclusive Login on the Same Device — only one online session is allowed per device type

❌ Out of Scope（替代方案）

❌ Out of Scope (Alternatives)

二级认证/账号封禁/模拟他人/多账号 → sa-token-advanced
SSO 单点登录 → sa-token-sso
OAuth2.0 服务端 → sa-token-oauth2
微服务 Same-Token/网关鉴权 → sa-token-micro
API 签名/API Key/临时 Token → sa-token-api-security
JWT 集成/Redis 持久化/模板引擎 → sa-token-integration

Secondary authentication/account banning/impersonation/multi-account support → sa-token-advanced
SSO single sign-on → sa-token-sso
OAuth2.0 server → sa-token-oauth2
Microservices Same-Token/gateway authorization → sa-token-micro
API signing/API Key/temporary Token → sa-token-api-security
JWT integration/Redis persistence/template engine → sa-token-integration

适用场景

Applicable Scenarios

当用户需要以下场景时，激活此技能：

新项目集成权限认证 — SpringBoot项目引入Sa-Token，配置StpInterface，实现登录/权限校验
现有项目添加鉴权 — 为已有接口添加登录校验/权限校验/角色校验
配置路由拦截器 — 统一拦截所有请求，按模块划分不同鉴权规则
使用注解鉴权 — 使用@SaCheckLogin/@SaCheckPermission等注解
前后端分离适配 — 无Cookie环境下Token的传递与校验
调试与排错 — 排查NotLoginException各类场景值、Token有效期问题

Activate this skill when users need the following:

Permission authentication integration for a new project — add Sa-Token to a Spring Boot project, configure StpInterface, and implement login and permission validation
Add authentication to an existing project — add login validation, permission validation, and role validation to existing APIs
Configure a route interceptor — centrally intercept all requests and apply different authorization rules by module
Use annotation-based authorization — use annotations such as
```
@SaCheckLogin
```
and
```
@SaCheckPermission
```
Frontend-backend separation adaptation — Token transmission and validation in environments without Cookie support
Debugging and troubleshooting — diagnose different NotLoginException scene values and Token expiration issues

Workflow

Step 1. 引入依赖 — 添加

sa-token-spring-boot-starter

依赖（根据SpringBoot版本选择） Step 2. 配置框架 — application.yml 配置 token 名称、有效期、风格等 Step 3. 实现 StpInterface — 自定义权限加载器，返回权限码和角色集合 Step 4. 登录认证 — 调用

StpUtil.login(id)

完成会话登录 Step 5. 权限校验 — 使用 StpUtil 方法或注解进行权限/角色校验 Step 6. 路由拦截 — SaInterceptor + SaRouter 实现全局路由鉴权 Step 7. 集成测试 — 验证登录/注销/权限校验/注解鉴权全流程

Step 1. Add the dependency — add the

sa-token-spring-boot-starter

dependency, selecting the appropriate version for the Spring Boot version Step 2. Configure the framework — configure the Token name, expiration, style, and other options in application.yml Step 3. Implement StpInterface — customize the permission loader to return permission codes and role sets Step 4. Login authentication — call

StpUtil.login(id)

to complete session login Step 5. Permission validation — use StpUtil methods or annotations for permission and role validation Step 6. Route interception — implement global route authorization with SaInterceptor + SaRouter Step 7. Integration testing — verify the complete flow of login/logout, permission validation, and annotation-based authorization

StpUtil 核心 API 速查

StpUtil Core API Quick Reference

java

// === 登录认证 ===
StpUtil.login(Object loginId);                          // 会话登录
StpUtil.login(10001, "PC");                             // 指定设备类型
StpUtil.login(10001, true);                             // 指定记住我
StpUtil.login(10001, new SaLoginParameter()...);        // 完整参数模式
StpUtil.logout();                                       // 当前会话注销
StpUtil.logout(10001);                                  // 指定账号注销
	StpUtil.logoutByTokenValue(token);                      // 指定Token注销
	StpUtil.logoutByLoginId(10001, "PC");                   // 指定账号+设备注销
	StpUtil.kickout(10001);                                 // 踢人下线
	StpUtil.kickoutByTokenValue(token);                     // 根据Token值踢人
StpUtil.isLogin();                                      // 是否登录(true/false)
StpUtil.checkLogin();                                   // 校验登录(未登录抛NotLoginException)

	// === 会话/Token查询 ===
	StpUtil.getLoginId();                                   // 当前账号id
	StpUtil.getLoginIdAsString()/AsInt()/AsLong();          // 类型化获取
	StpUtil.getLoginIdDefaultNull();                        // 未登录返回null
	StpUtil.getLoginIdByToken(token);                       // 根据token查账号
	StpUtil.getTokenValue();                                // 当前token值
	StpUtil.getTokenValueByLoginId(10001);                  // 获取指定账号的token值
	StpUtil.getTokenListByLoginId(10001);                   // 获取指定账号所有token列表
	StpUtil.getTokenName();                                 // token名称(satoken)
	StpUtil.getTokenTimeout();                              // 剩余有效期(秒)
	StpUtil.getTokenInfo();                                 // 完整TokenInfo
	StpUtil.setTokenValue("xxx-xxx");                       // 手动设置当前会话token值
	StpUtil.renewRefresh();                                // 自动续签token有效期
	StpUtil.getTerminalListByLoginId(10001);                // 获取指定账号所有终端列表

	// === 权限/角色校验 ===
	StpUtil.getPermissionList();                            // 权限码集合
	StpUtil.hasPermission("user.add");                     // boolean
	StpUtil.checkPermission("user.add");                   // 失败抛NotPermissionException
	StpUtil.checkPermissionAnd("add","del","get");          // 全部拥有
	StpUtil.checkPermissionOr("add","del","get");          // 至少一个
	StpUtil.hasRole("admin");                               // boolean
	StpUtil.checkRole("admin");                             // 失败抛NotRoleException
	
	// === Session会话 ===
	StpUtil.getSession();                                   // 当前账号Account-Session
	StpUtil.getSessionByLoginId(10001);                     // 指定账号的Session
	StpUtil.getTokenSession();                              // 当前Token-Session
	StpUtil.getTokenSessionByTokenValue("xxx-xxx");        // 按token值获取Token-Session
	SaSessionCustomUtil.getSessionById("goods-10001");     // Custom-Session

java

// === 登录认证 ===
StpUtil.login(Object loginId);                          // 会话登录
StpUtil.login(10001, "PC");                             // 指定设备类型
StpUtil.login(10001, true);                             // 指定记住我
StpUtil.login(10001, new SaLoginParameter()...);        // 完整参数模式
StpUtil.logout();                                       // 当前会话注销
StpUtil.logout(10001);                                  // 指定账号注销
	StpUtil.logoutByTokenValue(token);                      // 指定Token注销
	StpUtil.logoutByLoginId(10001, "PC");                   // 指定账号+设备注销
	StpUtil.kickout(10001);                                 // 踢人下线
	StpUtil.kickoutByTokenValue(token);                     // 根据Token值踢人
StpUtil.isLogin();                                      // 是否登录(true/false)
StpUtil.checkLogin();                                   // 校验登录(未登录抛NotLoginException)

	// === 会话/Token查询 ===
	StpUtil.getLoginId();                                   // 当前账号id
	StpUtil.getLoginIdAsString()/AsInt()/AsLong();          // 类型化获取
	StpUtil.getLoginIdDefaultNull();                        // 未登录返回null
	StpUtil.getLoginIdByToken(token);                       // 根据token查账号
	StpUtil.getTokenValue();                                // 当前token值
	StpUtil.getTokenValueByLoginId(10001);                  // 获取指定账号的token值
	StpUtil.getTokenListByLoginId(10001);                   // 获取指定账号所有token列表
	StpUtil.getTokenName();                                 // token名称(satoken)
	StpUtil.getTokenTimeout();                              // 剩余有效期(秒)
	StpUtil.getTokenInfo();                                 // 完整TokenInfo
	StpUtil.setTokenValue("xxx-xxx");                       // 手动设置当前会话token值
	StpUtil.renewRefresh();                                // 自动续签token有效期
	StpUtil.getTerminalListByLoginId(10001);                // 获取指定账号所有终端列表

	// === 权限/角色校验 ===
	StpUtil.getPermissionList();                            // 权限码集合
	StpUtil.hasPermission("user.add");                     // boolean
	StpUtil.checkPermission("user.add");                   // 失败抛NotPermissionException
	StpUtil.checkPermissionAnd("add","del","get");          // 全部拥有
	StpUtil.checkPermissionOr("add","del","get");          // 至少一个
	StpUtil.hasRole("admin");                               // boolean
	StpUtil.checkRole("admin");                             // 失败抛NotRoleException
	
	// === Session会话 ===
	StpUtil.getSession();                                   // 当前账号Account-Session
	StpUtil.getSessionByLoginId(10001);                     // 指定账号的Session
	StpUtil.getTokenSession();                              // 当前Token-Session
	StpUtil.getTokenSessionByTokenValue("xxx-xxx");        // 按token值获取Token-Session
	SaSessionCustomUtil.getSessionById("goods-10001");     // Custom-Session

参考文档

Reference Documentation

主题	文件	来源
登录认证完整指南	references/login-auth.md	GitHub
权限/角色认证	references/jur-auth.md	GitHub
注解鉴权	references/at-check.md	GitHub
路由拦截鉴权	references/route-check.md	GitHub
Session 会话	references/session.md	GitHub
框架配置	references/config.md	GitHub
踢人下线	references/kickout.md	GitHub
Token 有效期	references/token-timeout.md	GitHub
NotLoginException	references/not-login-scene.md	GitHub
前后端分离 & 记住我	references/not-cookie.md	GitHub、remember-me
Token 风格 & 前缀	references/token-style.md	GitHub、token-prefix
登录参数详解	references/login-parameter.md	GitHub
同端互斥登录	references/mutex-login.md	GitHub
快速入门	examples/quickstart.md	GitHub

Topic	File	Source
Complete Login Authentication Guide	references/login-auth.md	GitHub
Permission/Role Authentication	references/jur-auth.md	GitHub
Annotation-Based Authorization	references/at-check.md	GitHub
Route-Interceptor Authorization	references/route-check.md	GitHub
Session Management	references/session.md	GitHub
Framework Configuration	references/config.md	GitHub
Forced Logout	references/kickout.md	GitHub
Token Expiration	references/token-timeout.md	GitHub
NotLoginException	references/not-login-scene.md	GitHub
Frontend-Backend Separation & Remember Me	references/not-cookie.md	GitHub, remember-me
Token Style & Prefix	references/token-style.md	GitHub, token-prefix
Login Parameter Details	references/login-parameter.md	GitHub
Mutually Exclusive Login on the Same Device	references/mutex-login.md	GitHub
Quick Start	examples/quickstart.md	GitHub

Gotchas

StpInterface 不会在启动时执行 — 只在调用鉴权方法时触发查询
注解鉴权默认关闭 — 必须手动注册
```
SaInterceptor
```
SaSession ≠ HttpSession — 两者无任何关系，不要混淆使用
前端鉴权只是辅助 — 不能替代后端校验
@SaIgnore
只对 SaInterceptor 和 AOP 生效 — 自定义拦截器不受影响
@SaCheckPermission
默认 AND 模式 — OR 模式需指定
```
mode = SaMode.OR
```
StpUtil.logout()
注销范围可通过
logout-range
配置 — 默认只注销当前 token
Cookie 模式默认注入 Cookie — 关闭可用
```
is-read-cookie: false
```

StpInterface is not executed at startup — queries are triggered only when an authorization method is called
Annotation-based authorization is disabled by default —
```
SaInterceptor
```
must be registered manually
SaSession ≠ HttpSession — the two are completely unrelated and should not be confused
Frontend authorization is only supplementary — it cannot replace backend validation
@SaIgnore
only applies to SaInterceptor and AOP — custom interceptors are unaffected
@SaCheckPermission
uses AND mode by default — OR mode requires
```
mode = SaMode.OR
```
The logout scope of
StpUtil.logout()
can be configured through
logout-range
— by default, only the current Token is logged out
Cookie mode injects a Cookie by default — it can be disabled with
```
is-read-cookie: false
```

Data Privacy

本技能不收集、存储或传输任何用户数据。

This skill does not collect, store, or transmit any user data.