mirror of
https://github.com/click33/sa-token-go.git
synced 2025-12-24 13:48:04 +08:00
7.7 KiB
7.7 KiB
English | 中文文档
StpUtil API 文档
概述
StpUtil 是 Sa-Token-Go 的全局工具类，提供了所有核心功能的便捷访问。
初始化
import (
"github.com/click33/sa-token-go/core"
"github.com/click33/sa-token-go/stputil"
"github.com/click33/sa-token-go/storage/memory"
)
func init() {
stputil.SetManager(
core.NewBuilder().
Storage(memory.NewStorage()).
Build(),
)
}
登录认证 API
Login
登录并返回Token
签名：
func Login(loginID interface{}, device ...string) (string, error)
参数：
loginID- 登录ID，支持 int/int64/uint/stringdevice- 可选，设备类型，默认"default"
返回：
string- Token值error- 错误信息
示例：
token, _ := stputil.Login(1000)
token, _ := stputil.Login("user123", "mobile")
IsLogin
检查Token是否有效
签名：
func IsLogin(tokenValue string) bool
参数：
tokenValue- Token值
返回：
bool- true表示已登录
说明：
- 自动触发异步续签（如果开启）
- 检查活跃超时（如果配置）
示例：
if stputil.IsLogin(token) {
// 已登录
}
GetLoginID
获取登录ID
签名：
func GetLoginID(tokenValue string) (string, error)
参数：
tokenValue- Token值
返回：
string- 登录IDerror- 错误信息
示例：
loginID, err := stputil.GetLoginID(token)
Logout
登出
签名：
func Logout(loginID interface{}, device ...string) error
参数：
loginID- 登录IDdevice- 可选，设备类型
示例：
stputil.Logout(1000)
stputil.Logout(1000, "mobile")
Kickout
踢人下线
签名：
func Kickout(loginID interface{}, device ...string) error
参数：
loginID- 登录IDdevice- 可选，设备类型
示例：
stputil.Kickout(1000)
stputil.Kickout(1000, "mobile")
权限验证 API
SetPermissions
设置权限
签名：
func SetPermissions(loginID interface{}, permissions []string) error
参数：
loginID- 登录IDpermissions- 权限列表
示例：
stputil.SetPermissions(1000, []string{
"user:read",
"user:write",
"admin:*",
})
HasPermission
检查是否有指定权限
签名：
func HasPermission(loginID interface{}, permission string) bool
参数：
loginID- 登录IDpermission- 权限字符串
返回：
bool- true表示有权限
示例：
if stputil.HasPermission(1000, "user:read") {
// 有权限
}
HasPermissionsAnd
检查是否拥有所有权限（AND逻辑）
签名：
func HasPermissionsAnd(loginID interface{}, permissions []string) bool
示例：
if stputil.HasPermissionsAnd(1000, []string{"user:read", "user:write"}) {
// 同时拥有两个权限
}
HasPermissionsOr
检查是否拥有任一权限（OR逻辑）
签名：
func HasPermissionsOr(loginID interface{}, permissions []string) bool
示例：
if stputil.HasPermissionsOr(1000, []string{"admin", "super"}) {
// 拥有admin或super权限之一
}
角色管理 API
SetRoles
设置角色
签名：
func SetRoles(loginID interface{}, roles []string) error
示例：
stputil.SetRoles(1000, []string{"admin", "manager"})
HasRole
检查是否有指定角色
签名：
func HasRole(loginID interface{}, role string) bool
示例：
if stputil.HasRole(1000, "admin") {
// 有admin角色
}
HasRolesAnd / HasRolesOr
多角色检查
示例：
// AND逻辑
stputil.HasRolesAnd(1000, []string{"admin", "manager"})
// OR逻辑
stputil.HasRolesOr(1000, []string{"admin", "super"})
账号封禁 API
Disable
封禁账号
签名：
func Disable(loginID interface{}, duration time.Duration) error
参数：
loginID- 登录IDduration- 封禁时长，0表示永久封禁
示例：
stputil.Disable(1000, 1*time.Hour) // 封禁1小时
stputil.Disable(1000, 0) // 永久封禁
IsDisable
检查是否被封禁
签名：
func IsDisable(loginID interface{}) bool
示例：
if stputil.IsDisable(1000) {
// 账号已被封禁
}
Untie
解封账号
签名：
func Untie(loginID interface{}) error
示例：
stputil.Untie(1000)
GetDisableTime
获取剩余封禁时间
签名：
func GetDisableTime(loginID interface{}) (int64, error)
返回：
int64- 剩余秒数，-2表示未封禁
示例：
remaining, _ := stputil.GetDisableTime(1000)
fmt.Printf("剩余封禁时间: %d秒\n", remaining)
Session管理 API
GetSession
获取Session
签名：
func GetSession(loginID interface{}) (*Session, error)
示例：
sess, _ := stputil.GetSession(1000)
// 设置数据
sess.Set("nickname", "张三")
sess.Set("age", 25)
// 读取数据
nickname := sess.GetString("nickname")
age := sess.GetInt("age")
DeleteSession
删除Session
签名：
func DeleteSession(loginID interface{}) error
示例：
stputil.DeleteSession(1000)
高级 API
GetTokenInfo
获取Token详细信息
签名：
func GetTokenInfo(tokenValue string) (*TokenInfo, error)
返回：
type TokenInfo struct {
LoginID string
Device string
CreateTime int64
ActiveTime int64
Tag string
}
示例：
info, _ := stputil.GetTokenInfo(token)
fmt.Printf("登录ID: %s\n", info.LoginID)
fmt.Printf("设备: %s\n", info.Device)
SetTokenTag
设置Token标签
签名：
func SetTokenTag(tokenValue, tag string) error
示例：
stputil.SetTokenTag(token, "admin-panel")
GetTokenValueList
获取账号的所有Token
签名：
func GetTokenValueList(loginID interface{}) ([]string, error)
示例：
tokens, _ := stputil.GetTokenValueList(1000)
fmt.Printf("该账号有 %d 个Token\n", len(tokens))
GetSessionCount
获取账号的Session数量
签名：
func GetSessionCount(loginID interface{}) (int, error)
示例：
count, _ := stputil.GetSessionCount(1000)
fmt.Printf("该账号有 %d 个Session\n", count)
完整方法列表
登录认证
Login- 登录LoginByToken- 使用指定Token登录Logout- 登出LogoutByToken- 根据Token登出IsLogin- 检查登录CheckLogin- 检查登录（抛出错误）GetLoginID- 获取登录IDGetLoginIDNotCheck- 获取登录ID（不检查）GetTokenValue- 获取Token值GetTokenInfo- 获取Token信息
踢人下线
Kickout- 踢人下线
账号封禁
Disable- 封禁账号Untie- 解封账号IsDisable- 检查封禁状态GetDisableTime- 获取剩余封禁时间
Session管理
GetSession- 获取SessionGetSessionByToken- 根据Token获取SessionDeleteSession- 删除Session
权限验证
SetPermissions- 设置权限GetPermissions- 获取权限HasPermission- 检查权限HasPermissionsAnd- AND逻辑HasPermissionsOr- OR逻辑
角色管理
SetRoles- 设置角色GetRoles- 获取角色HasRole- 检查角色HasRolesAnd- AND逻辑HasRolesOr- OR逻辑
Token管理
SetTokenTag- 设置Token标签GetTokenTag- 获取Token标签GetTokenValueList- 获取所有TokenGetSessionCount- 获取Session数量