Пълно въведение към Apollo, инструментариума на GraphQL

Искате да научите JavaScript? Вземете безплатната ми електронна книга на jshandbook.com

Въведение в Аполон

През последните няколко години GraphQL стана изключително популярен като алтернативен подход за изграждане на API над REST.

GraphQL е чудесен начин да оставите клиента да реши кои данни иска да бъдат предавани по мрежата, вместо сървърът да изпраща фиксиран набор от данни.

Също така, тя ви позволява да укажете вложени ресурси, като намалявате понякога напред и назад при работа с REST API.

Apollo е екип и общност, която се изгражда върху GraphQL и предоставя различни инструменти, които ви помагат да изградите вашите проекти.

Лого на Аполон с любезното съдействие на apollographql.com

Инструментите, предоставени от Аполон са главно три: Клиент, Сървър, Двигател.

Apollo Client ви помага да консумирате GraphQL API с поддръжка на най-популярните интерфейсни уеб технологии като React, Vue, Angular, Ember и Meteor. Той също така поддържа собствена разработка за iOS и Android.

Apollo Server е сървърната част на GraphQL, която взаимодейства с вашия backkend и изпраща отговори обратно на клиентските заявки.

Apollo Engine е хоствана инфраструктура (SaaS), която служи като среден човек между клиента и вашия сървър, осигурява кеширане, отчитане на производителността, измерване на натоварването, проследяване на грешки, статистика на използването на схемата, исторически статистики и много други добрини. В момента е безплатен до 1 милион искания на месец и това е единствената част на Аполон, която не е с отворен код и е безплатна. Той осигурява финансиране за отворения код на проекта.

Струва си да се отбележи, че тези три инструмента не са свързани помежду си по никакъв начин и можете да използвате само Apollo Client, за да взаимодействате с API на трета част или да обслужвате API, използвайки Apollo Server, без да имате клиент, например.

Някои ползи от използването на Apollo

Всичко е съвместимо със стандартната спецификация на GraphQL, така че няма собственост или несъвместими технологии в Apollo.

Но е много удобно всички тези инструменти да бъдат събрани под един покрив като пълен пакет за всички ваши нужди, свързани с GraphQL.

Аполон се стреми да бъде лесен за използване и лесно да допринесе за това.

Apollo Client и Apollo Server са всички проекти на общността, изградени от общността, за общността. Аполон е подкрепен от Meteor Development Group (компанията зад Meteor), много популярна JavaScript рамка.

Аполон е фокусиран върху опростяването на нещата. Това е нещо ключово за успеха на една технология, която иска да стане популярна. Голяма част от технологиите или рамките или библиотеките там могат да бъдат излишни за 99% от малките или средните компании и наистина са подходящи за големите компании с много сложни нужди.

Apollo Client

Apollo Client е водещият клиент на JavaScript за GraphQL. Тъй като е задвижван от общността, той е създаден да ви позволява да изграждате UI компоненти, които взаимодействат с GraphQL данни - или при показване на тези данни, или при извършване на мутации, когато се случват определени действия.

Не е необходимо да променяте всичко в приложението си, за да използвате Apollo Client. Можете да започнете само с един миниатюрен слой и една заявка и да разширите оттам.

Най-вече, Apollo Client е създаден да бъде прост, малък и гъвкав от самото начало.

В тази публикация ще опиша подробно процеса на използване на Apollo Client в приложението React.

Ще използвам GitHub GraphQL API като сървър.

Стартирайте приложението React

Използвам create-react-app, за да настроя приложението React, което е много удобно и просто добавя голите кости от това, от което се нуждаем:

npx create-react-app myapp
npx е команда, налична в последните npm версии. Актуализирайте npm, ако нямате тази команда.

Стартирайте локалния сървър на приложението с

старт на преждата

Отворете src / index.js:

import React от 'реагира'
import ReactDOM от 'react-dom'
import './index.css'
импортиране на приложение от „./App“
import registerServiceWorker от './registerServiceWorker'

ReactDOM.render (<Приложение />, document.getElementById ('root'))
registerServiceWorker ()

и премахнете цялото това съдържание.

Започнете с Apollo Boost

Apollo Boost е най-лесният начин да започнете да използвате Apollo Client при нов проект. Ще го инсталираме в допълнение към реакция-apollo и graphql.

В конзолата пуснете

прежда добавете аполо-усилваща реакция-Аполон graphql

или с npm:

