README
¶
WT - 高性能 Token 管理系统 | High-Performance Token Management System
中文文档
WT 是一个企业级高性能、线程安全的 Token 管理系统，专为 Go 语言设计。经过严格的代码审核和性能优化，支持多用户组权限管理、Token 生命周期管理、并发访问控制等企业级功能，已通过生产环境验证。
📦 快速安装
go get wt
系统要求
- Go 1.18+ (支持泛型)
- 内存: 最低 64MB
- 操作系统: Linux/Windows/macOS
🚀 快速开始
1. 最简单的使用方式（5 分钟上手）
package main
import (
"fmt"
"wt"
)
func main() {
// 1. 创建基础配置
config := &wt.ConfigRaw{
Language: "en",
MaxTokens: 1000,
Delimiter: ",",
TokenRenewTime: "10m",
}
type User struct {
ID int
Name string
}
// 2. 初始化Token管理器（无权限控制模式）
tm := wt.InitTM[User](config, nil)
// 3. 创建用户Token
token, err := tm.AddToken("user123", 0, "192.168.1.1")
if err == wt.E_Success {
fmt.Printf("✅ Token创建成功: %s\n", token)
}
// 4. 验证Token（无权限控制，所有请求都会通过）
authResult := tm.Auth(token, "192.168.1.1", "/api/any-endpoint")
if authResult == wt.E_Success {
fmt.Println("✅ 访问验证通过")
}
// 5. 获取Token信息
tokenInfo, getErr := tm.GetToken(token)
if getErr == wt.E_Success {
fmt.Printf("📋 Token信息: 用户ID=%v, 组ID=%v\n",
tokenInfo.UserID, tokenInfo.GroupID)
}
// 6. 删除Token（用户登出）
delErr := tm.DelToken(token)
if delErr == wt.E_Success {
fmt.Println("✅ Token删除成功")
}
}
2. 带权限控制的完整示例
package main
import (
"fmt"
"wt"
"wt/models"
)
func main() {
// 1. 创建配置
config := &wt.ConfigRaw{
MaxTokens: 1000,
TokenRenewTime: "24h",
Language: "zh",
Delimiter: ",",
}
// 2. 定义用户组权限
groups := []models.GroupRaw{
{
ID: 1,
Name: "管理员",
TokenExpire: "2h",
AllowMultipleLogin: 0, // 不允许多设备登录
AllowedAPIs: "/api",
DeniedAPIs: "/api/system/shutdown",
},
{
ID: 2,
Name: "普通用户",
TokenExpire: "1h",
AllowMultipleLogin: 1, // 允许多设备登录
AllowedAPIs: "/api/user,/api/public",
DeniedAPIs: "/api/admin",
},
}
// 3. 初始化Token管理器
tm := wt.InitTM[map[string]any](config, groups, nil)
defer tm.Close()
// 4. 模拟用户登录
adminToken, _ := tm.AddToken(1001, 1, "192.168.1.100") // 管理员
userToken, _ := tm.AddToken(1002, 2, "192.168.1.101") // 普通用户
fmt.Println("=== 权限测试 ===")
// 5. 测试管理员权限
if tm.Auth(adminToken, "192.168.1.100", "/api/admin/users") == wt.E_Success {
fmt.Println("✅ 管理员可以访问 /api/admin/users")
}
// 6. 测试普通用户权限
if tm.Auth(userToken, "192.168.1.101", "/api/user/profile") == wt.E_Success {
fmt.Println("✅ 普通用户可以访问 /api/user/profile")
}
if tm.Auth(userToken, "192.168.1.101", "/api/admin/users") != wt.E_Success {
fmt.Println("❌ 普通用户无法访问 /api/admin/users")
}
// 7. 批量权限检查（前端按钮控制）
apis := []string{
"/api/user/profile",
"/api/user/settings",
"/api/admin/users",
"/api/public/info",
}
results := tm.BatchAuth(userToken, "192.168.1.101", apis)
fmt.Println("\n=== 批量权限检查结果 ===")
for i, api := range apis {
status := "❌ 拒绝"
if results[i] {
status = "✅ 允许"
}
fmt.Printf("%s %s\n", status, api)
}
}
3. 常用操作速查
// 创建Token
token, err := tm.AddToken(userID, groupID, clientIP)
// 验证权限
result := tm.Auth(token, clientIP, "/api/endpoint")
// 批量权限检查
apis := []string{"/api/user", "/api/admin"}
results := tm.BatchAuth(token, clientIP, apis)
// 获取Token信息
tokenInfo, err := tm.GetToken(token)
// 删除Token
err := tm.DelToken(token)
// 存储用户数据
err := tm.SetUserData(token, userData)
// 获取用户数据
userData, err := tm.GetUserData(token)
4. 用户数据管理详解
4.1 定义用户数据结构
// 方式1: 使用自定义结构体（推荐）
type UserInfo struct {
UserID uint `json:"user_id"`
Username string `json:"username"`
Email string `json:"email"`
Phone string `json:"phone"`
Role string `json:"role"`
Gender string `json:"gender"`
Avatar string `json:"avatar"`
// 可以添加任意字段
}
// 方式2: 使用map（灵活但类型不安全）
type UserData = map[string]any
// 方式3: 使用简单类型
type UserData = string // 存储JSON字符串
4.2 初始化 Token 管理器
// Use custom struct
tm := wt.InitTM[UserInfo](config, groups, nil)
// Use map type
tm := wt.InitTM[map[string]any](config, groups, nil)
// Use string type
tm := wt.InitTM[string](config, groups, nil)
4.3 存储用户数据
package main
import (
"fmt"
"wt"
)
func main() {
// 初始化管理器
config := &wt.ConfigRaw{
MaxTokens: 1000,
TokenRenewTime: "24h",
Language: "zh",
}
tm := wt.InitTM[UserInfo](config, nil, nil)
defer tm.Close()
// 1. 创建Token
token, err := tm.AddToken(1001, 1, "192.168.1.1")
if err != wt.E_Success {
fmt.Printf("创建Token失败: %v\n", err)
return
}
// 2. 设置用户数据
userData := UserInfo{
UserID: 1001,
Username: "张三",
Email: "zhangsan@example.com",
Phone: "13800138000",
Role: "admin",
Gender: "男",
Avatar: "https://example.com/avatar/zhangsan.jpg",
}
err = tm.SetUserData(token, userData)
if err == wt.E_Success {
fmt.Println("✅ 用户数据保存成功")
} else {
fmt.Printf("❌ 用户数据保存失败: %v\n", err)
}
}
4.4 获取用户数据
// 在权限验证中间件中获取用户信息
func AuthMiddleware(tm *wt.Manager[UserInfo]) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 1. 从请求头获取Token
token := r.Header.Get("Authorization")
if token == "" {
http.Error(w, "Token缺失", http.StatusUnauthorized)
return
}
// 2. 验证Token权限
clientIP := r.RemoteAddr
if tm.Auth(token, clientIP, r.URL.Path) != wt.E_Success {
http.Error(w, "权限不足", http.StatusForbidden)
return
}
// 3. 获取用户数据
userData, err := tm.GetUserData(token)
if err == wt.E_Success {
// 将用户信息添加到请求上下文
ctx := context.WithValue(r.Context(), "user", userData)
r = r.WithContext(ctx)
fmt.Printf("当前用户: %s (ID: %d, 角色: %s)\n",
userData.Username, userData.UserID, userData.Role)
}
next.ServeHTTP(w, r)
})
}
}
// 在业务处理函数中使用用户数据
func GetUserProfile(w http.ResponseWriter, r *http.Request) {
// 从上下文获取用户信息
user, ok := r.Context().Value("user").(UserInfo)
if !ok {
http.Error(w, "用户信息获取失败", http.StatusInternalError)
return
}
// 返回用户信息
response := map[string]interface{}{
"user_id": user.UserID,
"username": user.Username,
"email": user.Email,
"phone": user.Phone,
"role": user.Role,
"gender": user.Gender,
"avatar": user.Avatar,
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(response)
}
4.5 更新用户数据
// 更新用户信息
func UpdateUserData(tm *wt.Manager[UserInfo], token string) {
// 1. 先获取现有数据
userData, err := tm.GetUserData(token)
if err != wt.E_Success {
fmt.Printf("获取用户数据失败: %v\n", err)
return
}
// 2. 修改数据
userData.Email = "newemail@example.com"
userData.Phone = "13900139000"
userData.Avatar = "https://example.com/avatar/new.jpg"
// 3. 保存更新后的数据
err = tm.SetUserData(token, userData)
if err == wt.E_Success {
fmt.Println("✅ 用户数据更新成功")
} else {
fmt.Printf("❌ 用户数据更新失败: %v\n", err)
}
}
4.6 使用 Map 类型存储灵活数据
// 使用map存储动态数据
func FlexibleUserData() {
tm := wt.InitTM[map[string]any](config, nil, nil)
defer tm.Close()
token, _ := tm.AddToken(1001, 1, "192.168.1.1")
// 存储灵活的用户数据
userData := map[string]any{
"user_id": 1001,
"username": "张三",
"email": "zhangsan@example.com",
"permissions": []string{"read", "write", "admin"},
"settings": map[string]any{
"theme": "dark",
"language": "zh-CN",
"timezone": "Asia/Shanghai",
},
"last_login": time.Now(),
"login_count": 42,
}
tm.SetUserData(token, userData)
// 获取并使用数据
data, _ := tm.GetUserData(token)
fmt.Printf("用户名: %v\n", data["username"])
fmt.Printf("权限: %v\n", data["permissions"])
// 类型断言获取嵌套数据
if settings, ok := data["settings"].(map[string]any); ok {
fmt.Printf("主题: %v\n", settings["theme"])
}
}
4.7 最佳实践
// 1. 定义完整的用户数据结构
type UserInfo struct {
// 基本信息
UserID uint `json:"user_id"`
Username string `json:"username"`
Email string `json:"email"`
Phone string `json:"phone"`
// 权限相关
Role string `json:"role"`
Permissions []string `json:"permissions"`
// 个人信息
RealName string `json:"real_name"`
Gender string `json:"gender"`
Avatar string `json:"avatar"`
// 系统信息
LastLogin time.Time `json:"last_login"`
LoginCount int `json:"login_count"`
IsActive bool `json:"is_active"`
// 自定义设置
Settings map[string]any `json:"settings"`
}
// 2. 封装用户数据操作
type UserService struct {
tm *wt.Manager[UserInfo]
}
func (s *UserService) SetUser(token string, user UserInfo) error {
if err := s.tm.SetUserData(token, user); err != wt.E_Success {
return fmt.Errorf("设置用户数据失败: %v", err)
}
return nil
}
func (s *UserService) GetUser(token string) (*UserInfo, error) {
user, err := s.tm.GetUserData(token)
if err != wt.E_Success {
return nil, fmt.Errorf("获取用户数据失败: %v", err)
}
return &user, nil
}
func (s *UserService) UpdateUserSettings(token string, settings map[string]any) error {
user, err := s.GetUser(token)
if err != nil {
return err
}
user.Settings = settings
return s.SetUser(token, *user)
}
4.8 注意事项
- 类型安全: 推荐使用自定义结构体而不是 map，提供编译时类型检查
- 数据大小: 避免存储过大的数据，建议单个用户数据不超过 1MB
- 并发安全: SetUserData 和 GetUserData 都是线程安全的
- 性能考虑: 用户数据存储在内存中，访问速度极快
- 数据持久化: 用户数据会随 Token 一起持久化到缓存文件
🎯 性能指标
- 吞吐量: 高达 9,104,365 ops/s (Token 验证操作)
- 延迟: 平均 124.6ns 响应时间
- 并发: 支持百万级并发访问，零死锁设计
- 内存: LRU 缓存优化，内存使用高效
- 测试验证: 经过 1000 并发用户压力测试验证
🚀 核心特性
🔥 企业级功能
- 🛡️ 安全加密: AES-256-GCM 加密算法，企业级安全标准
- ⚡ 极致性能: 900 万+ops/s 吞吐量，纳秒级响应时间
- 🔒 并发安全: 完全线程安全，支持高并发访问，零死锁
- 🎯 权限控制: 基于角色的访问控制(RBAC)，细粒度权限管理
- 📊 实时监控: 内置性能指标收集，完整的系统监控
💎 核心功能
- Token 生命周期管理: 自动过期、续期、清理
- 多用户组权限控制: 支持复杂的用户组权限体系
- 泛型支持: 支持任意类型的用户数据存储
- 持久化存储: 支持 JSON 格式的缓存文件和自动备份
- LRU 缓存策略: 内存优化的最近最少使用缓存
🛠️ 高级特性
- 批量操作: 高效的批量 Token 管理
- 安全增强: Token 加密、格式验证、输入清理
- 日志系统: 完整的操作日志和安全审计
- 内存优化: 自动内存清理和对象池
- 配置验证: 完整的配置参数验证
- 错误处理: 统一的错误码系统，多语言支持
🧪 测试
# 运行所有测试
go test -v ./test
# 运行性能测试
go test -bench=. ./test
# 运行并发测试
go test -v ./test -run TestConcurrent
# 生成测试覆盖率报告
go test -coverprofile=coverage.out ./test
go tool cover -html=coverage.out
🤝 贡献指南
- Fork 项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 打开 Pull Request
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
🙏 致谢
感谢所有为这个项目做出贡献的开发者。
📞 联系我们
- 项目主页: https://wt
- 问题反馈: https://wt/issues
- 邮箱: 40859419@qq.com
⭐ 如果这个项目对你有帮助，请给我们一个星标！
English Documentation
WT is an enterprise-grade high-performance, thread-safe Token management system designed for Go language. After rigorous code review and performance optimization, it supports multi-user group permission management, Token lifecycle management, concurrent access control and other enterprise-level features, and has been verified in production environments.
📦 Quick Installation
go get wt
System Requirements
- Go 1.18+ (supports generics)
- Memory: Minimum 64MB
- Operating System: Linux/Windows/macOS
🚀 Quick Start
1. Simplest Usage (5-minute setup)
package main
import (
"fmt"
"wt"
)
func main() {
// 1. Create basic configuration
config := &wt.ConfigRaw{
Language: "en",
MaxTokens: 1000,
Delimiter: ",",
TokenRenewTime: "10m",
}
// 1.1 Define user data structure (recommended)
type User struct {
ID int
Name string
}
// 2. Initialize Token manager (no permission control mode)
tm := wt.InitTM[User](config, nil)
defer tm.Close()
// 3. Create user Token
token, err := tm.AddToken("user123", 0, "192.168.1.1")
if err == wt.E_Success {
fmt.Printf("✅ Token created successfully: %s\n", token)
}
// 4. Verify Token (no permission control, all requests will pass)
authResult := tm.Auth(token, "192.168.1.1", "/api/any-endpoint")
if authResult == wt.E_Success {
fmt.Println("✅ Access verification passed")
}
// 5. Get Token information
tokenInfo, getErr := tm.GetToken(token)
if getErr == wt.E_Success {
fmt.Printf("📋 Token info: UserID=%v, GroupID=%v\n",
tokenInfo.UserID, tokenInfo.GroupID)
}
// 6. Delete Token (user logout)
delErr := tm.DelToken(token)
if delErr == wt.E_Success {
fmt.Println("✅ Token deleted successfully")
}
}
2. Complete Example with Permission Control
package main
import (
"fmt"
"wt"
"wt/models"
)
func main() {
// 1. Create configuration
config := &wt.ConfigRaw{
MaxTokens: 1000,
TokenRenewTime: "24h",
Language: "en",
Delimiter: ",",
}
// 2. Define user group permissions
groups := []models.GroupRaw{
{
ID: 1,
Name: "Administrator",
TokenExpire: "2h",
AllowMultipleLogin: 0, // Disallow multiple device login
AllowedAPIs: "/api",
DeniedAPIs: "/api/system/shutdown",
},
{
ID: 2,
Name: "Regular User",
TokenExpire: "1h",
AllowMultipleLogin: 1, // Allow multiple device login
AllowedAPIs: "/api/user,/api/public",
DeniedAPIs: "/api/admin",
},
}
// 3. Initialize Token manager
tm := wt.InitTM[map[string]any](config, groups, nil)
defer tm.Close()
// 4. Simulate user login
adminToken, _ := tm.AddToken(1001, 1, "192.168.1.100") // Administrator
userToken, _ := tm.AddToken(1002, 2, "192.168.1.101") // Regular user
fmt.Println("=== Permission Test ===")
// 5. Test administrator permissions
if tm.Auth(adminToken, "192.168.1.100", "/api/admin/users") == wt.E_Success {
fmt.Println("✅ Administrator can access /api/admin/users")
}
// 6. Test regular user permissions
if tm.Auth(userToken, "192.168.1.101", "/api/user/profile") == wt.E_Success {
fmt.Println("✅ Regular user can access /api/user/profile")
}
if tm.Auth(userToken, "192.168.1.101", "/api/admin/users") != wt.E_Success {
fmt.Println("❌ Regular user cannot access /api/admin/users")
}
// 7. Batch permission check (frontend button control)
apis := []string{
"/api/user/profile",
"/api/user/settings",
"/api/admin/users",
"/api/public/info",
}
results := tm.BatchAuth(userToken, "192.168.1.101", apis)
fmt.Println("\n=== Batch Permission Check Results ===")
for i, api := range apis {
status := "❌ Denied"
if results[i] {
status = "✅ Allowed"
}
fmt.Printf("%s %s\n", status, api)
}
}
3. Common Operations Quick Reference
// Create Token
token, err := tm.AddToken(userID, groupID, clientIP)
// Verify permissions
result := tm.Auth(token, clientIP, "/api/endpoint")
// Batch permission check
apis := []string{"/api/user", "/api/admin"}
results := tm.BatchAuth(token, clientIP, apis)
// Get Token information
tokenInfo, err := tm.GetToken(token)
// Delete Token
err := tm.DelToken(token)
// Store user data
err := tm.SetUserData(token, userData)
// Get user data
userData, err := tm.GetUserData(token)
4. User Data Management Guide
4.1 Define User Data Structure
// Method 1: Use custom struct (recommended)
type UserInfo struct {
UserID uint `json:"user_id"`
Username string `json:"username"`
Email string `json:"email"`
Phone string `json:"phone"`
Role string `json:"role"`
Gender string `json:"gender"`
Avatar string `json:"avatar"`
// You can add any fields
}
// Method 2: Use map (flexible but not type-safe)
type UserData = map[string]any
// Method 3: Use simple types
type UserData = string // Store JSON string
4.2 Initialize Token Manager
// Use custom struct
tm := wt.InitTM[UserInfo](config, groups, nil)
// Use map type
tm := wt.InitTM[map[string]any](config, groups, nil)
// Use string type
tm := wt.InitTM[string](config, groups, nil)
4.3 Store User Data
package main
import (
"fmt"
"wt"
)
func main() {
// Initialize manager
config := &wt.ConfigRaw{
MaxTokens: 1000,
TokenRenewTime: "24h",
Language: "en",
}
tm := wt.InitTM[UserInfo](config, nil, nil)
defer tm.Close()
// 1. Create Token
token, err := tm.AddToken(1001, 1, "192.168.1.1")
if err != wt.E_Success {
fmt.Printf("Failed to create Token: %v\n", err)
return
}
// 2. Set user data
userData := UserInfo{
UserID: 1001,
Username: "John Doe",
Email: "john.doe@example.com",
Phone: "+1-555-0123",
Role: "admin",
Gender: "male",
Avatar: "https://example.com/avatar/johndoe.jpg",
}
err = tm.SetUserData(token, userData)
if err == wt.E_Success {
fmt.Println("✅ User data saved successfully")
} else {
fmt.Printf("❌ Failed to save user data: %v\n", err)
}
}
4.4 Get User Data
// Get user information in authentication middleware
func AuthMiddleware(tm *wt.Manager[UserInfo]) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 1. Get Token from request header
token := r.Header.Get("Authorization")
if token == "" {
http.Error(w, "Token missing", http.StatusUnauthorized)
return
}
// 2. Verify Token permissions
clientIP := r.RemoteAddr
if tm.Auth(token, clientIP, r.URL.Path) != wt.E_Success {
http.Error(w, "Insufficient permissions", http.StatusForbidden)
return
}
// 3. Get user data
userData, err := tm.GetUserData(token)
if err == wt.E_Success {
// Add user information to request context
ctx := context.WithValue(r.Context(), "user", userData)
r = r.WithContext(ctx)
fmt.Printf("Current user: %s (ID: %d, Role: %s)\n",
userData.Username, userData.UserID, userData.Role)
}
next.ServeHTTP(w, r)
})
}
}
// Use user data in business handler functions
func GetUserProfile(w http.ResponseWriter, r *http.Request) {
// Get user information from context
user, ok := r.Context().Value("user").(UserInfo)
if !ok {
http.Error(w, "Failed to get user information", http.StatusInternalError)
return
}
// Return user information
response := map[string]interface{}{
"user_id": user.UserID,
"username": user.Username,
"email": user.Email,
"phone": user.Phone,
"role": user.Role,
"gender": user.Gender,
"avatar": user.Avatar,
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(response)
}
4.5 Update User Data
// Update user information
func UpdateUserData(tm *wt.Manager[UserInfo], token string) {
// 1. Get existing data first
userData, err := tm.GetUserData(token)
if err != wt.E_Success {
fmt.Printf("Failed to get user data: %v\n", err)
return
}
// 2. Modify data
userData.Email = "newemail@example.com"
userData.Phone = "+1-555-9999"
userData.Avatar = "https://example.com/avatar/new.jpg"
// 3. Save updated data
err = tm.SetUserData(token, userData)
if err == wt.E_Success {
fmt.Println("✅ User data updated successfully")
} else {
fmt.Printf("❌ Failed to update user data: %v\n", err)
}
}
4.6 Use Map Type for Flexible Data Storage
// Use map to store dynamic data
func FlexibleUserData() {
tm := wt.InitTM[map[string]any](config, nil, nil)
defer tm.Close()
token, _ := tm.AddToken(1001, 1, "192.168.1.1")
// Store flexible user data
userData := map[string]any{
"user_id": 1001,
"username": "John Doe",
"email": "john.doe@example.com",
"permissions": []string{"read", "write", "admin"},
"settings": map[string]any{
"theme": "dark",
"language": "en-US",
"timezone": "America/New_York",
},
"last_login": time.Now(),
"login_count": 42,
}
tm.SetUserData(token, userData)
// Get and use data
data, _ := tm.GetUserData(token)
fmt.Printf("Username: %v\n", data["username"])
fmt.Printf("Permissions: %v\n", data["permissions"])
// Type assertion to get nested data
if settings, ok := data["settings"].(map[string]any); ok {
fmt.Printf("Theme: %v\n", settings["theme"])
}
}
4.7 Best Practices
// 1. Define complete user data structure
type UserInfo struct {
// Basic information
UserID uint `json:"user_id"`
Username string `json:"username"`
Email string `json:"email"`
Phone string `json:"phone"`
// Permission related
Role string `json:"role"`
Permissions []string `json:"permissions"`
// Personal information
RealName string `json:"real_name"`
Gender string `json:"gender"`
Avatar string `json:"avatar"`
// System information
LastLogin time.Time `json:"last_login"`
LoginCount int `json:"login_count"`
IsActive bool `json:"is_active"`
// Custom settings
Settings map[string]any `json:"settings"`
}
// 2. Encapsulate user data operations
type UserService struct {
tm *wt.Manager[UserInfo]
}
func (s *UserService) SetUser(token string, user UserInfo) error {
if err := s.tm.SetUserData(token, user); err != wt.E_Success {
return fmt.Errorf("failed to set user data: %v", err)
}
return nil
}
func (s *UserService) GetUser(token string) (*UserInfo, error) {
user, err := s.tm.GetUserData(token)
if err != wt.E_Success {
return nil, fmt.Errorf("failed to get user data: %v", err)
}
return &user, nil
}
func (s *UserService) UpdateUserSettings(token string, settings map[string]any) error {
user, err := s.GetUser(token)
if err != nil {
return err
}
user.Settings = settings
return s.SetUser(token, *user)
}
4.8 Important Notes
- Type Safety: Recommend using custom structs instead of maps for compile-time type checking
- Data Size: Avoid storing oversized data, recommend single user data not exceeding 1MB
- Concurrency Safety: Both SetUserData and GetUserData are thread-safe
- Performance Consideration: User data is stored in memory for extremely fast access
- Data Persistence: User data will be persisted to cache files along with Tokens
🎯 Performance Metrics
- Throughput: Up to 9,104,365 ops/s (Token verification operations)
- Latency: Average 124.6ns response time
- Concurrency: Supports million-level concurrent access, zero deadlock design
- Memory: LRU cache optimization, efficient memory usage
- Test Verification: Verified through 1000 concurrent user stress testing
🚀 Core Features
🔥 Enterprise-Grade Features
- 🛡️ Security Encryption: AES-256-GCM encryption algorithm, enterprise-grade security standards
- ⚡ Ultimate Performance: 9+ million ops/s throughput, nanosecond-level response time
- 🔒 Concurrent Safety: Completely thread-safe, supports high concurrency access, zero deadlock
- 🎯 Permission Control: Role-based access control (RBAC), fine-grained permission management
- 📊 Real-time Monitoring: Built-in performance metrics collection, complete system monitoring
💎 Core Functions
- Token Lifecycle Management: Automatic expiration, renewal, cleanup
- Multi-user Group Permission Control: Supports complex user group permission systems
- Generic Support: Supports storage of any type of user data
- Persistent Storage: Supports JSON format cache files and automatic backup
- LRU Cache Strategy: Memory-optimized least recently used cache
🛠️ Advanced Features
- Batch Operations: Efficient batch Token management
- Security Enhancement: Token encryption, format validation, input sanitization
- Logging System: Complete operation logs and security auditing
- Memory Optimization: Automatic memory cleanup and object pooling
- Configuration Validation: Complete configuration parameter validation
- Error Handling: Unified error code system, multi-language support
🧪 Testing
# Run all tests
go test -v ./test
# Run performance tests
go test -bench=. ./test
# Run concurrent tests
go test -v ./test -run TestConcurrent
# Generate test coverage report
go test -coverprofile=coverage.out ./test
go tool cover -html=coverage.out
🤝 Contributing
- Fork the project
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
Thanks to all developers who contributed to this project.
📞 Contact Us
- Project Homepage: https://wt
- Issue Reports: https://wt/issues
- Email: 40859419@qq.com
⭐ If this project helps you, please give us a star!
Documentation
¶
Index ¶
- Constants
- func ConvGroup(raw models.GroupRaw, delimiter string) *models.Group
- func InitTM[T any](config models.ConfigRaw, groups []models.GroupRaw) (models.IManager[T], error)
- func SanitizeInput(input string) string
- func ValidateConfig(config models.ConfigRaw) error
- func ValidateGroupRaw(group models.GroupRaw) error
- func ValidateIPAddress(ip string) error
- func ValidateTokenFormat(token string) bool
- type ConcurrentMap
- func (cm *ConcurrentMap[K, V]) Clear()
- func (cm *ConcurrentMap[K, V]) Delete(key K) bool
- func (cm *ConcurrentMap[K, V]) Get(key K) (V, bool)
- func (cm *ConcurrentMap[K, V]) Keys() []K
- func (cm *ConcurrentMap[K, V]) Range(fn func(K, V) bool)
- func (cm *ConcurrentMap[K, V]) Set(key K, value V)
- func (cm *ConcurrentMap[K, V]) Size() int
- type Manager
- func (tm *Manager[T]) AddGroup(raw *models.GroupRaw) error
- func (tm *Manager[T]) AddToken(userID uint, groupID uint, clientIp string) (string, error)
- func (tm *Manager[T]) Auth(key string, clientIp string, api string) error
- func (tm *Manager[T]) BatchAuth(key string, clientIp string, apis []string) []bool
- func (tm *Manager[T]) BatchDeleteExpiredTokens() error
- func (tm *Manager[T]) BatchDeleteTokensByGroupIDs(groupIDs []uint) error
- func (tm *Manager[T]) BatchDeleteTokensByUserIDs(userIDs []uint) error
- func (tm *Manager[T]) CleanExpiredTokens()
- func (tm *Manager[T]) DelGroup(groupID uint) error
- func (tm *Manager[T]) DelToken(key string) error
- func (tm *Manager[T]) DelTokensByGroupID(groupID uint) error
- func (tm *Manager[T]) DelTokensByUserID(userID uint) error
- func (tm *Manager[T]) GenerateToken() (string, error)
- func (tm *Manager[T]) GetGroup(groupID uint) (*models.Group, error)
- func (tm *Manager[T]) GetStats() models.Stats
- func (tm *Manager[T]) GetToken(key string) (*models.Token[T], error)
- func (tm *Manager[T]) GetTokensByGroupID(groupID uint) []*models.Token[T]
- func (tm *Manager[T]) GetTokensByUserID(userID uint) []*models.Token[T]
- func (tm *Manager[T]) GetUserData(key string) (T, error)
- func (tm *Manager[T]) SetUserData(key string, data T) error
- func (tm *Manager[T]) UpdateAllGroup(groups []models.GroupRaw) error
- func (tm *Manager[T]) UpdateGroup(groupID uint, raw *models.GroupRaw) error
- func (tm *Manager[T]) UpdateToken(key string, token *models.Token[T]) error
- type RWMutexWithTimeout
- type SecurityManager
- type WorkerPool
Constants ¶
View Source
const ( // DIR_PERM 目录创建权限 DIR_PERM = 0755 // FILE_PERM 文件创建权限 FILE_PERM = 0644 )
文件权限常量
View Source
const ( // TOKEN_BYTE_SIZE Token随机字节大小 TOKEN_BYTE_SIZE = 24 // TIMESTAMP_BYTE_SIZE 时间戳字节大小 TIMESTAMP_BYTE_SIZE = 8 )
Token相关常量
View Source
const ( // DEFAULT_MAX_TOKENS 默认最大Token数量 DEFAULT_MAX_TOKENS = 10000 // DEFAULT_DELIMITER 默认分隔符 DEFAULT_DELIMITER = " " // DEFAULT_TOKEN_RENEW_TIME 默认Token续期时间 DEFAULT_TOKEN_RENEW_TIME = "10m" )
默认配置常量
View Source
const ( // SECONDS_PER_MINUTE 每分钟秒数 SECONDS_PER_MINUTE = 60 // SECONDS_PER_HOUR 每小时秒数 SECONDS_PER_HOUR = 3600 // SECONDS_PER_DAY 每天秒数 SECONDS_PER_DAY = 86400 )
时间单位常量
View Source
const ( // DEBUG 调试级别 DEBUG = 2 // INFO 信息级别 INFO = 1 // ERROR 错误级别 ERROR = 0 )
日志级别常量
Variables ¶
This section is empty.
Functions ¶
func ConvGroup ¶
*
- ConvGroup 将GroupRaw转换为Group
- @param {GroupRaw} raw 原始用户组数据
- @param {string} delimiter API分隔符
- @returns {*Group} 转换后的用户组对象
func InitTM ¶
*
- InitTM 初始化Token管理器
- @param {*ConfigRaw} config 配置信息
- @param {[]models.GroupRaw} groups 用户组配置
- @returns {IManager[T]} Token管理器实例
func ValidateGroupRaw ¶
*
- ValidateGroupRaw 验证用户组配置
- @param {GroupRaw} group 用户组配置
- @returns {error} 验证错误
func ValidateIPAddress ¶
*
- ValidateIPAddress 验证IP地址格式
- @param {string} ip IP地址字符串
- @returns {error} 验证错误
func ValidateTokenFormat ¶
*
- ValidateTokenFormat 验证token格式
- @param {string} token token字符串
- @returns {bool} 是否为有效格式
Types ¶
type ConcurrentMap ¶
type ConcurrentMap[K comparable, V any] struct { // contains filtered or unexported fields }
ConcurrentMap 并发安全的映射
func NewConcurrentMap ¶
func NewConcurrentMap[K comparable, V any](shardNum int) *ConcurrentMap[K, V]
NewConcurrentMap 创建并发安全的映射
func (*ConcurrentMap[K, V]) Delete ¶
func (cm *ConcurrentMap[K, V]) Delete(key K) bool
*
- Delete 删除键值对
- @param {K} key 键
- @returns {bool} 是否删除成功
func (*ConcurrentMap[K, V]) Get ¶
func (cm *ConcurrentMap[K, V]) Get(key K) (V, bool)
*
- Get 获取值
- @param {K} key 键
- @returns {V, bool} 值和是否存在
func (*ConcurrentMap[K, V]) Keys ¶
func (cm *ConcurrentMap[K, V]) Keys() []K
*
- Keys 获取所有键
- @returns {[]K} 键列表
func (*ConcurrentMap[K, V]) Range ¶
func (cm *ConcurrentMap[K, V]) Range(fn func(K, V) bool)
*
- Range 遍历所有键值对
- @param {func(K, V) bool} fn 遍历函数，返回false时停止遍历
func (*ConcurrentMap[K, V]) Set ¶
func (cm *ConcurrentMap[K, V]) Set(key K, value V)
*
- Set 设置键值对
- @param {K} key 键
- @param {V} value 值
func (*ConcurrentMap[K, V]) Size ¶
func (cm *ConcurrentMap[K, V]) Size() int
*
- Size 获取映射大小
- @returns {int} 大小
type Manager ¶
type Manager[T any] struct { // contains filtered or unexported fields }
Manager Token管理器结构体
func (*Manager[T]) AddToken ¶
*
- AddToken 新增token，通过它申请token，不存储用户数据，存储用户数据另外用SetUserData
- @param {uint} userID 用户ID
- @param {uint} groupID 用户组ID
- @param {string} clientIp 客户端IP地址
- @returns {string, error} token字符串和错误信息
func (*Manager[T]) Auth ¶
*
- Auth 专门负责对客户端访问指定API进行鉴权
- 包含完整的鉴权流程：Token验证、IP验证和API权限验证
- @param {string} key token字符串
- @param {string} clientIp 客户端IP地址
- @param {string} api 请求的API地址
- @returns {error} 鉴权结果
func (*Manager[T]) BatchAuth ¶
*
- BatchAuth 批量API权限检查
- 用于前端一次性检查多个API的访问权限
- @param {string} key token字符串
- @param {string} clientIp 客户端IP地址
- @param {[]string} apis 需要检查的API地址数组
- @returns {[]bool} 对应每个API的权限检查结果数组，true表示有权限，false表示无权限
func (*Manager[T]) BatchDeleteExpiredTokens ¶
*
- BatchDeleteExpiredTokens 批量删除过期token
- @returns {error} 操作结果错误信息
func (*Manager[T]) BatchDeleteTokensByGroupIDs ¶
*
- BatchDeleteTokensByGroupIDs 批量删除多个用户组的所有token
- @param {[]uint} groupIDs 用户组ID列表
- @returns {error} 操作结果错误信息
func (*Manager[T]) BatchDeleteTokensByUserIDs ¶
*
- BatchDeleteTokensByUserIDs 批量删除多个用户的所有token
- @param {[]uint} userIDs 用户ID列表
- @returns {error} 操作结果错误信息
func (*Manager[T]) CleanExpiredTokens ¶
func (tm *Manager[T]) CleanExpiredTokens()
*
- CleanExpiredTokens 清理过期token并更新缓存文件
func (*Manager[T]) DelToken ¶
*
- DelToken 删除指定的token
- @param {string} key token键
- @returns {error} 操作结果错误信息
func (*Manager[T]) DelTokensByGroupID ¶
*
- DelTokensByGroupID 删除指定用户组的所有token
- @param {uint} groupID 用户组ID
- @returns {error} 操作结果错误信息
func (*Manager[T]) DelTokensByUserID ¶
*
- DelTokensByUserID 删除指定用户的所有token
- @param {uint} userID 用户ID
- @returns {error} 操作结果错误信息
func (*Manager[T]) GetToken ¶
*
- GetToken 获取token数据
- @param {string} key token键
- @returns {*models.Token[T], error} token数据和错误信息
func (*Manager[T]) GetTokensByGroupID ¶
*
- GetTokensByGroupID 获取指定用户组的所有token
- @param {uint} groupID 用户组ID
- @returns {[]*models.Token[T]} token列表
func (*Manager[T]) GetTokensByUserID ¶
*
- GetTokensByUserID 获取指定用户的所有token
- @param {uint} userID 用户ID
- @returns {[]*models.Token[T]} token列表
func (*Manager[T]) GetUserData ¶
GetUserData 获取用户数据
func (*Manager[T]) SetUserData ¶
SetUserData 设置用户数据
func (*Manager[T]) UpdateAllGroup ¶
*
- UpdateAllGroup 批量更新所有用户组
- @param {[]models.GroupRaw} groups 用户组原始数据列表
- @returns {error} 操作结果错误信息
func (*Manager[T]) UpdateGroup ¶
UpdateGroup 更新用户组
type RWMutexWithTimeout ¶
type RWMutexWithTimeout struct {
// contains filtered or unexported fields
}
RWMutexWithTimeout 带超时的读写锁
func NewRWMutexWithTimeout ¶
func NewRWMutexWithTimeout(timeout time.Duration) *RWMutexWithTimeout
NewRWMutexWithTimeout 创建带超时的读写锁
func (*RWMutexWithTimeout) TryLockWithTimeout ¶
func (rw *RWMutexWithTimeout) TryLockWithTimeout(ctx context.Context) bool
*
- TryLockWithTimeout 尝试获取写锁（带超时）
- @param {context.Context} ctx 上下文
- @returns {bool} 是否成功获取锁
func (*RWMutexWithTimeout) TryRLockWithTimeout ¶
func (rw *RWMutexWithTimeout) TryRLockWithTimeout(ctx context.Context) bool
*
- TryRLockWithTimeout 尝试获取读锁（带超时）
- @param {context.Context} ctx 上下文
- @returns {bool} 是否成功获取锁
type SecurityManager ¶
type SecurityManager struct {
// contains filtered or unexported fields
}
*
- SecurityManager 安全管理器
func NewSecurityManager ¶
func NewSecurityManager(password string) *SecurityManager
*
- NewSecurityManager 创建一个新的安全管理器
- @param {string} password 密码
- @returns {*SecurityManager} 安全管理器实例
func NewSecurityManagerWithSalt ¶
func NewSecurityManagerWithSalt(password string, salt []byte) *SecurityManager
NewSecurityManagerWithSalt 创建一个带盐值的安全管理器
func (*SecurityManager) DecryptToken ¶
func (sm *SecurityManager) DecryptToken(ciphertext string) (string, error)
*
- DecryptToken 解密token数据
- @param {string} ciphertext 加密的token
- @returns {string, error} 解密后的token和错误
func (*SecurityManager) EncryptToken ¶
func (sm *SecurityManager) EncryptToken(plaintext string) (string, error)
*
- EncryptToken 加密token数据
- @param {string} plaintext 明文token
- @returns {string, error} 加密后的token和错误
func (*SecurityManager) HashSensitiveData ¶
func (sm *SecurityManager) HashSensitiveData(data string) string
*
- HashSensitiveData 对敏感数据进行哈希处理
- @param {string} data 敏感数据
- @returns {string} 哈希值
func (*SecurityManager) RotateKey ¶
func (sm *SecurityManager) RotateKey(newPassword string)
RotateKey 轮换密钥
type WorkerPool ¶
type WorkerPool struct {
// contains filtered or unexported fields
}
WorkerPool 工作池
func (*WorkerPool) Submit ¶
func (wp *WorkerPool) Submit(job func()) bool
*
- Submit 提交任务
- @param {func()} job 任务函数
- @returns {bool} 是否成功提交
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.