GraphQL — bu nədir, sorğu dili və mobil layihələrdə tətbiqi

GraphQL nədir?

GraphQL — API üçün spesifikasiya və icra mühitidir ki, müştəriyə alınan məlumatlar üzərində tam nəzarət verir. Facebook mühəndisləri tərəfindən News Feed mobil tətbiqinin problemlərini həll etmək üçün hazırlanmış, spesifikasiya 2015-ci ildə açıq standart kimi dərc edilmişdir. 2018-ci ildən etibarən GraphQL Linux Foundation və Apollo, AWS, GitHub, SAP və digər şirkətlərin dəstəyi ilə GraphQL Foundation tərəfindən idarə olunur.

REST-dən fərqli olaraq, hər bir endpoint sabit məlumat strukturu qaytarır, GraphQL sorğu sətrini qəbul edən vahid endpoint istifadə edir. Müştəri sorğuda hansı sahələrə ehtiyacı olduğunu təsvir edir və server dəqiq onları qaytarır. Məsələn, { user(id: “1”) { name email } } sorğusu istifadəçinin yalnız name və email sahələrini qaytaracaq, REST-də alınmalı olan address, phone və ya createdAt kimi artıq sahələr olmadan.

GraphQL heç bir konkret verilənlər bazası və ya dilə bağlı deyil. Spesifikasiya yalnız sorğu və cavab formatını müəyyən edir. Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) və digər dillərdə server tətbiqləri mövcuddur. Müştəri kitabxanaları iOS, Android və Web üçün Apollo Client daxil olmaqla bütün əsas platformalar üçün əlçatandır.

GraphQL necə işləyir

GraphQL memarlığı üç əsas komponentdən ibarətdir: sxem (Schema), resolverlər (Resolvers) və icra mühərriki (GraphQL Engine). Sxem hansı məlumat növlərinin mövcud olduğunu, hansı sorğuların yerinə yetirilə biləcəyini və hansı arqumentləri qəbul etdiyini müəyyən edir. Resolverlər server tərəfində sxemin hər bir sahəsi üçün məlumat qaytaran funksiyalardır. İcra mühərriki daxil olan sorğunu qəbul edir, onu sxemə görə yoxlayır, müvafiq resolverləri çağırır və cavabı tərtib edir.

Sorğunun işlənmə prosesi belədir:

• Müştəri /graphql ünvanına JSON gövdəsi { “query”: “...” } ilə POST sorğusu göndərir
• Server sorğunu təhlil edir, AST (Abstract Syntax Tree) qurur və onu sxemə görə yoxlayır
• Mühərrik AST üzrə hərəkət edərək hər bir sahə üçün resolverləri çağırır və məlumatları toplayır
• Cavab sorğunun strukturuna ciddi uyğun gələn JSON formatında qaytarılır

GraphQL memarlığının əsas üstünlüyü sahə səviyyəsində həll etmədir. REST-də tərtibatçı ya resursun bütün sahələrini alır (bəlkə də artıqlaması ilə), ya da ?fields=name,email kimi genişlənmələrə əl atır. GraphQL-də belə filtrləmə dilə daxil edilmişdir: hər bir sorğu hansı sahələrin lazım olduğunu açıq şəkildə müəyyən edir və server dəqiq onları qaytarır. Bu, ötürülən məlumatların həcminin yükləmə sürətinə və trafik sərfiyyatına birbaşa təsir etdiyi mobil tətbiqlər üçün xüsusilə vacibdir.

Query, Mutation və Subscription

GraphQL üç növ əməliyyat təyin edir, hər biri müəyyən qarşılıqlı əlaqə ssenarisinə uyğundur. Query — məlumatların oxunması üçün, REST-də GET-ə bənzəyir. Mutation — məlumatların dəyişdirilməsi üçün (yaratma, yeniləmə, silmə), POST/PUT/DELETE-ə bənzəyir. Subscription — WebSocket vasitəsilə real-time yeniləmələr üçün, klassik REST-də birbaşa analoqu yoxdur (WebSocket və ya Server-Sent Events kimi əlavə həllər tələb edir).

Sorğuların əsas sintaksisi intuitivdir:

// Sadə sorğu arqumentlə
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Dəyişdirilmiş məlumatları qaytaran mutation
mutation {
    updateProfile(name: "İvan") {
        id
        name
        updatedAt
    }
}

