URQL 与 TypeScript 深度集成指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01033/article/details/148439834

URQL 与 TypeScript 深度集成指南

urql The highly customizable and versatile GraphQL client with which you add on features like normalized caching as you grow. 项目地址: https://gitcode.com/gh_mirrors/ur/urql

前言

在现代前端开发中，类型安全已成为提升开发效率和代码质量的关键因素。URQL 作为一款轻量级且功能强大的 GraphQL 客户端，通过与 TypeScript 的深度集成，能够为开发者提供完整的类型安全支持。本文将详细介绍如何配置和使用 URQL 与 TypeScript 的集成方案。

环境准备

安装必要依赖

首先需要安装以下开发依赖：

yarn add -D graphql typescript @graphql-codegen/cli @graphql-codegen/client-preset
# 或使用 npm
npm install -D graphql typescript @graphql-codegen/cli @graphql-codegen/client-preset

这些包提供了 GraphQL 类型生成所需的核心功能：

graphql: GraphQL 核心库
typescript: TypeScript 支持
@graphql-codegen/cli: 代码生成器命令行工具
@graphql-codegen/client-preset: 客户端预设配置

配置脚本命令

在 package.json 中添加代码生成脚本：

{
  "scripts": {
    "codegen": "graphql-codegen"
  }
}

项目配置

根据项目使用的框架不同，配置方式略有差异。

React 项目配置

创建 codegen.ts 配置文件：

import { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: '你的GraphQL API地址',
  documents: ['src/**/*.tsx'],
  ignoreNoDocuments: true, // 提升文件监听体验
  generates: {
    './src/gql/': {
      preset: 'client',
      plugins: [],
    },
  },
};

export default config;

Vue 项目配置

Vue 项目需要额外配置类型导入方式：

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: '你的GraphQL API地址',
  documents: ['src/**/*.vue'],
  ignoreNoDocuments: true,
  generates: {
    './src/gql/': {
      preset: 'client',
      config: {
        useTypeImports: true, // 使用 TypeScript 的类型导入语法
      },
      plugins: [],
    },
  },
};

export default config;

类型化查询、变更和订阅

配置完成后，运行代码生成器：

yarn codegen
# 或
npm run codegen

这将生成 ./src/gql 目录，其中包含一个 graphql() 函数，用于编写类型安全的 GraphQL 操作。

使用示例

以下是一个 React 组件的示例：

import React from 'react';
import { useQuery } from 'urql';
import Film from './Film';
import { graphql } from '../src/gql';

// 使用 graphql() 函数定义查询
const allFilmsWithVariablesQueryDocument = graphql(/* GraphQL */ `
  query allFilmsWithVariablesQuery($first: Int!) {
    allFilms(first: $first) {
      edges {
        node {
          ...FilmItem
        }
      }
    }
  }
`);

function App() {
  // data 和 variables 都已自动类型化
  const [{ data }] = useQuery({
    query: allFilmsWithVariablesQueryDocument,
    variables: { first: 10 },
  });
  
  return (
    <div className="App">
      {data && (
        <ul>
          {data.allFilms?.edges?.map(
            (e, i) => e?.node && <Film film={e?.node} key={`film-${i}`} />
          )}
        </ul>
      )}
    </div>
  );
}

export default App;

通过这种方式，查询结果和变量都将自动获得正确的 TypeScript 类型。

深入使用片段(Fragments)

GraphQL 片段是组织查询和组件数据需求的强大工具。

定义片段

import { FragmentType, useFragment } from './gql/fragment-masking';
import { graphql } from '../src/gql';

export const FilmFragment = graphql(/* GraphQL */ `
  fragment FilmItem on Film {
    id
    title
    releaseDate
    producers
  }
`);

使用片段组件

const Film = (props: {
  film: FragmentType<typeof FilmFragment>;
}) => {
  const film = useFragment(FilmFragment, props.film);
  return (
    <div>
      <h3>{film.title}</h3>
      <p>{film.releaseDate}</p>
    </div>
  );
};

关键点说明：