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!) 查询字段。文件放在模块级作用域,避免组件每次渲染时重新定义操作文档。
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,因此文档本身可以被缓存、分析和代码生成工具稳定识别。
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>
);
}预期结果
<Product name> — <VALUE>
<Product name> — <VALUE>
...实际商品名、价格和行数由服务端数据决定。若把 limit 改成字符串,TypedDocumentNode 声明的变量类型会在 TypeScript 检查阶段阻止错误调用。
用类型检查验证调用契约
在已经安装 TypeScript 并配置好 tsconfig.json 的项目中,可以直接执行类型检查。
npx tsc --noEmit && printf 'TYPECHECK_OK\n'预期输出
TYPECHECK_OK如果把调用改成 variables: { category, limit: "12" },类型检查应失败,因为 limit 被声明为 number。这能防住调用点的类型错误,但手写的 TypeScript 类型仍可能与服务端 Schema 漂移;生产项目更适合从 Schema 和操作文档生成类型,而不是长期人工同步两套定义。
保持操作文档可维护
不要把用户输入直接插入 gql 模板字符串来生成新的查询文档。除了增加注入与转义风险,它还会让同一逻辑产生大量不同文档,削弱追踪、持久化查询和文档分析工具对操作身份的稳定识别。
Fragment 应围绕稳定的数据需求复用,而不是把所有字段塞进一个“万能 Fragment”。列表卡片、详情页和编辑表单需要的字段不同,就应保留不同 Fragment;同一文档内 Fragment 名称必须唯一,同时为缓存实体保留稳定标识字段,例如 id。操作保持命名、变量保持动态、Fragment 保持聚焦,文档规模增长后仍然容易定位和修改。