Echo v5起已彻底移除内置JWT中间件，middleware.JWT()会编译失败或panic；必须使用github.com/labstack/echo-jwt/v4独立包，通过echojwt.WithConfig()配置SigningKey、NewClaimsFunc和ContextKey，并显式绑定claims到context，否则c.Get("user")无法获取解析结果。
直接说结论：Echo v5 起已彻底移除内置 JWT 中间件，middleware.JWT() 会编译失败或 panic；必须用独立包 github.com/labstack/echo-jwt/v4，且鉴权逻辑和权限提取必须手动绑定到请求上下文，否则 Context.Get("user") 拿不到解析后的 claims。
为什么 e.Use(middleware.JWT()) 报错 undefined？
根本原因是 Echo v5 已删除整个 github.com/labstack/echo/middleware 包，更别说 JWT() 函数了。v4 版本里这个函数就只在 echo-jwt 独立包中存在，不是“被隐藏”，是物理不存在。
- 错误现象：
undefined: middleware.JWT或cannot find package "github.com/labstack/echo/middleware" - 正确导入路径只能是：
github.com/labstack/echo-jwt/v4（注意末尾/v4） - 安装命令必须带版本：
go get github.com/labstack/echo-jwt/v4，不加/v4会拉错分支或旧版 - 不能写
e.Use(middleware.JWT(...))，必须先构造中间件实例：e.Use(echojwt.WithConfig(...))
如何把用户 ID 和角色塞进 Context 并在 handler 里取？
默认中间件只校验 token 合法性，不会自动把 claims 注入 echo.Context。你需要显式配置 NewClaimsFunc 和 ContextKey，否则所有 handler 都得自己重复解析 token。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 定义自定义 claims 结构体：
type CustomClaims struct { UserID uint `json:"user_id"` Role string `json:"role"` jwt.StandardClaims } - 在
echojwt.Config中指定：NewClaimsFunc: func() jwt.Claims { return new(CustomClaims) } - 设置挂载键名：
ContextKey: "user"（这是默认值，可省略，但建议显式写出） - handler 中安全取值：
if user, ok := c.Get("user").(*CustomClaims); ok { userID := user.UserID } - 别直接断言
c.Get("user").(jwt.MapClaims)—— 如果用了自定义结构体，类型不匹配会 panic
TokenLookup 配错导致中间件完全不触发？
TokenLookup 决定中间件从哪读 token，默认是 "header:Authorization"，意思是期望前端传 Authorization: Bearer xxx。如果前端实际传的是 query:token=xxx 或 cookie:jwt=xxx，中间件根本不会去解析，直接放行或报 400，看起来像“没生效”。
- 支持的格式包括：
"header:Authorization"、"query:token"、"cookie:session_id"、"param:id" - 多个位置可组合使用，但需配合
TokenLookupFuncs字段自定义 extractor，不能只改TokenLookup字符串 - 若前端传的是
X-API-Key头，必须设为"header:X-API-Key"，且确保 header 名大小写匹配（HTTP 头不区分大小写，但 Go 的Header.Get()区分） - 调试时可在中间件前加日志打印
c.Request().Header和c.QueryParams()，确认 token 确实到达了服务端
400 还是 401？错误码混乱怎么统一？
echo-jwt 默认行为非常机械：没 Authorization 头 → 400；token 格式非法 → 400；签名错 / 过期 → 401。很多团队希望全部返回 401，但不能靠改状态码硬来，必须用 ErrorHandler 捕获并重写响应。
- 默认 400 是因为中间件认为“客户端根本没传凭证”属于使用错误，不是身份问题
- 统一返回 401 的写法：
ErrorHandler: func(c echo.Context, err error) error { return c.JSON(http.StatusUnauthorized, map[string]string{"error": "unauthorized"}) } - 如果还想区分错误类型（比如过期 vs 无效），可以在
ErrorHandler里判断errors.Is(err, jwt.ErrExpired)等具体错误 - 注意：一旦用了
ErrorHandler，中间件不再自动返回任何 JSON，所有响应格式由你控制
最常被忽略的一点：SigningKey 类型是 interface{}，但实际必须是 []byte（HS256）或 *ecdsa.PrivateKey（ES256），传错类型会导致验签永远失败，且错误信息极不明确——它不会报 “key type mismatch”，而是静默返回 401。