// Subscription — real-time yeniləmələri dinləyir
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query paralel yerinə yetirilir — eyni səviyyədəki bütün sahələr eyni anda yüklənir. Bu, əlaqəli məlumatları (istifadəçi və onun postları) çoxsaylı round-trip olmadan bir sorğu ilə yükləməyə imkan verir. Mutation ardıcıl yerinə yetirilir — bir sorğudakı mutasiyalar elan olunma sırası ilə bir-birinin ardınca yerinə yetirilir. Subscription WebSocket vasitəsilə daimi əlaqə qurur, server hadisə baş verdikdə məlumat göndərir.

Əməliyyatlar məlumatları sorğudan ayırmaq üçün dəyişənlər, sahələrin şərti daxil edilməsi üçün direktivlər (@include, @skip) və sahə dəstlərinin təkrar istifadəsi üçün fraqmentlər qəbul edə bilər. Bu imkanlar GraphQL sorğularını çevik və təkrar istifadə edilə bilən edir, bu da çoxsaylı ekran və komponentləri olan böyük layihələrdə xüsusilə vacibdir.

GraphQL sxemi və tip sistemi

GraphQL-in əsasında API-nin bütün mümkün məlumatlarını və əməliyyatlarını təsvir edən tip sistemi dayanır. Sxem (Schema) serverin qaytara biləcəyi tiplərin və qəbul etdiyi sorğuların təsviridir. Sxem Schema Definition Language (SDL) dilində yazılır və müştəri ilə server arasında müqavilə rolunu oynayır. Müştəri sxemi introspeksiya vasitəsilə əldə edə bilər — API-nin tam təsvirini qaytaran __schema xüsusi sorğusu.

Bloq üçün sxem nümunəsi:

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String
    author: User!
}

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

Nida işarəsi (!) non-null sahəni bildirir — cavabda mütləq olacaq. Kvadrat mötərizələr [ ] siyahını bildirir. GraphQL skalyar tipləri (Int, Float, String, Boolean, ID), obyekt tiplərini, enum, union, interface və input-tiplərini (mutasiya arqumentləri üçün) dəstəkləyir. Ciddi tipləşdirmə API-ni öz-özünə sənədləşdirir və müştəri alətlərinə kod yaratmağa imkan verir: TypeScript tipləri, Kotlin məlumat sinifləri, Swift strukturları.

İntrospeksiya — REST-də olmayan GraphQL-in unikal imkanıdır. Müştəri sxemə sorğu göndərə və bütün tiplərin, sahələrin, arqumentlərin və direktivlərin tam təsvirini əldə edə bilər. Bu, tərtibatçılar üçün avtomatik sənədləşmə və avtotamamlama yaradan GraphiQL və Apollo Studio kimi alətlərin əsasını təşkil edir. İntrospeksiya həmçinin sxemin gözlənilən strukturuna uyğunluğunu yoxlayan avtomatik testlər yazmağa imkan verir.

GraphQL ilə REST-in müqayisəsi

GraphQL və REST arasında seçim API dizayn edərkən əsas memarlıq suallarından biridir. Hər iki yanaşmanın güclü və zəif tərəfləri var və seçim layihənin xüsusi tələblərindən asılıdır. REST sadəlik və universallıqda, GraphQL isə çeviklik və sorğu səmərəliliyində üstündür. Müqayisə cədvəlinə baxaq.

GraphQL-in əsas çatışmazlığı keşləmənin çətinliyidir. REST-də HTTP keşləməsi URL səviyyəsində işləyir: /api/users/42 ünvanına bir sorğu həmişə eyni strukturu qaytarır və cavab URL-ə görə keşlənə bilər. GraphQL-də bütün sorğular bir endpointə gedir, cavabın strukturu sorğunun məzmunundan asılıdır. Bu problemi həll etmək üçün Apollo Client müştəri tərəfində normallaşdırılmış keşdən istifadə edir ki, cavabları id-ə görə ayrı-ayrı varlıqlara bölür və yeni məlumat alındıqda onları avtomatik yeniləyir.

Digər vacib aspekt N+1 problemidir. İç-içə məlumatlar tələb edərkən (məsələn, istifadəçinin postları və hər posta şərhlər) GraphQL siyahının hər bir elementi üçün ayrıca SQL sorğusu yerinə yetirə bilər. Bu, DataLoader — verilənlər bazası sorğularını toplama və keşləmə vasitəsi ilə həll olunur, o, ayrı-ayrı sorğuları bir toplu sorğuda birləşdirir. REST-də bu problem daha az nəzərə çarpır, çünki tərtibatçı server tərəfində cavabın strukturuna nəzarət edir.

