GraphQL — schema, resolver, N+1 আর REST-এর সাথে তুলনা

১ · এক পর্দার জন্য তিনবার যাওয়া

“বাজারঘর”-এর পণ্যের পাতায় ফোনে দেখাতে হবে পণ্যের নাম, দাম, বিক্রেতার নাম আর রিভিউ। আগের পর্বগুলোতে আমরা REST endpoint বানিয়েছি, তাই ফোনের অ্যাপ এখন তিনটি জায়গায় যায়:

GET /products/7          → পণ্যের ২০টি field, দরকার ২টি
GET /sellers/2           → বিক্রেতার ১২টি field, দরকার ১টি
GET /products/7/reviews  → সব রিভিউ, দরকার শুধু rating

এখানে দুটি আলাদা সমস্যা আছে। প্রতিটি উত্তরে দরকারের চেয়ে বেশি ডেটা আসছে, একে বলে over-fetching. আবার এক উত্তরে সব ডেটা পাওয়া যাচ্ছে না, তাই বারবার যেতে হচ্ছে, একে বলে under-fetching.

সমস্যাটি বড় হয় যখন পর্দা বাড়ে। ফোনের অ্যাপ, ওয়েবসাইট, বিক্রেতার dashboard, তিনটির দরকার আলাদা। REST-এ উপায় দুটি: সবাইকে একই মোটা উত্তর দেওয়া, অথবা প্রতিটি পর্দার জন্য আলাদা endpoint বা BFF বানানো। GraphQL তৃতীয় পথ দেখায়: server একটিই schema প্রকাশ করবে, আর প্রতিটি client নিজের query লিখবে।

একটি হিসাব দেখুন। ধরে নিই ফোন থেকে server পর্যন্ত এক যাওয়া-আসায় (RTT) ৮০ ms লাগে, আর server-এর কাজের সময় বাদ দিই। REST-এ প্রথমে পণ্য আনতে হবে, কারণ বিক্রেতার id তার ভেতরে। তারপর বিক্রেতা আর রিভিউ একসাথে আনা যায়। মোট দুই ধাপ, অর্থাৎ ২ × ৮০ = ১৬০ ms. GraphQL-এ এক ধাপ, ৮০ ms. এই সংখ্যাগুলো ধরে নেওয়া, মাপা নয়; তবে ধীর মোবাইল নেটওয়ার্কে কেন এটি দরকারি ছিল, তা বোঝা যায়।

২ · Schema: client আর server-এর চুক্তি

GraphQL-এর কেন্দ্রে একটি চুক্তি। সেটি লেখা হয় SDL নামের ছোট ভাষায়। বাজারঘরের পণ্য, বিক্রেতা আর রিভিউর schema হলো এই (সত্যিকারের lab-এর কোড থেকে):

type Seller {
  id: ID!
  name: String!
  phone: String          # শুধু admin পড়তে পারবেন
  balance: Int!          # শুধু admin, ইচ্ছা করেই non-null
  products: [Product!]!
}
type Review { id: ID!  rating: Int!  comment: String  product: Product! }
type Product {
  id: ID!
  name: String!
  price: Int!
  seller: Seller!
  reviews: [Review!]!
  shippingEstimate: String
}
type Query {
  products(first: Int = 10): [Product!]!
  product(id: ID!): Product
}
input ReviewInput { productId: ID!  rating: Int!  comment: String }
type Mutation { addReview(input: ReviewInput!): Review }

কয়েকটি চিহ্ন পড়তে শিখুন:

• String, Int, ID হলো scalar: এর ভেতরে আর field নেই। Product-এর মতো object type-এর ভেতরে field থাকে।
• ! হলো non-null: এই field কখনো null হবে না। চিহ্ন না থাকলে field নিজে থেকেই nullable. এই পছন্দ পরে বড় প্রভাব ফেলবে, ৪ নম্বর অংশে দেখবেন।
• [Product!]! মানে তালিকাটি null নয়, ভেতরের কোনো পণ্যও null নয়।
• Query, Mutation হলো প্রবেশপথ। Client সব কিছু এখান থেকে শুরু করে।

তিন রকম operation

Query লেখা: variable আর fragment

Client যা লেখে তাকে বলে query document. দ্বিতীয় বন্ধনীর ভেতরের field-তালিকা হলো selection set. মান সরাসরি query-র লেখায় না বসিয়ে variable-এ পাঠানোই নিয়ম, ঠিক যেমন SQL-এ parameterized query. একই field-দল বারবার লাগলে fragment করা হয়। দুটিই এক জায়গায় (সত্যিকারের run):

