subgraph-builder

Subgraph 构建器

端到端构建 Goldsky Subgraph：设计架构、编写映射、配置清单，然后构建并部署到托管的 GraphQL 端点。对于需要通过灵活的 GraphQL 查询访问结构化链上数据的 dApp 前端和应用，Subgraph 最为合适。Subgraph 仅支持 EVM。

除非用户明确需要 GraphQL，否则默认选择 Turbo。 Turbo 更快、更可靠、成本更低，而且无需自定义索引代码。构建 Subgraph 之前，请确认用户确实需要托管的 GraphQL API（通常用于 dApp/前端查询链上数据）。如果实际目标是将链上数据移入数据库（PostgreSQL、ClickHouse、Kafka、S3），用于分析或后端，则应改为构建 Turbo 管道——/turbo-builder。只有在需要 GraphQL API 或自定义实体关系建模时，Subgraph 才是合适的选择。提醒一次即可；如果用户明确需要 GraphQL，就不要反复劝阻。

范围

• 构建和编写全新的 Subgraph（架构、映射、清单、部署、端点、标签、Webhook）。
• 不要诊断故障或停滞的 Subgraph——使用 /subgraph-doctor。
• 不要运行 The Graph 迁移——使用 /subgraph-migrate。
• 如需查看完整的 goldsky subgraph 标志，请使用 goldsky subgraph <cmd> --help——本技能介绍工作流，而非罗列标志。

先选择一种方案

你有……	方案	路径
合约和 ABI，希望快速获得 GraphQL API，且不需要自定义逻辑	即时 / 无代码 Subgraph	步骤 A
自定义实体、关系或处理器中的业务逻辑	基于代码的 Subgraph	步骤 B

两种方案都会部署到同一个托管端点。除非用户需要自定义逻辑，否则先选择即时方案。

步骤 0：验证身份验证

运行 goldsky project list 2>&1。如果尚未登录，请使用 /auth-setup。

步骤 A：即时 / 无代码 Subgraph（基于 ABI）

直接从合约 ABI 生成并部署——无需 AssemblyScript。

# Interactive wizard (prompts for contract, network, start block, events/calls)
goldsky subgraph init

# Or one-shot from an ABI file
goldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json

• 向导会写入 JSON 配置，你可以重新部署并为其进行版本管理。
• 使用 --enable-call-handlers 启用合约调用索引（仅与 --from-abi 搭配时有意义）。
• 如需构建功能更丰富的即时 Subgraph（计算字段、eth_call 增强、声明式调用），请参阅 references/schema-and-mappings.md →“即时 Subgraph 增强”。

跳转到 步骤 5：部署。

步骤 B：基于代码的 Subgraph

基于代码的 Subgraph 由三个文件组成：subgraph.yaml（清单）、schema.graphql（实体）和 src/ 中的 AssemblyScript 映射。

步骤 1：搭建脚手架

goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph

常用标志：--abi、--contract、--contract-events、--network、--start-block。请参阅 goldsky subgraph init --help。

步骤 2：设计架构

在 schema.graphql 中定义 dApp 要查询的实体。这是最重要的设计步骤——编写映射之前，先确保实体模型和类型正确。

对于任何非简单架构，均须阅读： references/schema-and-mappings.md，了解标量类型的选择（地址/哈希使用 Bytes，金额使用 BigInt，价格使用 BigDecimal）、@derivedFrom 关系、不可变实体以及协议示例（ERC-20/721、DEX、借贷、治理）。

步骤 3：配置清单

设置 specVersion、数据源（address、abi、startBlock、network），以及将哪些 eventHandlers / callHandlers / blockHandlers 映射到哪些函数。工厂模式（运行时创建的合约）请使用 templates。请参阅 references/schema-and-mappings.md →“清单”。

所有数据源必须使用相同的 apiVersion——混用不同版本会导致验证失败。 声明式 eth_calls（可提升性能）要求 specVersion: 1.2.0 或更高版本——请参阅 references/performance.md。

步骤 4：编写映射并构建

在 src/ 中编写处理器函数，将事件转换为实体。关键惯用写法（获取或创建、用于确保回滚安全的 try_ 调用、Bytes ID、BigInt/BigDecimal 运算）请参阅 references/schema-and-mappings.md。部署之前，请编写 Matchstick 单元测试——参阅 references/testing.md。

goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph --build
# or build as part of deploy below

第 5 步：部署

