Runtime

Runtime doğrulama, domain ve API kararlarının gerçek sorgu kullanımı altında beklendiği gibi davranıp davranmadığını teyit eder. Modelinin tasarımdan yürütmeye geçtiği katmandır — ve tüketicilerinden önce sorunları yakaladığın yerdir.

Runtime'ın Amacı

Runtime, geliştirme sürecinde pratik soruları erken yanıtlar:

• Alan yapıları tahmin edilebilir ve tutarlı mı?
• İlişki aramaları tutarlı ve doğru iç içe yerleştirilmiş mi?
• Sayfalandırma ve sıralama varsayımları gerçek veriler altında geçerli mi?
• Filtre ifadeleri doğru kayıt alt kümesini eşliyor mu?
• Null değerler tüketicilerinin beklediği şekilde mi işleniyor?

Bu davranışları modelleme sırasında — uygulama sonrasında değil — doğrulayarak, bütün bir entegrasyon hata kategorisini ortadan kaldırırsın.

rt-01-query-playgroundMissing

Canlı davranış kontrolleri için runtime sorgu paneli.

Mock Runtime Nasıl Çalışır

Mock runtime motoru, Mockomat'ın çekirdeğini oluşturur. GraphQL sorgularını kabul eder ve dört aşamalı bir pipeline üzerinden MongoDB işlemlerine çevirir:

1. GraphQL Request Parser

Gelen sorgu dizesi soyut bir söz dizimi ağacına (AST) ayrıştırılır. Bu aşamada sorgu söz dizimi doğrulanır ve istenen alanlar, argümanlar ve iç içe seçimler çıkarılır.

2. Query Planner

AST, bir yürütme planı oluşturmak için model meta verilerinle (entity tanımları, attribute bayrakları, ilişki yapılandırmaları) birlikte analiz edilir. Planlayıcı şunları belirler:

• Hangi MongoDB koleksiyonlarının sorgulanacağı
• Hangi alanların yansıtılacağı
• Hangi filtre ve sıralama işlemlerinin uygulanacağı
• Hangi ilişkilerin çözümlenmesi gerektiği

3. MongoDB Query Builder

Yürütme planı bir MongoDB aggregation pipeline'ına çevrilir. MongoDB verileri düz (denormalize) koleksiyonlarda depoladığı için, query builder ilişkisel yapıyı simüle eder:

• Lookup aşamaları koleksiyonlar arası ilişkili verileri derler
• Match aşamaları filtre ifadelerini uygular
• Sort aşamaları sonuçları istenen alanlara göre sıralar
• Skip ve limit aşamaları sayfalandırmayı yönetir

4. Result Assembler

Ham MongoDB sonuçları, beklenen GraphQL yanıt yapısına uygun şekilde yeniden şekillendirilir. İç içe ilişkiler doğru üst-alt hiyerarşisine derlenir ve alan adları GraphQL karşılıklarına eşlenir.

Bu pipeline her sorguda çalışır. Önizlemede gördüğün, aynı endpoint'ten dış tüketicilerin aldığı şeyin tamamen aynısıdır.

rt-01b-runtime-pipelineMissing

Dört aşamalı runtime pipeline: ayrıştır → planla → oluştur → derle.

Sorgu Örnekleri

Tüm sorgular aynı endpoint'e gider:

POST /mock/{slug}/graphql

Liste Sorgusu

Sayfalandırılmış bir kayıt koleksiyonu getir:

query {
  products(offset: 0, limit: 20) {
    id
    name
    price
    category {
      id
      name
    }
  }
}

Detay Sorgusu

Tanımlayıcısına göre tek bir kayıt getir:

query {
  product(id: "abc-123") {
    id
    name
    price
    description
    category {
      id
      name
    }
  }
}

Filtreli Sorgu

Sonuçları daraltmak için filtre ifadeleri uygula:

query {
  products(
    filter: {
      filterGroup: {
        operator: AND
        items: [
          { attribute: "price", operator: GE, value: "10" }
          { attribute: "price", operator: LE, value: "50" }
        ]
      }
    }
    limit: 10
  ) {
    id
    name
    price
  }
}

Sıralamalı Sorgu

Sonuçları sortable bir alana göre sırala:

query {
  products(
    sort: { field: "price", direction: DESC }
    limit: 10
  ) {
    id
    name
    price
  }
}

İç İçe İlişkili Sorgu

İlişkili verileri dahil etmek için ilişkileri çaprazla:

query {
  customers(limit: 5) {
    id
    firstName
    lastName
    orders {
      id
      totalAmount
      createdAt
      items {
        id
        productName
        quantity
      }
    }
  }
}

Filtreleme Detayları

Filtre sistemi, boolean mantığı kullanılarak birleştirilebilen tip güvenli, kompoze edilebilir ifadeleri destekler.

Mevcut Operatörler

Operatör	Açıklama	Çalıştığı Türler
EQ	Eşittir	Tüm türler
NE	Eşit değildir	Tüm türler
LT	Küçüktür	Sayılar, Tarihler
GT	Büyüktür	Sayılar, Tarihler
LE	Küçük eşittir	Sayılar, Tarihler
GE	Büyük eşittir	Sayılar, Tarihler
LIKE	Alt dize içerir	String'ler
IS_NULL	Alan null	Tüm türler
IS_NOT_NULL	Alan null değil	Tüm türler