query Vars($id: ID!, $withSeller: Boolean!) {
  product(id: $id) {
    ...Card
    seller @include(if: $withSeller) { name }
  }
}
fragment Card on Product { name price }

# variables: {"id":"8","withSeller":true}
{"data":{"product":{"name":"Nakshi Bag","price":850,"seller":{"name":"Mita Crafts"}}}}

উত্তরের আকার query-র আকারের মতোই। এটিই GraphQL-এর সবচেয়ে সহজ আনন্দ: উত্তর কেমন হবে, query পড়েই বোঝা যায়। আর schema server থেকেই জানা যায়, একে বলে introspection; GraphiQL-এর মতো tool এর ওপর দাঁড়িয়ে autocomplete দেয়।

৩ · Resolver: প্রতিটি field-এর পেছনের ফাংশন

Schema শুধু বলে কী পাওয়া যাবে। ডেটা কোথা থেকে আসবে, তা বলে resolver. এবার আসল server বানাই। লেখার সময়ে graphql 17.0.2, graphql-yoga 6.0.1 আর dataloader 2.2.3 ব্যবহার করেছি, Node 24.15-এ। Database হিসেবে Node-এর নিজস্ব node:sqlite, memory-তে, যাতে প্রতিটি SQL আমরা দেখতে পারি। Apollo Server (@apollo/server 5.5.1) একই ধরনের আরেকটি পথ; ধারণা একই, API আলাদা।

npm i graphql graphql-yoga dataloader
node server.js

const resolvers = {
  Query: {
    products: (_, { first }, ctx) =>
      sql(ctx, 'SELECT * FROM products ORDER BY id LIMIT ?', Math.min(first, 50)),
  },
  Product: {
    seller: (p, _, ctx) =>
      sql(ctx, 'SELECT * FROM sellers WHERE id = ?', p.seller_id)[0],
    reviews: (p, _, ctx) =>
      sql(ctx, 'SELECT * FROM reviews WHERE product_id = ?', p.id),
  },
};
export const schema = createSchema({ typeDefs, resolvers });

import { createServer } from 'node:http';
import { createYoga } from 'graphql-yoga';
import { schema } from './schema.js';

const yoga = createYoga({
  schema,
  context: () => ({ stats: { sql: 0 } }),   // প্রতি request-এ নতুন
});
createServer(yoga).listen(4136, '127.0.0.1');

প্রতিটি resolver চারটি জিনিস পায়: parent (ওপরের field-এর ফল), args, context (এই request-এর ভাগ করা জিনিস) আর info. লক্ষ করুন name, price-এর resolver লিখিনি। নিজের resolver না থাকলে default resolver parent থেকে একই নামের property তুলে নেয়। তাই database-এর সারি থেকেই name চলে আসে।

Executor query-কে একটি গাছের মতো হাঁটে: আগে ওপরের field, তার ফল নিয়ে ভেতরের field. “পরে” চেপে আসল ডেটায় দুটি পণ্যের একটি query অনুসরণ করুন:

1query Shop {2  products(first: 2) {3    name4    seller { name }5    reviews { rating }6  }7}

এই হাঁটার নিয়ম নিজে হাতে দেখা যাক। graphql প্যাকেজ এই পাতায় চালানো যায় না, তাই নিচে একটি শেখার মডেল: ২৫ লাইনের মতো একটি ছোট executor, যা একটি selection object ধরে resolver ডাকে। এটি আসল GraphQL নয়; parser, type-যাচাই বা error handling এখানে নেই। Query বদলে চালিয়ে দেখুন।

// শেখার মডেল: আসল graphql প্যাকেজ নয়, শুধু ধারণাটি দেখায়
const db = {
  products: [
    { id: 1, name: "Miniket Rice", price: 420, stock: 9, sellerId: 1 },
    { id: 2, name: "Clay Mug", price: 220, stock: 4, sellerId: 2 },
  ],
  sellers: { 1: { name: "Rahim Store" }, 2: { name: "Mita Crafts" } },
};
const returns = { "Query.products": "Product", "Product.seller": "Seller" };
const resolvers = {
  Query: { products: () => db.products },
  Product: { seller: (p) => db.sellers[p.sellerId] },
};
async function run(type, source, selection) {
  const out = {};
  for (const f in selection) out[f] = null;   // query-র ক্রম ঠিক থাকে
  await Promise.all(Object.keys(selection).map(async (f) => {
    const fn = resolvers[type]?.[f];
    const value = fn ? await fn(source) : source[f];   // resolver নেই: নিজের field
    const sub = selection[f];
    if (sub === true) { out[f] = value; return; }
    const child = returns[type + "." + f];
    out[f] = Array.isArray(value)
      ? await Promise.all(value.map((v) => run(child, v, sub)))
      : await run(child, value, sub);
  }));
  return out;
}
const phone = { products: { name: true, price: true } };
const detail = { products: { name: true, seller: { name: true } } };
run("Query", {}, phone).then((r) => {
  console.log(JSON.stringify(r));
  return run("Query", {}, detail);
}).then((r) => console.log(JSON.stringify(r)));

