GraphQL sxemi və tiplər: SDL, skalyarlar, obyekt tipləri, non-null

Əvvəlki dərsdə sxemi frontend ilə backend arasında müqavilə adlandırdıq. İndi onu yazmağı öyrənəcəyik. Klinikaya yazılarkən doldurduğunuz anketi təsəvvür edin: orada bütün xanalar sadalanıb (ad, doğum tarixi, telefon), hər xananın cavab formatı aydındır, məcburi xanalar isə qırmızı ulduzla işarələnib. GraphQL sxemi də eynilə anketdir, sadəcə API-nizin məlumatları üçündür: o, əvvəlcədən təsvir edir ki, hansı məlumat tipləri var, onlar hansı sahələrdən ibarətdir və hansı sahələr məcburidir. Server sxemdə olmayan heç nəyi nə qaytarır, nə də qəbul edir. Bu dərsdə istifadəçilərdən, postlardan və şərhlərdən ibarət blog sxemini təsvir edəcək və onu bütün modul boyu istifadə edəcəyik.

SDL: sxemin yazıldığı dil

Sxemi SDL (Schema Definition Language, «sxemi təsvir dili») ilə yazırlar. Bu nə JavaScript-dir, nə də JSON, kiçik deklarativ dildir: siz məlumatın necə əldə olunacağını yox, yalnız necə görünəcəyini təsvir edirsiniz. Əsas «kərpic» tipin elan edilməsidir:

type Post {
  id: ID!
  title: String!
  body: String!
  published: Boolean!
}

title: String! sətrini hissələrə ayıraq:

• title — sahənin adı;
• String — dəyərin tipi (mətn);
• ! — dəyər heç vaxt null olmur; bu işarə haqqında bir az aşağıda ətraflı danışacağıq.

Demək olar ki, hamının riayət etdiyi adlandırma qaydaları var: tipləri PascalCase ilə (Post, CreatePostInput), sahə və arqumentləri camelCase ilə (createdAt), enum dəyərlərini isə SCREAMING_SNAKE_CASE ilə (NEWEST) yazırlar. Şərhlər # ilə başlayır, server onları nəzərə almır. Tiplərin elan sırası vacib deyil: tipi təsvir olunmazdan əvvəl də işlətmək olar.

Skalyar tiplər: məlumatın «atomları»

İstənilən sorğunun sonunda konkret dəyərlər qalmalıdır: ədəd, mətn, «hə/yox». Bu cür «yarpaqlara» skalyar deyilir. GraphQL-də beş daxili skalyar var:

Yeni başlayanların büdrədiyi üç nüans:

• ID cavabda həmişə sətirdir. Bazada bu, 42 ədədi olsa belə, müştəri "42" alacaq. İdentifikator qeydləri tapmaq və müqayisə etmək üçündür, hesablamaq üçün yox: iki ID-ni toplamağın mənası yoxdur.
• Int 32 bitlidir. Maksimum dəyər 2 147 483 647-dir (təxminən 2,1 milyard). Daha böyük ədədlər üçün (məsələn, sosial şəbəkələrin identifikatorları) String götürürlər.
• Siyahıda tarix yoxdur. Tarix və vaxt üçün daxili tip yoxdur. Adətən tarixi ISO 8601 sətri kimi ötürürlər, məsələn, "2026-03-15T10:30:00Z"; createdAt sahəsində də belə edəcəyik. Böyük layihələrdə öz skalyarını (scalar DateTime) elan edirlər, məsələn, graphql-scalars kitabxanasının köməyi ilə.

Obyekt tipləri və onlar arasındakı əlaqələr

Əsas tip növü obyekt tipidir: adlandırılmış sahələr toplusu. Gəlin blogu təsvir edək. Onun üç varlığı var: istifadəçi (User), post (Post) və şərh (Comment):

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  body: String!
  published: Boolean!
  author: User!
  comments: [Comment!]!
  createdAt: String!
}

type Comment {
  id: ID!
  text: String!
  author: User!
  post: Post!
}