GraphQL

使用 WebStorm，您可以使用支持 GraphQL语言的 GraphQL 插件。以下功能可用：

对 GraphQL 规范的全面语言支持，包括模式定义语言 (SDL)。
模式感知的补全、错误高亮和文档支持。
语法高亮、代码格式化、折叠、注释器和括号匹配。
动态检测您的本地模式。可以通过自省轻松获取远程模式。您可以自省 GraphQL 端点以使用 GraphQL 类型系统定义语言生成模式声明文件。
支持通过可配置的项目范围或 graphql-config 文件的多模式项目。模式发现通过 graphql-config 文件配置，其中包括对多模式项目的支持。
内置支持 Apollo GraphQL和 Relay项目：JavaScript 和 TypeScript 中的 graphql 和 gql 标记模板字面量会自动识别为 GraphQL。
使用变量对可配置端点执行查询，包括对自定义头和环境变量的支持。
对模式类型、字段和片段的查找用法和转到声明。
通过结构视图导航 GraphQL 文件。
从 shell、 .env 文件加载变量，或为每个配置文件手动设置它们。
内置 Relay、 Federation 和 Apollo Kotlin 类型定义（您需要在设置 | 语言与框架 | GraphQL 中启用它们）。

GraphQL 通过专用的 GraphQL插件支持，该插件可从 JetBrains Marketplace获取。

安装 GraphQL 插件

按下 Ctrl+Alt+S 以打开设置，然后选择设置 | 插件。
在 Marketplace 选项卡中，在搜索字段中开始输入 graph ，从列表中选择 GraphQL ，然后点击安装。

配置您的应用程序以使用 GraphQL

配置模式类型的发现方式非常重要。基于模式类型的信息，WebStorm 提供代码辅助功能，例如代码补全和错误高亮。

模式及其类型使用 GraphQL 类型系统定义语言声明，该语言也被广泛称为 GraphQL 模式定义语言（通常缩写为 SDL）。如果您在 SDL 中编写模式，插件提供以下功能：

在定义字段、参数、实现的接口等时的类型补全。
对模式错误（如未知类型、错误使用类型以及实现接口时缺少字段）的错误高亮。
在 SDL 中查找用法和重构（如重命名），这将更新相关的查询、变更等。

对于单模式项目，模式类型会自动发现，无需您进行任何额外配置。 WebStorm 处理 .graphql 文件中的所有内容，在项目文件范围中查找类型定义，并将检测到的类型定义添加到单例类型注册表中。在项目文件范围内注入的 GraphQL 字符串会处理所有 JavaScript 文件类型 - .js、 .jsx、 .ts、 .tsx、 .html 和基于 html 的文件，如 .vue。

对于多模式项目，应为每个模式配置一个范围。特定模式的范围确保每种类型仅声明一次，并且仅在一个 GraphQL 类型注册表中被拾取，从而防止验证错误。此外，这些范围可防止非冲突类型出现在补全中，并确保验证仅识别属于当前模式的类型。

了解更多信息，请参阅 GraphQL 配置简介。

基本配置

在项目工具窗口中，将光标放在您希望创建简单配置文件的文件夹上，然后选择新建 | GraphQL 配置。

WebStorm 创建一个 graphql.config.yml 文件并在编辑器中打开它：

                        schema: schema.graphql
                        documents: '**/*.graphql'

此配置文件声明模式定义应位于 schema .graphql 文件中。 documents 键使用一个全局模式定义，该模式将包括当前或嵌套目录中的任何 GraphQL 操作。操作一词仅指 GraphQL 查询和片段，而不包括类型定义。

请注意，路径是相对于配置目录指定的，除非它们被明确定义为绝对路径。因此，您无需为它们添加 ./ 前缀。只需 schema.graphql 即可。全局模式同样适用。

node_modules 的配置

要从 node_modules 文件夹中使用模式，请创建一个 GraphQL 配置文件，例如 graphql.config.yml ，并在其中指定模式的精确路径，如下所示：

schema: node_modules/@octokit/graphql-schema/schema.graphql

复合模式

