GraphQL 在前端的数据获取架构：查询优化、缓存策略与 Fragment 治理

2026/7/17 16:00:02

GraphQL 在前端的数据获取架构：查询优化、缓存策略与 Fragment 治理

GraphQL 解决了 REST 接口的过度获取（over-fetching）和欠获取（under-fetching）问题，但引入了新的挑战：查询膨胀、缓存失效、Fragment 碎片化。一个未经治理的 GraphQL 前端，可能在单个页面发起 200 行的查询，包含 50 个 Fragment，并且缺乏有效的缓存策略。

本文从查询优化、缓存架构和 Fragment 治理三个维度，梳理 GraphQL 在前端的数据获取最佳实践。

一、查询优化：从构建到执行

查询编译与持久化

大型查询的传输本身就消耗带宽。持久化查询（Persisted Queries）将查询文本替换为一个哈希 ID，服务端通过 ID 查找预存的查询。

// 持久化查询的实现 class PersistedQueryManager { private queryStore: Map<string, string> = new Map(); private serverUrl: string; constructor(serverUrl: string) { this.serverUrl = serverUrl; } /** * 注册查询：本地存储查询文本，服务端同步 */ async registerQuery(id: string, query: string): Promise<void> { // 本地缓存 this.queryStore.set(id, query); // 服务端注册 try { const response = await fetch(`${this.serverUrl}/persisted-queries`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id, query }), }); if (!response.ok) { throw new Error(`查询注册失败: ${response.statusText}`); } } catch (error) { console.error('持久化查询注册失败:', error); } } /** * 执行持久化查询：仅发送 ID，不发送查询文本 */ async execute( id: string, variables: Record<string, unknown> = {} ): Promise<unknown> { const response = await fetch(this.serverUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ extensions: { persistedQuery: { version: 1, sha256Hash: id, }, }, variables, }), }); if (!response.ok) { // 如果服务端未注册，回退到完整查询 const fullQuery = this.queryStore.get(id); if (fullQuery) { return this.executeFallback(fullQuery, variables); } throw new Error(`GraphQL 请求失败: ${response.statusText}`); } return response.json(); } /** * 回退方案：发送完整查询 */ private async executeFallback( query: string, variables: Record<string, unknown> ): Promise<unknown> { const response = await fetch(this.serverUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query, variables }), }); return response.json(); } }

查询复杂度限制

客户端需要防范查询膨胀。通过编译时工具检测查询的深度、广度等复杂度指标。

// 查询复杂度分析器 class QueryComplexityAnalyzer { /** * 计算查询的复杂度分数 * 简单字段 = 1 分，连接字段 = 子字段分数 × 连接数量 */ analyze(queryAST: QueryNode): ComplexityReport { const score = this.calculateNodeScore(queryAST); return { score, /** 复杂度级别 */ level: this.classifyScore(score), /** 字段总数 */ fieldCount: this.countFields(queryAST), /** 最大嵌套深度 */ maxDepth: this.calculateDepth(queryAST, 0), /** 是否超过告警阈值 */ warnings: this.generateWarnings(score, queryAST), }; } private calculateNodeScore(node: QueryNode): number { let score = 0; for (const field of node.fields) { if (field.connection) { // 连接字段：基础 2 分 + 子字段分数 × 参数中的 first/last 值 const childScore = this.calculateNodeScore(field); const multiplier = this.getConnectionMultiplier(field); score += 2 + childScore * multiplier; } else { score += 1; } } return score; } /** * 获取连接的倍数因子 */ private getConnectionMultiplier(field: QueryField): number { const first = field.arguments?.first; const last = field.arguments?.last; if (typeof first === 'number') return Math.min(first, 100); if (typeof last === 'number') return Math.min(last, 100); return 10; // 默认值 } /** * 分类分值 */ private classifyScore(score: number): 'safe' | 'warning' | 'danger' { if (score <= 50) return 'safe'; if (score <= 200) return 'warning'; return 'danger'; } /** * 统计字段总数 */ private countFields(node: QueryNode): number { let count = node.fields.length; for (const field of node.fields) { if (field.connection) { count += this.countFields(field); } } return count; } /** * 计算嵌套深度 */ private calculateDepth(node: QueryNode, currentDepth: number): number { let maxDepth = currentDepth; for (const field of node.fields) { if (field.connection) { const depth = this.calculateDepth(field, currentDepth + 1); maxDepth = Math.max(maxDepth, depth); } } return maxDepth; } private generateWarnings( score: number, node: QueryNode ): string[] { const warnings: string[] = []; if (score > 200) { warnings.push(`查询复杂度过高 (${score})，建议拆分为多个子查询`); } if (this.countFields(node) > 30) { warnings.push(`查询字段过多，建议使用 Fragment 精简`); } return warnings; } } // AST 节点类型定义 interface QueryNode { fields: QueryField[]; } interface QueryField { connection?: boolean; arguments?: Record<string, unknown>; fields?: QueryField[]; }

