GraphQL

01Սխեմաներ, տիպեր և resolver-ներ

Պատկերացրեք REST API-ն որպես ֆիքսված մենյու. յուրաքանչյուր endpoint վերադարձնում է որոշակի ճաշատեսակ։ GraphQL-ը շվեդական սեղան է՝ ճշգրիտ պատվերի ձևաթղթով. կլիենտը նշում է իր ուզած ուտեստներն ու բաժինները։ Սերվերը նկարագրում է ամբողջ հասանելին սխեմայում, որը գրված է Schema Definition Language-ով (SDL)։ Object տիպերը (Product, Order) ունեն տիպավորված դաշտեր. scalar-ները հիմնականներն են (String, Int, Boolean, ID). բացականչական նշանը նշանակում է non-null. ցուցակները գրվում են քառակուսի փակագծերով։ Հատուկ root տիպերը սահմանում են մուտքի կետերը. Query՝ կարդալու, Mutation՝ գրելու, Subscription՝ իրական ժամանակի թարմացումների համար։ Յուրաքանչյուր դաշտի հետևում resolver է՝ ֆունկցիա, որը վերադարձնում է դրա արժեքը։ Սերվերը parse է անում query-ն, validate է անում այն սխեմայի դեմ, հետո դաշտ առ դաշտ կանչում resolver-ները՝ կառուցելով պատասխան, որը կրկնում է query-ի ձևը։ Անհայտ դաշտերը մերժվում են դեռ մինչև որևէ կոդի աշխատելը։

1type Product {
2  id: ID!
3  name: String!
4  price: Int!
5  category: Category!
6}
7 
8type Category {
9  id: ID!
10  name: String!
11}
12 
13type Query {
14  products(first: Int = 20, after: String): [Product!]!
15  product(id: ID!): Product
16}
17 
18type Mutation {
19  renameProduct(id: ID!, name: String!): Product!
20}

02Query-ներ, mutation-ներ և subscription-ներ

Query-ն տվյալներ է խնդրում. կլիենտն ընտրում է դաշտերը և կարող է մեկ request-ում հետևել կապերին, օրինակ՝ ապրանքներ իրենց կատեգորիաների անուններով։ Variable-ները query-ները պահում են ստատիկ և վերաօգտագործելի, ինչը նաև հնարավոր է դարձնում persisted query-ները։ Fragment-ները վերաօգտագործում են դաշտերի ընտրությունը կոմպոնենտների միջև, և շատ կլիենտային գրադարաններ դրանք տեղադրում են UI կոմպոնենտների կողքին։ Mutation-ը փոխում է տվյալները և վերադարձնում թարմացված օբյեկտը, որպեսզի կլիենտի cache-ը թարմանա առանց լրացուցիչ request-ի. մեկ request-ի mutation-ները կատարվում են հաջորդաբար։ Mutation-ները նախագծեք բիզնես գործողությունների շուրջ (placeOrder, cancelSubscription), ոչ թե աղյուսակների ընդհանուր թարմացումների, և սպասվող ձախողումների համար, օրինակ validation-ի, վերադարձրեք կառուցվածքային սխալներ payload-ի ներսում։ Subscription-ները թարմացումները push են անում կլիենտին, սովորաբար WebSocket-ներով կամ server-sent event-ներով, օրինակ՝ պատվերի կարգավիճակի կամ chat-ի համար։ Դրանք ավելացնում են stateful կապեր, որոնք պետք է մասշտաբավորել և պաշտպանել, ուստի օգտագործեք դրանք այնտեղ, որտեղ կենդանի թարմացումներն իսկապես կարևոր են։

03N+1 խնդիրը և DataLoader-ը