GraphQL Config 还可以通过指定模式文件列表，将多个模块化模式组合成一个 GraphQL 模式对象，如下所示：

                schema:
                  - ./foo.graphql
                  - ./bar.graphql
                  - ./baz.graphql
            
   

或者，您可以使用全局模式来查找并包含模式片段：

                schema: ./*.graphql # includes every GraphQL file in current directory
                # OR
                schema: ./**/*.graphql # includes GraphQL files recursively
            
   

GraphQL Config 会查找指定的文件，读取这些文件，并将它们合并生成一个 GraphQL 模式对象。

远程模式

如果您有一个 GraphQL 端点但尚未拥有本地模式文件，您可以定义一个或多个端点并执行自省查询。这将从服务器加载模式，将其转换为 GraphQL 文件，并将其保存在 IDE 的缓存目录中。

根据您是否需要为端点进行额外配置，您可以将其指定为字符串或包含诸如头信息等数据的附加键的对象。

schema: https://my.api.com/graphql

                  schema:
                    - https://my.api.com/one/graphql
                    - https://my.api.com/two/graphql
            
   

                  schema:
                    - https://my.api.com/one/graphql:
                        headers:
                          Authorization: Bearer ${TOKEN}
            
   

本地自省模式

要在本地存储自省结果，请像在旧版配置格式中一样配置一个端点。在端点扩展中定义一个或多个端点，然后执行自省查询。一个文件将保存在相应模式部分的第一个路径中，例如下面示例中的 local.graphql 文件。

                schema: local.graphql
                extensions:
                  endpoints:
                    One:
                      url: https://my.api.com/one/graphql
                      headers:
                        Authorization: bearer ${TOKEN}
                    Two:
                      url: https://my.api.com/two/graphql
            
   

高级配置

要更精细地控制哪些文件应包含在模式中，请使用可选的 include 和 exclude 键。首先，检查候选文件是否被排除。如果文件未被排除，则将文件路径与 include 模式进行匹配。

在下面的示例中， schema.graphql 和 src 目录中的每个文件（除了 __tests__ 目录中的文件）都将包含在该项目中。

                schema: schema.graphql
                exclude: 'src/**/__tests__/**'
                include: src/**
            
   

多个项目

每个项目的配置

config 文件定义了一个 GraphQL "module" 根，就像 package .json 或类似文件一样。即使 config 文件为空，其目录及嵌套目录中的所有文件也会使用与该配置关联的模式。

因此，分离不同模式的最简单方法是，在每个子目录中创建一个配置文件（如果它们完全独立，通常在 monorepos 中是这种情况）。通过这种方法，每个 config 文件的位置为每个子树创建了一个单独的范围。

单一配置

如果您更喜欢使用单个配置文件，您可以在同一个文件中指定多个项目。

                        - project root/
                            - .graphql.config.yml <-----
                            - frontend (schema one)/
                                - schema files and graphql aware components
                            - backend (schema two)/
                                - schema files and graphql aware components
                            - queries/
                    
     

这种情况下的配置应如下所示：

                        projects:
                          frontend:
                            schema: https://my.api.com/graphql
                            documents: frontend/**/*.{graphql,js,ts}
                          backend:
                            schema: backend/schema.graphql
                            documents: backend/**/*.graphql
                    
     

文件会按照项目定义的顺序与项目匹配。因此，如果一个文件匹配多个项目，将选择第一个项目。

当未为特定项目定义 include 或 exclude 键时，GraphQL 操作会以非严格方式匹配。这意味着，如果查询或片段未明确匹配任何项目，该文件将与第一个未定义 include 或 exclude 键的项目相关联。在上面的示例中，除了 backend 和 frontend 之外，还有一个名为 queries 的额外根目录。如果 queries 包含一些未匹配任何提供模式的 GraphQL 文档，则第一个项目 frontend 将与这些查询相关联。

