GraphQL: схема, запросы и мутации

mkdir catalog-graphql && cd catalog-graphql
npm init -y
npm pkg set type=module scripts.start="node src/server.js" scripts.test="node --test"
npm pkg delete main keywords author license description
npm i graphql-yoga@5.24.4 graphql@16.14.2 dataloader@2.2.3 @escape.tech/graphql-armor-max-depth@2.4.2

{
  "name": "catalog-graphql",
  "version": "1.0.0",
  "scripts": {
    "test": "node --test",
    "start": "node src/server.js"
  },
  "type": "module",
  "dependencies": {
    "@escape.tech/graphql-armor-max-depth": "^2.4.2",
    "dataloader": "^2.2.3",
    "graphql": "^16.14.2",
    "graphql-yoga": "^5.24.4"
  }
}

export const typeDefs = /* GraphQL */ `
  "Услуга из каталога"
  type Service {
    id: ID!
    title: String!
    category: Category!
    reviews: [Review!]!
  }

  type Category {
    id: ID!
    name: String!
    services: [Service!]!
  }

  type Review {
    id: ID!
    "Оценка от 1 до 5"
    rating: Int!
    text: String!
  }

  type Query {
    "Список услуг; first — сколько вернуть (1–50)"
    services(categoryId: ID, first: Int = 10): [Service!]!
    "Одна услуга или null, если такой нет"
    service(id: ID!): Service
    categories: [Category!]!
  }

  input AddReviewInput {
    serviceId: ID!
    rating: Int!
    text: String!
  }

  type Mutation {
    addReview(input: AddReviewInput!): Review!
  }
`;

import { createSchema, createYoga } from "graphql-yoga";
import { maxDepthPlugin } from "@escape.tech/graphql-armor-max-depth";
import { typeDefs } from "./typeDefs.js";
import { resolvers as defaultResolvers } from "./resolvers.js";
import { createLoaders } from "./loaders.js";

export function buildYoga({ db, resolvers = defaultResolvers, maxDepth = 5 }) {
  return createYoga({
    schema: createSchema({ typeDefs, resolvers }),
    // контекст создаётся заново на каждый запрос — вместе с загрузчиками
    context: () => ({ db, loaders: createLoaders(db) }),
    plugins: [maxDepthPlugin({ n: maxDepth })],
  });
}

import { createServer } from "node:http";
import { createDb } from "./db.js";
import { buildYoga } from "./yoga.js";

const port = Number(process.env.PORT ?? 4400);
const db = createDb({ onQuery: (sql, params) => console.log("[db]", sql, JSON.stringify(params)) });
const yoga = buildYoga({ db });
const server = createServer(yoga);

server.listen(port, () => {
  console.log(`GraphQL: http://localhost:${port}${yoga.graphqlEndpoint}`);
});

$ curl -s http://localhost:4400/graphql -H "content-type: application/json" -d '{"query":"{ services(first: 3) { title category { name } } }"}'
{"data":{"services":[{"title":"Корпоративный сайт","category":{"name":"Веб-разработка"}},{"title":"Интернет-магазин","category":{"name":"Веб-разработка"}},{"title":"Приложение на Flutter","category":{"name":"Мобильные приложения"}}]}}

$ npm start

> catalog-graphql@1.0.0 start
> node src/server.js

GraphQL: http://localhost:4400/graphql
[db] SELECT * FROM services WHERE ($1::text IS NULL OR category_id = $1) ORDER BY id LIMIT $2 [null,3]
[db] SELECT * FROM categories WHERE id = ANY($1) [["c1","c2"]]

{
  "query": "query ByCategory($cat: ID!, $n: Int) { services(categoryId: $cat, first: $n) { id title reviews { rating text } } }",
  "variables": { "cat": "c3", "n": 5 }
}

{
  "query": "mutation AddReview($input: AddReviewInput!) { addReview(input: $input) { id rating text } }",
  "variables": { "input": { "serviceId": "s5", "rating": 5, "text": "Остатки в 1С и на сайте совпадают" } }
}

$ curl -s http://localhost:4400/graphql -H "content-type: application/json" -d @requests/by-category.json
{"data":{"services":[{"id":"s4","title":"Telegram-бот","reviews":[{"rating":4,"text":"Бот принимает заявки"}]},{"id":"s5","title":"Обмен с 1С","reviews":[]}]}}
$ curl -s http://localhost:4400/graphql -H "content-type: application/json" -d @requests/add-review.json
{"data":{"addReview":{"id":"r3","rating":5,"text":"Остатки в 1С и на сайте совпадают"}}}
$ curl -s http://localhost:4400/graphql -H "content-type: application/json" -d @requests/bad-rating.json
{"errors":[{"message":"rating должен быть от 1 до 5","locations":[{"line":1,"column":47}],"path":["addReview"],"extensions":{"code":"BAD_USER_INPUT"}}],"data":null}

