基于Go语言JWT的刷新令牌实现方案的完整详解

核心设计思路非常清晰：采用双令牌机制协同工作——短期有效的 access_token 负责日常接口访问，长期有效的 refresh_token 专门用于获取新的 access_token。这种方案在保障安全性的同时，也兼顾了用户体验的流畅性。

接下来直接进入设计方案与具体实现环节，您可以按照这套思路快速落地。

1. 双令牌核心设计思路

双令牌机制构成了整套方案的基础架构，其目标十分明确：在确保用户体验不受影响的前提下，将安全风险降至最低。

• Access Token（访问令牌）：有效期较短，通常设置为 15 分钟至 2 小时。该令牌携带用户身份标识与权限信息，专门用于保护 API 接口安全。
• Refresh Token（刷新令牌）：有效期较长，一般设置为 24 小时至 7 天。该令牌的唯一用途是申请新的 Access Token，因此切勿在其中嵌入业务相关的自定义数据。

整个认证流程非常清晰：

• 登录阶段：服务端同步生成 access_token 与 refresh_token，将 refresh_token 的哈希值存入数据库（严禁存储原始 token），最后将两个令牌一同返回给客户端。
• 访问阶段：客户端每次发起请求时携带 access_token，服务端验证通过则放行，过期则拒绝访问。
• 刷新阶段：access_token 过期后，客户端使用 refresh_token 请求 /refresh 接口。服务端验证通过后，生成一对全新的 token 返回，并同时废弃旧的 refresh_token。
• 退出阶段：将该用户的 refresh_token 从数据库中删除或标记为失效状态。

2. 具体实现步骤详解

第一步：定义 Token 管理器与结构体

首先构建一个核心结构体，将 token 的生成与验证逻辑进行封装。基于 github.com/golang-jwt/jwt/v5 这一主流库进行开发，能够大幅简化工作。

import (
    "time"
    "github.com/golang-jwt/jwt/v5"
)

// JWTManager 负责管理 JWT
type JWTManager struct {
    secretKey          []byte
    accessTokenExpiry  time.Duration
    refreshTokenExpiry time.Duration
    issuer             string
}

// NewJWTManager 是构造函数
func NewJWTManager(secret string, accessExp, refreshExp time.Duration, issuer string) *JWTManager {
    return &JWTManager{
        secretKey:          []byte(secret),
        accessTokenExpiry:  accessExp,
        refreshTokenExpiry: refreshExp,
        issuer:             issuer,
    }
}

第二步：生成 Token 对

登录成功后直接调用此方法，即可同时获取 access_token 和 refresh_token。

// TokenPair 包含返回给客户端的两个 token 和它们的过期时间
type TokenPair struct {
    AccessToken           string    `json:"access_token"`
    RefreshToken          string    `json:"refresh_token"`
    AccessTokenExpiresAt  time.Time `json:"access_token_expires_at"`
    RefreshTokenExpiresAt time.Time `json:"refresh_token_expires_at"`
}

// GenerateTokenPair 为给定用户生成一对新 token
func (m *JWTManager) GenerateTokenPair(userID string) (*TokenPair, error) {
    now := time.Now()
    accessExp := now.Add(m.accessTokenExpiry)
    refreshExp := now.Add(m.refreshTokenExpiry)

    // 1. 生成 Access Token (携带用户自定义信息)
    accessClaims := &jwt.RegisteredClaims{
        Subject:   userID,
        Issuer:    m.issuer,
        IssuedAt:  jwt.NewNumericDate(now),
        ExpiresAt: jwt.NewNumericDate(accessExp),
    }
    accessToken, err := jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims).SignedString(m.secretKey)
    if err != nil {
        return nil, err
    }

    // 2. 生成 Refresh Token (只含标准声明，不含业务数据)
    refreshClaims := &jwt.RegisteredClaims{
        Subject:   userID,
        Issuer:    m.issuer,
        IssuedAt:  jwt.NewNumericDate(now),
        ExpiresAt: jwt.NewNumericDate(refreshExp),
    }
    refreshToken, err := jwt.NewWithClaims(jwt.SigningMethodHS256, refreshClaims).SignedString(m.secretKey)
    if err != nil {
        return nil, err
    }

    return &TokenPair{
        AccessToken:           accessToken,
        RefreshToken:          refreshToken,
        AccessTokenExpiresAt:  accessExp,
        RefreshTokenExpiresAt: refreshExp,
    }, nil
}