npm инсталирайте apollo-boost react-apollo graphql --save

Създайте обект ApolloClient

Започвате, като импортирате ApolloClient от apollo-клиент в index.js:

import {ApolloClient} от 'apollo-client'

const клиент = нов ApolloClient ()

По подразбиране Apollo Client използва / graphql крайната точка на текущия хост, така че нека използва Apollo Link, за да уточни подробностите за връзката към GraphQL сървъра, като зададе URI на крайната точка на GraphQL.

Връзки за Аполон

Apollo Link е представен от HttpLink обект, който импортираме от apollo-link-http.

Apollo Link ни дава начин да опишем как искаме да получим резултата от GraphQL операция и какво искаме да направим с отговора.

Накратко, създавате множество екземпляри Apollo Link, които всички действат по искане на GraphQL един след друг, осигурявайки крайния резултат, който искате. Някои връзки могат да ви дадат възможност да опитате отново, ако не е успешен, пакетиране и много други.

Ще добавим Apollo Link към нашия екземпляр за Apollo Client, за да използваме URI на крайната точка на GitHub GraphQL https://api.github.com/graphql

import {ApolloClient} от 'apollo-client'
import {HttpLink} от 'apollo-link-http'

const клиент = нов ApolloClient ({
  линк: нов HttpLink ({uri: 'https://api.github.com/graphql'})
})

кеширане

Все още не сме свършили. Преди да имаме работен пример, ние също трябва да кажем на ApolloClient коя стратегия за кеширане да използваме: InMemoryCache е по подразбиране и е добра тази, с която да започнете.

import {ApolloClient} от 'apollo-client'
import {HttpLink} от 'apollo-link-http'
import {InMemoryCache} от 'apollo-cache-inmemory'

const клиент = нов ApolloClient ({
  линк: нов HttpLink ({uri: 'https://api.github.com/graphql'}),
  кеш: нов InMemoryCache ()
})

Използвайте ApolloProvider

Сега трябва да свържем Apollo Client към нашето компонентно дърво. Правим това с помощта на ApolloProvider, като обвиваме нашия компонент на приложението в основния файл React:

import React от 'реагира'
import ReactDOM от 'react-dom'
import {ApolloClient} от 'apollo-client'
import {HttpLink} от 'apollo-link-http'
import {InMemoryCache} от 'apollo-cache-inmemory'
import {ApolloProvider} от „react-apollo“

импортиране на приложение от „./App“

const клиент = нов ApolloClient ({
  линк: нов HttpLink ({uri: 'https://api.github.com/graphql'}),
  кеш: нов InMemoryCache ()
})

