GraphQL 联邦架构在 DApp 中的实践：拆分合约查询与用户服务的 Schema 治理

一、单体 GraphQL 的膨胀困境

DApp 后端在一开始时，通常是一个简单的 Express 或 Fastify 服务，用 The Graph 的托管服务处理链上查询，再加几个 REST 端点管理用户数据。这个阶段 GraphQL 只有一个 schema、一个 Apollo Server 实例，清晰可控。但随着协议功能扩展 —— 加了治理模块、跨链桥、NFT 市场、DAO 投票 —— Schema 开始像癌细胞一样膨胀。

典型的症状包括：一个Pool类型同时承载了 DEX 流动性、借贷池、质押池三种语义，字段数量突破 30 个；Resolver 之间隐性依赖严重，User.positions内部调用了Pool.tvInUSD，造成 N+1 查询成倍放大；不同团队往同一个 Schema 里加字段时频繁产生类型冲突。

GraphQL 联邦架构（Federation）正是为了解决这个"单体 Schema 爆炸"问题而设计的。核心思想是把 Schema 按业务域拆分成多个独立服务，每个服务维护自己领域的类型和 Resolver，联邦网关（Gateway）负责在运行时把分散的 Schema 组合成一个统一的查询入口。

flowchart TD Client[DApp 前端] --> Gateway[Apollo Router / 联邦网关] Gateway --> PoolSrvc[Pool 服务] Gateway --> UserSrvc[User 服务] Gateway --> GovSrvc[治理服务] Gateway --> BridgeSrvc[跨链桥服务] PoolSrvc --> TheGraph[The Graph 子图] UserSrvc --> DB[(PostgreSQL)] GovSrvc --> ChainRPC[链上 RPC] BridgeSrvc --> BridgeAPI[跨链桥 API] subgraph 联邦子图 PoolSrvc UserSrvc GovSrvc BridgeSrvc end

二、联邦架构的实体扩展与查询规划

GraphQL Federation 的两个核心机制是实体扩展和查询规划。理解这两个机制才能正确设计子图的类型边界。

实体扩展允许一个子图定义一个实体（如User）的基础字段，另一个子图在不修改原服务的情况下为该实体添加新字段。关键是通过@key指令声明实体的主键，Gateway 用这个主键在子图之间解析跨服务引用。

例如，User服务定义基础用户信息，Pool服务扩展User类型，添加positions字段。当客户端查询{ user(id: "0x...") { address, positions { pool { tvInUSD } } } }时，Gateway 的查询规划器会生成两个阶段的执行计划：先从 User 服务获取基础字段，再用返回的id去 Pool 服务解析positions。

查询规划是一个重要的性能考量。Gateway 不是简单地把子图结果拼接，而是基于 Schema 的@key、@requires、@provides指令来优化执行顺序和并行度。如果规划不合理，一个简单的查询可能变成数次的串行子图调用。

sequenceDiagram participant Client as DApp 客户端 participant Gateway as Apollo Router participant UserService as 用户子图 participant PoolService as Pool 子图 Client->>Gateway: 查询 User 及其持仓 Note over Gateway: 查询规划阶段 Gateway->>Gateway: 分析 schema，识别跨服务引用 Gateway->>UserService: Phase 1: 获取 User 基础字段 UserService-->>Gateway: {id, address, joinedAt} Gateway->>Gateway: 构建实体引用 {__typename: "User", id: "0x..."} Gateway->>PoolService: Phase 2: 用 User id 解析 positions PoolService-->>Gateway: {positions: [...]} Gateway->>Gateway: 合并子图结果 Gateway-->>Client: 统一响应

三、生产级工程实现

3.1 子图定义：用户服务

