在 ts 中使用 graphql

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

场景

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

结合 ts 使用

基本思路

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

使用步骤

以下使用 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 支持

安装插件 JS GraphQL

创建 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
      }
    }
  }
}

最终效果

VSCode 支持

安装插件 Apollo GraphQL

添加配置 apollo.config.js

module.exports = {
  client: {
    service: {
      name: "github GraphQL Schema",
      localSchemaFile: "./schema.graphql",
    },
  },
};

最终效果

集成到 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();
      }
    },
  };
}