JWT解析失败时Echo默认返回500而非401，根本原因在于中间件未显式捕获jwt.Parse抛出的异常（如jwt.ErrTokenMalformed）且错误强转claims导致panic，触发Echo默认500响应；正确做法是先检查err非空，再验证token.Valid，统一返回401。
JWT解析失败时Echo默认返回500而非401
Echo框架本身不内置JWT验证逻辑，通常依赖github.com/gofrs/uuid或github.com/golang-jwt/jwt/v5等库做解析。但关键点在于：如果中间件里没显式捕获jwt.Parse抛出的错误（比如jwt.ErrSignatureInvalid、jwt.ErrTokenExpired或jwt.ErrTokenMalformed），而直接用token.Claims.(jwt.MapClaims)强转，就会panic，触发Echo默认的500响应——这不符合REST API对认证失败应返回401/400的惯例。
必须手动检查jwt.Parse的err和token.Valid
使用github.com/golang-jwt/jwt/v5时，jwt.Parse返回三个值：token、err、valid bool。仅靠err == nil不能说明token有效——比如签名错误时err可能是nil，但valid为false。正确做法是：
- 先检查
err是否非空，对应jwt.ErrTokenMalformed（Base64解码失败）、jwt.ErrTokenUnverifiable（缺少签名）等 - 再检查
token.Valid，覆盖jwt.ErrTokenExpired、jwt.ErrTokenNotValidYet、jwt.ErrSignatureInvalid - 对所有JWT格式/语义错误统一返回
c.JSON(401, map[string]string{"error": "invalid token"})或更细粒度的400
示例片段：
token, err := jwt.Parse(tokenString, keyFunc)
if err != nil {
return echo.NewHTTPError(http.StatusUnauthorized, "invalid token format")
}
if !token.Valid {
return echo.NewHTTPError(http.StatusUnauthorized, "token validation failed")
}
中间件中别用c.Get("user")前假设token已校验
很多Echo JWT中间件示例会把user塞进c.Set("user", claims)，然后在handler里直接c.Get("user")。但如果中间件因panic未执行完（比如上面提到的强转失败），c.Get("user")会返回nil，后续代码可能panic或逻辑错乱。安全做法是：
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 在中间件里完成全部JWT校验，并只在
token.Valid && err == nil时才c.Set("user", ...) - handler中用
if user, ok := c.Get("user").(jwt.MapClaims); !ok { return echo.NewHTTPError(http.StatusUnauthorized) }二次确认 - 避免在中间件外任何地方直接访问
c.Get("user")而不检查类型断言结果
调试JWT错误时优先打印原始tokenString和err.Error()
常见陷阱是前端传了不带Bearer 前缀的token，或token含URL unsafe字符（如+、/）被服务端误解码。建议在中间件开头加日志：
authHeader := c.Request().Header.Get("Authorization")
// 检查是否为 "Bearer xxx"
tokenString := strings.TrimPrefix(authHeader, "Bearer ")
if authHeader != "" && !strings.HasPrefix(authHeader, "Bearer ") {
return echo.NewHTTPError(http.StatusBadRequest, "authorization header format error")
}
log.Printf("raw token: %q, err: %v", tokenString, err)
注意tokenString过长时需截断，避免日志爆炸；生产环境去掉log.Printf，改用结构化日志记录错误类型而非原始值。
JWT错误处理的核心不是“怎么解析”，而是“在哪一层拦截、以什么HTTP状态码暴露、是否泄露敏感信息”。Echo的轻量设计意味着所有校验责任都在中间件，漏掉任意一个err分支或token.Valid检查，都会让格式错误请求穿透到业务层甚至引发panic。
