Go语言原生实现JWT的完整示例

Alice

发布时间：2026-10-15| 4人浏览过

原创

JWT（JSON Web Token）是一种广泛应用于系统间传输认证信息的安全令牌。在Go语言开发中，虽然有许多成熟的第三方库可用，但掌握其底层原理至关重要。本文详细展示了如何利用 Go 的标准库（如 crypto/hmac、crypto/sha256 等）原生编写 JWT 的生成与解析代码，并结合 Gin 框架提供完整的中间件鉴权示例。

目标与准备条件

我们的目标是构建一个轻量级且安全的 JWT 工具包，支持标准的 HS256 算法。无需引入任何第三方依赖，仅使用 Go 内置模块即可完成。主要涉及三个核心部分：

结构体定义：包含头部（Header）、负载（Payload）和签名（Signature）。
签名算法：使用 HMAC-SHA256 对前两部分内容进行加密处理。
编解码逻辑：将数据转换为 Base64Url 格式进行拼接与还原。

第1步：定义JWT结构与基础工具函数

首先封装基础的 JWT 结构体和辅助函数。为了保持简洁，我们将结构体的字段设为私有。

type JWT struct {
	header    string
	Payload   string
	signature string
}

接着封装 Base64 编码方法，JWT 规范要求使用 URL 安全的原始 Base64 编码：

func encodeBase64(data string) string {
	return base64.RawURLEncoding.EncodeToString([]byte(data))
}

封装签名生成方法，使用 crypto/hmac 和 crypto/sha256：

func generateSignature(key []byte, data []byte) (string, error) {
	hash := hmac.New(sha256.New, key)
	_, err := hash.Write(data)
	if err != nil {
		return "", err
	}
	// 计算摘要并进行 Base64 编码
	return encodeBase64(string(hash.Sum(nil))), nil
}

第2步：实现Token创建(CreateToken)

此步骤负责构建合法的 JWT 字符串。流程为：序列化 Payload -> 拼接 Header.Payload -> 计算签名 -> 输出最终 Token。

func CreateToken(key []byte, payloadData any) (string, error) {
	// 1. 定义标准头部
	header := `{"alg":"HS256","typ":"JWT"}`
	
	// 2. 将负载数据序列化为 JSON
	payload, jsonErr := json.Marshal(payloadData)
	if jsonErr != nil {
		return "", fmt.Errorf("负载json解析错误")
	}
	
	// 3. Base64 编码头部和负载，并用 "." 连接
	encodedHeader := encodeBase64(header)
	encodedPayload := encodeBase64(string(payload))
	headerAndPayload := encodedHeader + "." + encodedPayload
	
	// 4. 生成签名
	signature, err := generateSignature(key, []byte(headerAndPayload))
	if err != nil {
		return "", err
	}
	
	// 5. 拼接三部分返回
	return headerAndPayload + "." + signature, nil
}

第3步：实现Token解析(ParseJwt)

解析时需要严格校验签名的有效性，防止恶意伪造的 Token。如果签名不一致或格式不对，应立即拒绝。

func ParseJwt(token string, key []byte) (*JWT, error) {
	// 1. 分割 Token 字符串
	jwtParts := strings.Split(token, ".")
	if len(jwtParts) != 3 {
		return nil, fmt.Errorf("非法token")
	}
	
	encodedHeader := jwtParts[0]
	encodedPayload := jwtParts[1]
	signature := jwtParts[2]
	
	// 2. 重新计算签名以验证合法性
	confirmSignature, err := generateSignature(key, []byte(encodedHeader+"."+encodedPayload))
	if err != nil {
		return nil, fmt.Errorf("生成签名错误")
	}
	
	// 3. 比对签名，确保 Token 未被篡改
	if signature != confirmSignature {
		return nil, fmt.Errorf("token验证失败")
	}
	
	// 4. 解码负载并返回对象
	dstPayload, _ := base64.RawURLEncoding.DecodeString(encodedPayload)
	return &JWT{encodedHeader, string(dstPayload), signature}, nil
}

实际使用与测试场景

下面结合 gin 框架构建一个简单的 API 服务，演示如何注册中间件以及不同情况下的返回结果。

准备工作：密钥与数据结构

定义用户结构体和测试用的简单密钥：

type UserInfo struct {
	Name     string `json:"name"`
	Password string `json:"password"`
}
var Key []byte = []byte("123456") // 生产环境应使用强随机密钥

配置鉴权中间件

在 Gin 路由中使用自定义中间件拦截请求，白名单排除登录接口：

func jwtConfirm(context *gin.Context) {
	if context.Request.RequestURI == "/login" {
		context.Next()
		return
	}
	token := context.GetHeader("Token")
	jwtObj, err := utils.ParseJwt(token, Key)
	if err != nil {
		context.JSON(200, gin.H{"msg": err.Error()})
		context.Abort()
		return
	}
	context.JSON(200, gin.H{"payload": jwtObj.Payload})
}

主程序路由逻辑

实现 /login 用于获取 Token，以及受保护的 /doing 接口：

func main() {
	router := gin.Default()
	router.Use(jwtConfirm)
	
	router.POST("/login", func(context *gin.Context) {
		var userInfo UserInfo
		if bindErr := context.ShouldBindJSON(&userInfo); bindErr != nil {
			context.JSON(200, gin.H{"msg": bindErr.Error()})
			return
		}
		token, err := utils.CreateToken(Key, userInfo)
		if err != nil {
			context.JSON(500, gin.H{"err": err.Error()})
			return
		}
		context.JSON(200, gin.H{"token": token})
	})
	
	router.GET("/doing", func(context *gin.Context) {
		context.JSON(200, gin.H{"msg": "访问成功"})
	})
	
	router.Run()
}