为实现此目的，您可以将 exclude 模式添加到 frontend 项目配置中。这将把 queries 文件夹中的文件与 backend 项目相关联。

                        projects:
                          frontend:
                            schema: https://my.api.com/graphql
                            documents: frontend/**/*.{graphql,js,ts}
                            exclude: queries/**  # <--- will enable strict matching for that project
                          backend:
                            schema: backend/schema.graphql
                            documents: backend/**/*.graphql
                    
     

如前所述，这不适用于类型定义。 WebStorm 仅使用严格匹配 schema 或 include 键的文件中的类型定义。

配置文件

WebStorm 识别以下格式的配置文件：

graphql.config.json
graphql.config.js
graphql.config.cjs
graphql.config.mjs
graphql.config.ts
graphql.config.mts
graphql.config.cts
graphql.config.yaml
graphql.config.yml
.graphqlrc （YAML 和 JSON）
.graphqlrc.json
.graphqlrc.yaml
.graphqlrc.yml
.graphqlrc.js
.graphqlrc.mjs
.graphqlrc.ts
.graphqlrc.mts
.graphqlrc.cts

YAML

确保在 YAML 页面的已安装选项卡中启用了设置 | 插件捆绑插件，如安装插件中所述。

JavaScript

请确保您的计算机上安装了 Node.js。 Node.js 用于下载 JavaScript 配置文件。
WebStorm 不会转译配置文件，因此请确保它们使用适合 Node.js 的模块系统编写。在下面的示例中，使用了 module.exports 语法，而不是 export default。
module.exports = { schema: 'https://localhost:8000' }
要在您的配置中使用 ESM ，请将 "type": "module" 添加到您的 package.json 文件中。

TypeScript