৪ · একটিই ঠিকানা, status 200 আর errors

REST-এ পর্ব ২৮ আর পর্ব ৩৩-এ দেখেছেন, ভুলের খবর দেয় status code. GraphQL-এ সব অনুরোধ একটি ঠিকানায় যায়, POST /graphql, আর একটি অনুরোধে সফল আর ব্যর্থ দুই রকম field থাকতে পারে। তাই ভুলের হিসাব থাকে উত্তরের ভেতরে। সত্যিকারের run, লগইন ছাড়া phone চাইলে (অপ্রয়োজনীয় header বাদ):

$ curl -i http://127.0.0.1:4136/graphql -H 'content-type: application/json' \
    -d '{"query":"{ products(first: 1) { name seller { name phone } } }"}'
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"errors":[{"message":"Not allowed to read Seller.phone","locations":[{"line":1,"column":43}],
"path":["products",0,"seller","phone"],"extensions":{"code":"FORBIDDEN"}}],
"data":{"products":[{"name":"Miniket Rice 5kg","seller":{"name":"Rahim Store","phone":null}}]}}

Status 200, অথচ একটি ভুল। এই উত্তরের নাম partial response: যা পাওয়া গেছে তা data-তে, যা যায়নি তা null, আর কারণ errors-এ। path বলে দেয় ঠিক কোন field. extensions.code যন্ত্রে পড়ার মতো কারণ, এটিই client-এর দেখার জিনিস, বার্তার লেখা নয়।

Mutation-এও আংশিক ফল

এক mutation-এ তিনটি রিভিউ পাঠালে কী হয়? দ্বিতীয়টির rating 9, যা নিয়মের বাইরে। নিচের ধাপগুলো সত্যিকারের run থেকে নেওয়া। Field-গুলো ক্রমে চলছে কি না, আর ডেটা কী থেকে যাচ্ছে, লক্ষ করুন:

mutation TwoReviews {
  first:  addReview(input: {productId: "1", rating: 5, comment: "good"}) { id rating }
  second: addReview(input: {productId: "1", rating: 9}) { id }
  third:  addReview(input: {productId: "2", rating: 4}) { id }
}

SQL 1: INSERT INTO reviews ... RETURNING *  ["1",5,"good"]
"first":{"id":"21","rating":5}

"second": null
errors[0]: "Rating must be 1 to 5"
path: ["second"]   code: BAD_USER_INPUT

SQL 2: INSERT INTO reviews ... RETURNING *  ["2",4,null]
"third":{"id":"22"}

{"errors":[{"message":"Rating must be 1 to 5", ... }],
 "data":{"first":{"id":"21","rating":5},"second":null,"third":{"id":"22"}}}
operationName: "TwoReviews"
status: 200    errorCount: 1

একটি non-null সব মুছে দিতে পারে

এবার balance: Int! field-টি লগইন ছাড়া চাই। সত্যিকারের run:

query:  { products(first: 1) { name seller { name balance } } }
{"errors":[{"message":"Not allowed to read Seller.balance", ...
"path":["products",0,"seller","balance"], ...}],"data":null}

পণ্যের নাম, বিক্রেতার নাম, সব উধাও, data পুরোটাই null! কারণ balance null হতে পারে না, তাই null তার parent seller-এ উঠল। seller: Seller!-ও non-null, তাই উঠল পণ্যে। [Product!]!-ও, তাই শেষে data-তে। একটি ছোট field একটি পুরো পর্দা নামিয়ে দিল।

অপ্রত্যাশিত ভুল লুকানো থাকে

Lab-এ shippingEstimate resolver সাধারণ Error ছোড়ে, বার্তায় একটি নকল key আছে। Client পেল শুধু এটুকু:

