4. Go语言中的JWT实现：JWT结构解析、使用golang-jwt库生成与验证Token、Token的签名与验签

4.1 JWT 结构解析：三段式令牌的构成

JWT（JSON Web Token）是一种紧凑的、URL 安全的令牌格式，由三个 Base64URL 编码的段组成，以点号（.）分隔。在 GoBFF 架构中，JWT 作为服务间传递身份与权限声明的载体，其结构必须被精确理解。

4.2 使用 golang-jwt 库：安装与核心类型

golang-jwt/jwt/v5 是 Go 社区最主流的 JWT 库，支持多种签名算法（HS256、RS256、ES256 等）。在 GoBFF 项目中，我们统一使用该库进行 Token 的生成与验证。

安装命令：

go get github.com/golang-jwt/jwt/v5

核心类型与接口：

• jwt.MapClaims：声明类型，本质是 map[string]interface{}，适合快速原型开发。
• jwt.RegisteredClaims：预定义的标准声明结构体，包含 iss、sub、exp、iat、jti 等字段。
• jwt.SigningMethodHMAC：HMAC 签名方法族（HS256、HS384、HS512）。
• jwt.Token：代表一个解析后的 JWT 对象，包含 Method、Header、Claims、Signature 等字段。

4.3 Token 的签名与生成：HS256 对称签名实战

对称签名（HMAC）使用同一个密钥进行签名和验签，适合内部服务间通信。在 GoBFF 的 BFF 层与下游服务之间，我们使用 HS256 作为默认签名算法。

生成 Token 的标准步骤：

1. 创建 Claims（声明），设置过期时间、主题、自定义权限字段。
2. 调用 jwt.NewWithClaims() 创建 Token 对象。
3. 调用 token.SignedString() 传入密钥，生成最终的 JWT 字符串。

package main

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

// 自定义 Claims 结构体，嵌入标准声明
type CustomClaims struct {
    UserID string   `json:"user_id"`
    Roles  []string `json:"roles"`
    jwt.RegisteredClaims
}

func GenerateToken(secret []byte) (string, error) {
    claims := CustomClaims{
        UserID: "user_12345",
        Roles:  []string{"admin", "bff_access"},
        RegisteredClaims: jwt.RegisteredClaims{
            ExpiresAt: jwt.NewNumericDate(time.Now().Add(2 * time.Hour)),
            IssuedAt:  jwt.NewNumericDate(time.Now()),
            Issuer:    "gobff-auth",
            Subject:   "access_token",
        },
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString(secret)
}

4.4 Token 的验签与解析：验证完整性与声明

验签是 BFF 网关和下游服务接收 Token 后的第一道防线。验签失败直接拒绝请求，不进入业务逻辑。

验签的核心流程：

1. 使用 jwt.ParseWithClaims() 方法，传入 Token 字符串和 Claims 结构体指针。
2. 在 KeyFunc 回调中返回验签密钥。
3. 检查返回的 Token 是否有效（token.Valid）。
4. 类型断言获取自定义 Claims。

func ValidateToken(tokenString string, secret []byte) (*CustomClaims, error) {
    token, err := jwt.ParseWithClaims(tokenString, &CustomClaims{}, func(token *jwt.Token) (interface{}, error) {
        // 关键校验：确认签名算法符合预期
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, jwt.ErrSignatureInvalid
        }
        return secret, nil
    })

    if err != nil {
        return nil, err
    }

    claims, ok := token.Claims.(*CustomClaims)
    if !ok || !token.Valid {
        return nil, jwt.ErrTokenInvalidClaims
    }

    return claims, nil
}

4.5 签名算法对比：对称 vs 非对称

在 GoBFF 架构中，不同场景需要选择不同的签名策略。下表对比了 HS256（对称）与 RS256（非对称）的核心差异：

4.6 常见错误与避坑指南

• Token 过期未处理：解析时 jwt.ParseWithClaims 默认会校验 exp 声明，过期 Token 会返回 jwt.ErrTokenExpired。业务层应捕获该错误并返回 401 状态码。
• 忽略 iat 和 nbf：iat（签发时间）和 nbf（生效时间）可用于防止 Token 重放攻击。建议在签发时设置 nbf 为当前时间，避免时钟偏差问题。
• 密钥长度不足：HS256 要求密钥至少 32 字节。使用 []byte("short") 会导致签名强度不足，容易被暴力破解。
• 未校验 iss 和 aud：在多服务架构中，应校验 Token 的签发者（iss）和受众（aud），防止一个服务的 Token 被其他服务滥用。