GToken 介绍 - 基于 GoFrame 的 Token 认证插件

什么是 GToken？#

GToken 是一个基于 GoFrame 框架开发的 token 认证插件，通过服务端验证方式实现 token 认证。它已经完全可以支撑线上 token 认证，并通过 Redis 支持集群模式。

版本适配#

GoFrame v2.X.X：使用 gtoken v2.x 版本
GoFrame v1.X.X：使用 gtoken v1.4.x 版本

GToken 的优势#

相比传统的 JWT 方案，GToken 具有以下显著优势：

1. 支持服务端退出#

有效的避免了 JWT 服务端无法退出问题。在 JWT 方案中，一旦令牌颁发，在过期前都无法主动使其失效，而 GToken 通过服务端存储，可以随时销毁令牌。

2. 令牌可作废#

解决 JWT 无法作废已颁布的令牌，只能等到令牌过期问题。通过服务端存储，可以随时调用 Destroy 方法使令牌立即失效。

3. 高效的扩展信息存储#

通过用户扩展信息存储在服务端，有效规避了 JWT 携带大量用户扩展信息导致降低传输效率问题。JWT 需要在每个请求的 token 中携带用户信息，而 GToken 只在服务端存储，客户端只保存 token 本身。

4. 自动续期#

有效避免 JWT 需要客户端实现续签功能，增加客户端复杂度。GToken 支持服务端自动续期，客户端不需要关心续签逻辑。

1
// 通过 MaxRefresh 配置，默认当用户第五天访问时，自动续期
2
// 超时时间 默认 10 天
3
Timeout int
4
// 缓存刷新时间 默认为超时时间的一半
5
MaxRefresh int

特性说明#

支持 token 认证：不强依赖于 session 和 cookie，适用 JWT 和 session 认证所有场景
多种缓存模式：支持单机 gcache 和集群 gredis 模式

1
// 缓存模式 1 gcache 2 gredis 3 fileCache
2
CacheMode = 2

安装#

获取最新版本：

1
go get -u -v github.com/goflyfox/gtoken/v2

快速开始#

1. 初始化配置#

1
import (
2
    "github.com/goflyfox/gtoken/v2"
3
)
4

5
// 创建 gtoken 对象
6
gfToken := gtoken.NewDefaultToken(gtoken.Options{
7
    CacheMode:    2,              // 1 gcache 2 gredis 3 fileCache
8
    CachePreKey:  "GToken:",      // 缓存 key 前缀
9
    Timeout:      10 * 24 * 3600, // 超时时间 10 天（秒）
10
    MaxRefresh:   5 * 24 * 3600,  // 缓存刷新时间 5 天（秒）
11
    TokenDelimiter: "_",          // Token 分隔符
12
    EncryptKey:   "12345678912345678912345678912345", // Token 加密 key
13
    MultiLogin:   false,          // 是否支持多端登录
14
    AuthExcludePaths: []string{"/login", "/register"}, // 拦截排除地址
15
})

2. 注册认证中间件#

1
s := ghttp.NewServer()
2
s.SetPort(8199)
3

4
s.Group("/", func(group *ghttp.RouterGroup) {
5
    group.Middleware(CORS)
6
    // 注册 GfToken 中间件
7
    group.Middleware(gtoken.NewDefaultMiddleware(gfToken).Auth)
8

9
    // 需要认证的路由
10
    group.ALL("/system/data", func(r *ghttp.Request) {
11
        // 获取登陆信息
12
        ctx := r.Context()
13
        userKey := r.GetCtxVar(gtoken.KeyUserKey).String()
14
        _, data, err := gfToken.Get(ctx, userKey)
15
        if err != nil {
16
            r.Response.WriteJson(g.Map{"code": 500, "msg": err.Error()})
17
            return
18
        }
19
        r.Response.WriteJson(g.Map{"code": 0, "data": data})
20
    })
21

22
    // 登出路由
23
    group.ALL("/user/logout", func(r *ghttp.Request) {
24
        ctx := r.Context()
25
        userKey := r.GetCtxVar(gtoken.KeyUserKey).String()
26
        _ = gfToken.Destroy(ctx, userKey)
27
        r.Response.WriteJson(g.Map{"code": 0, "msg": "user logout"})
28
    })
29
})

3. 登录生成 Token#

1
s.BindHandler("/login", func(r *ghttp.Request) {
2
    ctx := r.Context()
3
    username := r.Get("username").String()
4
    password := r.Get("password").String()
5

6
    // 验证用户名密码（这里省略验证逻辑）
7
    if !validateUser(username, password) {
8
        r.Response.WriteJson(g.Map{"code": 401, "msg": "invalid credentials"})
9
        return
10
    }
11

12
    // 认证成功调用 Generate 生成 Token
13
    token, err := gfToken.Generate(ctx, username, "1")
14
    if err != nil {
15
        r.Response.WriteJson(g.Map{"code": 500, "msg": err.Error()})
16
        r.ExitAll()
17
        return
18
    }
19

20
    r.Response.WriteJson(g.Map{
21
        "code": 0,
22
        "data": g.Map{
23
            gtoken.KeyUserKey: username,
24
            gtoken.KeyToken:   token,
25
        },
26
    })
27
})
28

29
func validateUser(username, password string) bool {
30
    // 实现用户验证逻辑
31
    return true
32
}

配置项说明#

名称	配置字段	说明
缓存模式	`CacheMode`	1 gcache 2 gredis 3 fileCache 默认 1
缓存 key	`CachePreKey`	默认缓存前缀 GToken:
超时时间	`Timeout`	默认 10 天（秒）
缓存刷新时间	`MaxRefresh`	默认为超时时间的一半（秒）
Token 分隔符	`TokenDelimiter`	默认 `_`
Token 加密 key	`EncryptKey`	默认 12345678912345678912345678912345
是否支持多端登录	`MultiLogin`	默认 false
拦截排除地址	`AuthExcludePaths`	此路径列表不进行认证
拦截返回函数	`ResFun`	认证失败返回函数，默认返回 Code：300

使用建议#

由于中间件采用洋葱模型，注册 MiddlewareAuth 认证中间件时，建议放在：

在 MiddlewareCORS 之后：确保跨域处理优先
在用户权限 MiddlewareUserPermissions 认证之前：确保先认证再授权
在 Response 处理 MiddlewareHandlerResponse 之前：确保响应处理正确

1
s.Group("/", func(group *ghttp.RouterGroup) {
2
    group.Middleware(CORS)                    // 1. CORS 中间件
3
    group.Middleware(gtoken.NewDefaultMiddleware(gfToken).Auth) // 2. Token 认证
4
    group.Middleware(MiddlewareUserPermissions) // 3. 权限验证
5
    // ... 业务路由
6
})

项目扩展#

GToken-JWT#

如果需要短期 token 场景，可以使用 gtoken-jwt，这是基于 gtoken 的 JWT 扩展。

总结#

GToken 是一个功能完善、适用于企业生产级的 token 认证插件。它通过服务端存储的方式，有效解决了 JWT 的多个痛点问题：

✅ 支持服务端主动退出
✅ 令牌可随时作废
✅ 高效的扩展信息存储
✅ 服务端自动续期
✅ 支持单机和集群模式

如果你的项目基于 GoFrame 框架，并且需要可靠的 token 认证方案，GToken 是一个值得考虑的选择。

参考资源#

Gitee: https://gitee.com/goflyfox/gtoken
GitHub: https://github.com/goflyfox/gtoken
GoFrame: https://github.com/gogf/gf