在 ts 中使用 graphql

本文最后更新于:2021年11月19日 下午

场景

graphql 提供前后端一致的 api 架构元数据,同时通过请求合并、按需获取加快 web 与后端交互的性能。

结合 ts 使用

基本思路

  1. 扫描代码中所有 gql 字符串
  2. 获取到代码中 graphql 字符串然后生成类型定义
  3. 使用这些类型定义

使用步骤

以下使用 github [email protected] 进行演示

获取后端的元数据

curl https://docs.github.com/public/schema.docs.graphql > schema.graphql

安装基础 sdk

pnpm i @apollo/client graphql

安装代码生成器相关依赖

  • @graphql-codegen/cli 基础 cli
  • @graphql-codegen/typescript ts 插件
  • @graphql-codegen/typescript-operations ts 操作生成插件
  • @graphql-codegen/near-operation-file-preset ts 预设配置

创建配置 codegen.yml

overwrite: true
schema: "schema.graphql"
generates:
  ./src/graphql.gql.ts:
    plugins:
      - typescript
  ./:
    documents:
      - "src/**/*.ts"
      - "!src/**/*.gql.ts"
    preset: near-operation-file
    presetConfig:
      baseTypesPath: ./src/graphql.gql.ts
      extension: .gql.ts
    plugins:
      - typescript-operations

在代码中添加一些 graphql 变量

tip: 在非 react 项目中,请从 @apollo/client/core 导入所有非 react 的内容。

import { gql } from "@apollo/client";

export const findRepoStar = gql`
  query findRepoStar($name: String!, $owner: String!) {
    repository(name: $name, owner: $owner) {
      name
      stargazerCount
    }
  }
`;
export const findRepo = gql`
  query findRepo($name: String!, $owner: String!) {
    repository(name: $name, owner: $owner) {
      name
    }
  }
`;

使用 cli 生成类型定义

pnpm graphql-codegen --config codegen.yml

生成结果大致如下,基本上就是参数和结果类型

import * as Types from "../graphql.gql";

export type FindRepoStarQueryVariables = Types.Exact<{
  name: Types.Scalars["String"];
  owner: Types.Scalars["String"];
}>;

export type FindRepoStarQuery = {
  __typename?: "Query";
  repository?:
    | { __typename?: "Repository"; name: string; stargazerCount: number }
    | null
    | undefined;
};

export type FindRepoQueryVariables = Types.Exact<{
  name: Types.Scalars["String"];
  owner: Types.Scalars["String"];
}>;

export type FindRepoQuery = {
  __typename?: "Query";
  repository?: { __typename?: "Repository"; name: string } | null | undefined;
};

我们可以这样使用它

const res = await client.query<FindRepoStarQuery, FindRepoStarQueryVariables>({
  query: findRepoStar,
  variables: {
    name: "liuli-tools",
    owner: "rxliuli",
  },
});
console.log("res: ", res);

Jetbrains IDE 支持

  1. 安装插件 JS GraphQL

  2. 创建 graphql 基础配置文件 .graphqlconfig

    {
      "name": "github GraphQL Schema",
      "schemaPath": "schema.graphql",
      "extensions": {
        "endpoints": {
          "Default GraphQL Endpoint": {
            "url": "https://api.github.com/graphql",
            "headers": {
              "user-agent": "JS GraphQL",
              "Authorization": "bearer ${env:GITHUB_TOKEN}"
            },
            "introspect": false
          }
        }
      }
    }
  3. 最终效果
    1635317727128

VSCode 支持

  1. 安装插件 Apollo GraphQL

  2. 添加配置 apollo.config.js

    module.exports = {
      client: {
        service: {
          name: "github GraphQL Schema",
          localSchemaFile: "./schema.graphql",
        },
      },
    };
  3. 最终效果
    1635316734084

集成到 vite/rollup

关于为什么要将自动生成作为 vite 插件集成,之前在 是否需要将 cli 工具集成到构建工具中 中已经说明了。

vite-plugin-graphql-codegen 监视模式实际上有 bug,所以自行维护一个 rollup 插件

import { Plugin } from "vite";
import { CodegenContext, generate, loadContext } from "@graphql-codegen/cli";

async function codegen(watch: boolean) {
  const codegenContext = await loadContext();
  codegenContext.updateConfig({ watch });
  try {
    await generate(codegenContext);
  } catch (error) {
    console.log("Something went wrong.");
  }
}

export function graphQLCodegen(): Plugin {
  let codegenContext: CodegenContext;

  return {
    name: "rollup-plugin-graphql-codegen",
    async buildStart() {
      // noinspection ES6MissingAwait
      codegen(this.meta.watchMode);
    },
  };
}

这里其实还可以使用 worker_threads 尝试多线程加速

import { Plugin } from "vite";
import { generate, loadContext } from "@graphql-codegen/cli";
import { isMainThread, parentPort, Worker } from "worker_threads";
import { expose, wrap } from "comlink";
import nodeEndpoint from "comlink/dist/umd/node-adapter";

async function codegen(watch: boolean) {
  const codegenContext = await loadContext();
  codegenContext.updateConfig({ watch });
  try {
    await generate(codegenContext);
  } catch (error) {
    console.log("Something went wrong.");
  }
}

if (!isMainThread) {
  expose(codegen, nodeEndpoint(parentPort!));
}

export function graphQLCodegen(): Plugin {
  return {
    name: "rollup-plugin-graphql-codegen",
    async buildStart() {
      const worker = new Worker(__filename);
      try {
        const codegenWorker = wrap<(watch: boolean) => void>(
          nodeEndpoint(worker)
        );
        // noinspection ES6MissingAwait
        codegenWorker(this.meta.watchMode);
      } finally {
        worker.unref();
      }
    },
  };
}

已发布至 @liuli-util/rollup-plugin-graphql-codegen

安装 chrome 插件

GraphQL Network Inspector

1637290440947

参考

其他方案?

  • 使用 rollup 插件 @rollup/plugin-graphql 直接将 .graphql 文件视为可导入的 es 模块 – 主要问题是要处理相关工具的兼容性,主要包括 jest/eslint。