第三步：实现刷新逻辑

这是整个机制中最关键的环节。客户端使用 refresh_token 换取新的 access_token，逻辑必须清晰严谨。

// RefreshAccessToken 验证 refresh token 并生成新的 access token
func (m *JWTManager) RefreshAccessToken(refreshTokenStr string) (string, error) {
    // 1. 验证 refresh token 的签名和有效期
    token, err := jwt.Parse(refreshTokenStr, func(token *jwt.Token) (interface{}, error) {
        return m.secretKey, nil
    })
    if err != nil {
        return "", err // token 无效或过期
    }
    if !token.Valid {
        return "", jwt.ErrTokenInvalid
    }

    // 2. 从 token 中提取用户 ID (subject)
    claims, ok := token.Claims.(jwt.MapClaims)
    if !ok {
        return "", jwt.ErrTokenInvalid
    }
    userID, ok := claims["sub"].(string)
    if !ok || userID == "" {
        return "", jwt.ErrTokenInvalid
    }

    // 3. 生成一个全新的 access token
    newClaims := &jwt.RegisteredClaims{
        Subject:   userID,
        Issuer:    m.issuer,
        IssuedAt:  jwt.NewNumericDate(time.Now()),
        ExpiresAt: jwt.NewNumericDate(time.Now().Add(m.accessTokenExpiry)),
    }
    newAccessToken, err := jwt.NewWithClaims(jwt.SigningMethodHS256, newClaims).SignedString(m.secretKey)
    if err != nil {
        return "", err
    }

    return newAccessToken, nil
}

3. 数据库层：安全存储 Refresh Token

为确保安全可控，强烈建议服务端对每个 refresh_token 进行追踪，而非完全无状态运行。可以创建一张 sessions 或 refresh_tokens 表：

登录时，先计算 refresh_token 的哈希值并存入 refresh_token_hash 字段；刷新时，根据客户端传入的 refresh_token 计算哈希，再到数据库中进行匹配验证。

此外，最核心的安全机制是令牌轮换（Token Rotation）。每次刷新时，不仅需要生成新的 access_token，还必须同时生成新的 refresh_token，并用新的哈希值替换数据库中的旧记录。这一措施能够有效防止单个 refresh_token 被多次滥用。

// 在刷新接口的处理函数中，伪代码逻辑
func handleRefresh(refreshTokenStr string) {
    // 1. 计算哈希值并从 DB 查找
    hash := sha256.Sum256([]byte(refreshTokenStr))
    session, err := db.FindByRefreshHash(hex.EncodeToString(hash[:]))
    if err != nil {
        // token 无效或已撤销
        return
    }
    // 2. 验证 token 是否过期 (JWT 库会做，但数据库也要校验)
    if session.ExpiresAt.Before(time.Now()) {
        return
    }
    // 3. 生成全新的 token 对 (这就是 token rotation)
    newPair, err := jwtManager.GenerateTokenPair(session.UserID)
    // 4. 原子性地在数据库中删除旧记录，插入新记录
    err = db.ReplaceRefreshHash(session.RefreshTokenHash, newPair.RefreshTokenHash)
    if err != nil {
        // 处理错误...
    }
    // 5. 将新的 access_token 和 refresh_token 返回给客户端
    return newPair
}

总结与最佳实践

• 核心库：推荐使用 github.com/golang-jwt/jwt/v5 进行 JWT 的创建与验证，高效便捷。
• 双令牌机制：access_token 有效期短、携带业务信息；refresh_token 有效期长、仅用于刷新操作。
• 安全存储：服务端仅存储 refresh_token 的哈希值而非原文，这是安全底线。
• 令牌轮换：每次刷新操作均颁发全新的 access_token + refresh_token 对，并废弃旧的 refresh_token，这是推荐的最佳实践方案。

如需查看更完整的项目示例，可以参考 github.com/Jaro-c/authcore 仓库中的 auth/jwt 模块，其中从登录到令牌轮换的完整流程均有清晰演示。