Քանի որ յուրաքանչյուր դաշտ ունի իր resolver-ը, միամիտ սերվերը կատարում է մեկ query 50 ապրանքների ցուցակի համար, հետո մեկական query յուրաքանչյուր ապրանքի կատեգորիայի համար. 51 query մեկ request-ի համար։ Սա N+1 խնդիրն է, և ներդրված query-ներն այն ավելի են վատացնում։ Ստանդարտ լուծումը batching-ն է DataLoader-ով։ Անմիջապես տվյալ բերելու փոխարեն յուրաքանչյուր resolver loader-ից key է խնդրում. loader-ը հավաքում է event loop-ի նույն tick-ում խնդրված բոլոր key-երը և բերում դրանք մեկ query-ով (WHERE id IN ...), հետո արդյունքները վերադարձնում ճիշտ հերթականությամբ։ Այն նաև cache է անում request-ի սահմաններում, ուստի նույն կատեգորիան բեռնվում է մեկ անգամ։ Loader-ները ստեղծեք յուրաքանչյուր request-ի համար, երբեք գլոբալ, որպեսզի cache արված տվյալները չարտահոսեն օգտատերերի միջև։ Հետևեք resolver-ների ժամանակներին և query-ների քանակին յուրաքանչյուր operation-ի համար՝ regression-ները բռնելու համար։

1import DataLoader from "dataloader";
2 
3// One set of loaders per request, so caching never leaks between users
4export function createLoaders(db: Db) {
5  return {
6    categoryById: new DataLoader<string, Category | null>(async (ids) => {
7      const rows = await db.category.findMany({ where: { id: { in: [...ids] } } });
8      const byId = new Map(rows.map((c) => [c.id, c]));
9      return ids.map((id) => byId.get(id) ?? null);
10    }),
11  };
12}
13 
14export const resolvers = {
15  Product: {
16    category: (p: Product, _args: unknown, ctx: Ctx) =>
17      ctx.loaders.categoryById.load(p.categoryId),
18  },
19};

04Caching և անվտանգություն

REST-ը օգտվում է HTTP caching-ից. յուրաքանչյուր URL ռեսուրս է, որը browser-ները, CDN-ները և proxy-ները կարող են cache անել։ GraphQL-ը սովորաբար POST request-ներ է ուղարկում մեկ endpoint-ի, ուստի այդ շերտը վերանում է։ Պատասխանները. նորմալացված կլիենտային cache-եր (Apollo Client, urql, Relay), որոնք օբյեկտները պահում են ըստ տիպի և ID-ի. persisted query-ներ, որոնք ուղարկվում են GET-ով hash-ով, ինչը կրկին հնարավոր է դարձնում CDN caching-ը. և resolver-ների արդյունքների սերվերային caching՝ ըստ օգտատիրոջ զգույշ scope-ով։ Անվտանգությունը նույնքան ուշադրություն է պահանջում։ Կլիենտը կարող է գրել խորը ներդրված կամ հսկայական query, որը սերվերի վրա ահռելի արժենա, ուստի կիրառեք առավելագույն խորության, query-ի բարդության կամ արժեքի սահմանաչափեր, pagination-ի սահմանաչափեր և timeout-ներ։ Rate limit արեք ըստ արժեքի, ոչ միայն request-ների քանակի։ Production-ում մտածեք private API-ների համար introspection-ն անջատելու մասին, կամ, ավելի լավ, թույլ տվեք միայն ձեր սեփական կլիենտների persisted query-ները։ Թույլտվությունը (authorisation) ստուգեք resolver-ներում կամ բիզնես շերտում, անհրաժեշտության դեպքում՝ ըստ դաշտի, երբեք միայն endpoint-ում։

• Խորության և բարդության սահմաններ, գումարած պարտադիր pagination ցուցակների համար։
• Persisted query-ներ. ավելի փոքր request-ներ, CDN caching, անվտանգ allow-list։
• Դաշտի մակարդակի authorisation և ըստ request-ի DataLoader-ներ։

05GraphQL vs REST vs tRPC

