Blog

GraphQL Codegen Kullanımı: Yeni Başlayanlar İçin Kılavuz

Maurice Odida

Maurice Odida

20 June 2025

GraphQL Codegen Kullanımı: Yeni Başlayanlar İçin Kılavuz

Web geliştirmenin sürekli gelişen ortamında, GraphQL, geleneksel REST API'lerine güçlü bir alternatif olarak ortaya çıkmış ve istemcilere tam olarak ihtiyaç duydukları veriyi talep etme yeteneği sunmuştur. Ancak bu esneklik, özellikle ön uç ile arka uç arasındaki tip güvenliğini sürdürme konusunda yeni bir dizi zorluk getirebilir. İşte tam bu noktada graphql-codegen devreye giriyor; GraphQL şemanızdan tip tanımlı kodların otomatik olarak oluşturulmasını sağlayan, geliştirme iş akışınızı süper şarj eden ve bir dizi çalışma zamanı hatasını ortadan kaldıran devrim niteliğinde bir araç.

Bu makale, graphql-codegen'ı anlamak ve ustalaşmak için rehberiniz olacaktır. Temel kavramlarla başlayacak, aracın kurulumu ve yapılandırılmasına ilişkin pratik, adım adım bir örnek üzerinde ilerleyecek ve projelerinize entegre etmek için en iyi uygulamaları keşfedeceğiz. Bu rehberin sonunda, daha sağlam, sürdürülebilir ve tip güvenli uygulamalar oluşturmak için graphql-codegen'dan yararlanma yeteneğine sahip olacaksınız.

💡
Harika API Dokümantasyonu oluşturan harika bir API Test aracı mı istiyorsunuz?

Geliştirici Ekibinizin maksimum üretkenlikle birlikte çalışması için entegre, Hepsi Bir Arada bir platform mu istiyorsunuz?

Apidog tüm taleplerinizi karşılar ve Postman'ı çok daha uygun bir fiyata değiştirir!
button

graphql-codegen Nedir ve Neden İhtiyacınız Var?

Özünde, graphql-codegen, GraphQL şemanızı ve GraphQL operasyonlarınızı (sorgular, mutasyonlar ve abonelikler) inceleyen ve çeşitli dillerde kod üreten bir komut satırı aracıdır. Bu başlangıç rehberi için, en popüler kullanım durumuna odaklanacağız: ön uç uygulamaları için TypeScript tipleri ve hook'ları üretmek.

graphql-codegen'ın çözdüğü temel sorun, GraphQL API'nizin veri yapıları ve sorgularınızın sonuçları için TypeScript arayüzlerini manuel olarak yazmanın sıkıcı ve hataya açık sürecidir. Bu araç olmadan geliştiriciler, ya tip tanımlı olmayan verilerle çalışmak (TypeScript'in avantajlarını kaybetmek) ya da API geliştikçe kolayca güncelliğini yitirebilecek tipleri oluşturmak ve sürdürmek için önemli zaman harcamak zorunda kalırlar.

graphql-codegen'ı benimsemenin faydaları çoktur:

Bu yaklaşım, GraphQL şemasının API'nizin tek doğru kaynağı olarak hizmet ettiği "şema öncelikli" geliştirme felsefesiyle mükemmel bir şekilde uyumludur.

Başlarken: İlk graphql-codegen Kurulumunuz

graphql-codegen kullanmanın pratik yönlerine dalalım. Bu eğitim için, GraphQL, TypeScript hakkında temel bir anlayışa sahip olduğunuzu ve Node.js ile bir paket yöneticisinin (npm veya yarn gibi) kurulu olduğunu varsayacağız.

Amacımız, bir blog yazıları listesini görüntüleyen basit bir React uygulaması için graphql-codegen'ı kurmaktır.

Adım 1: Proje Başlatma ve Bağımlılıklar

İlk olarak, TypeScript ile yeni bir React projesi oluşturalım ve gerekli bağımlılıkları kuralım.Bash

npx create-react-app my-blog --template typescript
cd my-blog
npm install @apollo/client graphql
npm install -D @graphql-codegen/cli @graphql-codegen/client-preset typescript

Kurduğumuz bağımlılıkların bir dökümü aşağıdadır:

Adım 2: graphql-codegen Başlatma Sihirbazı

graphql-codegen ile başlamanın en kolay yolu, başlatma sihirbazını kullanmaktır. Projenizin kök dizininde aşağıdaki komutu çalıştırın:Bash

npx graphql-codegen init

Sihirbaz, projenizi yapılandırmanıza yardımcı olmak için bir dizi soru soracaktır. Blog uygulaması senaryomuz için tipik bir yanıt seti aşağıdadır:

Bu soruları yanıtladıktan sonra sihirbaz, projenizin kökünde bir codegen.ts dosyası oluşturacak ve package.json dosyanıza bir codegen scripti ekleyecektir.

Adım 3: Yapılandırma Dosyasını (codegen.ts) Anlamak

codegen.ts dosyası, graphql-codegen kurulumunuzun kalbidir. Sihirbazın ürettiği basitleştirilmiş bir versiyona göz atalım:TypeScript

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  overwrite: true,
  schema: "https://swapi-graphql.netlify.app/.netlify/functions/index",
  documents: "src/**/*.tsx",
  generates: {
    "src/gql/": {
      preset: "client",
      plugins: []
    }
  }
};

