API 设计 / 系统课时

组织变量、Fragment 与操作文档

组织变量、Fragment 与操作文档

本课解决 GraphQL 客户端代码最常见的可维护性问题:把动态输入放进变量,把重复字段抽成 Fragment,并让每个操作文档保持稳定、命名明确且具备 TypeScript 类型约束,避免字符串拼接和字段复制逐渐失控。

学习目标

  • 区分操作文档、变量与 Fragment 的职责,避免把运行时值拼进查询字符串。
  • 用 Fragment 复用稳定字段集合,并保持操作名称和文件边界清晰。
  • 使用 TypedDocumentNode 约束查询结果与变量,在调用点获得类型检查。

明确三种职责

操作文档描述“要取哪些字段”,变量提供“这次调用的动态值”,Fragment 则复用“某个 GraphQL 类型上的一组字段”。三者分开后,同一份文档可以反复执行而不需要根据用户输入重新拼接源码。

元素 放什么 不该放什么
操作文档 查询、Mutation、Subscription 的固定结构 用户输入拼接后的字面量
Variables ID、筛选条件、分页参数等运行时值 字段选择结构
Fragment 某个类型上可复用的字段集合 独立执行所需的操作入口

操作应尽量使用名称,例如 GetProducts,这样网络日志、服务端追踪和错误信息都能指向具体操作。动态值则通过 $variable 声明和 variables 对象传入。

把变量与 Fragment 组织成稳定文档

下面是片段示例,假设服务端存在 Product { id: ID!, name: String!, price: Float! } 类型,以及 products(category: String!, limit: Int!) 查询字段。文件放在模块级作用域,避免组件每次渲染时重新定义操作文档。

ts
import { gql, type TypedDocumentNode } from "@apollo/client";

export type ProductCard = {
  __typename: "Product";
  id: string;
  name: string;
  price: number;
};

type GetProductsData = {
  products: ProductCard[];
};

type GetProductsVariables = {
  category: string;
  limit: number;
};

export const PRODUCT_CARD_FRAGMENT = gql`
  fragment ProductCardFields on Product {
    __typename
    id
    name
    price
  }
`;

export const GET_PRODUCTS: TypedDocumentNode<
  GetProductsData,
  GetProductsVariables
> = gql`
  query GetProducts($category: String!, $limit: Int!) {
    products(category: $category, limit: $limit) {
      ...ProductCardFields
    }
  }

  ${PRODUCT_CARD_FRAGMENT}
`;

这里的 ProductCardFields 只能展开到兼容 Product 的位置;变量定义中的 String! 与 Int! 表示调用时必须提供非空值。Fragment 复用的是字段声明,不会自动减少响应数据量,它的主要价值是消除重复并让多个操作共享一致的数据契约。

在调用点只传运行时变量

下面继续使用同一操作文档。组件不修改 GraphQL 字符串,只传入本次查询所需的 category 和 limit,因此文档本身可以被缓存、分析和代码生成工具稳定识别。

tsx
import { useQuery } from "@apollo/client/react";
import { GET_PRODUCTS } from "./graphql/products";

type ProductListProps = {
  category: string;
};

export function ProductList({ category }: ProductListProps) {
  const { data, loading, error } = useQuery(GET_PRODUCTS, {
    variables: {
      category,
      limit: 12,
    },
  });

  if (loading) return <p>Loading products...</p>;
  if (error) return <p>Query failed: {error.message}</p>;

  return (
    <ul>
      {data?.products.map((product) => (
        <li key={product.id}>
          {product.name} — {product.price}
        </li>
      ))}
    </ul>
  );
}

预期结果

text
<Product name> — <VALUE>
<Product name> — <VALUE>
...

实际商品名、价格和行数由服务端数据决定。若把 limit 改成字符串,TypedDocumentNode 声明的变量类型会在 TypeScript 检查阶段阻止错误调用。

用类型检查验证调用契约

在已经安装 TypeScript 并配置好 tsconfig.json 的项目中,可以直接执行类型检查。

bash
npx tsc --noEmit && printf 'TYPECHECK_OK\n'

预期输出

text
TYPECHECK_OK

如果把调用改成 variables: { category, limit: "12" },类型检查应失败,因为 limit 被声明为 number。这能防住调用点的类型错误,但手写的 TypeScript 类型仍可能与服务端 Schema 漂移;生产项目更适合从 Schema 和操作文档生成类型,而不是长期人工同步两套定义。

保持操作文档可维护

不要把用户输入直接插入 gql 模板字符串来生成新的查询文档。除了增加注入与转义风险,它还会让同一逻辑产生大量不同文档,削弱追踪、持久化查询和文档分析工具对操作身份的稳定识别。

Fragment 应围绕稳定的数据需求复用,而不是把所有字段塞进一个“万能 Fragment”。列表卡片、详情页和编辑表单需要的字段不同,就应保留不同 Fragment;同一文档内 Fragment 名称必须唯一,同时为缓存实体保留稳定标识字段,例如 id。操作保持命名、变量保持动态、Fragment 保持聚焦,文档规模增长后仍然容易定位和修改。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

组织变量、Fragment 与操作文档

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通