GraphQL — nedir, sorgu dili ve mobil projelerde uygulanmasİ1

GraphQL nedir?

GraphQL — API'ler için bir spesifikasyon ve çalİ1Şfma zamanİ1dİ1r ve istemciye aldİ1ğİ1 veriler üzerinde tam kontrol sağlar. News Feed mobil uygulamasİ1nİ1n sorunlarİ1nİ1 çözmek için Facebook mühendisleri tarafİ1ndan geliŞftirilen spesifikasyon, 2015'te açİ1k standart olarak yayİ1nlanmİ1Şftİ1r. 2018'den bu yana GraphQL, Linux Foundation ve Apollo, AWS, GitHub, SAP gibi Şfirketlerin desteğiyle GraphQL Foundation tarafİ1ndan yönetilmektedir.

Her endpoint'in sabit bir veri yapİ1sİ1 döndürdüğü REST'in aksine, GraphQL bir sorgu dizesini kabul eden tek bir endpoint kullanİ1r. İ0stemci sorguda hangi alanlara ihtiyacİ1 olduğunu tanİ1mlar ve sunucu tam olarak bunlarİ1 döndürür. Örneğin, { user(id: "1") { name email } } sorgusu yalnİ1zca kullanİ1cİ1nİ1n adİ1nİ1 ve e-postasİ1nİ1 döndürür, REST'te alİ1nmasİ1 gereken address, phone veya createdAt gibi ek alanlar olmadan.

GraphQL belirli bir veritabanİ1na veya dile bağlİ1 değildir. Spesifikasyon yalnİ1zca sorgu ve yanİ1t biçimini tanİ1mlar. Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) ve diğer dillerde sunucu uygulamalarİ1 mevcuttur. iOS, Android ve web için Apollo Client dahil olmak üzere tüm ana platformlarda istemci kütüphaneleri mevcuttur.

GraphQL nasİ1l çalİ1Şfİ1r

GraphQL mimarisi üç temel bileŞfenden oluŞfur: Şeema (Schema), Çözümleyiciler (Resolvers) ve GraphQL Motoru (GraphQL Engine). Şeema, hangi veri türlerinin mevcut olduğunu, hangi sorgularİ1n yürütülebileceğini ve hangi argümanlarİ1 kabul ettiklerini tanİ1mlar. Çözümleyiciler, her Şfema alanİ1 için veri döndüren sunucu tarafİ1 iŞflevlerdir. Motor, gelen sorguyu alİ1r, Şfemaya karŞfİ1 doğrular, uygun çözümleyicileri çağİ1rİ1r ve yanİ1tİ1 birleŞftirir.

Sorgu iŞfleme süreci Şföyledir:

• İ0stemci JSON gövdesi { "query": "..." } ile /graphql'e POST isteği gönderir
• Sunucu sorguyu ayrİ1Şftİ1rİ1r, bir AST (Soyut Sözdizimi Ağacİ1) oluŞfturur ve Şfemaya karŞfİ1 doğrular
• Motor AST'yi dolaŞfİ1r, her alan için çözümleyicileri çağİ1rarak veri toplar
• Yanİ1t JSON biçiminde döndürülür ve sorgu yapİ1sİ1yla kesin olarak eŞfleŞfir

GraphQL mimarisinin temel avantajİ1 alan düzeyinde çözümlemedir. REST'te geliŞftirici bir kaynağİ1n tüm alanlarİ1nİ1 (muhtemelen fazlalİ1klarla) alİ1r veya ?fields=name,email gibi uzantİ1lara baŞfvurur. GraphQL'de bu filtreleme dile yerleŞfiktir: her sorgu hangi alanlarİ1n gerekli olduğunu açİ1kça belirtir ve sunucu tam olarak bunlarİ1 döndürür. Bu, aktarİ1lan veri miktarİ1nİ1n yükleme hİ1zİ1nİ1 ve veri kullanİ1mİ1nİ1 doğrudan etkilediği mobil uygulamalar için özellikle önemlidir.

Query, Mutation ve Subscription

GraphQL üç tür iŞflem tanİ1mlar ve her biri belirli bir etkileŞfim senaryosuna karŞfİ1lİ1k gelir. Query — veri okuma için, REST'teki GET'e benzer. Mutation — veri değiŞftirme için (oluŞfturma, güncelleme, silme), POST/PUT/DELETE'e benzer. Subscription — WebSocket üzerinden gerçek zamanlİ1 güncellemeler için, klasik REST'te doğrudan bir benzeri yoktur (WebSocket veya Server-Sent Events gibi ek çözümler gerektirir).

Temel sorgu sözdizimi sezgiseldir:

// Argümanlİ1 basit sorgu
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// DeğiŞftirilmiŞf verileri döndüren Mutation
mutation {
    updateProfile(name: "İ0van") {
        id
        name
        updatedAt
    }
}