[db] SELECT * FROM services WHERE ($1::text IS NULL OR category_id = $1) ORDER BY id LIMIT $2 ["c3",5]
[db] SELECT * FROM reviews WHERE service_id = ANY($1) ORDER BY id [["s4","s5"]]
[db] SELECT * FROM services WHERE id = $1 ["s5"]
[db] INSERT INTO reviews (service_id, rating, text) VALUES ($1, $2, $3) RETURNING * ["s5",5,"Остатки в 1С и на сайте совпадают"]

$ curl -s "http://localhost:4400/graphql?query=%7Bcategories%7Bname%7D%7D"
{"data":{"categories":[{"name":"Веб-разработка"},{"name":"Мобильные приложения"},{"name":"Интеграции"}]}}
$ curl -si "http://localhost:4400/graphql?query=mutation%7BaddReview(input:%7BserviceId:%22s1%22,rating:5,text:%22x%22%7D)%7Bid%7D%7D"
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json; charset=utf-8
Allow: POST

{"errors":[{"message":"Can only perform a mutation operation from a POST request.","extensions":{"code":"BAD_REQUEST"}}]}

import { GraphQLError } from "graphql";

function badInput(message) {
  return new GraphQLError(message, { extensions: { code: "BAD_USER_INPUT" } });
}

export const resolvers = {
  Query: {
    services: (_parent, { categoryId, first }, { db }) => {
      if (first < 1 || first > 50) throw badInput("first должен быть от 1 до 50");
      return db.listServices({ categoryId, limit: first });
    },
    service: (_parent, { id }, { db }) => db.findService(id),
    categories: (_parent, _args, { db }) => db.listCategories(),
  },

  Mutation: {
    addReview: async (_parent, { input }, { db }) => {
      const text = input.text.trim();
      if (input.rating < 1 || input.rating > 5) throw badInput("rating должен быть от 1 до 5");
      if (text.length === 0 || text.length > 1000) throw badInput("text: от 1 до 1000 символов");
      const service = await db.findService(input.serviceId);
      if (!service) {
        throw new GraphQLError(`Услуга ${input.serviceId} не найдена`, {
          extensions: { code: "NOT_FOUND" },
        });
      }
      return db.insertReview({ serviceId: service.id, rating: input.rating, text });
    },
  },

  // поля-связи: родительский объект приходит первым аргументом
  Service: {
    category: (service, _args, { loaders }) => loaders.categoryById.load(service.categoryId),
    reviews: (service, _args, { loaders }) => loaders.reviewsByServiceId.load(service.id),
  },

  Category: {
    services: (category, _args, { loaders }) => loaders.servicesByCategoryId.load(category.id),
  },
};

$ curl -s -w "\nHTTP %{http_code}\n" http://localhost:4400/graphql -H "content-type: application/json" -H "accept: application/json" -d @requests/typo.json
{"errors":[{"message":"Cannot query field \"servise\" on type \"Query\". Did you mean \"service\" or \"services\"?","locations":[{"line":1,"column":3}],"extensions":{"code":"GRAPHQL_VALIDATION_FAILED"}}]}
HTTP 200
$ curl -s -w "\nHTTP %{http_code}\n" http://localhost:4400/graphql -H "content-type: application/json" -H "accept: application/graphql-response+json" -d @requests/typo.json
{"errors":[{"message":"Cannot query field \"servise\" on type \"Query\". Did you mean \"service\" or \"services\"?","locations":[{"line":1,"column":3}],"extensions":{"code":"GRAPHQL_VALIDATION_FAILED"}}]}
HTTP 400