{"errors":[{"message":"Unexpected error.", ... "path":["products",0,"shippingEstimate"],
"extensions":{"code":"INTERNAL_SERVER_ERROR"}}],"data":{"products":[{"name":"Miniket Rice 5kg","shippingEstimate":null}]}}

এটি error masking, Yoga-তে এটি নিজে থেকেই চালু। শুধু GraphQLError ছুড়লে বার্তা client পর্যন্ত যায়। আসল বার্তাটি server-এর log-এ থাকে। Apollo Server বা নিজের লেখা server-এ আচরণ আলাদা হতে পারে, docs দেখে নেবেন।

Monitoring কেন বদলে যায়

এখানেই সবচেয়ে বড় ফাঁদ। ধরুন আপনার dashboard দেখে “কত শতাংশ অনুরোধ 5xx”, আর path ধরে latency ভাগ করে। উপরের masked error-এর সময় Yoga 6-এর নিজের log-এ এলো (সত্যিকারের run, requestId বাদ):

ERR
  err: { message: "courier API refused key example-secret" ... }
INF Request processed
  method: "POST"
  path: "/graphql"
  operationType: "query"
  status: 200
  errorCount: 1
  durationMs: 2

HTTP-র চোখে এটি সুস্থ: status 200. আর সব অনুরোধের path একটিই, /graphql. তাই পর্ব ৩১-এর structured log-এ আরও তিনটি জিনিস যোগ করতে হবে:

• operationName: query Shop লেখা থাকলে আর client নামটি পাঠালে log-এ operationName: "Shop" আসে। নামহীন query-কে আলাদা করা যায় না, তাই client-এ নাম দেওয়া বাধ্যতামূলক করুন।
• errorCount আর extensions.code: সতর্কবার্তা বসবে এখানে, 5xx-এ নয়। FORBIDDEN আর INTERNAL_SERVER_ERROR এক জিনিস নয়।
• প্রতি operation-এর SQL সংখ্যা: আমরা নিচে ঠিক এটিই মেপে N+1 ধরব।

৫ · N+1: সুন্দর query-র আড়ালে ২১টি SQL

আগের ধাপগুলোয় গুণটি দেখেছেন। এবার আসল সংখ্যা। Lab-এ ১০টি পণ্য, ৩ জন বিক্রেতা। Client একটি ছোট query পাঠাল:

query Shop { products(first: 10) { name seller { name } reviews { rating } } }

প্রতিটি SQL যাচ্ছে একটি helper দিয়ে, তাই log-টি আসল (সত্যিকারের run, মাঝের অংশ ছাঁটা):

  SQL  1: SELECT * FROM products ORDER BY id LIMIT ?  [10]
  SQL  2: SELECT * FROM sellers WHERE id = ?  [1]
  SQL  3: SELECT * FROM reviews WHERE product_id = ?  [1]
  SQL  4: SELECT * FROM sellers WHERE id = ?  [1]
  SQL  5: SELECT * FROM reviews WHERE product_id = ?  [2]
  SQL  6: SELECT * FROM sellers WHERE id = ?  [1]
  ...
  SQL 20: SELECT * FROM sellers WHERE id = ?  [3]
  SQL 21: SELECT * FROM reviews WHERE product_id = ?  [10]
{"op":"Shop","sql":21,"errors":0}

N+1 মানে তালিকার ১টি query আর প্রতিটি সারির জন্য N-টি। আমাদের সম্পর্ক দুটি, তাই ১ + ২ × ১০ = ২১. বিক্রেতা মাত্র ৩ জন, অথচ sellers-এ গেল ১০টি query, একই id বারবার। REST-এ এটি একটি ভুল; GraphQL-এ এটি নকশার স্বাভাবিক ফল, কারণ প্রতিটি resolver শুধু নিজের parent-কে চেনে, পাশের পণ্যটিকে নয়।

নিচের মডেলে সংখ্যা বাড়িয়ে দেখুন। এটিও শেখার মডেল, SQL শুধু গোনা হচ্ছে, কোনো database নেই।

