Gin 公开接口也要可选鉴权:否则登录态白带
公开接口的常见写法是把路由挂到一个不需要登录的分组里,游客能访问就算完成。上线后才发现:用户明明带着有效 token,接口里的 userId 还是 0。
结果是 VIP 工具判断把会员当成游客,评论归属记到匿名,审计字段也拿不到操作人。接口没有报错,只是所有依赖登录态的分支都走了游客路径。
这类问题的根因通常不是 token 无效,而是公开路由根本没有解析 token。本文基于 Gin 1.12.0,源码位置是 internal/router/router.go 和 internal/middleware/token.go。
公开组和登录组是两条链
项目的路由注册把每个模块拆成两个分组:
register := func(prefix string, registrars []RouteRegistrar) {
public := api.Group(prefix)
auth := api.Group(prefix)
// 公开组:可选鉴权,令牌有效时填充登录信息(令牌无效不拦截)
public.Use(optionalAuth)
// 登录组:必须登录,再叠加租户切换与数据权限
auth.Use(jwtAuth, middleware.VisitTenantMiddleware(), middleware.DataPermissionMiddleware())
for _, h := range registrars {
h.RegisterRoutes(public, auth)
}
}
同一个 handler 根据自己的接口语义,把路由注册到 public 或 auth:
func (h *AppVipHandler) RegisterRoutes(public, auth *gin.RouterGroup) {
public.GET("/vip/packages", h.GetVipPackageList)
public.GET("/vip/access-check", h.CheckAccess)
auth.GET("/vip/mine", h.GetMyVip)
auth.GET("/vip/records", h.GetMyVipRecordPage)
auth.POST("/vip/redeem", h.Redeem)
}
“公开”只表示不强制登录,不表示不需要识别用户。套餐列表可以不看人,工具可用性必须看人。
可选鉴权做的是“解析但不拦截”
OptionalJWTWithService 的实现很直接:
func OptionalJWTWithService(svc oauth2Svc.OAuth2TokenService) gin.HandlerFunc {
return func(c *gin.Context) {
authenticate(c, svc, false)
c.Next()
}
}
第三个参数 required 为 false,决定校验失败时的行为:
func authenticate(c *gin.Context, svc oauth2Svc.OAuth2TokenService, required bool) bool {
authHeader := c.GetHeader("Authorization")
if authHeader == "" {
if required {
response.Unauthorized(c, "未提供认证令牌")
c.Abort()
}
return false
}
parts := strings.SplitN(authHeader, " ", 2)
if len(parts) != 2 || parts[0] != "Bearer" {
if required {
response.Unauthorized(c, "认证令牌格式错误")
c.Abort()
}
return false
}
accessToken, err := svc.CheckAccessToken(c.Request.Context(), parts[1])
if err != nil {
if required {
response.Error(c, 401, "认证令牌无效或已过期")
c.Abort()
}
return false
}
c.Set("user_id", accessToken.UserID)
c.Set("user_type", accessToken.UserType)
c.Set("username", info.Nickname)
// ... 角色、权限、scopes
ctx := gormx.SetUserIDToContext(c.Request.Context(), accessToken.UserID)
ctx = gormx.SetUserTypeToContext(ctx, accessToken.UserType)
c.Request = c.Request.WithContext(ctx)
return true
}
可选鉴权的完整语义是:
| 请求头 | 校验结果 | 公开接口的行为 |
|---|---|---|
没有 Authorization | 未登录 | 放行,userId 为 0 |
Bearer 后是有效令牌 | 已登录 | 放行,写入用户、角色、权限和 GORM 上下文 |
Bearer 后是过期或伪造令牌 | 校验失败 | 仍放行,但按游客处理 |
格式不是 Bearer xxx | 格式错误 | 仍放行,但按游客处理 |
最后两行是设计取舍:公开接口不能因为一个坏 token 就 401,否则游客状态下的旧 token 会把整个页面打挂。代价是调用方无法从状态码区分“游客”和“token 失效”,需要业务自己按 userId == 0 处理。
公开接口为什么必须拿到 userId
工具可用性接口是典型例子:
func (h *AppVipHandler) CheckAccess(c *gin.Context) {
var req dto.AppVipToolAccessReqVO
if err := ginutil.BindQuery(c, &req); err != nil {
response.ValidationError(c, err)
return
}
// 未登录时会员编号为 0,仅 VIP 工具会返回 need-login
userID := gormx.GetUserIDFromContext(c.Request.Context())
vo, err := h.vipSvc.CheckAccess(c.Request.Context(), userID, req.ToolID)
if err != nil {
response.BizErr(c, err)
return
}
response.Success(c, vo)
}
这个接口不能强制登录:游客也要能看到“这个工具需要登录”或“需要 VIP”的提示,否则前端无法决定是弹登录框还是开通页。但如果公开组不解析 token,会员带着 token 访问也会得到 need-login,付费状态完全失效。
同样的模式还出现在评论、收藏、浏览记录等“游客可看、登录后多一层状态”的接口上。判断依据都是同一个 userId。
三个容易写错的点
1. 公开组完全不挂中间件
public := api.Group(prefix)
// 没有 public.Use(optionalAuth)
public.GET("/vip/access-check", h.CheckAccess)
这样游客能访问,登录用户也永远是游客。接口文档看不出问题,只有前端反馈“登录了还提示登录”时才会暴露。
2. 可选鉴权写成了强制鉴权
把 OptionalJWTWithService 内部改成校验失败 Abort,公开接口就会对过期 token 返回 401。游客第一次访问没问题,登录用户 token 过期后连公开页面都打不开。可选鉴权必须保证“失败也继续”。
3. 只写 Gin 上下文,不写 request context
c.Set("user_id", ...) 只对 handler 可见。GORM 的审计回调、数据权限回调读的是 c.Request.Context() 里的值。如果只设置前者,handler 里能拿到用户,落库时 creator 仍然是空。
项目里的 authenticate 同时做了两件事:
c.Set("user_id", accessToken.UserID)
ctx := gormx.SetUserIDToContext(c.Request.Context(), accessToken.UserID)
ctx = gormx.SetUserTypeToContext(ctx, accessToken.UserType)
c.Request = c.Request.WithContext(ctx)
两处都写,才能保证 handler、服务层和 GORM 回调看到同一个用户。
怎么验证登录态真的生效
准备两个请求:一个不带 token,一个带有效 token。用 curl 命令生成器 拼请求时,重点看响应里的 userId、reason 和审计字段,不要只看 HTTP 200。
# 游客:应返回 need-login 或 free
curl -s 'https://api.example.com/vip/access-check?toolId=1'
# 登录用户:VIP 工具应返回 vip 或 need-vip,而不是 need-login
curl -s -H "Authorization: Bearer $TOKEN" \
'https://api.example.com/vip/access-check?toolId=1'
再验证一次写入路径:调用评论创建这类需要登录的写接口,确认数据库里的 creator 是当前用户,而不是空字符串。只验证读接口,容易漏掉 request context 没注入的问题。
安全边界:可选鉴权不是授权
可选鉴权只负责“有 token 就识别”,不负责“这个用户能不能做这件事”。公开组里的写接口仍然要自己做权限判断:
- 创建评论必须要求
userId > 0,不能让游客写; - 删除、修改必须校验资源归属,不能只信任前端传来的 ID;
- VIP 工具的实际使用要在服务端再次校验会员状态,不能只靠前端隐藏按钮;
- 公开接口返回的数据要按登录态裁剪,游客不能看到仅会员可见的字段。
把 public 理解成“游客也能进来”,而不是“这里不需要安全控制”,可以避免大部分越权问题。
边界与常见错误
- 公开接口带无效 token 时按游客处理,是预期行为;需要严格区分的场景应在响应体里返回明确的状态字段。
public和auth是两个分组,同一个路径不要同时注册,否则后注册的路由会覆盖或产生不可预期的匹配顺序。- 可选鉴权依赖
CheckAccessToken的有状态校验,Redis 或数据库故障时会退化为游客,不会阻断公开访问;这是可用性优先的取舍。 - 角色、权限字段来自 token 里的
user_info,解析失败不会中断鉴权,但下游权限判断会拿到空列表,写操作要再校验。 - 租户切换中间件只挂在
auth组。公开接口如果需要租户上下文,必须从域名、参数或请求头显式解析,不能假设中间件已经注入。
相关工具
调试请求头和状态码可以用 curl 命令生成器;Gin 的路由、中间件和项目分层基础见 Gin 入门笔记,更多服务端设计文章在 后端开发分类。
FAQ
公开接口为什么要允许无效 token 通过?
因为公开接口的首要目标是游客可用。旧 token、跨环境 token、格式错误的请求头都可能出现,如果一律 401,游客访问会被无关的凭证问题阻断。识别失败按游客处理更稳。
可选鉴权和强制鉴权能共用一个中间件吗?
可以共用底层校验函数,但入口要分开:强制版在失败时 Abort,可选版只记录结果并 c.Next()。混在一起容易出现“公开接口 401”或“登录接口放行游客”。
为什么 handler 里拿得到 userId,数据库 creator 还是空?
handler 读的是 Gin 上下文,GORM 回调读的是 request context。只设置 c.Set 不够,还要把用户信息写入 c.Request.Context()。
公开接口返回 need-login,是不是说明 token 没传?
不一定。先确认请求头格式是 Authorization: Bearer <token>,再确认公开组挂了可选鉴权,最后检查 token 是否已过期或被登出删除。三者任一不满足都会得到游客结果。
结语:公开接口的“公开”是对游客的可用性要求,不是放弃登录识别。挂上可选鉴权,把用户信息同时写进 Gin 和 request context,再在业务层做真正的授权判断,登录态才不会白带。
評論
還沒有評論,來說兩句吧