mirror of
https://github.com/click33/sa-token-go.git
synced 2026-04-23 01:47:06 +08:00
chore: update README files for version 0.1.1, enhance documentation, and improve examples for better clarity
This commit is contained in:
Moling
+293
-350
@@ -2,7 +2,7 @@
|
||||
|
||||
**中文文档** | **[English](README.md)**
|
||||
|
||||
[]()
|
||||
[](https://img.shields.io)
|
||||
[](https://opensource.org/licenses/Apache-2.0)
|
||||
|
||||
一个轻量级、高性能的 Go 权限认证框架，参考 [sa-token](https://github.com/dromara/sa-token) 设计。
|
||||
@@ -24,78 +24,9 @@
|
||||
- 🔄 **Refresh Token** - 刷新令牌机制、无感刷新
|
||||
- 🔐 **OAuth2** - 完整的OAuth2授权码模式实现
|
||||
|
||||
## 🎨 Token 风格
|
||||
|
||||
Sa-Token-Go 支持 9 种 Token 生成风格：
|
||||
|
||||
| 风格 | 格式示例 | 长度 | 适用场景 |
|
||||
|------|----------|------|----------|
|
||||
| **UUID** | `550e8400-e29b-41d4-...` | 36 | 通用场景 |
|
||||
| **Simple** | `aB3dE5fG7hI9jK1l` | 16 | 紧凑型Token |
|
||||
| **Random32/64/128** | 随机字符串 | 32/64/128 | 高安全性 |
|
||||
| **JWT** | `eyJhbGciOiJIUzI1...` | 可变 | 无状态认证 |
|
||||
| **Hash** 🆕 | `a3f5d8b2c1e4f6a9...` | 64 | SHA256哈希 |
|
||||
| **Timestamp** 🆕 | `1700000000123_user1000_...` | 可变 | 可追溯时间 |
|
||||
| **Tik** 🆕 | `7Kx9mN2pQr4` | 11 | 短ID（类似抖音） |
|
||||
|
||||
[👉 查看 Token 风格示例](examples/token-styles/)
|
||||
|
||||
## 🔒 安全特性
|
||||
|
||||
### Nonce 防重放攻击
|
||||
|
||||
```go
|
||||
// 生成nonce
|
||||
nonce, _ := stputil.GenerateNonce()
|
||||
|
||||
// 验证nonce（一次性使用）
|
||||
valid := stputil.VerifyNonce(nonce) // true
|
||||
valid = stputil.VerifyNonce(nonce) // false（防止重放）
|
||||
```
|
||||
|
||||
### Refresh Token 刷新机制
|
||||
|
||||
```go
|
||||
// 登录获取访问令牌和刷新令牌
|
||||
tokenInfo, _ := stputil.LoginWithRefreshToken(1000, "web")
|
||||
fmt.Println("Access Token:", tokenInfo.AccessToken)
|
||||
fmt.Println("Refresh Token:", tokenInfo.RefreshToken)
|
||||
|
||||
// 刷新访问令牌
|
||||
newInfo, _ := stputil.RefreshAccessToken(tokenInfo.RefreshToken)
|
||||
```
|
||||
|
||||
### OAuth2 授权码模式
|
||||
|
||||
```go
|
||||
// 创建OAuth2服务器
|
||||
oauth2Server := stputil.GetOAuth2Server()
|
||||
|
||||
// 注册客户端
|
||||
oauth2Server.RegisterClient(&core.OAuth2Client{
|
||||
ClientID: "webapp",
|
||||
ClientSecret: "secret123",
|
||||
RedirectURIs: []string{"http://localhost:8080/callback"},
|
||||
GrantTypes: []core.OAuth2GrantType{core.GrantTypeAuthorizationCode},
|
||||
Scopes: []string{"read", "write"},
|
||||
})
|
||||
|
||||
// 生成授权码
|
||||
authCode, _ := oauth2Server.GenerateAuthorizationCode(
|
||||
"webapp", "http://localhost:8080/callback", "user123", []string{"read"},
|
||||
)
|
||||
|
||||
// 用授权码换取访问令牌
|
||||
accessToken, _ := oauth2Server.ExchangeCodeForToken(
|
||||
authCode.Code, "webapp", "secret123", "http://localhost:8080/callback",
|
||||
)
|
||||
```
|
||||
|
||||
[👉 查看 OAuth2 完整示例](examples/oauth2-example/)
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 安装
|
||||
### 📥 安装
|
||||
|
||||
#### 方式一：简化导入（推荐）✨
|
||||
|
||||
@@ -103,38 +34,38 @@ accessToken, _ := oauth2Server.ExchangeCodeForToken(
|
||||
|
||||
```bash
|
||||
# 只导入框架集成包（自动包含 core + stputil）
|
||||
go get github.com/click33/sa-token-go/integrations/gin@v0.1.0 # Gin框架
|
||||
go get github.com/click33/sa-token-go/integrations/gin@v0.1.1 # Gin框架
|
||||
# 或
|
||||
go get github.com/click33/sa-token-go/integrations/echo@v0.1.0 # Echo框架
|
||||
go get github.com/click33/sa-token-go/integrations/echo@v0.1.1 # Echo框架
|
||||
# 或
|
||||
go get github.com/click33/sa-token-go/integrations/fiber@v0.1.0 # Fiber框架
|
||||
go get github.com/click33/sa-token-go/integrations/fiber@v0.1.1 # Fiber框架
|
||||
# 或
|
||||
go get github.com/click33/sa-token-go/integrations/chi@v0.1.0 # Chi框架
|
||||
go get github.com/click33/sa-token-go/integrations/chi@v0.1.1 # Chi框架
|
||||
|
||||
# 存储模块（选一个）
|
||||
go get github.com/click33/sa-token-go/storage/memory@v0.1.0 # 内存存储（开发）
|
||||
go get github.com/click33/sa-token-go/storage/redis@v0.1.0 # Redis存储（生产）
|
||||
go get github.com/click33/sa-token-go/storage/memory@v0.1.1 # 内存存储（开发）
|
||||
go get github.com/click33/sa-token-go/storage/redis@v0.1.1 # Redis存储（生产）
|
||||
```
|
||||
|
||||
#### 方式二：分开导入
|
||||
|
||||
```bash
|
||||
# 核心模块
|
||||
go get github.com/click33/sa-token-go/core@v0.1.0
|
||||
go get github.com/click33/sa-token-go/stputil@v0.1.0
|
||||
go get github.com/click33/sa-token-go/core@v0.1.1
|
||||
go get github.com/click33/sa-token-go/stputil@v0.1.1
|
||||
|
||||
# 存储模块（选一个）
|
||||
go get github.com/click33/sa-token-go/storage/memory@v0.1.0 # 内存存储（开发）
|
||||
go get github.com/click33/sa-token-go/storage/redis@v0.1.0 # Redis存储（生产）
|
||||
go get github.com/click33/sa-token-go/storage/memory@v0.1.1 # 内存存储（开发）
|
||||
go get github.com/click33/sa-token-go/storage/redis@v0.1.1 # Redis存储（生产）
|
||||
|
||||
# 框架集成（可选）
|
||||
go get github.com/click33/sa-token-go/integrations/gin@v0.1.0 # Gin框架
|
||||
go get github.com/click33/sa-token-go/integrations/echo@v0.1.0 # Echo框架
|
||||
go get github.com/click33/sa-token-go/integrations/fiber@v0.1.0 # Fiber框架
|
||||
go get github.com/click33/sa-token-go/integrations/chi@v0.1.0 # Chi框架
|
||||
go get github.com/click33/sa-token-go/integrations/gin@v0.1.1 # Gin框架
|
||||
go get github.com/click33/sa-token-go/integrations/echo@v0.1.1 # Echo框架
|
||||
go get github.com/click33/sa-token-go/integrations/fiber@v0.1.1 # Fiber框架
|
||||
go get github.com/click33/sa-token-go/integrations/chi@v0.1.1 # Chi框架
|
||||
```
|
||||
|
||||
### 超简洁使用（一行初始化）
|
||||
### ⚡ 超简洁使用（一行初始化）
|
||||
|
||||
```go
|
||||
package main
|
||||
@@ -160,6 +91,7 @@ func init() {
|
||||
```
|
||||
|
||||
**启动时会显示 Banner：**
|
||||
|
||||
```
|
||||
_____ ______ __ ______
|
||||
/ ___/____ _ /_ __/___ / /_____ ____ / ____/____
|
||||
@@ -167,9 +99,9 @@ func init() {
|
||||
___/ / /_/ / / / / /_/ / ,< / __/ / / /_____/ /_/ / /_/ /
|
||||
/____/\__,_/ /_/ \____/_/|_|\___/_/ /_/ \____/\____/
|
||||
|
||||
:: Sa-Token-Go :: (v0.1.0)
|
||||
:: Sa-Token-Go :: (v0.1.1)
|
||||
:: Go Version :: go1.21.0
|
||||
:: GOOS/GOARCH :: darwin/arm64
|
||||
:: GOOS/GOARCH :: linux/amd64
|
||||
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Token Style : random64 │
|
||||
@@ -178,6 +110,7 @@ func init() {
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
```go
|
||||
func main() {
|
||||
// 🚀 直接使用 StpUtil，无需传递manager
|
||||
token, _ := stputil.Login(1000)
|
||||
@@ -196,7 +129,107 @@ func main() {
|
||||
}
|
||||
```
|
||||
|
||||
### Gin框架集成（单一导入）✨
|
||||
## 🔧 核心API
|
||||
|
||||
### 🔑 登录认证
|
||||
|
||||
```go
|
||||
// 登录（支持 int, int64, uint, string）
|
||||
token, _ := stputil.Login(1000)
|
||||
token, _ := stputil.Login("user123")
|
||||
token, _ := stputil.Login(1000, "mobile") // 指定设备
|
||||
|
||||
// 检查登录（自动异步续签）
|
||||
isLogin := stputil.IsLogin(token)
|
||||
|
||||
// 获取登录ID
|
||||
loginID, _ := stputil.GetLoginID(token)
|
||||
|
||||
// 登出
|
||||
stputil.Logout(1000)
|
||||
stputil.LogoutByToken(token)
|
||||
|
||||
// 踢人下线
|
||||
stputil.Kickout(1000)
|
||||
stputil.Kickout(1000, "mobile")
|
||||
```
|
||||
|
||||
### 🛡️ 权限验证
|
||||
|
||||
```go
|
||||
// 设置权限
|
||||
stputil.SetPermissions(1000, []string{
|
||||
"user:read",
|
||||
"user:write",
|
||||
"admin:*", // 通配符：匹配所有admin权限
|
||||
})
|
||||
|
||||
// 检查权限
|
||||
hasPermission := stputil.HasPermission(1000, "user:read")
|
||||
hasPermission := stputil.HasPermission(1000, "admin:delete") // 通配符匹配
|
||||
|
||||
// 多权限检查
|
||||
hasAll := stputil.HasPermissionsAnd(1000, []string{"user:read", "user:write"}) // AND逻辑
|
||||
hasAny := stputil.HasPermissionsOr(1000, []string{"admin", "super"}) // OR逻辑
|
||||
```
|
||||
|
||||
### 👥 角色管理
|
||||
|
||||
```go
|
||||
// 设置角色
|
||||
stputil.SetRoles(1000, []string{"admin", "manager"})
|
||||
|
||||
// 检查角色
|
||||
hasRole := stputil.HasRole(1000, "admin")
|
||||
|
||||
// 多角色检查
|
||||
hasAll := stputil.HasRolesAnd(1000, []string{"admin", "manager"})
|
||||
hasAny := stputil.HasRolesOr(1000, []string{"admin", "super"})
|
||||
```
|
||||
|
||||
### 💾 Session管理
|
||||
|
||||
```go
|
||||
// 获取Session
|
||||
sess, _ := stputil.GetSession(1000)
|
||||
|
||||
// 设置数据
|
||||
sess.Set("nickname", "张三")
|
||||
sess.Set("age", 25)
|
||||
|
||||
// 读取数据
|
||||
nickname := sess.GetString("nickname")
|
||||
age := sess.GetInt("age")
|
||||
|
||||
// 删除数据
|
||||
sess.Delete("nickname")
|
||||
|
||||
// 删除Session
|
||||
stputil.DeleteSession(1000)
|
||||
```
|
||||
|
||||
### 🚫 账号封禁
|
||||
|
||||
```go
|
||||
// 封禁1小时
|
||||
stputil.Disable(1000, 1*time.Hour)
|
||||
|
||||
// 永久封禁
|
||||
stputil.Disable(1000, 0)
|
||||
|
||||
// 解封
|
||||
stputil.Untie(1000)
|
||||
|
||||
// 检查是否被封禁
|
||||
isDisabled := stputil.IsDisable(1000)
|
||||
|
||||
// 获取剩余封禁时间
|
||||
remainingTime, _ := stputil.GetDisableTime(1000)
|
||||
```
|
||||
|
||||
## 🌐 框架集成
|
||||
|
||||
### 🌟 Gin 集成（单一导入）
|
||||
|
||||
**新方式：只导入 `integrations/gin` 即可使用所有功能！**
|
||||
|
||||
@@ -234,83 +267,158 @@ func main() {
|
||||
}
|
||||
```
|
||||
|
||||
## 📦 项目结构
|
||||
### 🎯 注解装饰器支持
|
||||
|
||||
```
|
||||
sa-token-go/
|
||||
├── core/ # 🔴 核心模块（必需）
|
||||
│ ├── adapter/ # 适配器接口
|
||||
│ │ ├── storage.go # 存储接口
|
||||
│ │ └── context.go # 请求上下文接口
|
||||
│ ├── manager/ # 认证管理器
|
||||
│ ├── builder/ # Builder构建器
|
||||
│ ├── session/ # Session管理
|
||||
│ ├── token/ # Token生成器（支持JWT）
|
||||
│ ├── listener/ # 事件监听系统
|
||||
│ ├── banner/ # 启动Banner
|
||||
│ ├── config/ # 配置定义
|
||||
│ ├── context/ # Sa-Token上下文
|
||||
│ ├── utils/ # 工具函数
|
||||
│ ├── errors.go # 错误定义
|
||||
│ └── satoken.go # 核心导出
|
||||
│
|
||||
├── stputil/ # 🔧 全局工具类（推荐）
|
||||
│ └── stputil.go # StpUtil.Login(), StpUtil.Logout()...
|
||||
│
|
||||
├── storage/ # 💾 存储后端
|
||||
│ ├── memory/ # 内存存储（开发环境）
|
||||
│ │ └── memory.go
|
||||
│ └── redis/ # Redis存储（生产环境）
|
||||
│ └── redis.go
|
||||
│
|
||||
├── integrations/ # 🌐 框架集成
|
||||
│ ├── gin/ # Gin框架（包含注解）
|
||||
│ │ ├── context.go
|
||||
│ │ ├── plugin.go
|
||||
│ │ └── annotation.go
|
||||
│ ├── echo/ # Echo框架
|
||||
│ │ ├── context.go
|
||||
│ │ └── plugin.go
|
||||
│ ├── fiber/ # Fiber框架
|
||||
│ │ ├── context.go
|
||||
│ │ └── plugin.go
|
||||
│ └── chi/ # Chi框架
|
||||
│ ├── context.go
|
||||
│ └── plugin.go
|
||||
│
|
||||
├── examples/ # 📚 示例项目
|
||||
│ ├── quick-start/
|
||||
│ │ └── simple-example/ # ⚡ 快速开始
|
||||
│ ├── annotation/
|
||||
│ │ └── annotation-example/ # 🎨 注解使用
|
||||
│ ├── jwt-example/ # 🔑 JWT Token示例
|
||||
│ ├── redis-example/ # 💾 Redis存储示例
|
||||
│ ├── listener-example/ # 🎧 事件监听示例
|
||||
│ ├── gin/gin-example/ # Gin集成示例
|
||||
│ ├── echo/echo-example/ # Echo集成示例
|
||||
│ ├── fiber/fiber-example/ # Fiber集成示例
|
||||
│ └── chi/chi-example/ # Chi集成示例
|
||||
│
|
||||
├── docs/ # 📖 文档
|
||||
│ ├── tutorial/ # 教程
|
||||
│ │ └── quick-start.md
|
||||
│ ├── guide/ # 指南
|
||||
│ │ ├── authentication.md
|
||||
│ │ ├── permission.md
|
||||
│ │ ├── annotation.md
|
||||
│ │ ├── listener.md
|
||||
│ │ ├── jwt.md
|
||||
│ │ ├── redis-storage.md # 英文
|
||||
│ │ └── redis-storage_zh.md # 中文
|
||||
│ ├── api/ # API文档
|
||||
│ └── design/ # 设计文档
|
||||
│
|
||||
├── go.work # Go工作区
|
||||
├── README.md # 英文README
|
||||
└── README_zh.md # 中文README
|
||||
**支持的注解：**
|
||||
|
||||
| 注解 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `@SaIgnore` | 忽略认证 | `sagin.Ignore()` |
|
||||
| `@SaCheckLogin` | 检查登录 | `sagin.CheckLogin()` |
|
||||
| `@SaCheckRole` | 检查角色 | `sagin.CheckRole("admin")` |
|
||||
| `@SaCheckPermission` | 检查权限 | `sagin.CheckPermission("admin:*")` |
|
||||
| `@SaCheckDisable` | 检查封禁 | `sagin.CheckDisable()` |
|
||||
|
||||
**使用示例：**
|
||||
|
||||
```go
|
||||
import sagin "github.com/click33/sa-token-go/integrations/gin"
|
||||
|
||||
func main() {
|
||||
r := gin.Default()
|
||||
|
||||
// 公开访问 - 忽略认证
|
||||
r.GET("/public", sagin.Ignore(), publicHandler)
|
||||
|
||||
// 需要登录
|
||||
r.GET("/user/info", sagin.CheckLogin(), userInfoHandler)
|
||||
|
||||
// 需要管理员权限
|
||||
r.GET("/admin", sagin.CheckPermission("admin:*"), adminHandler)
|
||||
|
||||
// 需要多个权限之一（OR逻辑）
|
||||
r.GET("/user-or-admin",
|
||||
sagin.CheckPermission("user:read", "admin:*"),
|
||||
userOrAdminHandler)
|
||||
|
||||
// 需要管理员角色
|
||||
r.GET("/manager", sagin.CheckRole("admin"), managerHandler)
|
||||
|
||||
// 检查账号是否被封禁
|
||||
r.GET("/sensitive", sagin.CheckDisable(), sensitiveHandler)
|
||||
|
||||
r.Run(":8080")
|
||||
}
|
||||
```
|
||||
|
||||
## 🎧 事件监听
|
||||
### 🔌 其他框架集成
|
||||
|
||||
**Echo / Fiber / Chi** 同样支持注解装饰器：
|
||||
|
||||
```go
|
||||
// Echo
|
||||
import saecho "github.com/click33/sa-token-go/integrations/echo"
|
||||
e.GET("/user", saecho.CheckLogin(), handler)
|
||||
|
||||
// Fiber
|
||||
import safiber "github.com/click33/sa-token-go/integrations/fiber"
|
||||
app.Get("/user", safiber.CheckLogin(), handler)
|
||||
|
||||
// Chi
|
||||
import sachi "github.com/click33/sa-token-go/integrations/chi"
|
||||
r.Get("/user", sachi.CheckLogin(), handler)
|
||||
```
|
||||
|
||||
## 🎨 高级特性
|
||||
|
||||
### 🎨 Token 风格
|
||||
|
||||
Sa-Token-Go 支持 9 种 Token 生成风格：
|
||||
|
||||
| 风格 | 格式示例 | 长度 | 适用场景 |
|
||||
|------|----------|------|----------|
|
||||
| **UUID** | `550e8400-e29b-41d4-...` | 36 | 通用场景 |
|
||||
| **Simple** | `aB3dE5fG7hI9jK1l` | 16 | 紧凑型Token |
|
||||
| **Random32/64/128** | 随机字符串 | 32/64/128 | 高安全性 |
|
||||
| **JWT** | `eyJhbGciOiJIUzI1...` | 可变 | 无状态认证 |
|
||||
| **Hash** 🆕 | `a3f5d8b2c1e4f6a9...` | 64 | SHA256哈希 |
|
||||
| **Timestamp** 🆕 | `1700000000123_user1000_...` | 可变 | 可追溯时间 |
|
||||
| **Tik** 🆕 | `7Kx9mN2pQr4` | 11 | 短ID（类似抖音） |
|
||||
|
||||
**JWT Token 支持：**
|
||||
|
||||
```go
|
||||
// 使用 JWT Token
|
||||
stputil.SetManager(
|
||||
core.NewBuilder().
|
||||
Storage(memory.NewStorage()).
|
||||
TokenStyle(core.TokenStyleJWT). // 使用 JWT
|
||||
JwtSecretKey("your-256-bit-secret"). // JWT 密钥
|
||||
Timeout(3600). // 1小时过期
|
||||
Build(),
|
||||
)
|
||||
|
||||
// 登录后获得 JWT Token
|
||||
token, _ := stputil.Login(1000)
|
||||
// 返回格式：eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
[👉 查看 Token 风格示例](examples/token-styles/)
|
||||
|
||||
### 🔒 安全特性
|
||||
|
||||
#### 🔐 Nonce 防重放攻击
|
||||
|
||||
```go
|
||||
// 生成nonce
|
||||
nonce, _ := stputil.GenerateNonce()
|
||||
|
||||
// 验证nonce（一次性使用）
|
||||
valid := stputil.VerifyNonce(nonce) // true
|
||||
valid = stputil.VerifyNonce(nonce) // false（防止重放）
|
||||
```
|
||||
|
||||
#### 🔄 Refresh Token 刷新机制
|
||||
|
||||
```go
|
||||
// 登录获取访问令牌和刷新令牌
|
||||
tokenInfo, _ := stputil.LoginWithRefreshToken(1000, "web")
|
||||
fmt.Println("Access Token:", tokenInfo.AccessToken)
|
||||
fmt.Println("Refresh Token:", tokenInfo.RefreshToken)
|
||||
|
||||
// 刷新访问令牌
|
||||
newInfo, _ := stputil.RefreshAccessToken(tokenInfo.RefreshToken)
|
||||
```
|
||||
|
||||
#### 🔑 OAuth2 授权码模式
|
||||
|
||||
```go
|
||||
// 创建OAuth2服务器
|
||||
oauth2Server := stputil.GetOAuth2Server()
|
||||
|
||||
// 注册客户端
|
||||
oauth2Server.RegisterClient(&core.OAuth2Client{
|
||||
ClientID: "webapp",
|
||||
ClientSecret: "secret123",
|
||||
RedirectURIs: []string{"http://localhost:8080/callback"},
|
||||
GrantTypes: []core.OAuth2GrantType{core.GrantTypeAuthorizationCode},
|
||||
Scopes: []string{"read", "write"},
|
||||
})
|
||||
|
||||
// 生成授权码
|
||||
authCode, _ := oauth2Server.GenerateAuthorizationCode(
|
||||
"webapp", "http://localhost:8080/callback", "user123", []string{"read"},
|
||||
)
|
||||
|
||||
// 用授权码换取访问令牌
|
||||
accessToken, _ := oauth2Server.ExchangeCodeForToken(
|
||||
authCode.Code, "webapp", "secret123", "http://localhost:8080/callback",
|
||||
)
|
||||
```
|
||||
|
||||
[👉 查看 OAuth2 完整示例](examples/oauth2-example/)
|
||||
|
||||
### 🎧 事件监听
|
||||
|
||||
监听认证和授权事件，实现审计日志、安全监控等功能：
|
||||
|
||||
@@ -345,6 +453,7 @@ eventMgr.RegisterFunc(core.EventAll, func(data *core.EventData) {
|
||||
```
|
||||
|
||||
**可用事件：**
|
||||
|
||||
- `EventLogin` - 用户登录
|
||||
- `EventLogout` - 用户登出
|
||||
- `EventKickout` - 强制下线
|
||||
@@ -353,9 +462,9 @@ eventMgr.RegisterFunc(core.EventAll, func(data *core.EventData) {
|
||||
- `EventRoleCheck` - 角色检查
|
||||
- `EventAll` - 所有事件（通配符）
|
||||
|
||||
[→ 查看 Listener 完整文档](docs/guide/listener.md)
|
||||
[→ 查看事件监听完整文档](docs/guide/listener_zh.md)
|
||||
|
||||
## 📖 项目结构
|
||||
## 📦 项目结构
|
||||
|
||||
```
|
||||
sa-token-go/
|
||||
@@ -402,184 +511,10 @@ sa-token-go/
|
||||
└── design/ # 设计文档
|
||||
```
|
||||
|
||||
## 🔧 核心API
|
||||
## 📚 文档与示例
|
||||
|
||||
### 登录认证
|
||||
### 📖 详细文档
|
||||
|
||||
```go
|
||||
// 登录（支持 int, int64, uint, string）
|
||||
token, _ := stputil.Login(1000)
|
||||
token, _ := stputil.Login("user123")
|
||||
token, _ := stputil.Login(1000, "mobile") // 指定设备
|
||||
|
||||
// 检查登录（自动异步续签）
|
||||
isLogin := stputil.IsLogin(token)
|
||||
|
||||
// 获取登录ID
|
||||
loginID, _ := stputil.GetLoginID(token)
|
||||
|
||||
// 登出
|
||||
stputil.Logout(1000)
|
||||
stputil.LogoutByToken(token)
|
||||
|
||||
// 踢人下线
|
||||
stputil.Kickout(1000)
|
||||
stputil.Kickout(1000, "mobile")
|
||||
```
|
||||
|
||||
### JWT Token 支持
|
||||
|
||||
```go
|
||||
// 使用 JWT Token
|
||||
stputil.SetManager(
|
||||
core.NewBuilder().
|
||||
Storage(memory.NewStorage()).
|
||||
TokenStyle(core.TokenStyleJWT). // 使用 JWT
|
||||
JwtSecretKey("your-256-bit-secret"). // JWT 密钥
|
||||
Timeout(3600). // 1小时过期
|
||||
Build(),
|
||||
)
|
||||
|
||||
// 登录后获得 JWT Token
|
||||
token, _ := stputil.Login(1000)
|
||||
// 返回格式：eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
|
||||
// JWT Token 包含用户信息，可在 https://jwt.io 解析
|
||||
```
|
||||
|
||||
**支持的 Token 风格：**
|
||||
- `TokenStyleUUID` - UUID（默认）
|
||||
- `TokenStyleSimple` - 简单随机字符串（16字符）
|
||||
- `TokenStyleRandom32/64/128` - 指定长度随机串（32/64/128字符）
|
||||
- `TokenStyleJWT` - JWT Token（推荐用于分布式）
|
||||
- `TokenStyleHash` - SHA256哈希风格（64字符，高安全性）🆕
|
||||
- `TokenStyleTimestamp` - 时间戳风格（格式：时间戳_loginID_随机数）🆕
|
||||
- `TokenStyleTik` - Tik短ID风格（11字符，类似抖音）🆕
|
||||
|
||||
### 权限验证
|
||||
|
||||
```go
|
||||
// 设置权限
|
||||
stputil.SetPermissions(1000, []string{
|
||||
"user:read",
|
||||
"user:write",
|
||||
"admin:*", // 通配符：匹配所有admin权限
|
||||
})
|
||||
|
||||
// 检查权限
|
||||
hasPermission := stputil.HasPermission(1000, "user:read")
|
||||
hasPermission := stputil.HasPermission(1000, "admin:delete") // 通配符匹配
|
||||
|
||||
// 多权限检查
|
||||
hasAll := stputil.HasPermissionsAnd(1000, []string{"user:read", "user:write"}) // AND逻辑
|
||||
hasAny := stputil.HasPermissionsOr(1000, []string{"admin", "super"}) // OR逻辑
|
||||
```
|
||||
|
||||
### 角色管理
|
||||
|
||||
```go
|
||||
// 设置角色
|
||||
stputil.SetRoles(1000, []string{"admin", "manager"})
|
||||
|
||||
// 检查角色
|
||||
hasRole := stputil.HasRole(1000, "admin")
|
||||
|
||||
// 多角色检查
|
||||
hasAll := stputil.HasRolesAnd(1000, []string{"admin", "manager"})
|
||||
hasAny := stputil.HasRolesOr(1000, []string{"admin", "super"})
|
||||
```
|
||||
|
||||
### 账号封禁
|
||||
|
||||
```go
|
||||
// 封禁1小时
|
||||
stputil.Disable(1000, 1*time.Hour)
|
||||
|
||||
// 永久封禁
|
||||
stputil.Disable(1000, 0)
|
||||
|
||||
// 解封
|
||||
stputil.Untie(1000)
|
||||
|
||||
// 检查是否被封禁
|
||||
isDisabled := stputil.IsDisable(1000)
|
||||
|
||||
// 获取剩余封禁时间
|
||||
remainingTime, _ := stputil.GetDisableTime(1000)
|
||||
```
|
||||
|
||||
### Session管理
|
||||
|
||||
```go
|
||||
// 获取Session
|
||||
sess, _ := stputil.GetSession(1000)
|
||||
|
||||
// 设置数据
|
||||
sess.Set("nickname", "张三")
|
||||
sess.Set("age", 25)
|
||||
|
||||
// 读取数据
|
||||
nickname := sess.GetString("nickname")
|
||||
age := sess.GetInt("age")
|
||||
|
||||
// 删除数据
|
||||
sess.Delete("nickname")
|
||||
|
||||
// 删除Session
|
||||
stputil.DeleteSession(1000)
|
||||
```
|
||||
|
||||
## 🎨 注解装饰器（Gin框架）
|
||||
|
||||
### 支持的注解
|
||||
|
||||
| 注解 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `@SaIgnore` | 忽略认证 | `sagin.Ignore()` |
|
||||
| `@SaCheckLogin` | 检查登录 | `sagin.CheckLogin()` |
|
||||
| `@SaCheckRole` | 检查角色 | `sagin.CheckRole("admin")` |
|
||||
| `@SaCheckPermission` | 检查权限 | `sagin.CheckPermission("admin:*")` |
|
||||
| `@SaCheckDisable` | 检查封禁 | `sagin.CheckDisable()` |
|
||||
|
||||
### 使用示例
|
||||
|
||||
```go
|
||||
import sagin "github.com/click33/sa-token-go/integrations/gin"
|
||||
|
||||
func main() {
|
||||
r := gin.Default()
|
||||
|
||||
// 公开访问 - 忽略认证
|
||||
r.GET("/public", sagin.Ignore(), publicHandler)
|
||||
|
||||
// 需要登录
|
||||
r.GET("/user/info", sagin.CheckLogin(), userInfoHandler)
|
||||
|
||||
// 需要管理员权限
|
||||
r.GET("/admin", sagin.CheckPermission("admin:*"), adminHandler)
|
||||
|
||||
// 需要多个权限之一（OR逻辑）
|
||||
r.GET("/user-or-admin",
|
||||
sagin.CheckPermission("user:read", "admin:*"),
|
||||
userOrAdminHandler)
|
||||
|
||||
// 需要管理员角色
|
||||
r.GET("/manager", sagin.CheckRole("admin"), managerHandler)
|
||||
|
||||
// 检查账号是否被封禁
|
||||
r.GET("/sensitive", sagin.CheckDisable(), sensitiveHandler)
|
||||
|
||||
r.Run(":8080")
|
||||
}
|
||||
```
|
||||
|
||||
## 📚 详细文档
|
||||
|
||||
### 语言切换
|
||||
- [中文文档](README_zh.md)
|
||||
- [English Documentation](README.md)
|
||||
|
||||
### 使用指南
|
||||
- [快速开始](docs/tutorial/quick-start_zh.md) - 5分钟上手
|
||||
- [登录认证](docs/guide/authentication_zh.md) - 登录认证详解
|
||||
- [权限验证](docs/guide/permission_zh.md) - 权限系统详解
|
||||
@@ -587,20 +522,21 @@ func main() {
|
||||
- [事件监听](docs/guide/listener_zh.md) - 事件系统详解
|
||||
- [JWT 使用](docs/guide/jwt_zh.md) - JWT Token 详解
|
||||
- [Redis 存储](docs/guide/redis-storage_zh.md) - Redis 存储配置
|
||||
- [Nonce 防重放](docs/guide/nonce_zh.md) - Nonce 防重放攻击
|
||||
- [Refresh Token](docs/guide/refresh-token_zh.md) - 刷新令牌机制
|
||||
- [OAuth2](docs/guide/oauth2_zh.md) - OAuth2 授权详解
|
||||
|
||||
### 📋 API 文档
|
||||
|
||||
### API文档
|
||||
- [StpUtil API](docs/api/stputil_zh.md) - 全局工具类完整API
|
||||
|
||||
### 设计文档
|
||||
### 🏗️ 设计文档
|
||||
|
||||
- [架构设计](docs/design/architecture_zh.md) - 系统架构、数据流转
|
||||
- [自动续签设计](docs/design/auto-renew_zh.md) - 异步续签机制
|
||||
- [模块化设计](docs/design/modular_zh.md) - 模块划分策略
|
||||
|
||||
### 存储
|
||||
- [Memory 存储](storage/memory/) - 用于开发环境
|
||||
- [Redis 存储](storage/redis/) - 用于生产环境
|
||||
|
||||
## 📖 示例项目
|
||||
### 💡 示例项目
|
||||
|
||||
| 示例 | 说明 | 路径 |
|
||||
|------|------|------|
|
||||
@@ -617,7 +553,10 @@ func main() {
|
||||
| 🌐 Fiber集成 | Fiber框架集成 | [examples/fiber/](examples/fiber/) |
|
||||
| 🌐 Chi集成 | Chi框架集成 | [examples/chi/](examples/chi/) |
|
||||
|
||||
### 💾 存储方案
|
||||
|
||||
- [Memory 存储](storage/memory/) - 用于开发环境
|
||||
- [Redis 存储](storage/redis/) - 用于生产环境
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
@@ -627,6 +566,10 @@ Apache License 2.0
|
||||
|
||||
参考 [sa-token](https://github.com/dromara/sa-token) 设计
|
||||
|
||||
---
|
||||
## 📞 支持
|
||||
|
||||
**Sa-Token-Go v0.1.0**
|
||||
- 📧 邮箱: <support@sa-token-go.dev>
|
||||
- 💬 问题反馈: [GitHub Issues](https://github.com/click33/sa-token-go/issues)
|
||||
- 📖 文档: [docs/](docs/)
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user