📚 课程目录第4章 JWT令牌解析与验证

4. JWT 令牌解析与验证：使用 golang-jwt 库实现 Token 的签发、解析与权限提取

JWT（JSON Web Token）是微服务网关中最常用的无状态认证载体。本章将基于 golang-jwt/jwt/v5 库，从零实现 Token 的签发、解析与权限声明提取，并集成到网关的 Mock 隔离环境中。

4.1 JWT 结构回顾与核心字段

一个标准 JWT 由三部分组成：Header、Payload、Signature，以 Base64URL 编码后通过 . 连接。在网关场景中，Payload 内的 sub、exp、iat 以及自定义权限字段最为关键。

字段	位置	说明	网关用途
`sub`	Payload	用户唯一标识（User ID）	路由鉴权、日志审计
`exp`	Payload	过期时间（Unix 时间戳）	Token 有效性校验
`iat`	Payload	签发时间	防重放、Token 生命周期管理
`roles`	Payload（自定义）	角色列表（如 `["admin","editor"]`）	权限提取与访问控制
`permissions`	Payload（自定义）	细粒度权限标识（如 `["read:order","write:user"]`）	接口级权限校验

4.2 使用 golang-jwt 签发 Token

首先安装依赖：

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

签发 Token 时需要指定签名算法（推荐 HS256 或 RS256），并构造自定义 Claims 结构体。以下示例使用 HMAC-SHA256 对称签名：

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

// 自定义 Claims，嵌入标准 Claims
type CustomClaims struct {
    UserID      string   `json:"sub"`
    Roles       []string `json:"roles"`
    Permissions []string `json:"permissions"`
    jwt.RegisteredClaims
}

// 签发 Token
func SignToken(secret []byte, userID string, roles, perms []string) (string, error) {
    claims := CustomClaims{
        UserID:      userID,
        Roles:       roles,
        Permissions: perms,
        RegisteredClaims: jwt.RegisteredClaims{
            ExpiresAt: jwt.NewNumericDate(time.Now().Add(2 * time.Hour)),
            IssuedAt:  jwt.NewNumericDate(time.Now()),
            Issuer:    "go-auth-gateway",
        },
    }
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString(secret)
}

最佳实践：对称签名（HS256）适合内部网关间通信；若涉及多服务或第三方，建议使用非对称签名（RS256/ES256），私钥签发、公钥验证，避免密钥泄露风险。

4.3 Token 解析与验证

解析 Token 时需同时完成签名验证、过期检查、Claims 提取。golang-jwt/v5 提供了 ParseWithClaims 方法，支持自定义验证选项：

func ParseAndVerify(tokenStr string, secret []byte) (*CustomClaims, error) {
    token, err := jwt.ParseWithClaims(tokenStr, &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
    }
    if claims, ok := token.Claims.(*CustomClaims); ok && token.Valid {
        return claims, nil
    }
    return nil, jwt.ErrTokenInvalidClaims
}

安全注意：必须显式校验 token.Method 是否为预期算法。攻击者可能将 RS256 改为 HS256 并利用公钥作为 HMAC 密钥伪造 Token，导致签名绕过。

4.4 权限提取与结构化输出

解析成功后，从 Claims 中提取 Roles 和 Permissions，供后续网关中间件做访问控制决策。以下函数将 Claims 转换为统一的权限上下文：

type AuthContext struct {
    UserID      string
    Roles       []string
    Permissions []string
}

func ExtractAuthContext(claims *CustomClaims) *AuthContext {
    return &AuthContext{
        UserID:      claims.UserID,
        Roles:       claims.Roles,
        Permissions: claims.Permissions,
    }
}

在网关的 Mock 隔离环境中，可将 AuthContext 注入到请求的 context.Context 中，下游服务通过 ctx.Value("auth") 获取权限信息，无需再次解析 Token。

4.5 完整流程：签发 → 解析 → 权限提取

下图展示了 JWT 在网关 Mock 隔离中的完整生命周期：

4.6 常见错误与调试

在 Mock 隔离测试中，Token 解析失败通常由以下原因导致：

签名不匹配：签发与解析使用的 secret 不一致，或算法类型不匹配。
Token 过期：exp 时间早于当前时间，golang-jwt 默认返回 ErrTokenExpired。
Claims 类型断言失败：自定义 Claims 结构体字段未导出（小写开头）或 JSON 标签缺失。
Base64 填充错误：JWT 标准要求去除 Base64 填充符 =，golang-jwt 自动处理，但手动拼接时易出错。

调试技巧：使用 jwt.NewParser(jwt.WithValidMethods([]string{"HS256"})) 显式指定允许的算法列表，可快速定位算法混淆问题。在 Mock 测试中，建议将解析错误日志输出到标准输出，便于追踪。

4.7 在 Mock 隔离中集成 Token 验证

在网关的 Mock 中间件中，将 Token 解析与权限提取封装为一个独立函数，供路由处理前调用：

func MockAuthMiddleware(secret []byte) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            tokenStr := extractTokenFromHeader(r)
            if tokenStr == "" {
                http.Error(w, "missing token", http.StatusUnauthorized)
                return
            }
            claims, err := ParseAndVerify(tokenStr, secret)
            if err != nil {
                http.Error(w, "invalid token: "+err.Error(), http.StatusUnauthorized)
                return
            }
            authCtx := ExtractAuthContext(claims)
            ctx := context.WithValue(r.Context(), "auth", authCtx)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

func extractTokenFromHeader(r *http.Request) string {
    authHeader := r.Header.Get("Authorization")
    if len(authHeader) > 7 && authHeader[:7] == "Bearer " {
        return authHeader[7:]
    }
    return ""
}

通过上述实现，网关可在不依赖真实认证中心的情况下，使用预签发的 Mock Token 完成权限验证，实现业务逻辑的快速迭代与测试。