// «База данных» в памяти. Каждый метод — один запрос: onQuery получает
// SQL, который выполнила бы настоящая СУБД, — по этим вызовам считаем запросы.
export function createDb({ onQuery = () => {} } = {}) {
  const categories = [
    { id: "c1", name: "Веб-разработка" },
    { id: "c2", name: "Мобильные приложения" },
    { id: "c3", name: "Интеграции" },
  ];
  const services = [
    { id: "s1", title: "Корпоративный сайт", categoryId: "c1" },
    { id: "s2", title: "Интернет-магазин", categoryId: "c1" },
    { id: "s3", title: "Приложение на Flutter", categoryId: "c2" },
    { id: "s4", title: "Telegram-бот", categoryId: "c3" },
    { id: "s5", title: "Обмен с 1С", categoryId: "c3" },
  ];
  const reviews = [
    { id: "r1", serviceId: "s1", rating: 5, text: "Сайт сдали в срок" },
    { id: "r2", serviceId: "s4", rating: 4, text: "Бот принимает заявки" },
  ];

  async function query(sql, params, run) {
    onQuery(sql, params);
    return run();
  }

  return {
    listCategories: () =>
      query("SELECT * FROM categories ORDER BY id", [], () => [...categories]),

    listServices: ({ categoryId, limit }) =>
      query(
        "SELECT * FROM services WHERE ($1::text IS NULL OR category_id = $1) ORDER BY id LIMIT $2",
        [categoryId ?? null, limit],
        () => services.filter((s) => !categoryId || s.categoryId === categoryId).slice(0, limit),
      ),

    findService: (id) =>
      query("SELECT * FROM services WHERE id = $1", [id], () => services.find((s) => s.id === id) ?? null),

    findCategory: (id) =>
      query("SELECT * FROM categories WHERE id = $1", [id], () => categories.find((c) => c.id === id) ?? null),

    // пакетные запросы для DataLoader: один запрос на много ключей
    categoriesByIds: (ids) =>
      query("SELECT * FROM categories WHERE id = ANY($1)", [ids], () =>
        categories.filter((c) => ids.includes(c.id)),
      ),

    servicesByCategoryIds: (ids) =>
      query("SELECT * FROM services WHERE category_id = ANY($1) ORDER BY id", [ids], () =>
        services.filter((s) => ids.includes(s.categoryId)),
      ),

    reviewsByServiceIds: (ids) =>
      query("SELECT * FROM reviews WHERE service_id = ANY($1) ORDER BY id", [ids], () =>
        reviews.filter((r) => ids.includes(r.serviceId)),
      ),

    insertReview: ({ serviceId, rating, text }) =>
      query("INSERT INTO reviews (service_id, rating, text) VALUES ($1, $2, $3) RETURNING *", [serviceId, rating, text], () => {
        const review = { id: `r${reviews.length + 1}`, serviceId, rating, text };
        reviews.push(review);
        return review;
      }),
  };
}

const naive = {
  ...resolvers,
  Service: {
    category: (service, _args, { db }) => db.findCategory(service.categoryId),
    reviews: async (service, _args, { db }) => db.reviewsByServiceIds([service.id]),
  },
};

import DataLoader from "dataloader";

// Пакетная функция обязана вернуть массив той же длины и в том же порядке,
// что и keys: базе порядок не важен, поэтому раскладываем строки по ключам.
function byKey(keys, rows, key) {
  const map = new Map(rows.map((row) => [row[key], row]));
  return keys.map((k) => map.get(k) ?? new Error(`Нет записи ${k}`));
}

function groupByKey(keys, rows, key) {
  const groups = new Map(keys.map((k) => [k, []]));
  for (const row of rows) groups.get(row[key])?.push(row);
  return keys.map((k) => groups.get(k));
}

// Новый набор загрузчиков на каждый HTTP-запрос: кэш DataLoader живёт
// только в пределах запроса и не смешивает данные разных пользователей.
export function createLoaders(db) {
  return {
    categoryById: new DataLoader(async (ids) => byKey(ids, await db.categoriesByIds(ids), "id")),
    servicesByCategoryId: new DataLoader(async (ids) =>
      groupByKey(ids, await db.servicesByCategoryIds(ids), "categoryId"),
    ),
    reviewsByServiceId: new DataLoader(async (ids) =>
      groupByKey(ids, await db.reviewsByServiceIds(ids), "serviceId"),
    ),
  };
}

$ curl -s -w "\nHTTP %{http_code}\n" http://localhost:4400/graphql -H "content-type: application/json" -d @requests/deep.json
{"errors":[{"message":"Syntax Error: Query depth limit of 5 exceeded, found 6."}]}
HTTP 200

// Минимальный клиент: тот же код работает в Node.js 18+ и в браузере
// (как <script type="module">, если сервер разрешает CORS для вашего сайта).
const ENDPOINT = "http://localhost:4400/graphql";

export async function gql(query, variables = {}) {
  const res = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      accept: "application/graphql-response+json, application/json",
    },
    body: JSON.stringify({ query, variables }),
  });
  const body = await res.json();
  // ошибки GraphQL приходят в теле — проверяем errors, а не только статус
  if (body.errors?.length) {
    const [first] = body.errors;
    throw new Error(`${first.extensions?.code ?? "GRAPHQL_ERROR"}: ${first.message}`);
  }
  return body.data;
}

