GolangJWT实现API认证详解

你在学习Golang相关的知识吗？本文《Golang JWT实现API认证教程》，主要介绍的内容就涉及到，如果你想提升自己的开发能力，就不要错过这篇文章，大家要知道编程理论基础和实战操作都是不可或缺的哦！

jwt-go v4+禁用none等不安全算法且Parse不校验签名，须用ParseWithClaims配合密钥回调和StandardClaims嵌入，并区分错误类型返回对应状态码。

为什么 jwt-go v4 之后的版本不能直接用 Parse 验证签名

因为 v4+ 默认禁用了不安全的算法（如 none），且 Parse 不再自动校验签名——它只解析结构，不验证 signature。如果你写了 token, _ := jwt.Parse(...) 却没调用 token.Valid 或手动验证，就等于完全绕过了认证。

正确做法是使用 ParseWithClaims 并传入密钥和自定义 Claims 类型，让库在解析时同步完成签名、过期、签发时间等全部校验。

• 必须显式提供 func(token *jwt.Token) (interface{}, error) 作为密钥回调，不能传裸字符串
• 如果用对称密钥（HS256），回调返回 []byte(yourSecret)
• 如果用非对称密钥（RS256），回调需根据 token.Method.Alg() 加载对应公钥
• 务必检查返回的 err 和 token.Valid：两者都为 nil/true 才算通过

如何安全地从 HTTP 请求中提取并验证 JWT

JWT 通常放在 Authorization: Bearer 头里，但很多初学者直接用 r.Header.Get("Authorization") 拿到后就 strings.Split，结果遇到空格缺失、大小写不一致或前缀缺失（比如传了 Bearer:）就 panic 或跳过验证。

推荐封装一个健壮的提取函数，统一处理边界情况：

func parseTokenFromRequest(r *http.Request, secret string) (*jwt.Token, error) {
	auth := r.Header.Get("Authorization")
	if auth == "" {
		return nil, errors.New("missing Authorization header")
	}
	parts := strings.Split(auth, " ")
	if len(parts) != 2 || strings.ToLower(parts[0]) != "bearer" {
		return nil, errors.New("invalid Authorization header format")
	}
	tokenStr := parts[1]

	keyFunc := func(t *jwt.Token) (interface{}, error) {
		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
			return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
		}
		return []byte(secret), nil
	}

	return jwt.ParseWithClaims(tokenStr, &CustomClaims{}, keyFunc)
}

注意：CustomClaims 必须嵌入 jwt.StandardClaims，否则 Valid 方法不会检查 exp/nbf 等字段。

怎样避免自定义 Claims 序列化时丢失标准字段

常见错误是定义 type CustomClaims struct { UserID uint `json:"user_id"` }，然后发现 token.Claims.(CustomClaims).ExpiresAt 总是 0 —— 因为没继承 jwt.StandardClaims，JSON 反序列化时根本不会填充这些字段。

正确结构必须显式嵌入：

type CustomClaims struct {
	UserID uint `json:"user_id"`
	jwt.StandardClaims
}

• StandardClaims 包含 Issuer、Subject、Audience、ExpiresAt、NotBefore、IssuedAt、ID
• 所有字段名必须首字母大写（导出），否则 JSON 解析失败
• 如果需要强制校验 aud 或 iss，要在 keyFunc 后额外调用 token.Claims.(jwt.Claims).Valid(...)

为什么中间件里解析失败不能只返回 401，还要区分错误类型

生产环境里，token expired 和 signature invalid 的处理逻辑不同：前者可引导前端刷新 token；后者大概率是恶意篡改或客户端 bug，应记录日志并限流。

直接用 errors.Is(err, jwt.ErrSignatureInvalid) 或检查 err.Error() 包含关键词太脆弱。更稳妥的是断言具体错误类型：

if errors.Is(err, jwt.ErrTokenExpired) {
	http.Error(w, "token expired", http.StatusUnauthorized)
	return
}
if errors.Is(err, jwt.ErrSignatureInvalid) {
	log.Printf("Invalid signature from IP: %s", r.RemoteAddr)
	http.Error(w, "forbidden", http.StatusForbidden)
	return
}
// 其他 err 统一视为 401

另外，token.Valid == false 但 err == nil 是可能的（比如过期但签名正确），这种情况也要单独判断并返回对应状态码。

别忘了：所有密钥硬编码在代码里、用 HS256 却把 secret 暴露在前端、token 存在 localStorage 被 XSS 窃取——这些都不是 JWT 本身的问题，而是集成时最容易忽略的落地细节。

到这里，我们也就讲完了《GolangJWT实现API认证详解》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！