// Subscription — gerçek zamanlİ1 güncellemeleri dinler
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query paralel olarak yürütülür — aynİ1 düzeydeki tüm alanlar aynİ1 anda yüklenir. Bu, birden çok round-trip olmadan tek bir istekle ilgili verileri (kullanİ1cİ1 ve gönderileri) yüklemeye olanak tanİ1r. Mutation sİ1ralİ1 olarak yürütülür — bir istekteki mutasyonlar bildirim sİ1rasİ1na göre birer birer yürütülür. Subscription WebSocket üzerinden kalİ1cİ1 bir bağlantİ1 kurar ve sunucu bir olay meydana geldiğinde veri gönderir.

İ0Şflemler, veriyi sorgudan ayİ1rmak için değiŞfkenler, koŞfullu alan ekleme için yönergeler (@include, @skip) ve alan kümelerini yeniden kullanmak için parçalar kabul edebilir. Bu yetenekler GraphQL sorgularİ1nİ1 esnek ve yeniden kullanİ1labilir kİ1lar; bu, birçok ekran ve bileŞfene sahip büyük projelerde özellikle önemlidir.

GraphQL Şfemasİ1 ve tip sistemi

GraphQL'in merkezinde, tüm olasİ1 verileri ve API iŞflemlerini tanİ1mlayan bir tip sistemi vardİ1r. Şeema, sunucunun döndürebileceği türlerin ve kabul ettiği sorgularİ1n bir açİ1klamasİ1dİ1r. Şeema, Schema Definition Language (SDL) ile yazİ1lİ1r ve istemci ile sunucu arasİ1nda bir sözleŞfme görevi görür. İ0stemci, içgözlem (introspection) yoluyla Şfemayİ1 elde edebilir — API'nin tam açİ1klamasİ1nİ1 döndüren özel bir __schema sorgusu.

Bir blog için Şfema örneği:

// 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!]!
}

Ünlem iŞfareti (!) boŞf olmayan bir alanİ1 belirtir — yanİ1tta bulunmasİ1 garantilidir. KöŞfeli parantezler [ ] bir listeyi belirtir. GraphQL skaler türleri (Int, Float, String, Boolean, ID), nesne türleri, enum, union, interface ve giriŞf türlerini (mutasyon argümanlarİ1 için) destekler. Katİ1 tipleme API'yi kendi kendine belgeler hale getirir ve istemci araçlarİ1nİ1n kod oluŞfturmasİ1na olanak tanİ1r: TypeScript türleri, Kotlin veri sİ1nİ1flarİ1, Swift yapİ1larİ1.

İ0çgözlem (Introspection) REST'te bulunmayan benzersiz bir GraphQL özelliğidir. İ0stemci, Şfemaya bir sorgu gönderebilir ve tüm türler, alanlar, argümanlar ve yönergeler hakkİ1nda tam bir açİ1klama alabilir. Bu, geliŞftiriciler için otomatik olarak belge ve otomatik tamamlama oluŞfturan GraphiQL ve Apollo Studio gibi araçlarİ1n temelidir. İ0çgözlem ayrİ1ca Şfemanİ1n beklenen yapİ1yla uyumluluğunu doğrulayan otomatik testler yazmaya da olanak tanİ1r.

GraphQL ve REST karŞfİ1laŞftİ1rmasİ1

GraphQL ve REST arasİ1ndaki seçim, bir API tasarlarken temel mimari kararlardan biridir. Her iki yaklaŞfİ1mİ1n da güçlü ve zayİ1f yönleri vardİ1r ve seçim, projenin özel gereksinimlerine bağlİ1dİ1r. REST basitlik ve evrensellikte kazanİ1rken, GraphQL esneklik ve sorgu verimliliğinde kazanİ1r. KarŞfİ1laŞftİ1rma tablosuna bakalİ1m.

GraphQL'in ana dezavantajİ1 önbellek karmaŞfİ1klİ1ğİ1dİ1r. REST'te HTTP önbelleklemesi URL düzeyinde çalİ1Şfİ1r: /api/users/42'ye yapİ1lan bir istek her zaman aynİ1 yapİ1yİ1 döndürür ve yanİ1t URL'ye göre önbelleğe alİ1nabilir. GraphQL'de tüm istekler tek bir endpoint'e gider ve yanİ1t yapİ1sİ1 istek gövdesine bağlİ1dİ1r. Bu sorunu çözmek için Apollo Client, istemci tarafİ1nda normalleŞftirilmiŞf bir önbellek kullanİ1r, yanİ1tlarİ1 kimliğe göre ayrİ1 varlİ1klara böler ve yeni veri alİ1ndİ1ğİ1nda bunlarİ1 otomatik olarak günceller.

Bir diğer önemli husus N+1 sorunudur. İ0ç içe veriler (örneğin, kullanİ1cİ1nİ1n gönderileri ve her gönderiye yapİ1lan yorumlar) talep edildiğinde, GraphQL listedeki her öğe için ayrİ1 bir SQL sorgusu yürütebilir. Bu, DataLoader — bireysel istekleri tek bir toplu iŞfte gruplayan ve tek bir HTTP isteği içinde sonuçlarİ1 önbelleğe alan bir veritabanİ1 sorgu toplu iŞfleme ve önbellekleme aracİ1 kullanİ1larak çözülür. REST'te bu sorun daha az belirgindir çünkü geliŞftirici sunucu tarafİ1nda yanİ1t yapİ1sİ1nİ1 kontrol eder.