Filtreleri Birleştirme

Filtreler AND ve OR operatörleriyle boolean cebiri kullanır. Filtre grupları karmaşık ifadeler için iç içe yerleştirilebilir:

filter: {
  filterGroup: {
    operator: OR
    groups: [
      {
        operator: AND
        items: [
          { attribute: "status", operator: EQ, value: "active" }
          { attribute: "price", operator: GT, value: "100" }
        ]
      }
      {
        operator: AND
        items: [
          { attribute: "status", operator: EQ, value: "featured" }
        ]
      }
    ]
  }
}

Bu örnek, ya (aktif VE pahalı) YA DA öne çıkan ürünleri döndürür.

Filterable Alanlar

Yalnızca modelde filterable: true olarak işaretlenmiş attribute'lar filtre ifadelerinde kullanılabilir. Filterable olmayan bir alanı filtreleme girişimi etkisiz olacaktır. Filterable bayraklarını Workspace tablo düzenleyicisinde yapılandır.

Sayfalandırma

Mockomat offset tabanlı sayfalandırma kullanır:

Parametre	Açıklama	Varsayılan
offset	Atlanacak öğe sayısı	0
limit	Döndürülecek öğe sayısı	20

Tipik bir sayfalandırılmış istek:

query {
  products(offset: 40, limit: 20) {
    id
    name
    price
  }
}

Bu, 41-60 arasındaki öğeleri döndürür. Sonraki sayfayı getirmek için offset'i limit değeri kadar artır.

Sıralama

Modelde sortable: true olarak işaretlenmiş alanlar sonuçları sıralamak için kullanılabilir.

Yön	Anlam
ASC	Artan (A→Z, 0→9, eskiden→yeniye)
DESC	Azalan (Z→A, 9→0, yeniden→eskiye)

Sorgu başına yalnızca bir sıralama alanı uygulanabilir. Sıralama belirtilmezse sonuçlar doğal depolama sırasında döndürülür.

İlişki Geçişi

Runtime'ın en güçlü özelliklerinden biri, düz MongoDB koleksiyonlarından ilişkisel veriyi simüle edebilmesidir.

Nasıl Çalışır

MongoDB verileri denormalize koleksiyonlarda depolar — her kayıt yabancı anahtar birleştirmeleri olmayan düz bir belgedir. Runtime, ilişkisel yapıyı şu şekilde simüle eder:

1. Modelindeki ilişki tanımını okur (kaynak entity, hedef entity, kardinalite).
2. İlişkili koleksiyonları birleştiren MongoDB aggregation pipeline'ında lookup aşamaları oluşturur.
3. GraphQL yanıt yapısına uyan iç içe sonuçlar derler.

Bu, GraphQL sorgularının, altta yatan depolama belge tabanlı olsa da, tamamen ilişkisel bir veritabanına karşı çalışıyormuş gibi davrandığı anlamına gelir.

Neyi Doğrulamalı

İlişki geçişini test ederken:

• 1:1 ilişkiler tek bir iç içe nesne (veya eşleşme yoksa null) döndürmeli.
• 1:n ilişkiler bir iç içe nesne dizisi döndürmeli.
• Boş ilişkiler null değil, boş bir dizi [] döndürmeli.
• Derinden iç içe ilişkiler (örneğin Customer → Order → OrderItem) her düzeyinde doğru çözümlenmelidir.

Sorgu Davranışı Kontrol Listesi

Modelindeki her anahtar entity için doğrula:

• Liste sorgusu kararlılığı — aynı sorgu tekrarlanan çağrılarda tutarlı yapı döndürüyor mu?
• Tekil öğe tutarlılığı — detay sorgusu beklenen tüm alanları döndürüyor mu?
• Null ve eksik alan davranışı — isteğe bağlı alanlar doğru bir şekilde null olarak mı temsil ediliyor?
• İlişki geçişi — iç içe nesneler doğru kardinalite ile çözümleniyor mu?
• Filtre doğruluğu — filtre ifadeleri beklenen alt kümeyi eşliyor mu?
• Sıralama doğruluğu — sıralama tahmin edilebilir, kararlı bir sıra üretiyor mu?
• Sayfalandırma sınırları — offset ve limit kopyasız temiz sayfa dilimleri üretiyor mu?

rt-02-filter-sort-paginationMissing

Filtre, sıralama ve sayfalandırma davranışı doğrulaması.

Runtime İnceleme ve Hata Ayıklama

Davranış yanlış göründüğünde, şu sırada incele:

1. Tablo ve Attribute Tanımlarını Kontrol Et

Beklenmeyen davranışların en yaygın nedeni yanlış yapılandırılmış bir attribute'tur:

• Alan türü doğru mu? (string olarak depolanan bir fiyat sayısal olarak sıralanamaz.)
• Alan sortable/filterable/searchable olarak işaretlenmiş mi?
• Alanın yapılandırılmış bir eşleştirmesi var mı?

