Docs
⌘ K

10 минуты

Инструменты клиента The Graph

Этот репозиторий является домом для потребительских инструментов The Graph (как для браузерных, так и для NodeJS сред).

Предисловие

Инструменты, предоставленные в этом репозитории, предназначены для улучшения и расширения разработческого опыта (DX), а также для добавления дополнительного слоя, необходимого для децентрализованных приложений (dApps), чтобы реализовать распределенные приложения.

Разработчики, которые потребляют данные через GraphQL API от The Graph, часто нуждаются в периферийных инструментах для облегчения потребления данных, а также в инструментах, которые позволяют использовать несколько индексаторов одновременно.

Функции и цели

Эта библиотека предназначена для упрощения сетевого аспекта потребления данных для децентрализованных приложений (dApps). Инструменты, предоставленные в этом репозитории, предназначены для работы во время сборки, чтобы сделать выполнение более быстрым и производительным в момент выполнения.

Инструменты, предоставленные в этом репозитории, могут использоваться как самостоятельно, так и в сочетании с любым существующим GraphQL клиентом!

СтатусФункцияПримечания
✅Несколько индексаторовосновано на стратегиях выборки
✅Стратегия выборкиtimeout, retry, fallback, race, highestValue
✅Валидации и оптимизации во время сборки
✅Композиция на стороне клиентас улучшенным планировщиком выполнения (на основе GraphQL-Mesh)
✅Кросс-чейн обработка субграфаИспользование схожих субграфов как единого источника
✅Выполнение сырых данных (автономный режим)напрямую, без GraphQL-клиента
✅Местные (клиентские) мутации
✅Отслеживание автоматического блокаотслеживание номеров блоков как описано здесь
✅Автоматическая пагинациявыполнение нескольких запросов в одном вызове для получения больше лимита индексатора
✅Интеграция с @apollo/client
✅Интеграция с urql
✅Поддержка TypeScriptсо встроенным GraphQL Codegen и TypedDocumentNode
✅@live запросыНа основе опроса

Вы можете найти расширенный архитектурный дизайн здесь

Начало работы

Вы можете подписаться на Episode 45 из graphql.wtf⁠, чтобы узнать больше о Graph Client:

GraphQL.wtf Эпизод 45

Чтобы начать, убедитесь, что установили [The Graph Client CLI] в свой проект:

yarn add -D @graphprotocol/client-cli# или, с NPM:npm install --save-dev @graphprotocol/client-cli

CLI устанавливается как зависимость для разработки, поскольку мы используем его для создания оптимизированных артефактов времени выполнения, которые могут быть загружены непосредственно из Вашего приложения!

Создайте конфигурационный файл (под названием .graphclientrc.yml) и укажите Ваши GraphQL конечные точки, предоставленные The Graph, например:

# .graphclientrc.ymlsources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2

Теперь создайте артефакт времени выполнения, запустив The Graph Client CLI:

graphclient build

Примечание: Вам нужно выполнить это с префиксом yarn, или добавить это как скрипт в свой package.json.

Это должно создать готовую к использованию автономную функцию execute, которую Вы сможете использовать для выполнения операций GraphQL в своем приложении. Вы должны получить вывод, похожий на следующий:

GraphClient: Очистка существующих артефактов GraphClient: Чтение конфигурации 🕸️: Генерация унифицированной схемы 🕸️: Генерация артефактов 🕸️: Генерация индекса в TypeScript 🕸️: Запись index.ts для ESM на диск 🕸️: Очистка 🕸️: Готово! => .graphclient

Теперь артефакт .graphclient для Вас сгенерирован, и Вы можете импортировать его напрямую в свой код и выполнять запросы:

import { execute } from '../.graphclient'const myQuery = gql`  query pairs {    pair(id: "0x00004ee988665cdda9a1080d5792cecd16dc1220") {      id      token0 {        id        symbol        name      }      token1 {        id        symbol        name      }    }  }`async function main() {  const result = await execute(myQuery, {})  console.log(result)}main()

Использование Vanilla JavaScript вместо TypeScript

