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ı içe aktarılan verilerle 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, projenin bir API key'i ile aynı endpoint'e gider (misafir projeler paylaşım token'larını kullanır — bkz. Entegratörler):

POST /mock/{slug}/graphql
Authorization: Bearer mck_your_api_key

Kök alan, API tasarımındaki bir operasyonun adıdır. Liste sorgusu kayıtlarını items içinde seçer ve total, page ile pageSize ekleyebilir; detay sorgusu alanları doğrudan seçer. Yanıt, tablonun eşlenmiş tüm attribute'larını ve ilişkilerini içerir — seçim kümesi yanıtı daraltmaz.

Liste Sorgusu

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

query {
  products(page: 1, pageSize: 20) {
    items {
      id
      name
      price
      category {
        id
        name
      }
    }
    total
    page
    pageSize
  }
}

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

Operasyonun API tasarımında tanımladığı parametreleri gönder — burada minPrice (price üzerinde, gte) ve maxPrice (price üzerinde, lte):

query {
  products(minPrice: 10, maxPrice: 50, pageSize: 10) {
    items {
      id
      name
      price
    }
    total
  }
}

Sıralamalı Sorgu

Sonuçları sortField (bir attribute adı) ve sortDirection ile sırala:

query {
  products(sortField: "price", sortDirection: DESC, pageSize: 10) {
    items {
      id
      name
      price
    }
    total
  }
}

İç İçe İlişkili Sorgu

Tablonun ilişkileri tek seviye derinlikte, iç içe döner:

query {
  customers(pageSize: 5) {
    items {
      id
      firstName
      lastName
      orders {
        id
        totalAmount
        createdAt
      }
    }
    total
  }
}

Filtreleme Detayları

Filtreler operasyona aittir: onları API tasarımında tanımlarsın ve runtime her istekte uygular. Kapsam filtreleri operasyonun sabit koşullarıdır; parametreler çağıranın gönderdiği argümanlardır — her biri bir attribute'a ve bir operatöre bağlıdır, isteğe bağlı olarak zorunlu ya da varsayılan değerlidir.

Mevcut Operatörler

Operatör	Açıklama	Çalıştığı Türler
eq	Eşittir	Tüm türler
neq	Eşit değildir	Tüm türler
gt / gte	Büyüktür / büyük eşittir	Sayılar, Tarihler
lt / lte	Küçüktür / küçük eşittir	Sayılar, Tarihler
in	Bir listedeki değerlerden biri	Tüm türler
like	İçerir (büyük/küçük harf duyarsız)	String'ler
notIn	Bir listedeki değerlerin hiçbiri (yalnızca kapsam filtreleri)	Tüm türler
isNull / isNotNull	Null / null değil (yalnızca kapsam filtreleri)	Tüm türler

Filtreleri Birleştirme

Bir operasyonun tüm kapsam filtreleri ve parametreleri AND ile birleşir — istek anında OR ya da iç içe yapı yoktur. Parametre değerlerini satır içinde veya GraphQL değişkenleri olarak gönder:

query ProductsInRange($min: Float, $max: Float) {
  products(minPrice: $min, maxPrice: $max, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
  }
}

{ "min": 10, "max": 50 } değişkenleriyle bu sorgu, fiyatı 10 ile 50 arasındaki ürünleri döndürür.

Parametre Doğrulama

Operasyonun tanımlamadığı bir argüman BAD_USER_INPUT ile reddedilir; varsayılan değeri olmayan eksik bir zorunlu parametre de öyle. Parametresi olmayan operasyonlar bilinmeyen argümanları yok sayar. Parametreleri API tasarımında tanımla.

Arama

searchTerm, aranabilir olarak işaretlenmiş tüm attribute'larda büyük/küçük harf duyarsız eşleşir (en fazla 64 karakter):

query {
  products(searchTerm: "oak", pageSize: 10) {
    items {
      id
      name
    }
    total
  }
}

Sayfalandırma

Mockomat sayfa tabanlı sayfalandırma kullanır:

Parametre	Açıklama	Varsayılan
page	Sayfa numarası, 1'den başlar	1
pageSize	Sayfa başına kayıt, en fazla 100	Operasyonun varsayılan sayfa boyutu (değiştirilmediyse 25)

Tipik bir sayfalandırılmış istek:

query {
  products(page: 3, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
    page
    pageSize
  }
}

Bu, 41-60 arasındaki kayıtları döndürür. total eşleşen tüm kayıtları sayar; son sayfa yukarı yuvarlanmış total / pageSize değeridir.

Sıralama

sortField (bir attribute adı) ve sortDirection ile sırala:

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. sortField verilmezse operasyonun varsayılan sıralaması geçerlidir; yoksa sonuçlar depolama sırasıyla gelir.

İ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.
• İç içe ilişkiler tek seviye derinlikte çözümlenir: ilişkili bir kayıt kendi attribute'larını taşır, ilişkilerini değil (Customer → Order çalışır; siparişin kalemleri dahil edilmez). Her üst kayıt en fazla 50 ilişkili kayıt alır.

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ı — page ve pageSize 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.)
• Arama için: Alan Searchable olarak işaretlenmiş mi?
• Sıralama için: sortField bir veri sütununa bağlı bir attribute'un adı mı?
• 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 (Veri kaynağı veya Sabit)?
• Veri kaynağı eşleştirmelerinde attribute, içe aktarılan verinin doğru sütununa bağlı mı ve bu sütun bu kayıtlar için değer içeriyor mu?
• Sabit değerler her satırda görünür: içe aktarılan verilerin satırlarında da, değer havuzlarından oluşturulan satırlarda da.
• Hesaplanmış eşleştirmelerde runtime ifadeleri değerlendirmez; bu yüzden hesaplanmış bir alan yanıtın parçası değildir.

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	Tablo içe aktarılan verilere bağlı değil (NOT_READY)	Tabloyu board'un Mappings panelinde içe aktarılan verilere bağla
Alanlar null döndürüyor	Eşleştirme yapılandırılmamış	Attribute'u içe aktarılan verinin bir sütununa bağla (Veri kaynağı eşleştirmesi)
İç 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	sortField eşlenmiş bir attribute değil	Eşlenmiş bir attribute'un adını kullan
Filtre her şeyi döndürüyor	Operasyon bu argüman için parametre tanımlamıyor	Parametreyi API tasarımında ekle
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	İstekler arasında pageSize değişti	pageSize'ı sabit tut ve page'i 1'er artır

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. Tüketicilerinin sıraladığı attribute'larla sıralamayı 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.