const SERVICES = /* GraphQL */ `
  query ServicesByCategory($categoryId: ID) {
    services(categoryId: $categoryId) {
      id
      title
      reviews { rating }
    }
  }
`;

const data = await gql(SERVICES, { categoryId: "c3" });
for (const s of data.services) {
  console.log(`${s.id} ${s.title} — отзывов: ${s.reviews.length}`);
}

try {
  await gql(`query Many($n: Int) { services(first: $n) { id } }`, { n: 100 });
} catch (err) {
  console.log("Ошибка:", err.message);
}

$ node src/client.js
s4 Telegram-бот — отзывов: 1
s5 Обмен с 1С — отзывов: 1
Ошибка: BAD_USER_INPUT: first должен быть от 1 до 50

import { test } from "node:test";
import assert from "node:assert/strict";
import { createDb } from "../src/db.js";
import { createLoaders } from "../src/loaders.js";
import { resolvers } from "../src/resolvers.js";
import { buildYoga } from "../src/yoga.js";

// Тестовый стенд: своя «БД» со счётчиком запросов и сервер без сети —
// yoga.fetch обрабатывает запрос в памяти, порт не открывается.
function setup(options = {}) {
  const queries = [];
  const db = createDb({ onQuery: (sql) => queries.push(sql) });
  const yoga = buildYoga({ db, ...options });
  async function gql(query, variables) {
    queries.length = 0;
    const res = await yoga.fetch("http://yoga/graphql", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ query, variables }),
    });
    return { status: res.status, body: await res.json() };
  }
  return { db, gql, queries };
}

const LIST = /* GraphQL */ `
  query ServiceList {
    services {
      title
      category { name }
      reviews { rating }
    }
  }
`;

test("запрос с переменной возвращает только запрошенные поля", async () => {
  const { gql } = setup();
  const { status, body } = await gql(
    `query ByCategory($cat: ID!) { services(categoryId: $cat) { id title } }`,
    { cat: "c3" },
  );
  assert.equal(status, 200);
  assert.deepEqual(body, {
    data: {
      services: [
        { id: "s4", title: "Telegram-бот" },
        { id: "s5", title: "Обмен с 1С" },
      ],
    },
  });
});

test("DataLoader: 5 услуг с категориями и отзывами — 3 запроса к БД", async () => {
  const { gql, queries } = setup();
  const { body } = await gql(LIST);
  assert.equal(body.data.services.length, 5);
  assert.equal(body.data.services[3].category.name, "Интеграции");
  assert.deepEqual(queries, [
    "SELECT * FROM services WHERE ($1::text IS NULL OR category_id = $1) ORDER BY id LIMIT $2",
    "SELECT * FROM categories WHERE id = ANY($1)",
    "SELECT * FROM reviews WHERE service_id = ANY($1) ORDER BY id",
  ]);
});

test("без DataLoader тот же запрос даёт N+1: 1 + 5 + 5 = 11 запросов", async () => {
  const naive = {
    ...resolvers,
    Service: {
      category: (service, _args, { db }) => db.findCategory(service.categoryId),
      reviews: async (service, _args, { db }) => db.reviewsByServiceIds([service.id]),
    },
  };
  const { gql, queries } = setup({ resolvers: naive });
  const { body } = await gql(LIST);
  assert.equal(body.data.services.length, 5);
  assert.equal(queries.length, 11);
  assert.equal(queries.filter((q) => q.startsWith("SELECT * FROM categories WHERE id = $1")).length, 5);
});

test("пакетная функция сохраняет порядок ключей и возвращает ошибку для отсутствующего", async () => {
  const db = createDb();
  const { categoryById } = createLoaders(db);
  const result = await categoryById.loadMany(["c3", "c1", "zz"]);
  assert.equal(result[0].name, "Интеграции");
  assert.equal(result[1].name, "Веб-разработка");
  assert.ok(result[2] instanceof Error);
});

test("несуществующая услуга — null без ошибки", async () => {
  const { gql } = setup();
  const { body } = await gql(`{ service(id: "s404") { title } }`);
  assert.deepEqual(body, { data: { service: null } });
});

test("ошибка в non-null поле обнуляет родителя, в errors есть path и code", async () => {
  const { gql, queries } = setup();
  const { status, body } = await gql(`{ services(first: 100) { title } }`);
  assert.equal(status, 200);
  assert.equal(body.data, null);
  assert.deepEqual(body.errors[0].path, ["services"]);
  assert.equal(body.errors[0].extensions.code, "BAD_USER_INPUT");
  assert.equal(queries.length, 0);
});