// শেখার মডেল: প্রতিটি resolver কতবার ডাকা হলো আর কতটি query গেল
function shop(n) {
  const products = [];
  for (let i = 1; i <= n; i++) products.push({ id: i, sellerId: (i % 3) + 1 });
  return products;
}
function runQuery(n) {
  const calls = {}, sql = [];
  const count = (k) => { calls[k] = (calls[k] || 0) + 1; };
  const resolvers = {
    products() {
      count("Query.products");
      sql.push("SELECT * FROM products LIMIT " + n);
      return shop(n);
    },
    seller(p) {
      count("Product.seller");
      sql.push("SELECT * FROM sellers WHERE id = " + p.sellerId);
    },
    reviews(p) {
      count("Product.reviews");
      sql.push("SELECT * FROM reviews WHERE product_id = " + p.id);
    },
  };
  for (const p of resolvers.products()) {
    resolvers.seller(p);
    resolvers.reviews(p);
  }
  return { calls, sql };
}
for (const n of [1, 10, 100]) {
  const { calls, sql } = runQuery(n);
  console.log("N=" + n, "query:", sql.length, JSON.stringify(calls));
}
console.log(runQuery(10).sql.slice(0, 3).join("\n"));

একটি হিসাব। ধরে নিই database-এর একটি query-তে নেটওয়ার্কসহ ২ ms লাগে আর query-গুলো একটির পর একটি চলে। ১০০টি পণ্যে ২০১ × ২ = ৪০২ ms. একটি পাতায় ২০০ জন একসাথে এলে ৪০,২০০টি query, যেখানে batching-এ ৬০০টি। Client যদি রিভিউর নিচে আরেক স্তর চায়, গুণ আবার বাড়ে: প্রতি রিভিউতে একটি করে query, গড়ে ৫টি রিভিউ হলে ১০০ × ৫ = ৫০০টি বাড়তি। এই সংখ্যাগুলো ধরে নেওয়া মানের ওপর হিসাব।

৬ · DataLoader: জমিয়ে একবারে আনা

ডাকঘরের পিয়নের কথা ভাবুন। প্রতিটি চিঠির জন্য আলাদা করে পাড়ায় না গিয়ে তিনি সকালের সব চিঠি জমান, তারপর একবারে যান। একই ঠিকানার ১০টি চিঠিতে যাত্রা একটিই। DataLoader তাই করে: resolver-গুলো এই tick-এ যত id চাইল জমিয়ে রাখে, একই id দুবার রাখে না, tick শেষে একটি WHERE id IN (...) পাঠায়। এই কৌশলের নাম query batching.

import DataLoader from 'dataloader';

// প্রতি request-এ নতুন: cache কখনো request-এর বাইরে যাবে না
export function createLoaders(ctx) {
  return {
    sellerById: new DataLoader(async (ids) => {
      const marks = ids.map(() => '?').join(',');
      const rows = sql(ctx, `SELECT * FROM sellers WHERE id IN (${marks})`, ...ids);
      const byId = new Map(rows.map((r) => [r.id, r]));
      return ids.map((id) => byId.get(id) ?? new Error(`seller ${id} missing`));
    }),
    reviewsByProduct: new DataLoader(async (ids) => {
      const marks = ids.map(() => '?').join(',');
      const rows = sql(ctx, `SELECT * FROM reviews WHERE product_id IN (${marks})`, ...ids);
      return ids.map((id) => rows.filter((r) => r.product_id === id));
    }),
  };
}

Batch ফাংশনের দুটি কঠিন নিয়ম: ফেরত array-র দৈর্ঘ্য ids-এর সমান হতে হবে, আর ক্রমও একই। Database সারি যে ক্রমে দেয় তা নয়, তাই Map দিয়ে সাজানো হয়েছে। Resolver এখন শুধু ctx.loaders.sellerById.load(p.seller_id) ডাকে। ? placeholder তৈরি হচ্ছে কোড থেকে, id সরাসরি SQL-এ বসছে না, তাই SQL injection-এর পথ বন্ধই থাকে।

একই query, একই ডেটা (সত্যিকারের run):

  SQL  1: SELECT * FROM products ORDER BY id LIMIT ?  [10]
  SQL  2: SELECT * FROM sellers WHERE id IN (?,?,?)  [1,2,3]
  SQL  3: SELECT * FROM reviews WHERE product_id IN (?,?,?,?,?,?,?,?,?,?)  [1,2,3,4,5,6,7,8,9,10]
{"op":"Shop","sql":3,"errors":0}

ধাপে ধাপে দুই পথ পাশাপাশি দেখুন:

“এক tick” বলতে কী বোঝায়, তা নিজে দেখুন। নিচে একটি শেখার মডেল: microtask দিয়ে একটি ছোট DataLoader. Event loop-এর পুরো ছবি আছে পর্ব ২৪-এ।