По умолчанию, GraphClient CLI генерирует артефакты клиента в виде файлов TypeScript, но Вы можете настроить CLI для генерации файлов JavaScript и JSON вместе с дополнительными файлами определений TypeScript, используя --fileType js или --fileType json.

Флаг js генерирует все файлы как JavaScript файлы с синтаксисом ESM, а флаг json генерирует исходные артефакты как JSON файлы, при этом файл точки входа будет на старом синтаксисе CommonJS, поскольку только CommonJS поддерживает JSON файлы как модули.

Если Вы специально не используете CommonJS (require), мы рекомендуем использовать флаг js.

graphclient --fileType js

Инструменты разработки The Graph Client

The Graph Client CLI включает встроенный GraphiQL, который позволяет Вам экспериментировать с запросами в реальном времени.

GraphQL-схема, обслуживаемая в этой среде, представляет собой итоговую схему, основанную на всех составленных субграфах и примененных преобразованиях.

Чтобы запустить DevTool GraphiQL, выполните следующую команду:

graphclient serve-dev

А затем откройте http://localhost:4000/⁠, чтобы использовать GraphiQL. Теперь Вы можете экспериментировать со своей GraphQL-схемой на стороне клиента локально! 🥳

Примеры

Вы также можете обратиться к каталогу с примерами в этом репозитории для более продвинутых примеров и примеров интеграции:

Продвинутые примеры/функции

Настройка сетевых вызовов

Вы можете настроить выполнение сетевых запросов (например, для добавления заголовков аутентификации), используя operationHeaders:

sources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2        operationHeaders:          Authorization: Bearer MY_TOKEN

Вы также можете использовать переменные времени выполнения, если хотите, и указать их декларативным способом:

sources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2        operationHeaders:          Authorization: Bearer {context.config.apiToken}

Затем Вы можете указать следующее, когда выполняете операции:

execute(myQuery, myVariables, {  config: {    apiToken: 'MY_TOKEN',  },})

Полную документацию по обработчику graphql можно найти здесь⁠.

Интерполяция переменных среды

Если Вы хотите использовать переменные среды в конфигурационном файле своего Graph Client, Вы можете использовать интерполяцию с помощью помощника env:

sources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2        operationHeaders:          Authorization: Bearer {env.MY_API_TOKEN} # время выполнения

Затем убедитесь, что MY_API_TOKEN определён, когда Вы выполняете process.env во время выполнения программы.

Вы также можете указать переменные среды, которые будут заполняться во время сборки (при запуске graphclient build), используя непосредственно имя переменной средв:

sources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2        operationHeaders:          Authorization: Bearer ${MY_API_TOKEN} # время разработки

Полную документацию по обработчику graphql можно найти здесь⁠.

Стратегии выборки данных и работа с несколькими Graph-индексаторами

Это обычная практика — использовать несколько индексаторов в децентрализованных приложениях (dApps), поэтому для достижения наилучшего опыта работы с The Graph Вы можете указать несколько стратегий fetch, чтобы сделать процесс более плавным и простым.

Все стратегииfetch можно комбинировать для создания идеального потока выполнения.

`retry`

Механизм retry позволяет указать количество попыток повторного запроса для одной GraphQL конечной точки/источника.

Механизм повторных попыток будет выполняться в обоих случаях: при ошибке сети или при ошибке выполнения (проблемы с индексированием/недоступность индексатора).

sources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2        retry: 2 # укажите здесь, если у вас нестабильный/подверженный ошибкам индексатор
`timeout`

Механизм timeout позволяет задать timeout для указанной конечной точки GraphQL.

sources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2        timeout: 5000 # 5 секунд
`fallback`

Механизм fallback позволяет указать несколько конечных точек GraphQL для одного и того же источника.

Это полезно, если Вы хотите использовать более одного индексатора для одного и того же субграфа и переключаться на другой в случае ошибки или тайм-аута. Вы также можете использовать эту стратегию для использования кастомного индексатора, но в случае необходимости переключаться на The Graph Hosted Service.

sources:  - name: uniswapv2    handler:      graphql:        strategy: fallback        sources:          - endpoint: https://bad-uniswap-v2-api.com            retry: 2            timeout: 5000          - endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2
`race`

