Day 27

Day 27：集成 Subgraph 到项目

在 momoweb3 中集成 Uniswap V3 Subgraph，从 The Graph 拉取协议统计与池子数据，完成代码提交与笔记

2025-02-06

The GraphSubgraphGraphQLUniswap V3集成Week4

Day 27: 集成 Subgraph 到项目

Week 4 学习路径

Week 4: NFT与新范式
├── Day 22–25: NFT / 账户抽象 ✅
├── Day 26: The Graph Subgraph 原理 ✅
├── Day 27: 集成 Subgraph 到项目 ✅ ← 今天
└── Day 28: Uniswap 产品分析文章

今日目标

把 Uniswap V3 Subgraph 集成到 momoweb3 项目，用 The Graph 的 GraphQL API 拉取链上索引数据（如协议统计、池子 TVL/成交量），在首页展示并完成代码提交。

实现概览

1. 数据源与端点

项目	说明
网络	Ethereum Mainnet
Subgraph	Uniswap V3（Subgraph ID: `5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV`）
端点	`https://gateway.thegraph.com/api//subgraphs/id/`
认证	需在 The Graph Studio 申请 API Key，环境变量 `NEXT_PUBLIC_GRAPH_API_KEY`

免费额度：Subgraph 查询每月 10 万次 免费，超出后约 $2/10 万次，学习与个人项目足够。

2. 项目结构

src/
├── lib/
│   └── uniswap-subgraph.ts   # Subgraph 客户端与 GraphQL 查询
├── components/
│   └── SubgraphPools.tsx     # 协议统计 + TVL 前 10 池子展示
app/
└── page.tsx                  # 首页增加 Uniswap V3 (Subgraph) 区块

3. 核心代码职责

uniswap-subgraph.ts

getSubgraphUrl()：根据 NEXT_PUBLIC_GRAPH_API_KEY 拼出 Gateway URL，未配置时返回 null。
fetchFactoryStats()：查询 Factory 实体（id: 0x1f98431c8ad98523631ae4a59f267346ea31f984），返回 poolCount、txCount、totalVolumeUSD、totalValueLockedUSD 等。
fetchTopPools(first)：pools 按 totalValueLockedUSD 降序，取前 first 个，含 token0/token1、feeTier、volumeUSD。
fetchEthPriceFromSubgraph()：查询 bundle(id: "1").ethPriceUSD，可用于与 CoinGecko 价格对比（本次仅实现接口，未在 UI 展示）。

SubgraphPools.tsx

未配置 API Key：展示说明文案 + The Graph Studio 申请链接 + .env.local 配置示例。
已配置：请求 fetchFactoryStats 与 fetchTopPools(10)，展示协议级 4 项指标 + TVL 前 10 池子表格（交易对、费率、TVL、成交量），支持刷新。

4. GraphQL 查询示例（本项目实际使用）

协议统计

query FactoryStats {
  factory(id: "0x1f98431c8ad98523631ae4a59f267346ea31f984") {
    poolCount
    txCount
    totalVolumeUSD
    totalVolumeETH
    totalValueLockedUSD
  }
}

TVL 前 N 池子

query TopPools($first: Int!) {
  pools(first: $first, orderBy: totalValueLockedUSD, orderDirection: desc) {
    id
    feeTier
    token0 { id symbol name decimals }
    token1 { id symbol name decimals }
    totalValueLockedUSD
    volumeUSD
    txCount
  }
}

变量: { "first": 10 }

环境配置

在项目根目录 .env.local 中增加：

NEXT_PUBLIC_GRAPH_API_KEY=你的API_KEY

.env.example 已补充该变量说明；README 中已注明可选环境变量与「Set up The Graph integration」已完成。

产出清单

[x] src/lib/uniswap-subgraph.ts：Subgraph 客户端与 Factory / Pools / Bundle 查询。
[x] src/components/SubgraphPools.tsx：协议统计 + 前 10 池子表格，无 Key 时展示配置指引。
[x] 首页集成 Uniswap V3 (Subgraph) 区块。
[x] .env.example 与 README 更新。
[x] 代码提交（Day 27 集成完成）。

与 Day 26 的衔接

Day 26	Day 27
理解 Subgraph 原理、Schema、GraphQL 查询	在项目中用 `fetch` 调同一 Subgraph 端点
在 Explorer/Postman 手写查询	用 TypeScript 封装查询与类型，组件内调用
产出 GraphQL 查询笔记	产出可运行的前端集成与笔记

面试可说的点

为什么用 The Graph 而不是直接读链？ 链上只有事件/状态，聚合与分页要自己扫块、算价格，成本高、体验差；Subgraph 已按实体索引，一次 GraphQL 请求拿协议级统计和池子列表，开发简单、响应快。
免费额度与成本：Subgraph 查询 10 万次/月免费，适合 Demo 与个人项目；量大了再考虑付费或自建 Indexer。

明日预告

Day 28：Uniswap 产品演进案例分析（对比 V2/V3 界面与机制），产出产品分析文章 #1。