Vendure电商平台：前端GraphQL代码生成指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01034/article/details/148488044

Vendure电商平台：前端GraphQL代码生成指南

vendure A headless GraphQL commerce platform for the modern web 项目地址: https://gitcode.com/gh_mirrors/ve/vendure

前言

在现代前端开发中，类型安全已成为提升开发效率和代码质量的关键因素。Vendure电商平台基于GraphQL API设计，通过代码生成技术可以自动创建TypeScript类型定义，让开发者获得完整的类型提示和编译时检查。本文将详细介绍如何在Vendure前端项目中配置和使用GraphQL代码生成工具。

代码生成原理

GraphQL代码生成的核心思想是基于GraphQL schema和操作自动生成对应的TypeScript类型定义。这种技术带来了几个显著优势：

类型安全：所有API调用都会进行类型检查
开发效率：自动补全和类型提示减少查阅文档时间
维护性：当API变更时，类型系统会立即反映这些变化

环境准备

安装依赖

首先需要安装必要的npm包：

npm i graphql
npm i -D typescript @graphql-codegen/cli

这里安装了两个关键包：

graphql：GraphQL核心库
@graphql-codegen/cli：代码生成器命令行工具

初始化配置

运行初始化命令：

npx graphql-code-generator init

初始化过程中会询问几个关键配置项：

Schema位置：输入http://localhost:3000/shop-api（Vendure默认的GraphQL端点）
操作文档位置：指定包含GraphQL查询的文件模式，如src/**/*.{ts,tsx}
配置文件格式：选择codegen.ts

高级配置

初始化完成后，需要修改生成的codegen.ts文件以适配Vendure的特殊需求：

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

const config: CodegenConfig = {
  overwrite: true,
  schema: 'http://localhost:3000/shop-api',
  documents: 'src/**/*.graphql.ts',
  generates: {
    'src/gql/': {
      preset: 'client',
      plugins: [],
      config: {
        scalars: {
          // 将Money标量映射为TypeScript的number类型
          Money: 'number',
        },
        namingConvention: {
          // 防止生成的枚举与内置类型冲突
          enumValues: 'keep',
        },
      }
    },
  }
};

export default config;

特别说明：

Money标量处理：Vendure中的价格字段使用Money标量类型，这里明确指定其对应TypeScript的number类型
枚举命名策略：保持原样避免与内置类型冲突

执行代码生成

配置完成后，运行生成命令：

npm run codegen

注意：运行前确保Vendure服务器已启动，因为代码生成器需要从运行中的服务器获取schema信息。

命令执行后会在src/gql目录下生成类型定义文件，包含：

所有GraphQL查询的类型定义
响应数据结构
变量类型定义

实际应用示例

生成类型后，可以在React组件中这样使用：

import { useQuery } from '@tanstack/react-query';
import request from 'graphql-request'
import { graphql } from './gql';

// 定义查询（自动获得类型支持）
const GET_PRODUCTS = graphql(`
    query GetProducts($options: ProductListOptions) {
        products(options: $options) {
            items {
                id
                name
                slug
                featuredAsset {
                    preview
                }
            }
        }
    }
`);

function ProductList() {
  const { isLoading, data } = useQuery({
    queryKey: ['products'],
    queryFn: async () =>
      request(
        'http://localhost:3000/shop-api',
        GET_PRODUCTS,
        {
          // 变量自动类型检查
          options: { take: 3 },
        }
      ),
  });

  // data自动推断为正确的类型
  if (isLoading) return <p>Loading...</p>;

  return data ? (
    data.products.items.map(({ id, name, slug, featuredAsset }) => (
      <div key={id}>
        <h3>{name}</h3>
        <img src={`${featuredAsset.preview}?preset=small`} alt={name} />
      </div>
    ))
  ) : null;
}