请先确认目标项目。 deploy 会静默使用 CLI 当前选中的项目，该项目可能并非你预期的项目；而且每次部署都会产生计费的 worker。部署前运行 goldsky project list 确认当前项目（或切换项目），尤其是在标记为 prod 时。

# From a local code-based build
goldsky subgraph deploy my-subgraph/1.0.0 --path .

# Tag at deploy time so your frontend URL is stable
goldsky subgraph deploy my-subgraph/1.0.0 --path . --tag prod

--path、--from-abi、--from-ipfs-hash 和 --from-url 互斥，请择一使用。

第 6 步：端点、标签和 Webhook

部署完成后，配置访问方式。详情请参阅 references/operations.md：

• GraphQL 端点 — https://api.goldsky.com/api/public/<project-id>/subgraphs/<name>/<version>/gn。可切换公开/私有，并为私有端点使用 API 密钥。
• 标签 — 将 prod/staging 固定到某个版本，这样重新部署时前端 URL 不会变化。
• Webhook — 将实体变更（INSERT/UPDATE/DELETE）推送到 HTTP 端点。
• 组合／编排多个子图（包括跨链） — Goldsky 不支持原生子图组合；不要引导用户使用 kind: subgraph / specVersion 1.3.0。组合意味着部署每个子图，然后在下游合并：使用独立端点（最简单）；当数据可从原始链数据推导时，使用 Turbo 流水线（首选）；或当必须复用子图的实体时，使用 Mirror 流水线（这是唯一需要 Mirror 的情况——Turbo 无法从子图获取数据）。识别出此类需求时，应据此引导；开始构建前确认用户确实需要合并。请参阅 references/operations.md。

第 7 步：验证

goldsky subgraph list my-subgraph/1.0.0

然后查询端点，先查询 _meta 以确认正在索引：

{ _meta { hasIndexingErrors block { number } } }

提供摘要（名称/版本、网络、端点 URL、标签）。如果索引停滞或出错，请引导用户前往 /subgraph-doctor。

重要规则

• 构建子图前，先确认是否确实需要 GraphQL。 如果用户只是需要将数据存入数据库，应引导他们使用 Turbo（/turbo-builder）——它更快、更可靠。不要默认选择子图。
• 提出或构建基于子图的任何流水线前，先确认用户确实需要。 对于跨链场景，应确认他们是否确实需要统一查询（而不是只使用两个端点），并优先选择 Turbo 而非 Mirror。在用户做出选择前，不要删除、重新部署或搭建数据库/流水线。
• 子图仅支持 EVM。对于 Solana/Sui/其他非 EVM 链，请使用 /turbo-builder（Turbo 可索引非 EVM 链；子图不能）。
• 每个版本都会单独计费（worker + 实体存储）。删除不再查询的旧版本。
• 重新部署会创建一个新的不可变版本——使用标签保持前端 URL 稳定。
• 确认合约地址存在于目标链上，并使用正确的链 slug（网络错误会导致索引不存在的区块——这是最常见的静默故障；请参阅 /subgraph-doctor）。
• startBlock 必须是被索引链上的区块号——不能使用其他链的区块号或随意填写的数值。使用合约的部署（创建）区块：在该链的区块浏览器中查找（合约创建交易），或使用无代码向导自动检测。设为 0 虽然可行，但会浪费时间扫描空历史记录。
• Goldsky 会永久缓存 RPC 调用，因此重新同步相同或相似的子图会快得多。
• 没有自定义逻辑时，优先使用即时子图；只有在实体建模或处理器逻辑有要求时才使用基于代码的子图。

参考文件

• references/schema-and-mappings.md — Schema 设计、标量类型、关系、清单、AssemblyScript 惯用写法、即时子图增强、协议方案
• references/performance.md — 已声明的 eth_calls、不可变实体、@derivedFrom、时间序列/聚合、修剪、移植、调用缓存
• references/operations.md — GraphQL 端点、公开/私有与 API 密钥、速率限制、标签、Webhook、生命周期、跨链、适用场景
• references/testing.md — Matchstick 单元测试、模拟库、Subgraph Linter

相关工具

• /subgraph-doctor — 诊断故障、停滞或无法部署的子图
• /subgraph-migrate — 将现有子图迁移出 The Graph
• /turbo-builder — 将原始链数据流式传输到数据库，而不是 GraphQL API（非 GraphQL 用例的首选默认方案，包括跨链用例）
• /mirror — 将现有子图实体同步到数据库——这是 Turbo 无法覆盖的唯一情况（例如，跨链合并子图实体）