JavaScript：GraphQL Shield（权限中间件）

graphql-github-io-zh-Hans生态项目与库

JavaScript：GraphQL Shield（权限中间件）

项目简介

GraphQL Shield 是一个用于构建 GraphQL 权限层的工具。它提供了一套直观的规则 API，让您可以在每个请求上应用权限校验，并通过智能缓存降低请求的响应时间。借助 GraphQL Shield，您可以确保应用始终保持快速响应，同时内部数据不会轻易暴露给未授权的用户。

功能特性

直观的规则 API：使用 rule、shield、and、or、not 等函数组合出灵活的权限逻辑。
权限层级清晰：支持按 Query、Mutation 以及对象类型分别配置权限规则。
智能缓存：通过 contextual 等缓存策略，减少重复校验，提升请求性能。
易于集成：可直接作为 GraphQL 中间件与 graphql-yoga 等服务器配合使用。

安装

bash 复制代码

npm install graphql-shield

快速开始

定义规则

规则是权限校验的基础单元。您可以使用 rule 函数定义一条规则，并在其中访问解析器参数（parent、args、ctx、info）来判断请求是否被允许。

ts 复制代码

import { rule, shield, and, or, not } from 'graphql-shield'

// 定义规则：用户是否已登录
const isAuthenticated = rule({ cache: 'contextual' })(
  async (parent, args, ctx, info) => {
    return ctx.user !== null
  },
)

// 定义规则：用户是否为管理员
const isAdmin = rule({ cache: 'contextual' })(
  async (parent, args, ctx, info) => {
    return ctx.user.role === 'admin'
  },
)

// 定义规则：用户是否为编辑者
const isEditor = rule({ cache: 'contextual' })(
  async (parent, args, ctx, info) => {
    return ctx.user.role === 'editor'
  },
)

配置权限

利用 shield 函数，您可以基于规则定义不同操作和类型的权限。and、or、not 等组合函数可以帮助您构建复杂的权限逻辑。

ts 复制代码

// 配置权限
const permissions = shield({
  Query: {
    frontPage: not(isAuthenticated), // 仅未登录用户可访问
    fruits: and(isAuthenticated, or(isAdmin, isEditor)), // 登录且为管理员或编辑者可访问
    customers: and(isAuthenticated, isAdmin), // 登录且为管理员可访问
  },
  Mutation: {
    addFruitToBasket: isAuthenticated, // 仅登录用户可执行
  },
  Fruit: isAuthenticated, // 所有 Fruit 类型字段需要登录
  Customer: isAdmin, // 所有 Customer 类型字段需要管理员权限
})

接入服务器

将权限中间件添加到 GraphQL 服务器的 middlewares 数组中即可生效。您还可以在 context 中注入用户身份信息，供权限规则使用。

ts 复制代码

// 服务器集成
const server = new GraphQLServer({
  typeDefs,
  resolvers,
  middlewares: [permissions],
  context: (req) => ({
    ...req,
    user: getUser(req),
  }),
})

总结

GraphQL Shield 通过简洁的规则 API 和灵活的权限组合方式，帮助开发者快速构建可维护、高性能的 GraphQL 权限层。无论是简单的登录校验，还是复杂的角色权限控制，它都能优雅地胜任。

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。