怎么在 GraphQL 接口中实现基于上下文的用户鉴权配置？

在 GraphQL 接口中实现基于上下文的用户鉴权，核心是通过中间件验证令牌后将用户信息存入请求上下文，解析器再从中读取并判断权限。适用于 Fiber、TypeGraphQL、gqlgen 等主流框架，风险边界在于上下文键名冲突和 WebSocket 连接阶段的独立鉴权。

先说结论：鉴权分为认证（身份）和授权（权限），上下文是传递载体，必须在请求生命周期早期完成身份注入。

适合：TypeScript、Go、PHP 等强类型或中间件支持完善的 GraphQL 栈
优先做：在 HTTP 中间件层提取 JWT 并验证，失败直接返回 401
再验证：未授权用户访问受保护字段应返回 null 或抛出授权错误

快速处理思路

GraphQL 鉴权不依赖特定命令，而是代码配置。核心流程分为中间件提取、上下文存储、解析器检查三个环节。

// 1. 中间件提取令牌 (以 Fiber 为例)
func AuthMiddleware(c *fiber.Ctx) error {
  token := extractToken(c) // 从 Authorization 头提取
  user, err := validateToken(token)
  if err != nil {
    return c.Status(fiber.StatusUnauthorized).SendString("Unauthorized")
  }
  c.SetContext(context.WithValue(c.Context(), "user", user)) // 存入上下文
  return c.Next()
}

// 2. 解析器检查权限 (以 TypeGraphQL 为例)
@Authorized("ADMIN") // 装饰器声明仅管理员可见
@Field()
adminField: string;

为什么会这样

上下文（Context）是 GraphQL 请求处理的核心载体，贯穿解析器执行的全生命周期。认证信息必须通过上下文传递，因为 GraphQL 解析器本身无状态，无法直接访问 HTTP 请求头。中间件负责在请求进入解析阶段前完成身份验证，解析器负责根据上下文中的用户身份决定数据可见性。这种分离确保了认证逻辑复用性和字段级权限控制的灵活性。

分步处理

按照认证提取、上下文传递、权限验证的顺序实施，每一步都有明确的检查点。

步骤 1：认证信息提取与验证

在 HTTP 层或 WebSocket 连接建立前拦截请求。推荐使用 FromAuthHeader 方法提取 Bearer 令牌，严格遵循 RFC 9110 标准。验证失败直接中断请求，避免无效流量进入解析层。

步骤 2：上下文传递认证状态

通过中间件完成认证后，将用户对象存储在请求上下文中。Go 语言使用 context.WithValue，TypeScript 使用 GraphQL Context 类型定义。确保上下文键名唯一，防止与其他包冲突，例如 gqlgen 中定义 userCtxKey 结构体。

步骤 3：解析器权限检查

在字段或操作解析器中读取上下文用户信息。TypeGraphQL 使用@Authorized 装饰器标记受保护字段，未授权用户访问时返回 null 或抛出错误。PHP 环境可在字段解析器内联检查 context['user'] 权限。

怎么验证是否生效

通过发送带令牌和不带令牌的请求对比响应结果。

检查点 1：无令牌访问

发送不包含 Authorization 头的 GraphQL 查询。受保护字段应返回 null，或整个请求返回 401 状态码。检查 GraphQL 错误列表中是否包含权限不足提示。

检查点 2：令牌失效访问

使用过期或签名错误的 JWT 发起请求。中间件应拦截并返回 Unauthorized 错误，解析器不应被执行。

检查点 3：角色权限隔离

使用普通用户令牌访问标记为@Authorized("ADMIN") 的字段。确认普通用户无法获取敏感数据，仅管理员可见。

常见坑

实施过程中容易在上下文键名、WebSocket 鉴权和空值处理上出错。

上下文键名冲突

不同中间件可能使用相同的上下文键名存储用户信息。建议定义唯一的 contextKey 结构体而非字符串，防止覆盖。

WebSocket 订阅鉴权

订阅基于 WebSocket 协议，连接建立阶段需单独验证身份。认证机制在连接建立和事件推送两个阶段生效，需在连接初始化时验证令牌并建立上下文。

敏感字段空值泄露

未授权用户访问受保护字段时，返回 null 可能泄露字段存在性。配置 authMode 为 error 可在权限不足时抛出错误而非返回 null，避免结构泄露。

常见问题

认证和授权在 GraphQL 中有什么区别？

认证是验证用户身份，确认“你是谁”，通常通过 JWT 实现；授权是确定已认证用户可以访问哪些资源，控制“你能做什么”，通常基于角色或策略。

客户端如何持久化保持登录状态？

成功登录后将令牌存储在 localStorage 或安全的 HTTP-only Cookie 中。应用初始化时检查存储的令牌并配置 Apollo 客户端的认证头。

如何实现基于角色的精细化权限？

使用@Authorized("ADMIN") 语法指定特定角色才能访问的字段。权限检查函数验证用户角色与所需权限的交集，普通用户只能获取公开字段。

参考来源

FiberGraphQL 订阅授权：基于上下文的权限验证完整指南
TypeGraphQL 条件字段：基于上下文的字段可见性控制
TypeGraphQL 订阅授权：保护实时数据的安全访问
Vue Apollo 权限控制终极指南：如何在 GraphQL 应用中实现用户认证和授权
使用 gqlgen 实现 GraphQL 服务认证机制详解
TypeGraphQL 授权系统：基于角色的访问控制实现方案
从入门到上线:PHP 实现 GraphQL 字段权限控制的全过程详解
GraphQL 中的权限与认证：一分钟浅谈