Golang登录状态管理库 - Token-go的使用指南

Token-go 是一个设计精良的Go语言登录状态管理库，它通过封装复杂的会话逻辑，为Web应用提供了简洁而强大的认证授权能力。以下是对其核心功能的使用指南和代码示例。

1. 核心概念与初始化

首先，你需要创建一个Enforcer实例，它是所有操作的核心。

import (
    "github.com/weloe/token-go"
    "github.com/weloe/token-go/config"
)

func main() {
    // 创建配置，通常从配置文件或环境变量加载
    conf := &config.Config{
        SecretKey: "your-secret-key", // 用于签名Token的密钥
        Timeout:   3600,              // Token默认超时时间（秒）
    }
    
    // 创建Enforcer实例
    enforcer, err := tokenGo.NewEnforcer(conf)
    if err != nil {
        panic(err)
    }
    
    // 通常会将enforcer保存为全局变量或通过依赖注入使用
}

2. 登录与令牌管理

登录操作会创建会话并返回令牌。

func loginHandler(w http.ResponseWriter, req *http.Request) {
    // 假设验证用户名密码后获得用户ID "user123"
    userID := "user123"
    
    // 执行登录，创建会话
    token, err := enforcer.Login(userID, tokenGo.NewHttpContext(req, w))
    if err != nil {
        http.Error(w, "登录失败", http.StatusInternalServerError)
        return
    }
    
    // token会自动通过Cookie或响应头返回给客户端
    // 你也可以手动处理它
    w.Write([]byte("登录成功，Token: " + token))
}

3. 会话状态检查与登出

中间件是检查登录状态的常见模式。

func authMiddleware(next http.HandlerFunc) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        ctx := tokenGo.NewHttpContext(r, w)
        
        // 检查是否已登录
        isLogin, err := enforcer.IsLogin(ctx)
        if err != nil || !isLogin {
            http.Error(w, "未授权", http.StatusUnauthorized)
            return
        }
        
        // 获取当前登录的用户ID
        loginID, err := enforcer.GetLoginID(ctx)
        if err != nil {
            http.Error(w, "会话异常", http.StatusInternalServerError)
            return
        }
        
        // 可以将用户ID存入请求上下文，供后续处理使用
        ctxWithUser := context.WithValue(r.Context(), "userID", loginID)
        next.ServeHTTP(w, r.WithContext(ctxWithUser))
    }
}

// 受保护的路由
func profileHandler(w http.ResponseWriter, r *http.Request) {
    userID := r.Context().Value("userID").(string)
    w.Write([]byte("用户 " + userID + " 的个人资料"))
}

// 登出
func logoutHandler(w http.ResponseWriter, r *http.Request) {
    err := enforcer.Logout(tokenGo.NewHttpContext(r, w))
    if err != nil {
        http.Error(w, "登出失败", http.StatusInternalServerError)
        return
    }
    w.Write([]byte("已登出"))
}

4. 高级会话控制

库提供了丰富的会话管理功能。

// 封禁用户
// 将用户"user123"在"login"业务场景下封禁100秒
err := enforcer.Banned("user123", "login", 1, 100)

// 踢出用户（强制使其所有会话下线）
err := enforcer.Kickout("user123")

// 检查用户是否被封禁
isBanned, err := enforcer.IsBanned("user123", "login")

5. 适配器与持久化

默认使用内存存储，生产环境建议使用Redis适配器。

import (
    "github.com/weloe/token-go/redisadapter"
    "github.com/go-redis/redis/v8"
)

func main() {
    // 创建Redis客户端
    redisOpts := &redis.Options{
        Addr: "localhost:6379",
    }
    
    // 创建Redis适配器
    adapter, err := redisadapter.NewAdapter(redisOpts)
    if err != nil {
        panic(err)
    }
    
    // 使用适配器创建Enforcer
    conf := &config.Config{
        SecretKey: "your-secret-key",
        Timeout:   3600,
        Adapter:   adapter, // 注入Redis适配器
    }
    
    enforcer, err := tokenGo.NewEnforcer(conf)
    if err != nil {
        panic(err)
    }
}

6. 多账户系统与登录策略

库支持复杂的多账户场景。

// 以不同身份登录同一设备（多账户系统登录）
token1, err := enforcer.Login("user123", tokenGo.NewHttpContext(req, w))
token2, err := enforcer.Login("admin456", tokenGo.NewHttpContext(req, w))

// 配置同端互斥登录（同一类型设备只允许一个会话）
conf := &config.Config{
    SecretKey: "your-secret-key",
    Timeout:   3600,
    LoginModel: tokenGo.LoginModelKick, // 新登录会踢掉旧会话
}

7. 权限验证示例

库内置了角色和权限验证支持。

// 为用户添加角色和权限
enforcer.AddRoleForUser("user123", "admin")
enforcer.AddPermissionForUser("user123", "article:delete")

// 验证权限
hasPerm, err := enforcer.HasPermission("user123", "article:delete")
if hasPerm {
    // 允许执行删除操作
}

// 临时令牌（用于一次性操作）
tempToken, err := enforcer.CreateTempToken("user123", 300) // 5分钟有效

Token-go通过合理的默认配置和清晰的API设计，显著降低了在Go中实现专业级认证系统的复杂度。其模块化设计也便于根据具体需求进行定制和扩展。