Intro to GraphQL in React Using React Apollo & Apollo Boost
Giriş
Modern web uygulamaları, kullanıcılarına zengin ve dinamik deneyimler sunmak için sürekli olarak daha verimli ve esnek veri alışverişi yöntemlerine ihtiyaç duyar. Bu bağlamda, Facebook tarafından geliştirilen GraphQL, API geliştirmeye ve kullanmaya yönelik devrim niteliğinde bir yaklaşım sunmaktadır. Geleneksel REST mimarisine kıyasla daha güçlü ve esnek bir alternatif olarak ortaya çıkan GraphQL, özellikle React gibi component tabanlı kullanıcı arayüzü kütüphaneleriyle birleştiğinde, geliştiricilere eşsiz bir verimlilik ve kontrol sağlar.
Bu makalede, React uygulamalarınızda GraphQL’i nasıl kullanacağınızı, özellikle de Apollo Client ekosistemini (React Apollo ve Apollo Boost’un modern karşılığı olan @apollo/client paketi) derinlemesine inceleyeceğiz. GraphQL’in temel prensiplerinden başlayarak, bir React uygulamasında veri sorgulama, değiştirme ve hatta gerçek zamanlı güncellemeler yapma süreçlerini adım adım ele alacağız. Amacımız, bu güçlü teknolojileri bir araya getirerek modern ve performanslı React uygulamaları geliştirmek için sağlam bir temel oluşturmaktır.
GraphQL Nedir ve Neden Önemlidir?
GraphQL, API’ler için bir sorgulama dili ve çalışma zamanı ortamıdır. Geleneksel REST API’lerinin aksine, GraphQL ile istemci tam olarak hangi veriye ihtiyacı olduğunu belirtebilir ve sunucu da sadece o veriyi döndürür. Bu, under-fetching (gereğinden az veri çekme) ve over-fetching (gereğinden fazla veri çekme) gibi sorunları ortadan kaldırır.
* Under-fetching: REST API’lerinde, tek bir endpoint üzerinden istenen tüm veriler alınamayabilir. Örneğin, bir kullanıcının bilgilerini ve o kullanıcının tüm siparişlerini almak için iki ayrı istek yapmak gerekebilir.
* Over-fetching: Bir endpoint, istemcinin ihtiyacından daha fazla veri döndürebilir. Bu durum, özellikle mobil cihazlarda bant genişliği ve performans sorunlarına yol açabilir.
GraphQL, tek bir endpoint üzerinden, istemcinin belirttiği karmaşık veri yapılarını sorgulama yeteneği sunar. Bu, ağ isteklerinin sayısını azaltır, veri transferini optimize eder ve istemci tarafında veri işleme mantığını basitleştirir. Ayrıca, güçlü bir tip sistemi sayesinde API’nizin tüm yetenekleri ve veri yapısı net bir şekilde tanımlanır, bu da istemci ve sunucu arasında daha iyi bir iletişim ve hata ayıklama deneyimi sağlar.
Apollo Client Ekosistemi
React uygulamalarında GraphQL ile etkileşime girmek için birçok kütüphane bulunmaktadır. Bunlar arasında en popüler ve kapsamlı olanı Apollo Client’tır. Apollo Client, React uygulamalarında GraphQL sorguları, mutasyonları ve aboneliklerini yönetmek için bir dizi araç ve özellik sunar. Önbellekleme, durum yönetimi, hata yönetimi ve UI entegrasyonu gibi konularda geliştiricilere büyük kolaylıklar sağlar.
Başlangıçta Apollo Client kurulumu için apollo-boost adında bir paket mevcuttu. Bu paket, temel Apollo Client kurulumunu “sıfır konfigürasyon” yaklaşımıyla basitleştirmeyi amaçlıyordu. Ancak zamanla, Apollo Client’ın ana paketi olan @apollo/client, bu kolaylıkları kendi içine entegre etti ve apollo-boost paketi artık ayrı bir bağımlılık olarak kullanılmamaktadır. Günümüzde, @apollo/client paketi hem temel Apollo Client işlevselliğini hem de basit kurulum kolaylıklarını tek bir çatı altında sunmaktadır. Bu makalede de güncel yaklaşıma uygun olarak @apollo/client paketini kullanarak örnekler vereceğiz.
GraphQL Temelleri
React uygulamalarında GraphQL kullanmaya başlamadan önce, GraphQL’in temel yapı taşlarını anlamak önemlidir.
Schema (Şema) ve Type System (Tip Sistemi)
GraphQL’in kalbinde şema ve tip sistemi bulunur. Şema, API’nizin hangi verileri sorgulayabileceğinizi, değiştirebileceğinizi ve hangi tiplere sahip olduklarını tanımlayan bir sözleşmedir. Her GraphQL API’sinin bir şeması vardır. Bu şema, API’nin istemciye sunduğu tüm veri tiplerini, alanlarını ve operasyonlarını belirtir.
* Object Types (Nesne Tipleri): Uygulamanızdaki veri nesnelerini temsil eder. Örneğin, bir User veya Product tipi.
* Fields (Alanlar): Bir nesne tipinin sahip olduğu özelliklerdir. Örneğin, User tipinin id, name, email gibi alanları olabilir.
* Scalar Types (Skaler Tipler): Temel veri tipleridir (String, Int, Float, Boolean, ID).
* Enums (Numaralandırmalar): Belirli bir değer kümesinden birini alabilen tiplerdir.
* Input Types (Girdi Tipleri): Mutasyonlara gönderilen verilerin yapısını tanımlamak için kullanılır.
* Interface (Arayüz) ve Union (Birleşim): Polimorfik veri yapıları oluşturmak için kullanılır.
Örnek bir GraphQL şeması tanımı (sunucu tarafında):
type Product {
id: ID!
name: String!
description: String
price: Float!
category: Category
}
type Category {
id: ID!
name: String!
products: [Product]
}
type Query {
products: [Product]
product(id: ID!): Product
categories: [Category]
}
type Mutation {
addProduct(name: String!, description: String, price: Float!, categoryId: ID!): Product
updateProduct(id: ID!, name: String, description: String, price: Float, categoryId: ID): Product
deleteProduct(id: ID!): Boolean
}Bu şema, Product ve Category adında iki nesne tipi, bu tiplerin alanları ve Query ile Mutation operasyonlarının nasıl yapılacağını tanımlar. Query tipi veri okuma operasyonlarını, Mutation tipi ise veri yazma (oluşturma, güncelleme, silme) operasyonlarını temsil eder.
Query (Sorgu)
GraphQL’de veri okumak için sorgular kullanılır. İstemci, sunucudan tam olarak hangi alanlara ihtiyacı olduğunu belirterek bir sorgu gönderir.
query GetProductList {
products {
id
name
price
category {
name
}
}
}Bu sorgu, tüm ürünlerin id, name, price alanlarını ve ilişkili kategorinin name alanını isteyecektir.
Değişkenlerle sorgu yapmak:
query GetProductById($productId: ID!) {
product(id: $productId) {
id
name
description
price
}
}Bu sorgu, $productId değişkeni ile belirli bir ürünü getirir. ! işareti, değişkenin zorunlu olduğunu gösterir.
Mutation (Değişiklik)
Veri oluşturmak, güncellemek veya silmek için mutasyonlar kullanılır. Mutasyonlar, sorgulara benzer bir yapıya sahiptir ancak veri üzerinde bir değişiklik yapma amacı taşırlar.
mutation AddNewProduct($name: String!, $description: String, $price: Float!, $categoryId: ID!) {
addProduct(name: $name, description: $description, price: $price, categoryId: $categoryId) {
id
name
price
}
}Bu mutasyon, yeni bir ürün ekler ve eklenen ürünün id, name ve price alanlarını döndürür.
Subscription (Abonelik)
GraphQL abonelikleri, istemcinin sunucudan gerçek zamanlı güncellemeler almasını sağlar. Bir olay meydana geldiğinde (örneğin, yeni bir mesaj gönderildiğinde), sunucu istemciye veri gönderir. Bu genellikle WebSocket bağlantıları üzerinden gerçekleştirilir.
subscription OnProductAdded {
productAdded {
id
name
price
}
}Bu abonelik, her yeni ürün eklendiğinde productAdded olayını dinler ve eklenen ürünün bilgilerini alır.
Apollo Client Nedir?
Apollo Client, GraphQL API’leri ile etkileşim kurmak için kapsamlı bir istemci tarafı kütüphanesidir. React, Vue, Angular gibi çeşitli UI kütüphaneleriyle entegre olabilir. Temel özellikleri şunlardır:
* Veri Çekme ve Yönetimi: GraphQL sorgularını ve mutasyonlarını kolayca yapmanızı sağlar.
* Önbellekleme: Çekilen verileri otomatik olarak önbelleğe alır, böylece aynı veriler için tekrar ağ isteği yapılmasına gerek kalmaz. Bu, uygulamanın performansını önemli ölçüde artırır.
* Durum Yönetimi: Uygulamanızın yerel durumunu GraphQL verileriyle birlikte yönetmenizi sağlar.
* Hata Yönetimi: Ağ ve GraphQL hatalarını kolayca yakalamanızı ve işlemenizi sağlar.
* Gerçek Zamanlı Güncellemeler: Abonelikler aracılığıyla gerçek zamanlı veri akışını destekler.
* UI Entegrasyonu: React gibi UI kütüphaneleri için özel Hook’lar ve bileşenler sunar, bu da veri bağlamayı ve UI güncellemelerini basitleştirir.
Apollo Client, sadece bir veri çekme kütüphanesi olmanın ötesinde, uygulamanızın veri katmanını yönetmek için güçlü bir çözüm sunar.
React Apollo ve Apollo Boost Kurulumu
Modern React uygulamalarında Apollo Client kullanmak için @apollo/client paketini kurmanız yeterlidir. Bu paket, eski apollo-boost paketinin tüm kolaylıklarını ve Apollo Client’ın tüm gücünü birleştirir.
Gereksinimler
* Node.js ve npm/yarn kurulu olmalı.
* Yeni veya mevcut bir React projesi (Create React App veya Vite ile oluşturulmuş olabilir).
Kurulum Adımları
React projenizin kök dizininde aşağıdaki komutu çalıştırarak @apollo/client ve graphql paketlerini kurun:
npm install @apollo/client graphql
veya
yarn add @apollo/client graphqlgraphql paketi, sorguları ayrıştırmak (parse etmek) için gereklidir.
ApolloClient Örneği Oluşturma
Uygulamanızın src/index.js veya src/App.js dosyasında, bir ApolloClient örneği oluşturmanız gerekir. Bu örnek, GraphQL sunucunuzun adresini ve önbellekleme stratejilerini içerecektir.
// src/index.js veya src/App.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';
// GraphQL sunucunuzun URI'sini belirtin
const client = new ApolloClient({
uri: 'http://localhost:4000/graphql', // Kendi GraphQL sunucu adresinizle değiştirin
cache: new InMemoryCache(), // Önbellekleme için InMemoryCache kullanın
});
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
);ApolloProvider ile React Uygulamasına Entegrasyon
ApolloProvider bileşeni, ApolloClient örneğini React component ağacına sağlar. Bu sayede, altındaki tüm React bileşenleri useQuery, useMutation ve useSubscription gibi Apollo Hook’larına erişebilir. Uygulamanızın en üst seviyesinde (App bileşeninin sarmalayıcısı olarak) ApolloProvider‘ı kullanmak en yaygın yaklaşımdır.
Bu kurulumla birlikte, React uygulamanız artık GraphQL API’nizle iletişim kurmaya hazır hale gelmiştir.
GraphQL Sorguları Yapma (useQuery)
Apollo Client’ın useQuery Hook’u, React bileşenlerinizden GraphQL sorguları yapmanın birincil yoludur. Bu Hook, sorgunun durumunu (yükleniyor, hata var, veri geldi) yönetir ve bileşeninizi otomatik olarak günceller.
useQuery Hook’unun Kullanımı
useQuery Hook’u, bir GraphQL sorgu dizesi (template literal içinde) alır ve bir nesne döndürür. Bu nesne genellikle üç önemli özellik içerir: loading, error ve data.
import React from 'react';
import { gql, useQuery } from '@apollo/client';
// GraphQL sorgusunu tanımlayın
const GET_PRODUCTS = gql
query GetProducts {
products {
id
name
price
category {
name
}
}
}
;
function ProductsList() {
const { loading, error, data } = useQuery(GET_PRODUCTS);
if (loading) return Ürünler yükleniyor...
;
if (error) return Hata oluştu: {error.message}
;
return (
Ürün Listesi
{data.products.map(product => (
{product.name}
Fiyat: {product.price} TL
Kategori: {product.category?.name}
))}
);
}
export default ProductsList;Bu örnekte:
* GET_PRODUCTS sabiti, gql template literal etiketi kullanılarak GraphQL sorgusunu tanımlar. Bu etiket, sorguyu ayrıştırır ve Apollo Client’ın anlayabileceği bir formata dönüştürür.
* useQuery(GET_PRODUCTS) çağrısı, sorguyu yapar ve loading, error, data durumlarını döndürür.
* loading doğru olduğunda, bir yükleme mesajı gösterilir.
* error varsa, bir hata mesajı gösterilir.
* data geldiğinde, ürün listesi render edilir.
Değişkenlerle Sorgu Yapma
Sorgulara dinamik değerler göndermek için variables seçeneğini kullanabilirsiniz.
import React from 'react';
import { gql, useQuery } from '@apollo/client';
const GET_PRODUCT_BY_ID = gql
query GetProductById($productId: ID!) {
product(id: $productId) {
id
name
description
price
}
}
;
function ProductDetail({ productId }) {
const { loading, error, data } = useQuery(GET_PRODUCT_BY_ID, {
variables: { productId }, // productId değişkenini gönderiyoruz
});
if (loading) return Ürün detayı yükleniyor...
;
if (error) return Hata oluştu: {error.message}
;
if (!data.product) return Ürün bulunamadı.
;
const { product } = data;
return (
{product.name}
{product.description}
Fiyat: {product.price} TL
);
}
export default ProductDetail;Burada, productId prop’u variables nesnesi aracılığıyla GraphQL sorgusuna iletilir.
fetchPolicy ve Önbellekleme Stratejileri
Apollo Client, güçlü bir önbelleğe alma mekanizmasına sahiptir. useQuery Hook’una fetchPolicy seçeneğini ileterek bu önbelleğin nasıl kullanılacağını kontrol edebilirsiniz:
* cache-first (varsayılan): Önce önbelleğe bakar. Veri varsa onu döndürür. Yoksa ağı kullanır ve sonucu önbelleğe alır.
* network-only: Önbelleği tamamen atlar ve her zaman ağdan veri çeker.
* cache-and-network: Önce önbellekten veriyi döndürür, ardından ağı kullanarak güncel veriyi çeker ve önbelleği günceller.
* no-cache: Önbelleği kullanmaz ve ağdan gelen veriyi önbelleğe almaz.
* standby: Sorguyu çalıştırmaz, ancak diğer sorgular tarafından tetiklenebilir.
const { loading, error, data } = useQuery(GET_PRODUCTS, {
fetchPolicy: 'network-only', // Her zaman ağdan çek
});GraphQL Mutasyonları Yapma (useMutation)
useMutation Hook’u, GraphQL API’nizde veri oluşturmak, güncellemek veya silmek için kullanılır. useQuery gibi, loading, error durumlarını ve mutasyonu tetikleyecek bir fonksiyonu döndürür.
useMutation Hook’unun Kullanımı
useMutation Hook’u, bir GraphQL mutasyon dizesi alır ve bir dizi döndürür: ilk öğe mutasyon fonksiyonu, ikinci öğe ise mutasyonun durumunu içeren bir nesnedir.
import React, { useState } from 'react';
import { gql, useMutation } from '@apollo/client';
const ADD_PRODUCT = gql
mutation AddProduct($name: String!, $description: String, $price: Float!, $categoryId: ID!) {
addProduct(name: $name, description: $description, price: $price, categoryId: $categoryId) {
id
name
price
}
}
;
// Ürün listesini güncelleyebilmek için GET_PRODUCTS sorgusunu da alalım
import { GET_PRODUCTS } from './ProductsList'; // ProductsList bileşeninde tanımladığımız sorgu
function AddProductForm() {
const [name, setName] = useState('');
const [description, setDescription] = useState('');
const [price, setPrice] = useState('');
const [categoryId, setCategoryId] = useState('');
const [addProduct, { loading, error }] = useMutation(ADD_PRODUCT, {
// Mutasyon başarılı olduğunda önbelleği güncelleme stratejisi
update(cache, { data: { addProduct } }) {
// Önbellekteki GET_PRODUCTS sorgusunun sonucunu oku
const existingProducts = cache.readQuery({ query: GET_PRODUCTS });
// Yeni ürünü mevcut ürün listesine ekle
cache.writeQuery({
query: GET_PRODUCTS,
data: { products: [...existingProducts.products, addProduct] },
});
},
// Veya daha basit: mutasyon sonrası belirli sorguları yeniden çek
// refetchQueries: [{ query: GET_PRODUCTS }],
});
const handleSubmit = async (e) => {
e.preventDefault();
try {
await addProduct({
variables: {
name,
description,
price: parseFloat(price),
categoryId,
},
});
alert('Ürün başarıyla eklendi!');
// Formu temizle
setName('');
setDescription('');
setPrice('');
setCategoryId('');
} catch (err) {
console.error("Ürün eklenirken hata oluştu:", err);
}
};
return (