// শেখার মডেল: ছোট DataLoader; আসল প্যাকেজের মতোই queue, batch আর cache
function tinyLoader(batchFn) {
  const cache = new Map();
  let queue = [];
  function dispatch() {
    const jobs = queue;
    queue = [];
    batchFn(jobs.map((j) => j.key)).then((values) => {
      jobs.forEach((j, i) => j.resolve(values[i]));
    });
  }
  return {
    load(key) {
      if (cache.has(key)) return cache.get(key);   // একই id দ্বিতীয়বার নয়
      const promise = new Promise((resolve) => {
        if (queue.length === 0) queueMicrotask(dispatch);   // tick শেষে পাঠাও
        queue.push({ key, resolve });
      });
      cache.set(key, promise);
      return promise;
    },
  };
}
let queries = 0;
const sellerById = tinyLoader(async (ids) => {
  queries++;
  console.log("SQL:", "SELECT * FROM sellers WHERE id IN (" + ids.join(",") + ")");
  return ids.map((id) => ({ id, name: "Seller-" + id }));
});
const products = [1, 1, 1, 2, 2, 2, 2, 3, 3, 3].map((sellerId) => ({ sellerId }));
Promise.all(products.map((p) => sellerById.load(p.sellerId))).then((sellers) => {
  console.log("পণ্য:", products.length, "SQL:", queries);
  console.log("প্রথম:", sellers[0].name, "শেষ:", sellers[9].name);
});

৭ · Authorization: route নয়, field

REST-এ পর্ব ২৬-এর middleware route-এর সামনে পাহারা বসায়। GraphQL-এ route একটিই। আর একই Seller object নানা পথে পৌঁছানো যায়: products → seller, product → seller, reviews → product → seller. দরজায় পাহারা দিলে পেছনের জানালা খোলা থাকে। তাই অনুমতি যাচাই বসে field-এর ওপর, যাকে বলে field-level authorization:

function requireAdmin(ctx, field) {
  if (ctx.user?.role !== 'admin')
    throw new GraphQLError(`Not allowed to read ${field}`, {
      extensions: { code: 'FORBIDDEN' },
    });
}
const resolvers = {
  Seller: {
    phone(s, _, ctx) { requireAdmin(ctx, 'Seller.phone'); return s.phone; },
  },
};

Lab-এ context request-এর header থেকে ctx.user বানায়। এখানে example-admin-token একটি নকল token, শুধু দেখানোর জন্য; আসল login আসবে পর্ব ৪৫ আর ৪৬-এ। একই query, token সহ (সত্যিকারের run):

{"data":{"products":[{"name":"Miniket Rice 5kg","seller":{"name":"Rahim Store","phone":"01700000001"}}]}}

Token ছাড়া এই field-টিই ছিল null আর FORBIDDEN, ৪ নম্বর অংশে দেখেছেন। Field-এর resolver-এ যাচাই রাখলে যে পথেই আসুক ধরা পড়ে। আরও ভালো হলো যাচাইটি পর্ব ২৯-এর service স্তরে রাখা, যাতে REST আর GraphQL একই নিয়ম মানে। কোন ধরনের ত্রুটি থেকে এই সতর্কতা, তা আছে Broken Access Control আর API Security পর্বে। Role আর মালিকানার পুরো নকশা আসবে পর্ব ৪৮-এ।

৮ · Query-র সীমা: depth, cost আর persisted query

REST-এ server ঠিক করে কোন endpoint কত কাজ করবে। GraphQL-এ সেই ক্ষমতা client-এর হাতে। আমাদের schema-তে Product → Seller → Product একটি চক্র, তাই যে কেউ লিখতে পারেন:

{ products(first: 10) { seller { products { seller { products {
  seller { products { name } } } } } } } }

লেখাটি মাত্র দুই লাইন, অথচ server-এর কাজ গুণ হয়ে বাড়ে। এটি সহজ একটি DoS. প্রতিরক্ষা তিন স্তরে।

Depth আর cost limit

Depth limit গভীরতা আটকায়, তবে চওড়া query ধরতে পারে না। সেজন্য query cost: প্রতিটি field-এর জন্য ১ ধরে তালিকার আকার দিয়ে গুণ করা। দুটিই query চালানোর আগে, validation ধাপে মাপা হয়। মডেলে দেখুন (শেখার মডেল, সীমা: depth 6, cost 500):

// শেখার মডেল: query চালানোর আগেই depth আর cost মাপা
const LIST_SIZE = { products: 10, reviews: 5 };   // ধরে নেওয়া গড় আকার
const MAX_DEPTH = 6, MAX_COST = 500;