2. Endpoint ve Sorgu Meta Verilerini Kontrol Et

Sorgunun API tasarım görünümünde doğru yapılandırıldığını doğrula:

• Sorgu etkin mi?
• Sorgu adı ve parametreleri doğru mu?
• Sayfalandırma yapılandırması uygun mu?

3. Kaynak Eşleştirme Durumunu Kontrol Et

Alanlar null veya beklenmeyen değerler döndürüyorsa:

• Eşleştirme türü doğru mu (OFF_FIELD, FAKE, CONST)?
• OFF_FIELD eşleştirmeleri için, kaynak veri seti beklenen verileri içeriyor mu?
• FAKE eşleştirmeleri için, Faker üreteci doğru veri türü için yapılandırılmış mı?

4. İlişki Politikalarını Kontrol Et

İç içe veriler eksik veya hatalıysa:

• İlişki yönü doğru mu (kaynak → hedef)?
• Kardinalite doğru mu (1:1 vs 1:n)?
• Hedef entity mevcut ve eşleştirilmiş veriye sahip mi?
• Bağlantı sütunları doğru belirtilmiş mi?

Yaygın Sorunlar ve Çözümler

Belirti	Olası Neden	Çözüm
Boş yanıt	Bu koleksiyon için veri içeri alınmamış	Veri içeri aktarmanın tamamlandığını kontrol et
Alanlar null döndürüyor	Eşleştirme yapılandırılmamış	OFF_FIELD, FAKE veya CONST eşleştirme ekle
İç içe ilişki boş	İlişki yanlış yapılandırılmış	Yönü, hedef entity'yi ve bağlantı sütunlarını doğrula
Sıralama çalışmıyor	Alan sortable olarak işaretlenmemiş	Tablo düzenleyicisinde sortable bayrağı etkinleştir
Filtre her şeyi döndürüyor	Alan filterable olarak işaretlenmemiş	Tablo düzenleyicisinde filterable bayrağı etkinleştir
Yanlış veri türleri	Eşleştirme türü uyumsuzluğu	Eşleştirmenin beklenen türü ürettiğini kontrol et
Sayfalandırma öğe atlıyor	Offset hesaplama hatası	Offset'in limit değeri kadar arttığını doğrula

rt-03-runtime-inspectionMissing

Runtime inceleme akışı ve hata ayıklama kontrol noktaları.

Dışa Aktarım Öncesi Doğrulama

Runtime, backend kod üretimine geçmeden önce hazırlık durumunu teyit etmelidir. Runtime doğrulamasını geçen bir model, temiz ve işlevsel bir oluşturulmuş backend üretme olasılığı çok daha yüksektir.

Hazırlık Kriterleri

Dışa aktarıma geçmeden önce şunları teyit et:

• Zorunlu alanlar kararlı — tüm zorunlu attribute'lar tutarlı, null olmayan değerlere sahip.
• İşlem yüzeyi bilinçli — yalnızca açmak istediğin sorgular etkin.
• İlişki davranışı açıklanabilir — her iç içe sorgu doğru çözümleniyor ve kardinalite iş kurallarınla eşleşiyor.
• Filtre ve sıralama davranışı tahmin edilebilir — tüketiciler bu işlemlerin belgelendiği gibi çalıştığına güvenebilir.
• Çözümlenmemiş ipucu yok — önizleme, eşleştirilmemiş attribute'lar veya eksik yapılandırma hakkında uyarı göstermiyor.

Dışa Aktarım Öncesi Doğrulama İş Akışı

1. Her entity için liste sorguları çalıştır — yapı ve veri kalitesini kontrol et.
2. Anahtar entity'ler için detay sorguları çalıştır — alan tamlığını kontrol et.
3. Yapılandırılmış tüm filtreleri test et — doğru alt kümelemeyi doğrula.
4. Her sortable alanda sıralama test et — sıralamayı doğrula.
5. Sayfalandırma sınırlarını test et — temiz sayfa geçişlerini doğrula.
6. İç içe ilişki sorgularını test et — her düzeyinde doğru derlemeyi doğrula.

rt-04-runtime-validationMissing

Dışa aktarım öncesi runtime doğrulama özet görünümü.

Entegratör ipucu

Developer / Integrator

Frontend veya alt akış tüketicileri entegre etmeden önce runtime doğrulamasını bir sözleşme kontrolü olarak kullan. Runtime endpoint'i önizleme ve dış tüketicilere aynı veriyi sunar, bu nedenle workspace'te doğruladığın şey tam olarak uygulamanın alacağı şeydir. Bu, entegrasyon karmaşasını önemli ölçüde azaltır.

Kurumsal runtime beklentileri

Enterprise User

Kurumsal takımlar, runtime doğrulamasını resmi bir kalite kapısı olarak değerlendirmeli. Her entity için doğrulama kriterleri tanımla (zorunlu alanlar, ilişki derinliği, filtre kapsamı) ve modelleri üretim kullanımına terfi ettirmeden önce inceleme sürecine runtime kontrollerini dahil et.