请确保您的计算机上安装了 Node.js。 Node.js 用于下载 TypeScript 配置文件。
要加载 TypeScript 配置，请通过在内置终端工具窗口 Alt+F12 中键入以下命令之一来下载并安装 ts-node 包：
- npm install --save-dev ts-node 以在您的项目中安装该包。
- npm install --g ts-node 以全局安装该包。计算机
了解更多信息，请参阅 Typestrong ts-node。
在您的项目中使用 ESM 模块：
- 将 ESM 模块配置为 "type": "module" ，位于您的 package .json 文件中。
- 通过将以下内容添加到您的 tsconfig.json 文件中，为 ts-node 设置 ESM 加载器：
  { "compilerOptions": { // or ES2015, ES2020 "module": "ESNext" }, "ts-node": { "esm": true } }
了解更多信息，请参阅原生 ECMAScript 模块。

迁移

如果您使用的是旧版配置文件，例如 .graphqlconfig ，强烈建议您将其转换为您选择的现代格式，例如 YAML，这是最方便的格式。 WebStorm 集成了一个自动转换工具，并在您打开旧版文件时在编辑器顶部显示通知面板。只需点击通知面板中的迁移，即可自动更新配置键和环境变量语法。

建议您将以前用于配置复合模式的现有 includes 模式迁移到新的 schema 键。请注意，环境变量现在具有不同的语法，例如支持指定默认值。

旧版配置

如果您仍然希望使用旧版配置格式，请确保在 includes 属性中明确指定模式文件的路径。否则，仅会使用 schemaPath 中的类型进行模式构建。

                {
                      "schemaPath": "schema.graphql",
                      "includes": [
                          "Types1.graphql",
                          "types/**/*.graphql",
                          "src/files/*.{graphql,js,ts}",
                          "everything/inside/**"
                      ],
                      "excludes": [
                          "types/excluded/**"
                      ]
                  }
            
   

环境变量

您可以在配置文件中使用环境变量来指定模式路径、URL 或头值。在配置文件中使用环境变量的语法如下：

                ${VARIABLE_NAME}
                ${VARIABLE_WITH_DEFAULT:./some/default/file.graphql}
                ${VARIABLE_QUOTED:"http://localhost:4000/graphql"}
            
   

您可以从环境变量加载定义，无论是否有回退值。

schema: ${SCHEMA_FILE:./schema.json}

如果您想定义一个回退端点，可能需要用引号将值括起来。

schema: ${SCHEMA_ENDPOINT:"http://localhost:4000/graphql"}

.env 文件

提供环境变量有几种方式。最推荐的方法是创建一个包含变量值的专用文件。为避免暴露您的凭据，请避免提交此文件。

以下文件名按优先级从高到低支持：

.env.local
.env.development.local
.env.development
.env.dev.local
.env.dev
.env

WebStorm 从包含相应配置文件的目录开始搜索指定文件，并向上搜索到项目根目录。

在此类文件中，环境变量以简单的键值对形式表示，使用 = 符号分隔。值可以选择用引号括起来。

                    S3_BUCKET="YOURS3BUCKET"
                    SECRET_KEY=YOURSECRETKEYGOESHERE # comment
                    SECRET_HASH="something-with-a-#-hash"
                
    

手动配置

要使用 .env 文件，请通过以下任一方式为每个配置文件手动提供环境变量：

要在配置文件中编辑 GraphQL 环境变量，请在编辑器中打开该文件，右键点击任意位置以打开上下文菜单，然后选择编辑 GraphQL 环境变量。这将打开一个模式对话框，您可以在其中为文件中的每个环境变量提供值。
打开任意 GraphQL 文件并点击工具栏。该对话框会自动找到匹配的配置文件。
否则，仅会在第一次自省查询或 GraphQL 请求时请求缺失的变量。

系统

如果在 .env 文件中未找到变量或未手动设置，WebStorm 会尝试从您的系统环境中检索它们。

框架

Gatsby

在项目根目录创建一个 graphql.config.js ，内容如下：

module.exports = require("./.cache/typegen/graphql.config.json")

内省

为了提供解析、补全和验证，WebStorm 需要一个模式。这可以通过执行自省查询来实现，需事先进行配置。

运行内省查询

打开 YAML 或 JSON 配置文件并点击装订区域中的。这将发起一次内省查询，并将文件本地保存到 IDE 缓存或项目源，根据配置而定。这将执行自省查询并将文件本地保存到 IDE 的缓存或项目源中，具体取决于配置。
打开架构文件并从工具栏中选择运行内省查询。
在 GraphQL 工具窗口中，右键点击一个端点并从上下文菜单中选择从端点获取 GraphQL 模式。
要在编辑器中检查自省文件的模式结构，请在工具栏上使用打开内省架构操作。这将为选定的端点打开一个文件。
如果您不希望在每次查询后打开自省结果文件，请按 Ctrl+Alt+S 打开设置并选择语言与框架 | GraphQL ，然后清除使用内省结果打开编辑器复选框。

重新运行最新的自省

如果您的模式不断变化，并且您发现自己反复对同一端点执行相同的自省操作，使用重新运行内省查询操作可能会更方便。请注意，此选项仅在您已经执行过自省查询后才会可用。

按 Ctrl+Shift+A 打开操作选项卡的随处搜索弹出窗口，开始输入 Rerun Introspection... ，并从列表中选择重新运行内省查询。了解更多信息，请参阅搜索操作。
要为此操作分配快捷键，请按 Alt+Enter 并在打开的对话框中指定一个按键。了解更多信息，请参阅添加键盘快捷键。

检测服务器功能

服务器功能将根据返回 __Type、 __Field、 __Directive 和 __InputValue 字段结构的内省查询动态确定。

query IntrospectionCapabilitiesQuery {
  __schema {
    types {
      name
      fields {
        name
        args {
          name
        }
      }
    }
  }
}
            
   

上述查询返回以下架构之一：

    type Query {
        id: ID
        name(arg: String @deprecated(reason: "Deprecated")): String
        email(filter: FilterArgs @deprecated): String
    }

    input SomeParams {
        id: ID = "<new>" @deprecated(reason: "SomeParams_id")
        name: String = "User123" @deprecated
    }

    directive @customDirective(arg: String @deprecated(reason: "directive_arg")) repeatable on QUERY

     

    type Query {
        id: ID
        name(arg: String): String
        email(filter: FilterArgs): String
    }

    input SomeParams {
        id: ID
        name: String
    }

    directive @customDirective(arg: String) on QUERY

     

按下 Ctrl+Alt+S 以打开设置，然后选择高级设置。
从架构功能检测模式列表中，选择以下之一：
- 自适应 — 在此模式下，WebStorm 会运行额外的预查询，从 GraphQL 服务器请求一组实际可用的功能。
  默认选择自适应模式。
- 最新 — 选择此模式以启用现代 GraphQL 服务器的所有默认功能，无需运行预查询并检测实际可用功能。
- 遗留 — 选择此模式可禁用旧版 GraphQL 实现的所有默认功能，无需运行预查询并检测实际可用功能。
如需提高与不兼容端点的兼容性，请选中在内省查询中跳过默认值复选框。此操作的副作用是会从架构中移除默认值信息。
默认情况下，该复选框处于未选中状态。
默认在内省结果中包含空类型。如需跳过空类型，请清除在内省结果中包含空类型复选框。

查询

要直接从编辑器执行查询，请将插入点放在查询定义上，然后点击工具栏中的执行 GraphQL 或按 Ctrl+Enter。查询将被发送到工具栏中选定的端点。
如果您的查询有变量，请点击工具栏中的以打开专用的变量编辑器，然后以 JSON 格式提供变量。
或者，创建一个 GraphQL 临时文件，并将其用作发送查询的测试场所。在 GraphQL 工具窗口中，双击端点节点并选择新建 GraphQL 临时文件。

临时文件

如果 GraphQL 临时文件的开头注释包含一个符合 # config=<path>[!<optionalProjectName>] 模式的字符串，则指定的配置和项目将用于解析和类型验证。符合此模式的注释被视为有效：

                # config=/user/local/project/.graphqlrc.yml
                # config=/user/local/project/.graphqlrc.yml!backend

工具栏

每个 GraphQL 文件都有一个工具栏，其中包含最常用的操作。

	打开配置文件	打开相应的配置文件，或者如果不存在则创建一个新的配置文件。
编辑环境变量		这将打开一个对话框，允许您为关联配置文件中定义的环境变量提供值。
	切换变量编辑器	这将打开一个编辑器窗口，您可以在其中以 JSON 格式提供查询变量。
端点列表		配置文件中定义了已知 URL 的列表，您可以使用它来选择 GraphQL 查询的目标 URL 或自省的来源 URL。
	执行 GraphQL	从下方编辑器运行选定的 GraphQL 查询。
	运行内省查询	此操作刷新从选定端点自省的模式。
	打开内省架构	此命令打开与选定端点对应的本地文件。

工具窗口

GraphQL 工具窗口提供了您的 GraphQL 项目的概览。它可以显示验证错误、执行自省查询、创建临时文件等。

架构和项目结构选项卡提供了检测到的配置文件及其关联的 GraphQL 模式的概览。在此树视图中，可用于多个节点的以下有用操作：

架构发现摘要 - 要搜索为每个项目发现的类型，请双击相应的节点。这将打开一个对话窗口，您可以在其中搜索每种类型并导航到其定义的位置。
架构错误 - 点击错误节点以导航到错误的来源。
端点 - 右键点击一个端点以执行自省查询或创建与选定配置文件和项目关联的临时文件。

工具窗口工具栏

GraphQL 工具窗口左侧的工具栏提供了以下便捷操作：

	添加架构配置	在所选目录中创建配置文件。或者，您可以按照基本配置中所述，从项目工具窗口创建一个配置文件。
	编辑所选架构配置	在工具窗口中为选定节点打开一个配置文件。
	重新启动架构发现	此操作清除所有已加载的模式，并从头开始重新启动发现过程。在缓存数据引发问题的情况下，这可能会很有用。

注入

标记模板字面量

WebStorm 支持 graphql、 gql、 Relay.QL 和 Apollo.gql 标签。

const QUERY = gql``;

IntelliJ 默认基于注释的注入

                // language=GraphQL
                const QUERY = `query { field }`;

C 风格注释

const QUERY = /* GraphQL */ `query { field }`;

GraphQL 注释

                const QUERY = `
                    #graphql

                    query { field }
            `;

最后修改日期： 2025年 12月 8日