# user-service/schema.graphql # 用户子图 Schema # 设计考量： # - @key 指令的 fields 参数用 "id" 而非复合键，保持实体主键简单化 # - User.chainAddresses 使用 @shareable 标记：让其他子图也能声明此字段（如跨链桥服务） # - 不在此 Schema 中定义链上数据字段：职责单一，用户服务只管理账户和偏好 extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@shareable"]) type User @key(fields: "id") { id: ID! address: String! @shareable chainAddresses: [String!]! @shareable joinedAt: String! preferences: UserPreferences! totalValueLockedUSD: Float! } type UserPreferences { locale: String! theme: String! notificationsEnabled: Boolean! } type Query { user(id: ID!): User usersByAddress(address: String!): User }

3.2 Pool 子图（实体扩展）

# pool-service/schema.graphql # Pool 子图 Schema — 扩展 User 实体，添加持仓信息 # 设计考量： # - User 类型使用 @key 标识为外部实体：基础定义在 user-service # - Pool 的 tvInUSD 使用 @shareable：治理子图在计算 TVL 时也需要此字段 # - 币种显示精度（decimals）直接在 schema 中提供：前端做格式化不需要额外查询合约 ABI extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@shareable", "@external", "@requires"]) # 声明 User 为外部实体，由 user-service 提供基础字段 type User @key(fields: "id") { id: ID! # @external 表明此字段不在本子图解析，但可能被 @requires 引用 address: String! @external # 扩展字段：用户的流动性持仓 positions(first: Int = 10): [Position!]! } type Pool @key(fields: "id") { id: ID! name: String! tokens: [Token!]! tvInUSD: Float! @shareable volume24hUSD: Float! apr: Float! createdAt: String! } type Token { address: String! symbol: String! decimals: Int! reserve: String! } type Position { id: ID! pool: Pool! liquidity: String! token0Amount: String! token1Amount: String! feesEarnedUSD: Float! } type Query { pool(id: ID!): Pool pools( first: Int = 20, orderBy: PoolOrderBy = VOLUME_DESC, minTVInUSD: Float = 0 ): [Pool!]! } enum PoolOrderBy { VOLUME_DESC TV_IN_USD_DESC APR_DESC CREATED_DESC }

3.3 Apollo Server 子图实现

// pool-service/src/server.ts import { ApolloServer } from '@apollo/server'; import { startStandaloneServer } from '@apollo/server/standalone'; import { buildSubgraphSchema } from '@apollo/subgraph'; import { readFileSync } from 'fs'; import { gql } from 'graphql-tag'; import { PoolResolvers } from './resolvers'; const typeDefs = gql(readFileSync('./schema.graphql', 'utf-8')); /** * Pool 子图 Resolver 实现 * 设计考量： * - User.__resolveReference 是 Federation 的关键入口：当 Gateway 需要在本子图解析 User 字段时， * 会传入 { __typename: "User", id: "..." } 实体引用 * - Pool.tvInUSD 的解析使用缓存的子图数据而非实时 RPC 查询：避免跨服务引用导致的级联延迟 * - positions 解析使用 DataLoader 批量处理：Gateway 的批量查询会导致多个 User.__resolveReference * 调用，DataLoader 将它们合并为单次子图查询 */ const resolvers: PoolResolvers = { User: { /** * Federation 实体引用解析 * 当 Gateway 查询 User.positions 时触发 * { __typename: "User", id: "0x..." } 是 Gateway 传入的实体引用 */ __resolveReference: async (ref, { dataSources }) => { return dataSources.subgraph.getUserPositions(ref.id); }, positions: async (user, { first }, { dataSources }) => { // DataLoader 批量加载，避免 N+1 return dataSources.positionLoader.load({ userId: user.id, first: first ?? 10, }); }, }, Pool: { tokens: async (pool, _, { dataSources }) => { return dataSources.subgraph.getPoolTokens(pool.id); }, tvInUSD: async (pool, _, { dataSources }) => { // 从子图缓存获取 TVL，而非实时 RPC // 实时性要求高的场景，在缓存 TTL 内做 trade-off return dataSources.subgraph.getPoolTVInUSD(pool.id); }, }, Query: { pool: async (_, { id }, { dataSources }) => { return dataSources.subgraph.getPool(id); }, pools: async (_, { first, orderBy, minTVInUSD }, { dataSources }) => { return dataSources.subgraph.getPools({ first, orderBy, minTVInUSD, }); }, }, }; const server = new ApolloServer({ schema: buildSubgraphSchema({ typeDefs, resolvers }), }); const { url } = await startStandaloneServer(server, { listen: { port: 4002 }, }); console.log(`Pool 子图运行在 ${url}`);