GraphQL sorğu nümunələri

Apollo Client ilə Kotlin-də mobil tətbiqdə GraphQL-dən praktik istifadə nümunələrinə baxaq. Nümunələr tipik ssenariləri nümayiş etdirir: profil ekranı üçün məlumatların yüklənməsi (query), yeni postun yaradılması (mutation) və yeni şərhlərə abunə olma (subscription). Hər bir nümunə həm GraphQL sorğusunu, həm də müştəri tərəfində kodu ehtiva edir.

Query: profil və postların yüklənməsi

Bir GraphQL sorğusu istifadəçini, onun son postlarını və izləyicilərin ümumi sayını yükləyir. REST-də bunun üçün ən azı 2-3 sorğu tələb olunardı: /users/42, /users/42/posts, /users/42/stats. GraphQL onları bir round-trip-də birləşdirərək yavaş əlaqələrdə ekran yükləmə vaxtını qısaldır.

// GraphQL sorğusu (.graphql faylında)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Müştəri tərəfində çağırış (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: yeni postun yaradılması

Mutasiya nəinki resurs yaradır, həm də UI-ni yeniləmək üçün onun aktual məlumatlarını qaytarır. __typename sahəsi Apollo Client tərəfindən keşin normallaşdırılması üçün istifadə olunur — müştəri mutasiyanın uğurlu cavabından sonra keşdə Post qeydini avtomatik yeniləyir.

// GraphQL mutasiyası
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Input-tipi ilə mutasiyanın çağırışı
val input = CreatePostInput(
    title = "GraphQL haqqında yeni post",
    content = "GraphQL API ilə işi asanlaşdırır..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

GraphQL-in mobil inkişaf kontekstində REST-dən mühüm üstünlüyü avtomatik kod yaradılmasıdır. Kotlin üçün Apollo Client (Apollo GraphQL) qurma mərhələsində .graphql fayllarından tip təhlükəsiz siniflər yaradır. Server sxemi dəyişərsə, layihə sorğular yenilənənə qədər qurulmayacaq. Bu, REST-ə xas olan, cavab strukturunun dəyişməsinin işlənmə zamanı fərq edilmədiyi iş vaxtı səhvlərinin qarşısını alır.

Ekosistem: Apollo, Relay və alətlər

GraphQL ekosistemi inkişaf və istismarı asanlaşdıran bir neçə əsas kitabxana və aləti əhatə edir. Apollo Client — React, iOS, Android və Kotlin Multiplatform-u dəstəkləyən ən populyar müştəri kitabxanasıdır. Facebook-un Relay məhsulu — məlumat idarəetmə və keşləməyə unikal yanaşması ilə React tətbiqləri üçün alternativdir. Apollo və Relay arasında seçim platformadan və performans tələblərindən asılıdır.

Server tərəfində Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) və graphql-ruby liderlik edir. Sxemin hazırlanması və sorğuların test edilməsi üçün GraphiQL — brauzerə daxil edilmiş interaktiv IDE istifadə olunur. Apollo Studio istehsal mühiti üçün performans metrikaları, sorğu izləmə və sxem idarəetmə təmin edir. Ayrıca GraphQL Code Generator — SDL sxemindən TypeScript, Kotlin, Swift və Dart tipləri yaradan aləti qeyd etmək lazımdır.

Mobil inkişaf üçün xüsusi maraq doğuran Apollo Kotlin (Apollo GraphQL) — tamamilə Kotlin-də korutin, Flow və Multiplatform dəstəyi ilə yazılmış kitabxanadır. O, Kotlin Multiplatform layihələrində Android və iOS üçün vahid GraphQL sorğularından istifadə etməyə imkan verir. Apollo Kotlin keşi normallaşdırır, sahə səviyyəsində səhvləri (partial errors) dəstəkləyir və .graphql fayllarından avtomatik məlumat modelləri yaradır. Bu, GraphQL-i inkişaf sürəti və tip təhlükəsizliyinin vacib olduğu böyük mobil layihələr üçün üstünlük təşkil edən seçim halına gətirir.