@apollo/generate-persisted-query-manifest

generate-persisted-query-manifest 是生成工具 持续查询表 来源于阿波罗客户端网络项目的源代码. 它扫描一个寻找GraphQL操作的源代码目录,对操作进行与阿波罗客户端Web运行时所做的相同的转换,并将其编译为持续查询的JSON文件.

(这不是从任意的GraphQL操作创建PQM JSON文件的通用工具:它专门针对阿波罗客户端网络在发送到服务器之前如何转换操作. )

设置

首先,安装 @apollo/generate-persisted-query-manifest 作为 dev 依赖的软件包 :

npm install --save-dev @apollo/generate-persisted-query-manifest

使用它的 CLI 从您的应用程序中提取询问:

npx generate-persisted-query-manifest

CLI 配置

要覆盖默认选项, 您可以提供配置文件 。 创建一个 persisted-query-manifest.config.json 在您的项目根中的文件.

{
  "documents": [
    "src/**/*.{graphql,gql,js,jsx,ts,tsx}",
    "!**/*.d.ts",
    "!**/*.spec.{js,jsx,ts,tsx}",
    "!**/*.story.{js,jsx,ts,tsx}",
    "!**/*.test.{js,jsx,ts,tsx}"
  ],
  "output": "persisted-query-manifest.json"
}

注:配置文件是可选的。 上方显示每个选项的默认值 .

如果您想在根以外的目录中定义配置文件, 您可以使用 : --config 选项.

npx generate-persisted-query-manifest --config path/to/persisted-query-manifest.config.json

支持的配置文件格式

配置文件可以多种格式提供,并且可以选择前缀为点(.) (中文(简体) ). CLI将在这些位置搜索一个配置文件:

• .persisted-query-manifest.config.json
• persisted-query-manifest.config.json
• .persisted-query-manifest.config.yml
• persisted-query-manifest.config.yml
• .persisted-query-manifest.config.yaml
• persisted-query-manifest.config.yaml
• .persisted-query-manifest.config.js
• persisted-query-manifest.config.js
• .persisted-query-manifest.config.ts
• persisted-query-manifest.config.ts
• .persisted-query-manifest.config.cjs
• persisted-query-manifest.config.cjs
• A 类 persisted-query-manifest 键入 package.json

配置

要自定义 CLI, 请使用您目录根上描述的一种格式创建配置文件 。 如果使用一个 .js , (中文(简体) ), .cjs,或 .ts 配置文件, 您的配置对象必须是默认导出 .

类型脚本

如果您将配置文件定义为 TypeScript 文件, 您可以通过导入选项获取自动补全和选项上的文档 PersistedQueryManifestConfig 从包中键入.

// persisted-query-manifest.config.ts
import { PersistedQueryManifestConfig } from "@apollo/generate-persisted-query-manifest";

const config: PersistedQueryManifestConfig = {
  // options
};

export default config;

选项

• documents - 说吧 string | string[]

告诉CLI去哪里找你的文件 您可以使用 glob 模式来决定查找位置 。 前缀图案 ! 忽略用于忽略测试或故事书故事中可能定义的询问的路径.

路径相对于当前工作目录进行解释,而不是配置文件的目录. 我们建议永远跑 generate-persisted-query-manifest 通过一个 npm run 脚本,用包含的目录运行命令 package.json 作为当前目录.

默认 :

[
  "src/**/*.{graphql,gql,js,jsx,ts,tsx}",
  "!**/*.d.ts",
  "!**/*.spec.{js,jsx,ts,tsx}",
  "!**/*.story.{js,jsx,ts,tsx}",
  "!**/*.test.{js,jsx,ts,tsx}"
]

使用 GraphQL 编码源文件的情况持续存在

图QL 编码源 是一个流行的代码 用于 GraphQL 的生成工具。 您可以使用 GraphQL 编码源 持续 文档 特性为 generate-persisted-query-manifest 通过提供 documents 选项 fromGraphQLCodegenPersistedDocuments 此套件导出的工具值 。 由于 GraphQL Codegen 已经为您做了大量的工作, 这有助于防止文件系统翻转来解析 GraphQL 文档 .

import type { PersistedQueryManifestConfig } from "@apollo/generate-persisted-query-manifest";
import { fromGraphQLCodegenPersistedDocuments } from "@apollo/generate-persisted-query-manifest";

const config: PersistedQueryManifestConfig = {
  documents: fromGraphQLCodegenPersistedDocuments(
    "./src/gql/persisted-documents.json",
  ),
};

export default config;

注:需要通过这个软件包运行这些文件,以确保阿波罗客户端发送给服务器的GraphQL文档与清单中的文件相匹配。 虽然GraphQL Codegen所坚持的文档变换意在与阿波罗客户端相似,但有些细微的差别可能会妨碍正确使用阿波罗坚持的询问. 这也确保了与阿波罗客户端引入的任何可能改变GraphQL文档输出的未来变换的向前兼容.

• output - 说吧 string

告诉CLI你在哪里写清单文件 路径相对于当前工作目录进行解释.

默认 : persisted-query-manifest.json

• createOperationId - 函数 (query: string, options: CreateOperationIdOptions) => string

自定义函数允许您自定义 id 用于查询操作。 默认情况下,将使用查询字符串的 SHA 256 散列来生成 id。只有在您的配置文件使用一个 .js, (中文(简体) ), .cjs 或者说 .ts 扩展名.

当您使用此选项时, 您无法使用 generatePersistedQueryIdsAtRuntime 函数从 @apollo/persisted-query-lists 在客户端中,因为该函数假设您正在使用默认的ID生成(身体的SHA256散列). 与 generatePersistedQueryIdsFromManifest。 。 。 .

interface CreateOperationIdOptions {
  /**
   * The name of the operation.
   */
  operationName: string;

  /**
   * The type of operation.
   */
  type: "query" | "mutation" | "subscription";

  /**
   * Helper function that returns the default generated ID for the operation.
   */
  createDefaultId: () => string;
}

这里的一个例子是,对命名的操作使用一个 Base 64 编码字符串 TestOperation,但将默认生成的ID用于所有其他人.

import { Buffer } from "node:buffer";

const config = {
  createOperationId(query, { operationName, type, createDefaultId }) {
    switch (operationName) {
      case "TestOperation":
        return Buffer.from(query).toString("base64");
      default:
        return createDefaultId();
    }
  },
};

• documentTransform - 说吧 DocumentTransform

一个 @apollo/client DocumentTransform 实例,用于转换 GraphQL 文档,然后将其保存到清单中。 如果您通过一个选项, 请使用此选项 documentTransform 选项.

更多信息见阿波罗客户端 文件转换 文档.

注: 只有在使用3.8.0或以上的阿波罗客户端时,此特性才可用.

import { DocumentTransform } from "@apollo/client/core";

const config = {
  // Inlined for this example, but ideally this should use the same instance
  // that is passed to your Apollo Client instance
  documentTransform: new DocumentTransform((document) => {
    // ... transform the document

    return transformedDocument;
  }),
};

• addTypename数字 : boolean

是否添加 __typename 字段到操作中的选择设置。 默认为真; 如果您也通过, 您应该将此设定为虚假 addTypename: false 给您的 InMemoryCache 在您的应用程序中构建器.

[注] 如果您在不使用阿波罗客户端的代码库上使用此工具,此选项将会有所帮助. 请注意,此工具不支持此使用例 .

注意通过的能力 addTypename: false 将不会使用 Aporo 客户端 v4 支持 .