Механизм race позволяет указать несколько GraphQL-эндпоинтов для одного источника данных, выполняя их конкурентный опрос при каждом запросе.

Это полезно, если вы хотите использовать несколько индексаторов для одного субграфа и позволить им конкурировать за получение самого быстрого ответа от всех указанных индексаторов.

sources:  - name: uniswapv2    handler:      graphql:        strategy: race        sources:          - endpoint: https://bad-uniswap-v2-api.com          - endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2
`highestValue`

Эта стратегия позволяет отправлять параллельные запросы к различным конечным точкам для одного и того же источника и выбирать наиболее актуальный ответ.

Это полезно, если Вы хотите выбрать наиболее синхронизированные данные для одного субграфа среди нескольких индексаторов/источников.

sources:  - name: uniswapv2    handler:      graphql:        strategy: highestValue        strategyConfig:          selectionSet: |            {              _meta {                block {                  number                }              }            }          value: '_meta.block.number'        sources:          - endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2-1          - endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2-2

Отслеживание блоков

Graph Client может отслеживать номера блоков и выполнять следующие запросы, следуя этой схеме с использованием преобразования blockTracking;

sources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2    transforms:      - blockTracking:          # Вы можете отключить проверку схемы для более быстрого старта          validateSchema: true          # Игнорируйте поля, которые вы не хотите отслеживать          ignoreFieldNames: [users, prices]          # Исключите операции с указанными именами          ignoreOperationNames: [NotFollowed]

Здесь Вы можете попробовать рабочий пример

Автоматическая пагинация

Для большинства субграфов количество записей, которые Вы можете извлечь, ограничено. В этом случае Вам нужно отправить несколько запросов с пагинацией.