GraphQL sorgu örnekleri

Apollo Client ile bir Kotlin mobil uygulamasİ1nda GraphQL kullanİ1mİ1na iliŞfkin pratik örneklere bakalİ1m. Örnekler tipik senaryolarİ1 gösterir: profil ekranİ1 için veri yükleme (query), yeni bir gönderi oluŞfturma (mutation) ve yeni yorumlara abone olma (subscription). Her örnek hem GraphQL sorgusunu hem de istemci tarafİ1 kodunu içerir.

Query: Gönderilerle profil yükleme

Tek bir GraphQL sorgusu, kullanİ1cİ1yİ1, en son gönderilerini ve toplam takipçi sayİ1sİ1nİ1 yükler. REST'te bunun için en az 2-3 istek gerekirdi: /users/42, /users/42/posts, /users/42/stats. GraphQL bunlarİ1 tek bir round-trip'te birleŞftirir ve yavaŞf bağlantİ1larda ekran yükleme süresini azaltİ1r.

// GraphQL sorgusu (.graphql dosyasİ1nda)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// İ0stemcide çağrİ1 (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: Yeni bir gönderi oluŞfturma

Mutasyon yalnİ1zca bir kaynak oluŞfturmakla kalmaz, aynİ1 zamanda kullanİ1cİ1 arayüzünü güncellemek için mevcut verilerini de döndürür. __typename alanİ1, Apollo Client tarafİ1ndan önbellek normalleŞftirmesi için kullanİ1lİ1r — istemci, baŞfarİ1lİ1 bir mutasyon yanİ1tİ1nda önbellekteki Post kaydİ1nİ1 otomatik olarak günceller.

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

// input türüyle mutasyon çağrİ1sİ1
val input = CreatePostInput(
    title = "GraphQL hakkİ1nda yeni gönderi",
    content = "GraphQL API ile çalİ1Şfmayİ1 basitleŞftirir..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Mobil geliŞftirme bağlamİ1nda REST'e göre GraphQL'in önemli bir avantajİ1 otomatik kod oluŞfturmadİ1r. Kotlin için Apollo Client (Apollo GraphQL), derleme zamanİ1nda .graphql dosyalarİ1ndan tür güvenli sİ1nİ1flar oluŞfturur. Sunucu Şfemayİ1 değiŞftirirse, sorgular güncellenene kadar proje derlenmez. Bu, yanİ1t yapİ1sİ1ndaki değiŞfikliklerin geliŞftirme sİ1rasİ1nda fark edilmeyebileceği REST'te tipik olan çalİ1Şfma zamanİ1 hatalarİ1nİ1 önler.

Ekosistem: Apollo, Relay ve araçlar

GraphQL ekosistemi, geliŞftirmeyi ve iŞfletmeyi basitleŞftiren birkaç temel kütüphane ve araç içerir. Apollo Client en popüler istemci kütüphanesidir ve React, iOS, Android ve Kotlin Multiplatform'u destekler. Facebook'un Relay'i, veri yönetimi ve önbelleğe benzersiz bir yaklaŞfİ1mla React uygulamalarİ1 için bir alternatiftir. Apollo ve Relay arasİ1ndaki seçim, platforma ve performans gereksinimlerine bağlİ1dİ1r.

Sunucu tarafİ1nda liderler Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) ve graphql-ruby'dir. Şeema geliŞftirme ve sorgu testi için, tarayİ1cİ1ya yerleŞfik etkileŞfimli bir IDE olan GraphiQL kullanİ1lİ1r. Apollo Studio, üretim ortamlarİ1 için performans metrikleri, sorgu izleme ve Şfema yönetimi sağlar. Ayrİ1ca belirtilmesi gereken GraphQL Code Generator — bir SDL Şfemasİ1ndan TypeScript, Kotlin, Swift ve Dart türleri oluŞfturan bir araçtİ1r.

Mobil geliŞftirme için Apollo Kotlin (Apollo GraphQL) özellikle ilgi çekicidir — coroutine, Flow ve Multiplatform desteğiyle tamamen Kotlin'de yazİ1lmİ1Şf bir kütüphanedir. Kotlin Multiplatform projelerinde Android ve iOS için birleŞfik GraphQL sorgularİ1 kullanİ1lmasİ1na olanak tanİ1r. Apollo Kotlin önbelleği normalleŞftirir, alan düzeyinde hatalarİ1 (kİ1smi hatalar) destekler ve .graphql dosyalarİ1ndan otomatik olarak veri modelleri oluŞfturur. Bu, geliŞftirme hİ1zİ1 ve tür güvenliğinin önemli olduğu büyük mobil projeler için GraphQL'i tercih edilen seçenek haline getirir.