export default config;

Temel yapılandırma seçeneklerini inceleyelim:

Adım 4: İlk GraphQL Sorgunuzu Yazmak

graphql-codegen yapılandırıldığına göre, blog yazılarımızı çekmek için bir GraphQL sorgusu yazalım. Yeni bir dosya oluşturun src/components/Posts.tsx:TypeScript

import { gql } from '../gql/gql';
import { useQuery } from '@apollo/client';

const GET_POSTS = gql(`
  query GetPosts {
    allFilms {
      films {
        id
        title
        director
        releaseDate
      }
    }
  }
`);

const Posts = () => {
  const { loading, error, data } = useQuery(GET_POSTS);

  if (loading) return <p>Yükleniyor...</p>;
  if (error) return <p>Hata :( </p>;

  return (
    <div>
      {data?.allFilms?.films?.map((film) => (
        <div key={film?.id}>
          <h2>{film?.title}</h2>
          <p>Yönetmen: {film?.director}</p>
          <p>Yayın Tarihi: {film?.releaseDate}</p>
        </div>
      ))}
    </div>
  );
};

export default Posts;

Üretilen src/gql/gql.ts dosyasından bir gql fonksiyonu içe aktardığımıza dikkat edin. Bu, client-preset tarafından sağlanan gql fonksiyonudur ve tip çıkarımının sihrini mümkün kılan budur.

Adım 5: graphql-codegen'ı Çalıştırmak ve Sihri Görmek

Şimdi, package.json dosyanızdan codegen scriptini çalıştırın:Bash

npm run codegen

Bu komut, şemayı inceleyecek, GET_POSTS sorgunuzu bulacak ve ilgili TypeScript tiplerini src/gql dizininde üretecektir.

Şimdi Posts.tsx dosyasındaki useQuery hook'u tarafından döndürülen data nesnesini incelerseniz, tamamen tip tanımlı olduğunu göreceksiniz! IDE'niz data.allFilms.films için otomatik tamamlama sağlayacak ve sorguda var olmayan bir alana erişmeye çalışırsanız TypeScript sizi uyaracaktır.

Daha Derin Bir Bakış: Pratik Bir Blog Ön Uç Örneği

Anlayışınızı pekiştirmek için örneğimizi genişletelim. Blogumuzun daha geleneksel bir şeması olduğunu hayal edin:GraphQL

type Author {
  id: ID!
  name: String!
}

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

type Query {
  posts: [Post!]!
  post(id: ID!): Post
}

type Mutation {
  createPost(title: String!, content: String!, authorId: ID!): Post!
}

Bu şemanın http://localhost:4000/graphql adresinde çalıştığını varsayalım. codegen.ts dosyamızı buna göre güncelleyeceğiz:TypeScript

// codegen.ts
// ...
schema: "http://localhost:4000/graphql",
// ...

Şimdi, tek bir gönderiyi görüntülemek için bir bileşen ve yeni bir tane oluşturmak için başka bir bileşen oluşturalım.

Tek Bir Gönderiyi ÇekmeTypeScript

// src/components/Post.tsx
import { gql } from '../gql/gql';
import { useQuery } from '@apollo/client';
import { useParams } from 'react-router-dom';

const GET_POST = gql(`
  query GetPost($id: ID!) {
    post(id: $id) {
      id
      title
      content
      author {
        id
        name
      }
    }
  }
`);

const Post = () => {
  const { id } = useParams<{ id: string }>();
  const { loading, error, data } = useQuery(GET_POST, {
    variables: { id },
  });

  if (loading) return <p>Yükleniyor...</p>;
  if (error) return <p>Hata :( </p>;

  return (
    <div>
      <h2>{data?.post?.title}</h2>
      <p>Yazar: {data?.post?.author?.name}</p>
      <p>{data?.post?.content}</p>
    </div>
  );
};

export default Post;

npm run codegen komutunu çalıştırdıktan sonra, GetPostQuery ve değişkenleri için tipler üretilecek ve useQuery hook'u ve sonucu için tip güvenliği sağlanacaktır.

Yeni Bir Gönderi OluşturmaTypeScript

// src/components/CreatePost.tsx
import { gql } from '../gql/gql';
import { useMutation } from '@apollo/client';
import { useState } from 'react';

const CREATE_POST = gql(`
  mutation CreatePost($title: String!, $content: String!, $authorId: ID!) {
    createPost(title: $title, content: $content, authorId: $authorId) {
      id
    }
  }
`);

const CreatePost = () => {
  const [title, setTitle] = useState('');
  const [content, setContent] = useState('');
  const [createPost, { data, loading, error }] = useMutation(CREATE_POST);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    createPost({ variables: { title, content, authorId: '1' } }); // Basitlik için authorId '1' varsayılıyor
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        placeholder="Başlık"
        value={title}
        onChange={(e) => setTitle(e.target.value)}
      />
      <textarea
        placeholder="İçerik"
        value={content}
        onChange={(e) => setContent(e.target.value)}
      />
      <button type="submit" disabled={loading}>
        {loading ? 'Oluşturuluyor...' : 'Gönderi Oluştur'}
      </button>
      {error && <p>Gönderi oluşturma hatası: {error.message}</p>}
      {data && <p>Gönderi ID'si ile oluşturuldu: {data.createPost.id}</p>}
    </form>
  );
};

export default CreatePost;

Burada, graphql-codegen, CreatePostMutation ve değişkenleri için tipleri üretir. Bu, createPost fonksiyonunu çağırdığınızda title, content ve authorId için doğru tipleri geçtiğinizden emin olmanızı sağlar.

İleri Kavramlar ve En İyi Uygulamalar

graphql-codegen ile daha rahat hale geldikçe, daha gelişmiş özellikler ve en iyi uygulamalarla karşılaşacaksınız:

Fragmentler: graphql-codegen, GraphQL fragmentleri için mükemmel desteğe sahiptir. Fragmentleri .tsx dosyalarınızda tanımlayabilirsiniz ve graphql-codegen tipleri doğru şekilde işleyerek bileşenleriniz için yeniden kullanılabilir ve birlikte konumlandırılmış veri bağımlılıklarını teşvik eder.

.graphql Dosyalarını Kullanma: Sorumlulukların daha iyi ayrılması için GraphQL sorgularınızı, mutasyonlarınızı ve fragmentlerinizi özel .graphql dosyalarına yazabilirsiniz. Sadece codegen.ts dosyanızdaki documents dizisini bu dosya uzantısını içerecek şekilde güncelleyin: documents: ["src/**/*.tsx", "src/**/*.graphql"].

Özel Scalar'lar: GraphQL şemanız özel scalar'lar kullanıyorsa (örneğin, Date, JSON), tip güvenliğini korumak için bunları codegen.ts dosyanızdaki karşılık gelen TypeScript tiplerine eşleyebilirsiniz.

Watch Modu: Sorunsuz bir geliştirme deneyimi için graphql-codegen'ı watch modunda çalıştırabilirsiniz. Bu, GraphQL operasyonu içeren bir dosyayı her kaydettiğinizde tiplerinizi otomatik olarak yeniden oluşturacaktır. Sadece package.json dosyanızdaki codegen scriptinize bir --watch bayrağı ekleyin: "codegen": "graphql-codegen --watch".

Yaygın Sorunları Giderme

graphql-codegen güçlü bir araç olsa da, başlangıç seviyesinde birkaç yaygın sorunla karşılaşabilirsiniz:

Sonuç: Tip Güvenli Geleceği Kucaklayın

graphql-codegen sadece bir kod üretim aracından daha fazlasıdır; GraphQL ile uygulama geliştirme şeklimizde bir paradigma değişikliğidir. Otomasyonu benimseyerek ve şemanızın gücünden yararlanarak, daha sağlam, sürdürülebilir ve çalışması keyifli kod tabanları oluşturabilirsiniz.

Bu eğitim, graphql-codegen ile başlamak için size sağlam bir temel sağlamıştır. Temel kavramları ele aldık, pratik bir örnek üzerinden geçtik ve en iyi uygulamalara değindik. Yolculuk burada bitmiyor. graphql-codegen ekosistemi geniştir ve çeşitli framework'lere ve kullanım durumlarına hitap eden zengin bir eklenti koleksiyonuna sahiptir. Resmi dokümantasyonu keşfetmenizi, farklı eklentilerle denemeler yapmanızı ve graphql-codegen'ın GraphQL geliştirme iş akışınızı nasıl devrim yaratabileceğini keşfetmenizi öneririm. Mutlu kodlamalar!

💡
Harika API Dokümantasyonu oluşturan harika bir API Test aracı mı istiyorsunuz?

Geliştirici Ekibinizin maksimum üretkenlikle birlikte çalışması için entegre, Hepsi Bir Arada bir platform mu istiyorsunuz?

Apidog tüm taleplerinizi karşılar ve Postman'ı çok daha uygun bir fiyata değiştirir!
button

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir