@graphql-schema-filter/core

中文文档
0.3.0发布于 2025/11/29MITTypeScriptESM + CJS零依赖近 30 天下载 9万

图QL 筛选库中包含 @ expose 指令支持的目标访问控制

中文使用文档
文档目录13 节
  1. 特征
  2. 安装
  3. 快速启动
  4. API 密码
  5. filterSchema(schema, options)
  6. 导出类型
  7. FormatSchemaOptions
  8. 指令定义
  9. 指令
  10. @expose(tags: [String!]!)
  11. @disableAutoExpose
  12. 文档
  13. 许可证

@ graphql-schema- filter/ 核心

GraphQL 筛选库 @expose 指令支持基于目标的访问控制.

特征

  • 基于目标的过滤: 基于 @expose 以标签为基础的访问控制指令
  • 智能默认: 自动曝光输出类型字段,允许输入类型处理,明确查询/混合字段控制
  • 类型安全: 包含全面类型定义的完整类型脚本支持
  • 零配置: 有合理默认的简单 API
  • 生产准备: 有源地图和声明文件的双格式(ESM + CJS)

安装

npm install @graphql-schema-filter/core graphql

快速启动

import { buildSchema } from "graphql";
import { filterSchema } from "@graphql-schema-filter/core";

const schema = buildSchema(`
  directive @expose(tags: [String!]!) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION

  type Query {
    users: [User!]! @expose(tags: ["readonly", "admin"])
    adminUsers: [User!]! @expose(tags: ["admin"])
  }

  type User {
    id: ID!
    name: String!
    email: String!
    salary: Float @expose(tags: ["admin"])
  }
`);

// Filter for readonly users
const readonlySchema = filterSchema(schema, {
  target: "readonly",
});

// Filter for admin users
const adminSchema = filterSchema(schema, {
  target: "admin",
});

API 密码

filterSchema(schema, options)

过滤 GraphQL 计划的主要切入点 .

参数:

  • schema: GraphQLSchema - 过滤的 GraphQL 方案
  • options: FilterSchemaOptions
    • target: string - 过滤的目标标记(例如“admin”、“只读”)
    • logLevel?: LogLevel - 日志级别(例如“调试”、“信息”、“警告”、“无”)(默认:“无”)
    • formatOptions?: FormatSchemaOptions - Schema格式化选项(默认:字母排序)

回返情况: GraphQLSchema - 过滤计划

导出类型

import type {
  FilterSchemaOptions,
  FormatSchemaOptions,
  DefinitionsSortOptions,
  SortFieldsOptions,
} from "@graphql-schema-filter/core";

FormatSchemaOptions

控制被过滤的 schema 输出的格式.

interface FormatSchemaOptions {
  definitionsSort: DefinitionsSortOptions;
  fieldsSort: SortFieldsOptions;
}

type DefinitionsSortOptions =
  | { type: "alphabetical" }  // Sort by group then alphabetically
  | { type: "none" };         // Preserve original order

type SortFieldsOptions =
  | { type: "alphabetical" }  // Sort fields alphabetically
  | { type: "none" };         // Preserve original order

定义组(按顺序排列):

  1. 根类型( 查询、 变异、 订阅)
  2. 斯卡尔
  3. 指令
  4. 命名类型( 对象、 界面、 输入、 联盟、 Enum - 按字母排序)

指令定义

包包括一个 directives.graphql 文件位于 dist/directives.graphql。您可以将该文件链接到您的工程,或者根据需要将定义复制到您的计划:

ln -s node_modules/@graphql-schema-filter/core/dist/directives.graphql src/graphql/directives.graphql

指令

@expose(tags: [String!]!)

标记字段为暴露于特定目标.

directive @expose(
  tags: [String!]!
) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION

@disableAutoExpose

禁用某种类型的自动字段曝光( 如查询/ 混合等处理) .

directive @disableAutoExpose on OBJECT | INTERFACE

文档

关于详细文件、实例和先进用途,请访问 GitHub 仓库。 。 。 .

许可证

麻省理工学院

版本与发布记录

@graphql-schema-filter/core 共发布 5 个版本,首次发布于 2025/11/29;过去 12 个月发布了 5 个版本。

版本发布日期距今
0.3.0latest2025/11/2911 个月前
0.2.02025/11/2911 个月前
0.1.12025/11/2911 个月前
0.1.02025/11/2911 个月前
0.0.12025/11/2911 个月前

关于 @graphql-schema-filter/core 的常见问题

@graphql-schema-filter/core 是什么?

图QL 筛选库中包含 @ expose 指令支持的目标访问控制

如何安装 @graphql-schema-filter/core?

在项目目录运行 npm install @graphql-schema-filter/core,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:graphql(^16.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@graphql-schema-filter/core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@graphql-schema-filter/core 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@graphql-schema-filter/core 可以商用吗?

@graphql-schema-filter/core 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@graphql-schema-filter/core 的下载量有多少?

根据 npm 官方下载统计,@graphql-schema-filter/core 在 2026/10/17 – 2026/11/15 这 30 天内被下载 89,945 次,日均约 2,998 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@graphql-schema-filter/core 还在维护吗?

最新版本 0.3.0 发布于 2025/11/29(11 个月前);至今共发布 5 个版本,其中过去 12 个月发布了 5 个;首次发布于 2025/11/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。