二、缓存策略：规范化存储

GraphQL 缓存的难点在于响应是嵌套结构，而数据应该在存储层扁平化（规范化），使得不同查询之间能共享缓存。

// GraphQL 规范化缓存的实现 type NormalizedCache = Map<string, Map<string, Entity>>; interface Entity { __typename: string; id: string; fields: Record<string, unknown>; } class NormalizedCacheStore { /** 实体存储：typename -> id -> entity */ private store: NormalizedCache = new Map(); /** 查询缓存：序列化的查询变量 -> 响应 */ private queryCache: Map<string, { data: unknown; timestamp: number }> = new Map(); /** 缓存有效期（毫秒） */ private ttl: number = 5 * 60 * 1000; /** * 写入规范化缓存 * @param data - GraphQL 响应数据 */ write(data: Record<string, unknown>): void { this.normalizeAndWrite(data); } /** * 递归规范化并写入 */ private normalizeAndWrite( data: Record<string, unknown>, path: string[] = [] ): void { for (const [key, value] of Object.entries(data)) { if (value === null || value === undefined) continue; if (this.isEntity(value)) { const entity = value as Entity; this.writeEntity(entity); } else if (Array.isArray(value)) { for (const item of value) { if (this.isEntity(item)) { this.writeEntity(item as Entity); } } } else if (typeof value === 'object') { // 递归处理嵌套对象 this.normalizeAndWrite(value as Record<string, unknown>, [...path, key]); } } } /** * 判断对象是否为 GraphQL 实体（包含 __typename 和 id） */ private isEntity(obj: unknown): boolean { return ( typeof obj === 'object' && obj !== null && '__typename' in obj && 'id' in obj ); } /** * 写入单个实体 */ private writeEntity(entity: Entity): void { const { __typename, id, ...fields } = entity; if (!this.store.has(__typename)) { this.store.set(__typename, new Map()); } const typeStore = this.store.get(__typename)!; const existing = typeStore.get(id); if (existing) { // 合并字段：新字段覆盖旧字段 existing.fields = { ...existing.fields, ...fields }; } else { typeStore.set(id, { __typename, id, fields }); } } /** * 读取实体 */ readEntity(__typename: string, id: string): Entity | undefined { return this.store.get(__typename)?.get(id); } /** * 缓存查询结果 */ cacheQuery( queryKey: string, data: unknown, variables: Record<string, unknown> = {} ): void { const key = this.serializeKey(queryKey, variables); this.queryCache.set(key, { data, timestamp: Date.now() }); // 同时写入规范化存储 if (typeof data === 'object' && data !== null) { this.write(data as Record<string, unknown>); } } /** * 读取查询缓存 */ getCachedQuery( queryKey: string, variables: Record<string, unknown> = {} ): unknown | null { const key = this.serializeKey(queryKey, variables); const cached = this.queryCache.get(key); if (!cached) return null; if (Date.now() - cached.timestamp > this.ttl) { this.queryCache.delete(key); return null; } return cached.data; } /** * 序列化缓存键 */ private serializeKey( queryKey: string, variables: Record<string, unknown> ): string { return `${queryKey}:${JSON.stringify(variables, Object.keys(variables).sort())}`; } /** * 失效特定实体类型的所有缓存 */ invalidateType(__typename: string): void { this.store.delete(__typename); // 清除相关的查询缓存（简单策略：全部清除） this.queryCache.clear(); } /** * 失效特定实体 */ invalidateEntity(__typename: string, id: string): void { this.store.get(__typename)?.delete(id); this.queryCache.clear(); } }

三、Fragment 治理策略

Fragment 是 GraphQL 的核心复用单元，但无治理的 Fragment 会演变为维护灾难。