Ընտրեք ըստ կլիենտների լանդշաֆտի և թիմի կառուցվածքի։ GraphQL-ը հաղթում է, երբ տարբեր կարիքներով շատ կլիենտներ կիսում են հարուստ, փոխկապակցված դոմեն, երբ պլատֆորմային թիմը սպասարկում է մի քանի պրոդուկտային թիմի, կամ երբ մի քանի backend միավորում եք մեկ graph-ի մեջ (federation)։ REST-ը հաղթում է public API-ների, պարզ ռեսուրսային մոդելների, ֆայլերի upload-ի և download-ի, webhook-ների և այն ամենի համար, ինչը շահում է HTTP caching-ից և ծանոթ գործիքներից. OpenAPI-ով դուք միևնույն է ստանում եք տիպավորված կլիենտներ։ tRPC-ն հաղթում է TypeScript monorepo-ներում, որտեղ նույն թիմն է տիրապետում սերվերին և կլիենտին. procedure-ները կանչվում են ֆունկցիաների պես՝ end-to-end տիպերով և սխեմայի գրեթե զրոյական overhead-ով, բայց այն միայն TypeScript-ի համար է և նախատեսված չէ որպես public, լեզվից անկախ API։ Շատ համակարգեր խառնում են դրանք. REST կամ tRPC ներքին հավելվածների համար, public REST API գործընկերների համար, և GraphQL միայն այնտեղ, որտեղ դրա ճկունությունն արդարացնում է իր բարդությունը։

06Կատարման ներքին մեխանիզմները․ nullability և մասնակի արդյունքներ

GraphQL պատասխանը կարող է պարունակել և՛ data, և՛ errors։ Երբ resolver-ը սխալ է նետում, սխալն ավելացվում է errors զանգվածին՝ ձախողված դաշտի path-ով, և այդ դաշտը դառնում է null։ Եթե դաշտը հայտարարված է non-null, null-ը թույլատրված չէ, ուստի null-ը «բարձրանում» է մինչև մոտակա nullable ծնողը՝ հնարավոր է ջնջելով ամբողջ ցանկը կամ ամբողջ data օբյեկտը։ Դա nullability-ն դարձնում է դիզայնի որոշում, ոչ թե զարդարանք։ Դաշտերը նշիր non-null, երբ դրանք իսկապես միշտ առկա են և էժան (id, name), և պահիր nullable, երբ դրանք կախված են մեկ այլ ծառայությունից կամ թույլտվության ստուգումից, որպեսզի մեկ ձախողումը վատացնի մեկ դաշտ, ոչ թե ամբողջ էջը։ Կլիենտները պետք է կարողանան աշխատել մասնակի տվյալների հետ։ Resolver-ների կատարման հերթականությունը նույնպես կարևոր է․ query-ի հարևան դաշտերը կարող են resolve լինել զուգահեռ, իսկ mutation-ի վերին մակարդակի դաշտերը կատարվում են հաջորդաբար։

• Սխալները կրում են path․ ձախողված դաշտը դառնում է null։
• Non-null դաշտերը null-ը տարածում են վերև՝ մինչև մոտակա nullable ծնողը։
• Անկայուն կախվածություններ կանչող դաշտերը դարձրու nullable։

07Արժեքի վերլուծություն և pagination մեծ մասշտաբով

Միայն խորության սահմանները թույլ են․ ծանծաղ query-ն, որը պահանջում է 100 ապրանք, յուրաքանչյուրը 100 կարծիքով, յուրաքանչյուրը 100 հեղինակով, կարող է պահանջել միլիոն օբյեկտ։ Ստատիկ cost analysis-ը յուրաքանչյուր դաշտին տալիս է արժեք, ցանկի դաշտերը բազմապատկում է պահանջված էջի չափով և մերժում է բյուջեից բարձր query-ները մինչև կատարումը։ Արժեքը հրապարակիր պատասխանի extension-ում, որպեսզի կլիենտները տեսնեն այն, և rate limit արա ըստ արժեքի՝ րոպեում։ Pagination-ը դարձրու պարտադիր՝ էջի առավելագույն չափով։ Cursor-ի վրա հիմնված connections պատերնը (edges, node, pageInfo՝ endCursor-ով և hasNextPage-ով) դե ֆակտո ստանդարտ է․ cursor-ները անթափանց են, կայուն են insert-ների դեպքում և խուսափում են խորը OFFSET scan-երից, որոնք դանդաղեցնում են տվյալների բազաները։ Cursor-ում կոդավորիր sort key-ը և ID-ն, իսկ ներքևում օգտագործիր keyset query (WHERE (created_at, id) < (...) ORDER BY created_at DESC, id DESC)։

