快速开始

安装

go get github.com/cybergodev/jwt

要求 Go 1.25+。

基础使用

1. 创建 Processor

package main

import (
    "fmt"
    "time"

    "github.com/cybergodev/jwt"
)

func main() {
    cfg := jwt.DefaultConfig()
    cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!" // HMAC 至少 32 字节
    cfg.AccessTokenTTL = 15 * time.Minute
    cfg.RefreshTokenTTL = 7 * 24 * time.Hour

    processor, err := jwt.New(cfg)
    if err != nil {
        panic(err)
    }
    defer processor.Close() // 安全清除密钥
}

2. 签发令牌

claims := &jwt.Claims{
    UserID:   "user123",
    Username: "alice",
    Role:     "admin",
    Permissions: []string{"read", "write"},
}

// 访问令牌（短期）
accessToken, err := processor.Create(claims)
if err != nil {
    panic(err)
}

// 刷新令牌（长期）
refreshToken, err := processor.CreateRefresh(claims)
if err != nil {
    panic(err)
}

3. 验证令牌

parsed, valid, err := processor.Validate(accessToken)
if err != nil {
    // 处理错误：过期、签名无效等
    panic(err)
}
if valid {
    fmt.Println("UserID:", parsed.UserID)
    fmt.Println("Role:", parsed.Role)
    fmt.Println("ExpiresAt:", parsed.ExpiresAt.Time)
}

4. 刷新令牌

newAccessToken, err := processor.Refresh(refreshToken)
if err != nil {
    panic(err)
}
fmt.Println("New Access Token:", newAccessToken)

5. 吊销令牌

// 将令牌加入黑名单
err := processor.Revoke(accessToken)
if err != nil {
    panic(err)
}

// 检查是否已吊销
revoked, err := processor.IsRevoked(accessToken)
if err != nil {
    panic(err)
}
fmt.Println("Revoked:", revoked) // true

更多功能

以上涵盖了令牌生命周期的核心操作。CyberGo JWT 还提供以下功能，点击进入对应指南获取详细用法：

功能	说明	指南
签名算法	HMAC、RSA、RSA-PSS、ECDSA 四类 12 种算法	签名算法
自定义 Claims	通过 CustomClaims 接口定义业务字段	自定义 Claims
令牌刷新与轮换	双层令牌 TTL 设计、重用与一次性轮换策略	令牌刷新与轮换
令牌黑名单	吊销机制、内置存储与 Redis 自定义后端	令牌黑名单
速率限制	令牌桶算法，防止签发接口被滥用	速率限制
配置详解	签发者/受众校验、时钟偏移、强制过期、输入校验	配置详解
错误处理	19 个哨兵错误分类与 errors.Is 匹配	错误处理
测试与时钟注入	FixedClock 固定时钟，精确控制时间流逝	测试与时钟注入

下一步

• 签名算法 — 算法选择与密钥配置
• 令牌刷新与轮换 — 双层令牌与轮换策略
• 配置详解 — 安全配置与输入校验
• API 参考 — 完整 API 参考文档
• 基础示例 — 可运行的完整示例
• Web 服务器集成 — 认证中间件与 RBAC 实战