test("мутация добавляет отзыв, следующий запрос его видит", async () => {
  const { gql } = setup();
  const READ = `{ service(id: "s2") { reviews { id } } }`;
  const before = await gql(READ);
  assert.deepEqual(before.body.data.service.reviews, []);
  const add = await gql(
    `mutation AddReview($input: AddReviewInput!) { addReview(input: $input) { id rating text } }`,
    { input: { serviceId: "s2", rating: 5, text: "  Каталог удобный  " } },
  );
  assert.deepEqual(add.body.data.addReview, { id: "r3", rating: 5, text: "Каталог удобный" });
  const read = await gql(READ); // новый запрос — новые загрузчики, без устаревшего кэша
  assert.deepEqual(read.body.data.service.reviews, [{ id: "r3" }]);
});

test("мутация проверяет ввод и отклоняет неизвестную услугу без записи", async () => {
  const { gql, queries } = setup();
  const MUTATION = `mutation AddReview($input: AddReviewInput!) { addReview(input: $input) { id } }`;
  const bad = await gql(MUTATION, { input: { serviceId: "s1", rating: 9, text: "ok" } });
  assert.equal(bad.body.errors[0].extensions.code, "BAD_USER_INPUT");
  const missing = await gql(MUTATION, { input: { serviceId: "s404", rating: 5, text: "ok" } });
  assert.equal(missing.body.errors[0].extensions.code, "NOT_FOUND");
  assert.ok(!queries.some((q) => q.startsWith("INSERT")));
});

test("переменная не того типа — 400 до выполнения", async () => {
  const { gql, queries } = setup();
  const { status, body } = await gql(
    `mutation AddReview($input: AddReviewInput!) { addReview(input: $input) { id } }`,
    { input: { serviceId: "s1", rating: "5", text: "ok" } },
  );
  assert.equal(status, 400);
  assert.match(body.errors[0].message, /Int cannot represent non-integer value/);
  assert.equal(queries.length, 0);
});

test("слишком глубокий запрос отклоняется до обращения к БД", async () => {
  const { gql, queries } = setup();
  const { body } = await gql(
    `{ categories { services { category { services { category { name } } } } } }`,
  );
  assert.equal(body.data, undefined);
  assert.match(body.errors[0].message, /depth limit of 5 exceeded, found 6/);
  assert.equal(queries.length, 0);
});

test("неожиданная ошибка маскируется: детали не уходят клиенту", async () => {
  const db = createDb();
  db.listCategories = async () => {
    throw new Error("connect ECONNREFUSED 10.0.0.5:5432");
  };
  const yoga = buildYoga({ db });
  const res = await yoga.fetch("http://yoga/graphql", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ query: "{ categories { name } }" }),
  });
  const body = await res.json();
  assert.equal(body.errors[0].message, "Unexpected error.");
  assert.doesNotMatch(JSON.stringify(body), /ECONNREFUSED/);
});

$ npm test

> catalog-graphql@1.0.0 test
> node --test

✔ запрос с переменной возвращает только запрошенные поля (27.7426ms)
ERR Error: connect ECONNREFUSED 10.0.0.5:5432
    at db.listCategories (file:///…/catalog-graphql/test/api.test.js:153:11)
    …
  path: [ 'categories' ],
  locations: [ { line: 1, column: 3 } ],
  extensions: [Object: null prototype] {}
}
✔ DataLoader: 5 услуг с категориями и отзывами — 3 запроса к БД (3.5657ms)
✔ без DataLoader тот же запрос даёт N+1: 1 + 5 + 5 = 11 запросов (3.0164ms)
✔ пакетная функция сохраняет порядок ключей и возвращает ошибку для отсутствующего (0.2793ms)
✔ несуществующая услуга — null без ошибки (2.3158ms)
✔ ошибка в non-null поле обнуляет родителя, в errors есть path и code (2.8934ms)
✔ мутация добавляет отзыв, следующий запрос его видит (3.8273ms)
✔ мутация проверяет ввод и отклоняет неизвестную услугу без записи (2.982ms)
✔ переменная не того типа — 400 до выполнения (2.0594ms)
✔ слишком глубокий запрос отклоняется до обращения к БД (2.4009ms)
✔ неожиданная ошибка маскируется: детали не уходят клиенту (2.1038ms)
ℹ tests 11
ℹ suites 0
ℹ pass 11
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 323.6923