function measure(selection, depth = 1, mult = 1) {
  let deepest = depth, cost = 0;
  for (const field in selection) {
    cost += mult;
    const sub = selection[field];
    if (sub === true) continue;
    const size = LIST_SIZE[field] ?? 1;
    const inner = measure(sub, depth + 1, mult * size);
    deepest = Math.max(deepest, inner.deepest);
    cost += inner.cost;
  }
  return { deepest, cost };
}
function check(name, query) {
  const { deepest, cost } = measure(query);
  let verdict = "চলবে";
  if (deepest > MAX_DEPTH) verdict = "বাতিল: depth";
  else if (cost > MAX_COST) verdict = "বাতিল: cost";
  console.log(name, "depth", deepest, "cost", cost, verdict);
}
check("তালিকা", { products: { name: true, price: true } });
check("রিভিউসহ", { products: { name: true, reviews: { rating: true } } });
check("চওড়া", { products: { reviews: { product: { reviews: { product: { rating: true } } } } } });
const trap = (d) => (d === 0 ? { name: true } : { seller: { products: trap(d - 1) } });
check("ফাঁদ", { products: trap(4) });

আসল server-এ একই নিয়ম validation rule হিসেবে লিখেছি (limits.js, প্রায় ৪০ লাইন; first-এর মান আগে না জানলে সবচেয়ে খারাপ ৫০ ধরে নেয়)। Fragment-এর ভেতরেও ঢুকতে হয়, নইলে সীমা ফাঁকি দেওয়া যায়। সত্যিকারের run, Accept: application/graphql-response+json সহ:

400 {"errors":[{"message":"Query depth 8 is over the limit 6","extensions":{"code":"DEPTH_LIMIT"}}]}
400 {"errors":[{"message":"Query cost 1801 is over the limit 500","extensions":{"code":"COST_LIMIT"}}]}

দ্বিতীয়টি ছিল { products(first: 50) { reviews { product { reviews { rating } } } } }, হিসাব 1 + 50 + 250 + 250 + 1250 = 1801. সাধারণ rate limit অনুরোধ গোনে; এখানে অনুরোধ একটিই, কাজ অনেক। তাই পরিণত API-তে rate limit-ও অনেক সময় cost দিয়ে মাপা হয়।

Persisted query: অচেনা query চলবেই না

আপনার ওয়েব আর ফোনের অ্যাপ যে query পাঠায়, তা build-এর সময়েই জানা। তাহলে server-কে যেকোনো লেখা চালাতে দেওয়ার দরকার কী? Persisted query-তে query আগে থেকে server-এ জমা থাকে, client শুধু একটি id বা hash পাঠায়, অনেকটা হোটেলের ক্রমিক নম্বর দেওয়া মেনুর মতো। এটি একটি allowlist. সত্যিকারের run, @graphql-yoga/plugin-persisted-operations 4.0.1 দিয়ে:

# অজানা query-র লেখা পাঠালে
{"errors":[{"message":"PersistedQueryOnly","extensions":{"code":"CANNOT_SEND_PQ_ID_AND_BODY"}}]}

# extensions.persistedQuery.sha256Hash = cheap-list-v1
{"data":{"products":[{"name":"Miniket Rice 5kg","price":420},{"name":"Soybean Oil 1L","price":190}]}}

# তালিকায় নেই এমন id
{"errors":[{"message":"PersistedQueryNotFound","extensions":{"code":"PERSISTED_QUERY_NOT_IN_LIST"}}]}

লক্ষ করুন, এই তিনটি উত্তরই status 200 ছিল। নিজের অ্যাপের জন্য বানানো API-তে এটিই সবচেয়ে শক্ত প্রতিরক্ষা। সবার জন্য খোলা API-তে এটি চলে না, সেখানে depth আর cost limit-ই ভরসা। Automatic Persisted Queries (APQ) আলাদা জিনিস: সেখানে client অচেনা query-ও চলার সময়ে জমা দিতে পারে, তাই এটি bandwidth বাঁচায়, নিরাপত্তা দেয় না।

৯ · Cache, client, codegen আর REST বনাম GraphQL বনাম tRPC

Cache এখানে কঠিন কেন

REST-এর বড় উপহার হলো HTTP নিজেই cache বোঝে: GET /products/7 একটি URL, তাতে Cache-Control আর ETag বসানো যায়, browser আর CDN বিনা চেষ্টায় জমা রাখে (Web Caching ও CDN পর্ব দেখুন)। GraphQL-এ তিনটি কারণে এটি ভাঙে:

• অনুরোধ সাধারণত POST, আর HTTP cache আর CDN বাস্তবে সাধারণত POST-এর উত্তর জমা রাখে না।
• URL একটিই, পার্থক্য body-তে। প্রতিটি client-এর query আলাদা, তাই hit rate কমে।
• এক উত্তরে নানা বয়সের ডেটা মেশানো: দাম মিনিটে বদলায়, বিক্রেতার নাম মাসে। একটি max-age দুটিকে মানায় না। অনুমতি-নির্ভর field থাকলে উত্তর public-ও করা যায় না।

পথ আছে, তবে কাজ বেশি। Yoga-তে GET-এ query চলে (lab-এ 200 এসেছে), আর persisted query-র ছোট id দিলে URL ছোট থাকে, ফলে CDN-এ রাখা সম্ভব। Client-এর দিকে চলে normalized cache: উত্তরকে Product:7-এর মতো চাবিতে ভেঙে রাখা। Server-এর দিকে চলে resolver-স্তরের cache (পর্ব ৪৪).

Client আর codegen, সংক্ষেপে

সাধারণ fetch-এও GraphQL চলে, শুধু JSON body পাঠাতে হয়। দুটি জনপ্রিয় client হলো urql (লেখার সময়ে 5.0.4) আর Apollo Client (4.3.5); এদের cache আর hook আছে। পর্ব ১৯-এর TanStack Query-র সাথেও জোড়া যায়। কোনটি নেবেন তা নির্ভর করে cache কতটা দরকার তার ওপর, আমরা একটিকে সেরা বলছি না।

Schema typed, তাই code generation দিয়ে query থেকেই TypeScript type বানানো যায়, যেমন @graphql-codegen/cli (7.4.6) দিয়ে। Field-এর নাম ভুল হলে build-এই ধরা পড়ে। পর্ব ৩৫-এর OpenAPI থেকে type বানানোর সাথে তুলনা করে দেখবেন, চিন্তা একই।

সৎ সিদ্ধান্তের ছক

এই বিষয়ে community-তে তীব্র মতভেদ আছে। কেউ বলেন GraphQL ছোট দলে বাড়তি বোঝা, কেউ বলেন অনেক client থাকলে এটি ছাড়া চলে না। দুই পক্ষেরই যুক্তি আছে, তাই শর্ত দিয়ে ভাবুন:

• REST দিয়ে শুরু করুন যদি API বাইরের লোক ব্যবহার করবেন, client একটি বা দুটি, আর দল ছোট। পর্ব ৩২–৩৫-এর শৃঙ্খলাই যথেষ্ট।
• GraphQL ভাবুন যদি অনেক আলাদা client একই ডেটা নানা আকারে চায়, আর দল N+1, limit ও monitoring-এর খরচ বহন করতে পারে।
• tRPC ভাবুন যদি একই TypeScript project-এ React আর Node থাকে, আর বাইরের client নেই। পর্ব ৩৭-এ দেখবেন।
• একটি কঠিন সিদ্ধান্ত নয়: বাইরে REST আর ভেতরের পর্দার জন্য GraphQL, এমন মিশ্রণও চলে।

১০ · AI-এর যুগে GraphQL

AI খুব দ্রুত schema আর resolver লিখে দেয়, আর সেগুলো চলেও। সমস্যা হলো GraphQL-এর ভুল প্রায়ই “চলে”, ধরা পড়ে production-এর ভিড়ে। সাধারণ ভুলগুলো হলো:

AI-এর GraphQL কোড হাতে পেলে: যাচাইয়ের তালিকা

• নিজের version-এর official docs খুলে API মিলিয়েছি, আর npm view দিয়ে package-টি আসল কি না দেখেছি
• চালিয়ে দেখেছি, আর ১০০ সারি ডেটায় প্রতি operation-এর SQL গুনেছি
• Token ছাড়া nested query পাঠিয়ে দেখেছি, সংবেদনশীল field null আসছে
• Depth আর cost limit-এর ওপরে একটি query পাঠিয়ে দেখেছি, চালানোর আগেই আটকাচ্ছে
• Diff পড়েছি: নতুন dependency সত্যিই দরকার কি না, npm ls graphql-এ একটিই কপি আছে কি না
• কোনো আসল secret বা token AI-কে দিইনি, আর error-এর আসল বার্তা client-এ যাচ্ছে না