query {  # Выдаст ошибку, если лимит равен 1000  users(first: 2000) {    id    name  }}

Таким образом, Вам нужно отправить следующие операции одну за другой:

query {  # Выдаст ошибку, если лимит равен 1000  users(first: 1000) {    id    name  }}

Затем после первого ответа:

query {  # Выдаст ошибку, если лимит равен 1000  users(first: 1000, skip: 1000) {    id    name  }}

После второго ответа Вам пришлось бы вручную объединять результаты. Однако Graph Client позволяет выполнить первый запрос, а затем в фоновом режиме обрабатывает все остальные.

Всё, что Вам нужно сделать, это:

sources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2    transforms:      - autoPagination:          # Вы можете отключить проверку схемы для более быстрого старта          validateSchema: true

Здесь Вы можете попробовать рабочий пример

Композиция на стороне клиента

Graph Client имеет встроенную поддержку композиции GraphQL на стороне клиента (реализованную с помощью GraphQL-Tools Schema-Stitching⁠).

Вы можете использовать эту функцию для создания единого слоя GraphQL из нескольких субграфов, развернутых на нескольких индексаторах.

💡 Совет: Вы можете комбинировать любые источники GraphQL, а не только субграфы!

Тривиальную композицию можно выполнить, добавив более одного источника GraphQL в Ваш файл .graphclientrc.yml, вот пример:

sources:  - name: uniswapv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2  - name: compoundv2    handler:      graphql:        endpoint: https://api.thegraph.com/subgraphs/name/graphprotocol/compound-v2

Пока нет конфликтов между объединёнными схемами, Вы можете их составлять, а затем выполнить один запрос ко всем субграфам:

query myQuery {  # этот запрос поступает от compound-v2  markets(first: 7) {    borrowRate  }  # этот запрос поступает от uniswap-v2  pair(id: "0x00004ee988665cdda9a1080d5792cecd16dc1220") {    id    token0 {      id    }    token1 {      id    }  }}

Вы также можете разрешать конфликты, переименовывать части схемы, добавлять пользовательские поля GraphQL и изменять всю фазу выполнения.

Для сложных сценариев использования композиций обратитесь к следующим ресурсам:

Поддержка TypeScript

Если Ваш проект написан на TypeScript, Вы можете использовать возможности TypedDocumentNode⁠ и получить полностью типизированный опыт работы с GraphQL-клиентом.

Автономный режим The GraphQL, а также популярные библиотеки GraphQL-клиентов, такие как Apollo-Client и urql, имеют встроенную поддержку TypedDocumentNode!

CLI Graph Client поставляется с готовой конфигурацией для GraphQL Code Generator⁠ и может генерировать TypedDocumentNode на основе Ваших GraphQL-операций.

Чтобы начать, определите Ваши GraphQL-операции в коде приложения и укажите пути к этим файлам в разделе documents файла .graphclientrc.yml:

sources:  -  # ... Ваши Субграфы/источники GQL здесьdocuments:  - ./src/example-query.graphql

Вы также можете использовать выражения Glob или даже указывать файлы кода, и CLI автоматически найдет Ваши GraphQL-запросы:

documents:  - './src/**/*.graphql'  - './src/**/*.{ts,tsx,js,jsx}'

Теперь снова выполните команду build в GraphQL CLI, и CLI сгенерирует объект TypedDocumentNode в .graphclient для каждой найденной операции.

Обязательно давайте имена Вашим GraphQL-операциям, иначе они будут проигнорированы!

Например, для запроса с именем query ExampleQuery будет сгенерирован соответствующий ExampleQueryDocument в .graphclient. Теперь вы можете импортировать его и использовать для GraphQL-запросов, получая полностью типизированный опыт без необходимости вручную писать или указывать TypeScript:

import { ExampleQueryDocument, execute } from '../.graphclient'async function main() {  // переменная "result" полностью типизирована и представляет точную структуру полей, которые вы выбрали в вашем запросе.  const result = await execute(ExampleQueryDocument, {})  console.log(result)}

Вы можете найти пример проекта на TypeScript здесь.

Мутации на стороне клиента

Из-за особенностей настройки Graph-Client, возможно добавление схемы на стороне клиента, которую затем можно использовать для выполнения произвольного кода.

Это полезно, потому что Вы можете внедрить пользовательский код в часть своей схемы GraphQL и использовать его как единую схему приложения, что облегчает отслеживание и разработку.

Этот документ объясняет, как добавить пользовательские мутации, но на самом деле Вы можете добавить любую операцию GraphQL (запросы/мутации/подписки). Для получения дополнительной информации о данной функции, см. статью Расширение единой схемы⁠.

Чтобы начать, определите раздел additionalTypeDefs в Вашем конфигурационном файле:

additionalTypeDefs: |  # Мы должны определить отсутствующий тип `Mutation`  extend schema {    mutation: Mutation  }  type Mutation {    doSomething(input: SomeCustomInput!): Boolean!  }  input SomeCustomInput {    field: String!  }

Затем добавьте указатель на файл с пользовательскими GraphQL-ресолверами:

additionalResolvers:  - './resolvers'

Теперь создайте файл resolver.js (или resolvers.ts) в своем проекте и внедрите свою пользовательскую мутацию:

module.exports = {  Mutation: {    async doSomething(root, args, context, info) {      // Здесь Вы можете выполнить все, что хотите.      // Например, использовать библиотеку `web3`, подключить кошелек и так далее.      return true    },  },}

Если Вы используете TypeScript, Вы также можете получить полностью безопасную типизацию подписей, сделав следующее:

import { Resolvers } from './.graphclient'// Теперь всё написано!const resolvers: Resolvers = {  Mutation: {    async doSomething(root, args, context, info) {      // Здесь Вы можете выполнить любые операции, которые хотите.      // Например, использовать библиотеку `web3`, подключить кошелек и так далее.      return true    },  },}export default resolvers

Если Вам нужно внедрить переменные времени выполнения в Ваш context выполнения GraphQL, вы можете использовать следующий сниппет:

execute(  MY_QUERY,  {},  {    myHelper: {}, // это будет доступно в Вашем ресолвере мутации как `context.myHelper`  },)

Вы можете прочитать больше о расширениях схемы на стороне клиента здесь⁠

Вы также можете делегировать и вызывать поля Query в рамках Вашей мутации⁠

Лицензия

Выпущена под лицензией MIT.