1type ProductConnection {
2  edges: [ProductEdge!]!
3  pageInfo: PageInfo!
4}
5 
6type ProductEdge {
7  cursor: String!
8  node: Product!
9}
10 
11type PageInfo {
12  hasNextPage: Boolean!
13  endCursor: String
14}
15 
16type Query {
17  products(first: Int! = 20, after: String): ProductConnection!
18}

08Federation․ մեկ գրաֆ շատ ծառայություններից

Federation-ը թույլ է տալիս մի քանի թիմերի, որոնցից յուրաքանչյուրին պատկանում է իր subgraph-ը, մինչ կլիենտները տեսնում են մեկ supergraph։ Subgraph-ը հայտարարում է entity-ներ key-ով, օրինակ՝ Product, որը նույնականացվում է id-ով։ Մեկ այլ subgraph կարող է ընդլայնել այդ entity-ն իր դաշտերով, օրինակ՝ reviews-ով, և տրամադրում է reference resolver, որը բեռնում է ապրանքի լրացուցիչ տվյալները՝ ունենալով միայն նրա key-ը։ Router-ը կազմում է subgraph-ների սխեմաները, պլանավորում յուրաքանչյուր մուտքային query, կանչում subgraph-ները ճիշտ հերթականությամբ, հաճախ զուգահեռ, և միավորում արդյունքները։ Սա պահպանում է թիմերի ինքնավարությունը՝ կլիենտներին տալով մեկ API։ Ծախսերը․ CI-ում composition-ի ստուգումները դառնում են կրիտիկական, որովհետև մեկ subgraph կարող է կոտրել supergraph-ը, query plan-երը կարող են բաշխվել բազմաթիվ ներքին կանչերի, ուստի entity resolver-ները պետք է batch անեն, և debugging-ը պահանջում է tracing router-ի միջով։ Սա հարմար է մի քանի backend թիմ ունեցող կազմակերպությունների համար․ մեկ թիմի համար դա ավելորդ ծախս է։

09Սխալները որպես տվյալ, input-ների դիզայն և սպեցիֆիկացիայի նոր հնարավորություններ

errors զանգվածն օգտագործիր անսպասելի ձախողումների համար, իսկ սպասվող բիզնես արդյունքները մոդելավորիր սխեմայում։ Mutation-ը կարող է վերադարձնել union, օրինակ՝ PlaceOrderResult = OrderPlaced | OutOfStock | PaymentDeclined, և կլիենտները յուրաքանչյուր դեպք մշակում են fragment-ներով՝ ստանալով տիպավորված դաշտեր ամեն արդյունքի համար։ Input-ները նախագծիր ըստ գործողության․ placeOrder(input: PlaceOrderInput!)-ը արգումենտները պահում է զարգացվող։ GraphQL սպեցիֆիկացիայի 2025-ի սեպտեմբերի խմբագրությունը, առաջինը 2021-ից ի վեր, ավելացրեց OneOf input օբյեկտներ, որտեղ պետք է տրվի ճիշտ մեկ դաշտ, ինչը կոկիկ մոդելավորում է «գտնել ապրանքը id-ով կամ sku-ով»։ Incremental delivery-ն @defer-ով և @stream-ով, որը թույլ է տալիս պատասխանի դանդաղ մասերին հասնել ավելի ուշ, աջակցվում է մի քանի սերվերների և կլիենտների կողմից, բայց դեռ անցնում է սպեցիֆիկացիայի գործընթացով, ուստի մինչև դրա վրա հենվելը ստուգիր քո stack-ի աջակցությունը։

1union PlaceOrderResult = OrderPlaced | OutOfStock | PaymentDeclined
2 
3type OrderPlaced { order: Order! }
4type OutOfStock { productIds: [ID!]! }
5type PaymentDeclined { reason: String! }
6 
7input ProductLookup @oneOf {
8  id: ID
9  sku: String
10}
11 
12type Mutation {
13  placeOrder(input: PlaceOrderInput!): PlaceOrderResult!
14}
15 
16type Query {
17  product(by: ProductLookup!): Product
18}