Iris 的 ctx.UserValue 不适合存用户身份,因其无生命周期管理、类型不安全且不参与认证流程;应改用 ctx.Values().Set() 配合显式鉴权与封装获取函数。

为什么 Iris 的 ctx.UserValue 不适合直接存用户身份?
因为 ctx.UserValue 是纯键值存储,不带生命周期管理、无类型安全、也不自动参与认证流程。你手动塞一个 user 进去,后续所有中间件和 handler 都得自己做非空判断和类型断言,一漏就 panic。Iris 本身不拦截或校验它——它只是个“便利贴”,不是“通行证”。
真正该用的是 ctx.Values().Set() 配合显式鉴权逻辑,再配合统一的获取封装(比如 GetUser(ctx)),避免散落各处的 ctx.Values().Get("user")。
如何写一个带 JWT 解析和角色校验的中间件?
核心是:解析 token → 验证签名和过期 → 提取 claims → 检查角色/权限 → 写入上下文 → 拦截非法请求。别在中间件里做数据库查用户,除非 token 里只存 ID,且你确定每次都要查(会拖慢性能)。
实操建议:
- 用
github.com/golang-jwt/jwt/v5解析,密钥从配置读,别硬编码 - token 从
Authorization: Bearer <token></token>头取,注意前缀校验,别直接ctx.Header("Authorization")后全量解析 - 解析成功后,用
ctx.Values().Set("user_id", claim.UserID)和ctx.Values().Set("roles", claim.Roles),别塞整个 user struct - 校验失败时,统一返回
ctx.StatusCode(401)或403,并调用ctx.StopExecution()阻止后续处理
示例片段:
func JWTAuth(secret string) iris.Handler {
return func(ctx iris.Context) {
auth := ctx.GetHeader("Authorization")
if auth == "" || !strings.HasPrefix(auth, "Bearer ") {
ctx.StatusCode(401)
ctx.WriteString("missing or malformed Authorization header")
ctx.StopExecution()
return
}
tokenStr := strings.TrimPrefix(auth, "Bearer ")
token, err := jwt.ParseWithClaims(tokenStr, &jwt.MapClaims{}, func(t *jwt.Token) (interface{}, error) {
return []byte(secret), nil
})
if err != nil || !token.Valid {
ctx.StatusCode(401)
ctx.WriteString("invalid token")
ctx.StopExecution()
return
}
claims, ok := token.Claims.(jwt.MapClaims)
if !ok {
ctx.StatusCode(401)
ctx.WriteString("invalid claims")
ctx.StopExecution()
return
}
ctx.Values().Set("user_id", claims["sub"])
ctx.Values().Set("roles", claims["roles"])
}
}
如何让中间件支持白名单路径(如 /login、/health)?
硬编码 if 判断路径太脆弱,容易漏加新接口。推荐用路径前缀匹配 + 显式排除列表,而不是正则(正则开销大,且易出错)。
实操建议:
- 把免鉴权路径定义为常量 slice,比如
var publicPaths = []string{"/login", "/register", "/health"} - 在中间件开头用
iris.PathStripQuery(ctx.Request().URL.Path)获取纯净路径,再遍历比对 - 用
strings.HasPrefix()支持前缀,比如/api/public/下全部放行,但别滥用——/api/public/admin 就不该被误放行 - 注意静态文件路径(
/static/)是否也需放行,Iris 的app.StaticWeb()不走常规路由链,中间件不生效,得单独配
为什么 ctx.Next() 之后还要检查错误?
因为中间件链是线性的,ctx.Next() 只是执行后续 handler,不保证它没 panic 或没写状态码。尤其当业务 handler 抛出未捕获错误,或提前 ctx.StopExecution() 后又写了响应,会导致状态码/响应体混乱。
关键点:
- 认证中间件通常不需要在
ctx.Next()后做清理,但如果你在中间件里开了 DB 连接或加了 trace span,就得 defer 或显式回收 - 真正要检查的是 handler 是否已写响应:
if ctx.Response().IsStarted() { return },避免重复写 header - 如果想记录认证后的请求耗时,必须在
ctx.Next()前打点,结束后算差值——不能依赖defer,因为defer在函数退出才执行,而ctx.Next()可能早于函数结束就返回
复杂点在于:JWT token 刷新逻辑不能塞进这个中间件里(它只负责鉴权),刷新应由单独 endpoint 处理;另外,Iris 默认不支持多签发者(issuer)动态切换,若要兼容多个服务签发的 token,得自己维护 issuer→key 映射表,而不是传死 secret。


















