Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Как мыслить графами или почему GraphQL — это не...

Как мыслить графами или почему GraphQL — это не просто представление структуры БД

Доклад предназначен для тех, кто еще не разрабатывал свои API на GraphQL, и для тех, кто уже попробовал и не увидел особой разницы с REST.
Мы определимся с тем, что такое GraphQL, поговорим о его философии, и попробуем ответить на следующие вопросы:
как пользоваться языком запросов?
что можно сделать с помощью GraphQL?
что нельзя сделать с помощью GraphQL?
что такое схема и зачем она нужна?
как реализовать GraphQL API?
какие паттерны проектирования схемы API существуют?

Dmitry Tsepelev

August 02, 2019
Tweet

More Decks by Dmitry Tsepelev

Other Decks in Programming

Transcript

  1. КАК МЫСЛИТЬ ГРАФАМИ или Почему GraphQL - это не просто

    представление структуры БД Дмитрий Цепелев Злые Марсиане
  2. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev REST GET /users GET /users/:id

    POST /users PATCH /users/:id DELETE /users/:id 5 • ресурсы определяются с помощью URL • действия определяются через HTTP verbs • ассоциации выражены через IDs
  3. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 6 REST • ресурсы определяются

    с помощью URL • действия определяются через HTTP verbs • ассоциации выражены через IDs GET /users GET /users/:id POST /users PATCH /users/:id DELETE /users/:id
  4. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev GET /users/42 { "id": 42,

    "name": "John Doe", "accountId": 23 } 7 REST • ресурсы определяются с помощью URL • действия определяются через HTTP verbs • ассоциации выражены через IDs
  5. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev POST /users/42/join-community POST /communities/67/join 9

    действие определено через URL + HTTP verb Как правильно?
  6. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 11 Представление данных в виде

    графа • каждая сущность - тип • каждый тип имеет список полей (field) • некоторые типы связаны
  7. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev • каждая сущность - тип

    • каждый тип имеет список полей (field) • некоторые типы связаны 12 Представление данных в виде графа
  8. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 13 Представление данных в виде

    графа • каждая сущность - тип • каждый тип имеет список полей (field) • некоторые типы связаны
  9. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 14 Представление данных в виде

    графа • каждая сущность - тип • каждый тип имеет список полей (field) • некоторые типы связаны
  10. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 16 GET /user GET /repos/:owner/:repo

    GET /repos/:owner/:repo/issues Underfetching в REST
  11. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 17 GET /user { "login":

    "octocat", "id": 1, "node_id": "MDQ6VXNlcjE=", "avatar_url": "https:"//github.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https:"//api.github.com/users/octocat", "html_url": "https:"//github.com/octocat", "followers_url": "https:"//api.github.com/users/octocat/followers", "following_url": "https:"//api.github.com/users/octocat/following{/ other_user}", "gists_url": "https:"//api.github.com/users/octocat/gists{/gist_id}", "starred_url": "https:"//api.github.com/users/octocat/starred{/owner}{/ repo}", "subscriptions_url": "https:"//api.github.com/users/octocat/subscriptions", "organizations_url": "https:"//api.github.com/users/octocat/orgs", "repos_url": "https:"//api.github.com/users/octocat/repos", "events_url": "https:"//api.github.com/users/octocat/events{/privacy}", "received_events_url": "https:"//api.github.com/users/octocat/ received_events", "type": "User", "site_admin": false, "name": "monalisa octocat", … Overfetching в REST … "company": "GitHub", "blog": "https:"//github.com/blog", "location": "San Francisco", "email": "[email protected]", "hireable": false, "bio": "There once was""...", "public_repos": 2, "public_gists": 1, "followers": 20, "following": 0, "created_at": "2008-01-14T04:33:35Z", "updated_at": "2008-01-14T04:33:35Z", "private_gists": 81, "total_private_repos": 100, "owned_private_repos": 100, "disk_usage": 10000, "collaborators": 8, "two_factor_authentication": true, "plan": { "name": "Medium", "space": 400, "private_repos": 20, "collaborators": 0 } }
  12. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev Что такое GraphQL? • язык

    запросов • среда исполнения 18
  13. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 19 ⇨ Язык запросов ⇦

    Схема API Реализация API Что может пойти не так Как проектировать схему Эволюция API
  14. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 20 Request: query { currentUserId

    } Response: { "data": { "currentUserId": 42 } } Поля
  15. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 21 Request: query { user(id:

    42) { orders { items { product { title } quantity } } } } Response: { "data": { "user": { "orders": [ { "items": [ { "product": { "title": "iPhone 7" }, "quantity": 2 } ] } ] } } } Аргументы
  16. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 22 Вложенные выборки Request: query

    { user(id: 42) { orders { items { product { title } quantity } } } } Response: { "data": { "user": { "orders": [ { "items": [ { "product": { "title": "iPhone 7" }, "quantity": 2 } ] } ] } } }
  17. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 23 query FetchUser($userId: Int) {

    user(id: $userId) { orders { items { product { title } quantity } } } } variables { "userId": 42 } Именованные запросы
  18. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 24 Переменные query FetchUser($userId: Int)

    { user(id: $userId) { orders { items { product { title } quantity } } } } variables { "userId": 42 }
  19. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev Транспортный уровень 25 • согласно

    спецификации – transport-agnostic • в реализациях: - HTTP POST - один эндпоинт - код ответа 200 - OK
  20. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 26 Request: query { user(id:

    404) { id name } } Response: { "data": null, "errors": [ { "message": "User not found" } ] } Представление ошибок
  21. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 28 Request: mutation { createPost(

    title: "draft", content: "no content" ) { id } } Response: { "data": { "createPost" { "id": 4 } } } Мутации: обновление данных
  22. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 29 Request: subscription { postCreated

    { id title content } } Response: { "data": { "postCreated": { "id": 4, "title": "draft", "content": "no content" } } } Подписки: получение обновлений
  23. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 30 Язык запросов ⇨ Схема

    API ⇦ Реализация API Что может пойти не так Как проектировать схему Эволюция API
  24. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 31 type UserType { name:

    String! orders(page: Int): [OrderType]! } Типы
  25. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 32 Поля type UserType {

    name: String! orders(page: Int): [OrderType]! }
  26. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 33 Скалярные типы type UserType

    { # Int|Float|Boolean|String|ID name: String! orders(page: Int): [OrderType]! }
  27. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 36 type QueryType { users:

    [UserType]! } type MutationType { signUp(login: String!, password: String!): UserType! } type SubscriptionType { userSignedUp: UserType! } Корневые типы
  28. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 37 Валидация аргументов type QueryType

    { orders(page: Int):[OrderType]! } query { orders(page: "1") { id } } { "errors": [{ "message": "Argument 'page' on Field 'orders' has an invalid value. Expected type 'Int'.", "fields": ["query", "orders", "page"] }] }
  29. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 38 enum UserModerationStatus { MODERATION

    APPROVED REJECTED } type UserType { name: String! moderationStatus: UserModerationStatus! } Перечисления
  30. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 39 scalar DateTime type OrderType

    { placedAt: DateTime! } { "placedAt": "2019-03-01T19:18:37+03:00" } Пользовательские скалярные типы
  31. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 42 Язык запросов Схема API

    ⇨ Реализация API ⇦ Что может пойти не так Как проектировать схему Эволюция API
  32. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev class QueryType < GraphQL"::Schema"::Object field

    :users, [UserType], description: "List of all users", null: false def users # SELECT * FROM users; User.all end end QueryType на бэке: объявляем поле 43
  33. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 44 QueryType на бэке: возвращаемый

    тип class QueryType < GraphQL"::Schema"::Object field :users, [UserType], description: "List of all users", null: false def users # SELECT * FROM users; User.all end end
  34. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 45 QueryType на бэке: resolver

    class QueryType < GraphQL"::Schema"::Object field :users, [UserType], description: "List of all users", null: false def users # SELECT * FROM users; User.all end end
  35. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 46 QueryType на бэке: источник

    данных class QueryType < GraphQL"::Schema"::Object field :users, [UserType], description: "List of all users", null: false def users # SELECT * FROM users; User.all end end
  36. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 47 class UserType < GraphQL"::Schema"::Object

    field :name, String, null: false field :orders, [OrderType], null: false do argument :page, Int, required: false end def orders(page: nil) object.orders.page(page) end end Объявление типа на бэке: объявляем поле
  37. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 48 Объявление типа на бэке:

    resolver class UserType < GraphQL"::Schema"::Object field :name, String, null: false field :orders, [OrderType], null: false do argument :page, Int, required: false end def orders(page: nil) object.orders.page(page) end end
  38. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 49 Объявление типа на бэке:

    передаем аргументы class UserType < GraphQL"::Schema"::Object field :name, String, null: false field :orders, [OrderType], null: false do argument :page, Int, required: false end def orders(page: nil) object.orders.page(page) end end
  39. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 50 Язык запросов Схема API

    Реализация API ⇨ Что может пойти не так ⇦ Как проектировать схему Эволюция API
  40. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 51 query { user(id: 42)

    { orders { user { orders { user { … } } } } } } Сложность и глубина запросов
  41. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 52 Request: query { articles

    { id author { name } } } Response: { "data": { "articles" [ { "id": "1", "author": { "name": "John" } }, { "id": "2", "author": { "name": "John" } }, ] } } Дублирование данных в ответе
  42. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 53 type CategoryType { name:

    String! subcategories: [CategoryType]! } query { categories { name subcategories { name subcategories { name } } } } Нет рекурсивных запросов
  43. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 54 Сложно кэшировать ответы •

    REST: ответ зависит от HTTP verb и URL • GraphQL: ответ зависит от selection set • нет легкого и эффективного способа кэшировать ответ GraphQL $
  44. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 55 class QueryType < GraphQL"::Schema"::Object

    field :users, [UserType], null: false def users # SELECT * FROM users; # SELECT * FROM orders where user_id = ?; # SELECT * FROM orders where user_id = ?; # SELECT * FROM orders where user_id = ?; # SELECT * FROM orders where user_id = ?; User.all end end class UserType < GraphQL"::Schema"::Object field :orders, [OrderType], null: false end Проблема N+1
  45. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 56 class QueryType < GraphQL"::Schema"::Object

    field :users, [UserType], null: false def users # SELECT * FROM users; # SELECT * FROM orders where user_id IN (…); User.preload(:orders) end end class UserType < GraphQL"::Schema"::Object field :orders, [OrderType], null: false end Устраняем N+1: preload
  46. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 57 query { user(id: 24)

    { id name } } # SELECT * FROM users; # SELECT * FROM orders where user_id IN (…); Устраняем N+1: preload
  47. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 58 class QueryType < GraphQL"::Schema"::Object

    field :users, [UserType], null: false, extras: [:lookahead] def users(lookahead:) if lookahead.selects?(:orders) User.preload(:orders) else User.all end end end class UserType < GraphQL"::Schema"::Object field :orders, [OrderType], null: false end Устраняем N+1: работаем с запросом
  48. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 59 class QueryType < GraphQL"::Schema"::Object

    field :users, [UserType], null: false, extras: [:lookahead] def users(lookahead:); end end class OrganisationType < GraphQL"::Schema"::Object field :users, [UserType], null: false, extras: [:lookahead] def users(lookahead:) if lookahead.selects?(:orders) object.users.preload(:orders) else object.users end end end Устраняем N+1: работаем с запросом
  49. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 60 Устраняем N+1: batching class

    QueryType < GraphQL"::Schema"::Object field :users, [UserType], null: false def users User.all end end class UserType < GraphQL"::Schema"::Object field :orders, [OrderType], null: false def orders AssociationLoader.for(User, :orders).load(object) end end
  50. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 61 Язык запросов Схема API

    Реализация API Что может пойти не так ⇨ Как проектировать схему ⇦ Эволюция API
  51. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev type OrderType { items: [ItemType]!

    userId: ID! userName: String! } 62 type UserType { id: ID! name: String! } type OrderType { items: [ItemType]! user: UserType! } ✅ Не возвращайте данные других сущностей
  52. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev type UserType { id: ID!

    name: String! moderationStatus: ModerationStatusType! moderationDate: DateTime! } 63 Выделяйте связанные данные в типы type UserModerationType { status: ModerationStatusType! date: DateTime! } type UserType { id: ID! name: String! moderation: UserModerationType! } ✅
  53. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev type ProductType { id: ID!

    } type ItemType { product: ProductType! quantity: Int! } type OrderType { items: [ItemType]! } 64 Дайте доступ и к данным и к логике Как клиент может проверить наличие определенного товара в заказе?
  54. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 65 const query = gql`

    query GetOrder($id: ID!) { order(id: $id) { items { product { id } } } } ` const order = request(query, { id }) const found = order.items.find(item "=> item.product.id "== productId) if (found ""!== null) { "//… } Дайте доступ и к данным и к логике
  55. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 66 type ProductType { id:

    ID! } type ItemType { product: ProductType! quantity: Int! } type OrderType { items: [ItemType]! hasProduct(id: ID!): Bool! } Дайте доступ и к данным и к логике
  56. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 67 const query = gql`

    query GetOrder($id: ID!, $productId: ID!) { order(id: $id) { hasProduct(productId: $productId) } } ` const order = request(query, { id, productId }) if (order.hasProduct) { "//… } Дайте доступ и к данным и к логике
  57. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev Пример проектирования мутаций: блог •

    две страницы - страница чтения and форма редактирования • title и content могут быть изменены на форме редактирования • статья может быть опубликована/спрятана с помощью кнопки на странице чтения • тэги могут быть изменены с помощью выпадающего списка на странице чтения 68
  58. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev type MutationType { createPost( title:

    String, content: String, tags: [String], published: Bool ): PostType! updatePost( id: ID!, title: String, content: String, tags: [String], published: Bool ): PostType! deletePost(id: ID!): Bool } CRUD 69
  59. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 70 input PostInput { title:

    String, content: String } type MutationType { createPost(postInput: PostInput): PostType! updatePost(id: ID!, postInput: PostInput): PostType! deletePost(id: ID!): Bool publishPost(id: ID!): PostType! unpublishPost(id: ID!): PostType! addTag(id: ID!, tag: String!): PostType! removeTag(id: ID!, tag: String!): PostType! } Атомарные мутации
  60. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 71 input PostInput { title:

    String, content: String } type MutationType { createPost(postInput: PostInput): PostType! updatePost(id: ID!, postInput: PostInput): PostType! deletePost(id: ID!): Bool publishPost(id: ID!): PostType! unpublishPost(id: ID!): PostType! addTag(id: ID!, tag: String!): PostType! removeTag(id: ID!, tag: String!): PostType! } Атомарные мутации
  61. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 72 input PostInput { title:

    String, content: String } type MutationType { createPost(postInput: PostInput): PostType! updatePost(id: ID!, postInput: PostInput): PostType! } Input • CQRS - Command Query Responsibility Segregation • поля в input могут быть только scalar или input
  62. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 73 input PostInput { title:

    String, content: String } type MutationType { createPost(postInput: PostInput): PostType! updatePost(id: ID!, postInput: PostInput): PostType! deletePost(id: ID!): Bool publishPost(id: ID!): PostType! unpublishPost(id: ID!): PostType! addTag(id: ID!, tag: String!): PostType! removeTag(id: ID!, tag: String!): PostType! } Атомарные мутации
  63. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 74 input PostInput { title:

    String, content: String } type MutationType { createPost(postInput: PostInput): PostType! updatePost(id: ID!, postInput: PostInput): PostType! deletePost(id: ID!): Bool publishPost(id: ID!): PostType! unpublishPost(id: ID!): PostType! addTag(id: ID!, tag: String!): PostType! removeTag(id: ID!, tag: String!): PostType! } Атомарные мутации
  64. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 75 Язык запросов Схема API

    Реализация API Что может пойти не так Как проектировать схему ⇨ Эволюция API ⇦
  65. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 76 type ItemType { id:

    ID! quantity: Integer! } Аддитивные изменения безопасны type ItemType { id: ID! quantity: Integer! addedAt: DateTime! }
  66. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 77 type ItemType { quantity:

    Integer! count: Integer! @deprecated( reason: "Use `quantity`." ) } @deprecated
  67. IT NIGHTS 2019 DmitryTsepelev @dmitrytsepelev 79 Аварийное отключение мутаций mutation

    { transferMoney(to: 42, amount: 100) { id } } { "data": null, "errors": [ { "mutationDeprecated": "transferMoney", "message": "Please update your app" } ] }
  68. !80 Зачем использовать GraphQL? • нет overfetching и underfetching •

    схема API - часть технологии: - документация - валидация запросов • предсказуемое поведение бэкенда • подписки