3.4 Apollo Router 网关配置

# router.yaml — Apollo Router 网关配置 # 设计考量： # - override_subgraph_url 允许你在本地开发时指向本地子图 # - traffic_shaping 配置超时和重试： # - subgraph 级别的超时用于兜底单服务故障不拖垮整个 Gateway # - 链上 RPC 服务的超时设得比用户服务高：RPC 调用天然更慢 # - cors 配置限制了 allowed_origins：DApp 通常嵌入 iframe 或在钱包浏览器中运行 supergraph: listen: 0.0.0.0:4000 introspection: true override_subgraph_url: users: http://localhost:4001 pools: http://localhost:4002 governance: http://localhost:4003 bridge: http://localhost:4004 traffic_shaping: subgraphs: users: timeout: 5000ms retry: max_attempts: 2 retryable_status_codes: [500, 502, 503, 504] pools: # 池子服务依赖子图 RPC，超时设宽 timeout: 15000ms retry: max_attempts: 1 retryable_status_codes: [500, 502, 503, 504] cors: allow_any_origin: false origins: - https://app.example.com - http://localhost:3000

3.5 DataLoader 批量处理

// pool-service/src/dataloaders/positionLoader.ts import DataLoader from 'dataloader'; /** * Position DataLoader * 设计考量： * - 缓存键使用 userId + first 组合：同一用户的同一查询参数复用缓存 * - 单次批处理周期（tick）内收集所有 load() 调用，合并为一次子图查询 * - maxBatchSize 限制为 50：单次子图查询的实体数量上限，防止超时 */ interface PositionLoadKey { userId: string; first: number; } export function createPositionLoader(subgraphClient: SubgraphClient) { return new DataLoader<PositionLoadKey, Position[]>( async (keys) => { // keys 是当前 tick 内所有 load() 调用的集合 // 构建批量子图查询 const queries = keys.map(({ userId, first }) => ({ query: ` query($userId: String!, $first: Int!) { user(id: $userId) { positions(first: $first) { id liquidity token0Amount token1Amount feesEarnedUSD pool { id tvInUSD } } } } `, variables: { userId, first }, })); const results = await subgraphClient.batchQuery(queries); // 按原始 key 顺序返回结果 return keys.map((key, idx) => results[idx]?.user?.positions ?? []); }, { cacheKeyFn: (key) => `${key.userId}:${key.first}`, maxBatchSize: 50, } ); }

四、边界分析

跨子图查询的延迟叠加。联邦查询的每一层引用解析都是一个额外的网络往返。如果User → positions → pool → tvInUSD这个三跳引用链没有做任何缓存，总延迟会接近 3 倍单服务延迟。需要配合 DataLoader 的批处理和 Apollo Router 的查询缓存来缓解。

Schema 变更的传播问题。一个子图的 Schema 变更可能影响其他子图。比如User服务移除了address字段，但Pool子图通过@external依赖了这个字段，这会在 Gateway 组合阶段报错。解决方案是使用 Schema 组合的 CI 检查：每次子图发布前，在 Gateway 中做一次rover supergraph compose验证。

Gateway 成为单点瓶颈。所有 DApp 查询都经过 Gateway，这既是灵活性所在也是风险所在。Gateway 宕机会导致整个 GraphQL 层不可用。生产环境需要至少配置 Gateway 的水平副本，并通过负载均衡分发流量。

不适用于实时数据流。联邦架构是 "拉取" 模式，不适合 WebSocket 订阅或实时价格推送。对于 DApp 的交易对价格、区块确认等实时数据，应该使用独立的 WebSocket 通道。

五、总结