// Fragment 注册表：集中管理所有 Fragment class FragmentRegistry { /** Fragment 名称 → 定义 */ private fragments: Map<string, FragmentDef> = new Map(); /** Fragment → 使用它的组件 */ private usageMap: Map<string, Set<string>> = new Map(); /** * 注册 Fragment */ register(name: string, definition: FragmentDef, component: string): void { if (this.fragments.has(name)) { console.warn( `Fragment "${name}" 已注册，组件 ${component} 将覆盖原有定义` ); } this.fragments.set(name, definition); // 记录使用关系 if (!this.usageMap.has(name)) { this.usageMap.set(name, new Set()); } this.usageMap.get(name)!.add(component); } /** * 检查孤儿 Fragment：已定义但无组件使用 */ findOrphanFragments(): string[] { const orphans: string[] = []; for (const [name, def] of this.fragments) { const usage = this.usageMap.get(name); if (!usage || usage.size === 0) { orphans.push(name); } } return orphans; } /** * 检查重复 Fragment：相同字段定义但不同名称 */ findDuplicateFragments(): Array<{ names: string[]; fields: string[] }> { const fieldMap = new Map<string, string[]>(); for (const [name, def] of this.fragments) { const fieldKey = def.fields.sort().join(','); if (fieldMap.has(fieldKey)) { fieldMap.get(fieldKey)!.push(name); } else { fieldMap.set(fieldKey, [name]); } } return [...fieldMap.entries()] .filter(([, names]) => names.length > 1) .map(([fields, names]) => ({ names, fields: fields.split(','), })); } /** * 构建 Fragment 依赖图 */ buildDependencyGraph(): Map<string, string[]> { const graph = new Map<string, string[]>(); for (const [name, def] of this.fragments) { const deps = this.extractFragmentDependencies(def.body); graph.set(name, deps); } return graph; } /** * 从 Fragment 定义体中提取依赖的其他 Fragment */ private extractFragmentDependencies(body: string): string[] { const pattern = /\.\.\.(\w+)/g; const deps: string[] = []; let match: RegExpExecArray | null; while ((match = pattern.exec(body)) !== null) { if (match[1] !== '') { deps.push(match[1]); } } return deps; } /** * 检测循环依赖 */ detectCircularDependencies(): string[][] { const graph = this.buildDependencyGraph(); const cycles: string[][] = []; const visited = new Set<string>(); const recStack = new Set<string>(); const dfs = (node: string, path: string[]): void => { visited.add(node); recStack.add(node); const currentPath = [...path, node]; for (const neighbor of graph.get(node) || []) { if (!visited.has(neighbor)) { dfs(neighbor, currentPath); } else if (recStack.has(neighbor)) { // 发现环 const cycleStart = currentPath.indexOf(neighbor); cycles.push(currentPath.slice(cycleStart)); } } recStack.delete(node); }; for (const node of graph.keys()) { if (!visited.has(node)) { dfs(node, []); } } return cycles; } } interface FragmentDef { /** 目标类型 */ on: string; /** 字段列表 */ fields: string[]; /** Fragment 定义体 */ body: string; }

Fragment 命名与组织规范

// Fragment 命名规范: ComponentName_FieldGroup // 示例：UserProfile_BasicInfo, PostList_PostCard const fragmentNamingConvention = { /** Fragment 命名校验 */ validate(name: string, component: string): boolean { // 格式: {ComponentName}_{FieldGroup} const pattern = /^[A-Z][a-zA-Z]+_[A-Z][a-zA-Z]+$/; return pattern.test(name); }, /** 建议：每个组件最多 3 个 Fragment */ maxFragmentsPerComponent: 3, /** 建议：每个 Fragment 最多 10 个字段 */ maxFieldsPerFragment: 10, };

四、查询执行策略：Batching 与 Dedup

// 请求批量处理与去重 class QueryBatcher { private pending: Map<string, QueryRequest> = new Map(); private batchTimer: ReturnType<typeof setTimeout> | null = null; private batchInterval: number = 10; // 10ms 批量窗口 /** * 添加查询到批处理队列 */ enqueue( query: string, variables: Record<string, unknown>, resolve: (value: unknown) => void, reject: (reason: Error) => void ): void { const key = JSON.stringify({ query, variables }); // 去重：相同查询合并为一个 if (this.pending.has(key)) { this.pending.get(key)!.subscribers.push({ resolve, reject }); return; } this.pending.set(key, { query, variables, subscribers: [{ resolve, reject }], }); // 延迟批量发送 if (!this.batchTimer) { this.batchTimer = setTimeout(() => this.flush(), this.batchInterval); } } /** * 批量执行所有待处理查询 */ private async flush(): Promise<void> { this.batchTimer = null; const batch = [...this.pending.entries()]; this.pending.clear(); // 构造批量查询请求 const batchQuery = batch.map(([, req]) => ({ query: req.query, variables: req.variables, })); try { const response = await fetch('/graphql/batch', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(batchQuery), }); if (!response.ok) { throw new Error(`批量请求失败: ${response.statusText}`); } const results = await response.json(); // 将结果分发回各个订阅者 for (let i = 0; i < batch.length; i++) { const [, req] = batch[i]; const result = results[i]; for (const subscriber of req.subscribers) { if (result.errors) { subscriber.reject(new Error(result.errors[0].message)); } else { subscriber.resolve(result.data); } } } } catch (error) { // 失败时通知所有订阅者 for (const [, req] of batch) { for (const subscriber of req.subscribers) { subscriber.reject(error as Error); } } } } } interface QueryRequest { query: string; variables: Record<string, unknown>; subscribers: Array<{ resolve: (value: unknown) => void; reject: (reason: Error) => void; }>; }