ReactDOM.render (
  
    <Приложение />
  ,
  document.getElementById ( "корен)
)

Това е достатъчно, за да се покаже екранът на приложението създаване-реакция по подразбиране, с Apollo Client инициализиран:

Маркерът на шаблона на gql

Вече сме готови да направим нещо с Apollo Client и ще вземем някои данни от API на GitHub и ще ги предоставим.

За целта трябва да импортираме маркера на шаблон на gql:

импортиране на gql от 'graphql-tag'

Всяка GraphQL заявка ще бъде изградена с помощта на този шаблон, като този:

const заявка = gql`
  заявка {
    ...
  }
`

Изпълнете заявка за GraphQL

gql беше последният елемент, който ни беше необходим в нашия набор от инструменти.

Вече сме готови да направим нещо с Apollo Client и ще вземем някои данни от API на GitHub и ще ги предоставим.

Получете маркер за достъп за API

Първото нещо, което трябва да направите, е да получите личен маркер за достъп от GitHub.

GitHub го прави лесно, като предоставя интерфейс, от който избирате всяко разрешение, което може да ви е необходимо:

За целите на този примерния урок, не се нуждаете от никое от тези разрешения. Те са предназначени за достъп до лични потребителски данни, но ние просто ще изискаме данните от публичните хранилища.

Означението, което получавате, е OAuth 2.0 носител.

Можете лесно да го тествате, като стартирате от командния ред:

$ curl -H "Упълномощаване: носител *** _ YOUR_TOKEN_HERE _ ***" -X POST -d "\
 {\
   \ "заявка \": \ "заявка {viewer {вход}} \" \
 } \
„https://api.github.com/graphql

което трябва да ви даде резултата

{ "Данни": { "зрителя": { "в акаунта": "*** _ _ YOUR_LOGIN_NAME ***"}}}

или

{
  "message": "Лоши идентификационни данни",
  "документация_url": "https://developer.github.com/v4"
}

ако нещо се обърка.

Използвайте Apollo Link за удостоверяване

И така, трябва да изпратим заглавката за упълномощаване заедно с нашата искане за GraphQL, точно както направихме в заявката за къдрене по-горе.

Можем да направим това с Apollo Client, като създадем междинен софтуер Apollo Link. Започнете с инсталирането на apollo-link-context:

npm инсталирайте apollo-link-context

Този пакет ни позволява да добавим механизъм за удостоверяване чрез задаване на контекста на нашите заявки.

Можем да го използваме в този код, като позоваваме функцията setContext по този начин:

const authLink = setContext ((_, {headers}) => {
  const token = '*** YOUR_TOKEN **'

  връщане {
    заглавки: {
      ... горни
      оторизация: `Приносител $ {token}`
    }
  }
})

и след като имаме тази нова Apollo Link, можем да я съставим с HttpLink, който вече имахме, използвайки метода concat () на връзка:

const link = authLink.concat (httpLink)

Ето пълния код за файла src / index.js с кода, който имаме в момента:

import React от 'реагира'
import ReactDOM от 'react-dom'
import {ApolloClient} от 'apollo-client'
import {HttpLink} от 'apollo-link-http'
import {InMemoryCache} от 'apollo-cache-inmemory'
import {ApolloProvider} от „react-apollo“
import {setContext} от 'apollo-link-context'
импортиране на gql от 'graphql-tag'

импортиране на приложение от „./App“

const httpLink = нов HttpLink ({uri: 'https://api.github.com/graphql'})

const authLink = setContext ((_, {headers}) => {
  const token = '*** YOUR_TOKEN **'

  връщане {
    заглавки: {
      ... горни
      оторизация: `Приносител $ {token}`
    }
  }
})

const link = authLink.concat (httpLink)

const клиент = нов ApolloClient ({
  връзка: връзка,
  кеш: нов InMemoryCache ()
})

ReactDOM.render (
  
    <Приложение />
  ,
  document.getElementById ( "корен)
)
ВНИМАНИЕ Имайте предвид, че този код е пример за образователни цели. Той разкрива вашия GitHub GraphQL API за света, който да видите във вашия фронтален код. Производственият код трябва да поддържа този маркер частен.

Вече можем да направим първата заявка на GraphQL в долната част на този файл и тази примерна заявка изисква имената и собствениците на 10-те най-популярни хранилища с повече от 50 000 звезди:

const POPULAR_REPOSITORIES_LIST = gql`
{
  търсене (заявка: "звезди:> 50000", тип: РЕПОЗИТОРИЯ, първо: 10) {
    repositoryCount
    ръбове {
      възел {
        ... в хранилище {
          име
          собственик {
            Влизам
          }
          stargazers {
            TOTALCOUNT
          }
        }
      }
    }
  }
}
`

client.query ({заявка: POPULAR_REPOSITORIES_LIST}). тогава (console.log)

Изпълняването на този код успешно връща резултата от нашето запитване в конзолата на браузъра:

Представете набор от резултати на GraphQL заявка в компонент

Това, което видяхме досега, вече е готино. Който е още по-готин, използва набора от GraphQL, за да изобрази вашите компоненти.

Оставяме на Apollo Client да носи тежестта (или радостта) или да извлича данни и да борави с всички ниско ниво. Това ни позволява да се съсредоточим върху показването на данните, използвайки подобрителя на компонента graphql, предлаган от react-apollo:

import React от 'реагира'
import {graphql} от 'react-apollo'
import {gql} от 'apollo-boost'

const POPULAR_REPOSITORIES_LIST = gql`
{
  търсене (заявка: "звезди:> 50000", тип: РЕПОЗИТОРИЯ, първо: 10) {
    repositoryCount
    ръбове {
      възел {
        ... в хранилище {
          име
          собственик {
            Влизам
          }
          stargazers {
            TOTALCOUNT
          }
        }
      }
    }
  }
}
`

const App = graphql (POPULAR_REPOSITORIES_LIST) (реквизит =>
  <Ул>
    {props.data.loading? '': props.data.search.edges.map ((ред, i) =>
      
  •         {row.node.owner.login} / {row.node.name}: {''}         <Силно>           {Row.node.stargazers.totalCount}                     )}    ) експорт по подразбиране App
  • Ето резултата от нашето запитване, представено в компонента

    Apollo Server

    Графичният сървър има задачата да приема входящи заявки в крайна точка, да интерпретира заявката и да търси всички данни, необходими за изпълнение на нуждите на клиента.

    Има много различни реализации на GraphQL сървър за всеки възможен език.

    Apollo Server е GraphQL сървър за JavaScript, по-специално за платформата Node.js.

    Той поддържа много популярни Node.js рамки, включително:

    • изразявам
    • Hapi
    • Коа
    • Restify

    Основно Apollo Server ни дава три неща:

    • Начин да опишем нашите данни със схема.
    • Рамката за разделители, които са функции, които пишем, за да извлечем данните, необходими за изпълнение на заявка.
    • Той улеснява обработката на автентичността за нашия API.

    За да научим основите на Apollo Server, няма да използваме нито една от поддържаните Node.js рамки. Вместо това ще използваме нещо, което е изградено от екипа на Аполон, нещо наистина страхотно, което ще бъде основата на нашето обучение: Launchpad.

    Launchpad

    Launchpad е проект, който е част от чадъра на продуктите на Apollo и е доста невероятен инструмент, който ни позволява да пишем код в облака и да създаваме онлайн Apollo Server, точно както бихме пуснали фрагмент от код на Codepen, JSFiddle или JSBin.

    С изключение на това, че вместо да изградим визуален инструмент, който ще бъде изолиран там и означаващ само като витрина или като инструмент за обучение, с Launchpad създаваме GraphQL API. Това ще бъде обществено достъпно.

    Всеки проект на Launchpad се нарича pad и има своя URL адрес на GraphQL за крайна точка, като:

    https://1jzxrj129.lp.gql.zone/graphql

    След като създадете тампон, Launchpad ви дава възможност да изтеглите пълния код на приложението Node.js, което го изпълнява, и просто трябва да стартирате npm install и npm да започнете да имате локално копие на вашия Apollo GraphQL Server.

    В обобщение, това е чудесен инструмент за учене, споделяне и прототип.

    Здравейте свят на Apollo Server

    Всеки път, когато създавате нова подложка за стартиране, вие се представяте с Hello, World! на Apollo Server. Нека се потопим в него

    Първо импортирате функцията makeExecutableSchema от graphql-tools.

    import {makeExecutableSchema} от 'graphql-tools'

    Тази функция се използва за създаване на обект GraphQLSchema, като му предоставя определение на схемата (написано на езика на GraphQL схемата) и набор от разделители.

    Дефиницията на схемата е буквален низ на шаблон, съдържащ описанието на нашата заявка и типовете, свързани с всяко поле:

    const typeDefs = `
      въведете запитване {
        здравей: Струн
      }
    `

    Резолювърът е обект, който картографира полета в схемата за функциите на разделителя. Той може да търси данни, за да отговори на заявка.

    Ето един прост разделител, съдържащ резолюционната функция за полето здравей, който просто връща Hello Hello! низ:

    const resvers = {
      Запитване: {
        здравей: (root, args, context) => {
          връщане 'Здравей свят!'
        }
      }
    }

    Като се имат предвид тези два елемента, дефиницията на схемата и резолюцията, ние използваме функцията makeExecutableSchema, която импортирахме преди това, за да получим обект GraphQLSchema, който присвояваме на const на схемата.

    експортиране схема const = makeExecutableSchema ({typeDefs, резолюции})

    Това е всичко, което ви трябва, за да обслужвате обикновен API само за четене. Launchpad се грижи за малките детайли.

    Ето пълния код за простия пример Hello World:

    import {makeExecutableSchema} от 'graphql-tools'
    
    const typeDefs = `
      въведете запитване {
        здравей: Струн
      }
    `
    
    const resvers = {
      Запитване: {
        здравей: (root, args, context) => {
          връщане 'Здравей свят!'
        }
      }
    }
    
    export const схема = makeExecutableSchema ({
      typeDefs,
      резолверите
    })

    Launchpad предоставя чудесен вграден инструмент за консумация на API:

    И както казах преди, API е обществено достъпен, така че просто трябва да влезете и да запазите тампона си.

    Направих тампон, който излага крайната си точка на https://kqwwkp0pr7.lp.gql.zone/graphql, така че нека опитаме с помощта на curl от командния ред:

    $ curl \
      -X POST \
      -H "Тип съдържание: application / json" \
      --data '{"query": "{hello}"}} \
      https://kqwwkp0pr7.lp.gql.zone/graphql

    което успешно ни дава резултатът, който очакваме:

    {
      "данни": {
        "здравей": "Здравей свят!"
      }
    }

    Стартирайте локално GraphQL Server

    Споменахме, че всичко, което създадете в Launchpad, е за изтегляне, така че нека да продължим.

    Пакетът е съставен от два файла. Първата, schema.js е това, което имаме по-горе.

    Вторият, server.js, беше невидим в Launchpad и именно това осигурява основната функционалност на Apollo Server, задвижвана от Express, популярната рамка на Node.js.

    Това не е най-простият пример за настройка на Apollo Server, така че за да обясня, ще го заменя с по-прост пример (но не се колебайте да го проучите, след като сте разбрали основите).

    Вашият първи код на Apollo Server

    Първо, стартирайте npm install и npm start на стартовия код, който сте изтеглили.

    Сървърът на възлите, който инициализирахме превиузно, използва nodemon за рестартиране на сървъра, когато файловете се променят, така че когато промените кода, сървърът се рестартира с приложените промени.

    Добавете този код в server.js:

    const express = изисквам ('express')
    const bodyParser = изисквам ('body-parser')
    const {graphqlExpress} = изисквам ('apollo-server-express')
    const {schema} = изисквам ('./ схема')
    
    const сървър = express ()
    
    server.use ('/ graphql', bodyParser.json (), graphqlExpress ({схема}))
    
    server.listen (3000, () => {
      console.log („Слушане на GraphQL на http: // localhost: 3000 / graphql“)
    })

    Само с 11 реда това е много по-просто от сървъра, създаден от Launchpad, защото премахнахме всички неща, които направиха този код по-гъвкав за техните нужди.

    Кодирането ви принуждава да вземате трудни решения: колко гъвкавост ви трябва сега? Колко важно е да имате чист, разбираем код, който можете да изберете от шест месеца и лесно да го оправите или да предавате на други разработчици и членове на екипа, така че да могат да бъдат продуктивни за възможно най-малко време?

    Ето какво прави кодът:

    Първо импортираме няколко библиотеки, които ще използваме.

    • експресно, което ще даде възможност на основната функционалност на мрежата да разкрие крайната точка
    • bodyParser е средният софтуер за анализ на тялото на Node
    • graphqlExpress е обектът Apollo Server за Express
    const express = изисквам ('express')
    const bodyParser = изисквам ('body-parser')
    const {graphqlExpress} = изисквам ('apollo-server-express')

    След това импортираме обекта GraphQLSchema, който създадохме във файла schema.js по-горе като Схема:

    const {schema} = изисквам ('./ схема')

    Ето някои стандартни експресни набори и ние просто инициализираме сървър на порт 3000

    const сървър = express ()

    Сега сме готови да инициализираме Apollo Server:

    graphqlExpress ({схема})

    и ние го предаваме като обратен сигнал към крайната ни точка към HTTP JSON заявки:

    server.use ('/ graphql', bodyParser.json (), graphqlExpress ({схема}))

    Всичко, което трябва сега, е да стартираме Express:

    server.listen (3000, () => {
      console.log („Слушане на GraphQL на http: // localhost: 3000 / graphql“)
    })

    Добавете крайна точка на GraphiQL

    Ако използвате GraphiQL, можете лесно да добавите / graphiql крайна точка, за да консумирате с GraphiQL интерактивен IDE в браузъра:

    server.use ('/ graphiql', graphiqlExpress ({
      крайна точкаURL: '/ graphql',
      заявка: ``
    }))

    Сега просто трябва да стартираме Express сървъра:

    server.listen (PORT, () => {
      console.log („Слушане на GraphQL на http: // localhost: 3000 / graphql“)
      console.log („Слушане на GraphiQL на http: // localhost: 3000 / graphiql“)
    })

    Можете да го тествате, като използвате curl отново:

    $ curl \
      -X POST \
      -H "Тип съдържание: application / json" \
      --data '{"query": "{hello}"}} \
      HTTP: // Localhost: 3000 / graphql

    Това ще ви даде същия резултат като по-горе, където сте се обадили на стартовите сървъри:

    {
      "данни": {
        "здравей": "Здравей свят!"
      }
    }
    Искате да научите JavaScript? Вземете безплатната ми електронна книга на jshandbook.com