Temel Kavramlar

Mockomat tek bir merkezi ilke üzerine inşa edilmiştir: domain niyeti, modelden runtime'a kadar görünür kalmalıdır.

Aldığın her karar — bir entity'yi adlandırmak, bir alan türü tanımlamak, bir ilişki kurmak — bağlı bir pipeline üzerinden akar: domain modelinden, API tanımlarına, canlı runtime davranışına ve nihayetinde sana ait oluşturulmuş bir backend'e. Bu sayfa, bunu mümkün kılan kavramsal katmanları açıklar.

1. Domain Katmanı: Sistemin Ne Anlama Geldiği

Domain katmanı, projenin anlamsal temelidir. Herhangi bir API veya uygulama detayı karara bağlanmadan önce verilerinin yapısını ve anlamını tanımlar.

Entity'ler ve Tablolar

Bir entity (veya tablo), gerçek bir iş konseptini temsil eder: Customer, Order, Invoice, Subscription. Her entity'nin bir adı, bir dizi attribute'u (sütunu) ve isteğe bağlı olarak diğer entity'lerle bir veya daha fazla ilişkisi vardır.

Adlandırma önemlidir. Mockomat, genel örnek adlar yerine takımının gerçek iş dilini kullanmanı teşvik eder. Customer ve Subscription ile oluşturulmuş bir model, niyeti Table1 ve Table2'den çok daha iyi iletir.

Attribute'lar

Her attribute şunlara sahiptir:

• Name — tanımlayıcı bir isim (örneğin firstName, totalAmount, isActive)
• Type — veri türü, örneğin String, Integer, Float, Boolean, Date, JSON, Enum
• Required bayrağı — alanın her zaman bir değere sahip olması gerekip gerekmediği
• Searchable bayrağı — alanın liste işlemlerinin searchTerm aramasına katılıp katılmadığı
• Sortable ve Filterable bayrakları — modelle birlikte saklanır; Sortable ayrıca kod dışa aktarımında sıralanabilir liste sütunlarını işaretler

Bu bayraklardan yalnızca Searchable mock API'yi değiştirir. Sıralama, bir veri sütununa bağlı her attribute ile çalışır (sortField); filtreleme ise bir işlemde tanımladığın parametreleri kullanır (bkz. API Design (İngilizce)).

İlişkiler

İlişkiler, entity'leri birbirine bağlar ve iş sahipliği veya referans desenlerini ifade eder:

• Bire-Bir (1:1) — örneğin User → Profile
• Bire-Çok (1:n) — örneğin Customer → Order[]
• Çoka-Çok (m:n) — örneğin Product ↔ Category

Her ilişkinin bir yönü ve bir kardinalitesi vardır. İlişki tanımı, runtime'ın aramaları nasıl çözümleyeceğini belirler: bir Order sorgularken, ilişkili Customer verileri bu tanımlara dayanarak temel veri kaynağından derlenir.

Bu Katman Neden Önemli

• Adlandırma sapmasını azaltır — takımdaki herkes aynı terminolojiyi kullanır.
• Takımlar arası hizalanmayı iyileştirir — frontend ve backend geliştiricileri tek bir gerçeklik modeli paylaşır.
• Mimariyi incelenebilir kılar — domain niyeti, kodun içine gömülmek yerine açıkça belirtilir.
• Otomasyonu mümkün kılar — kod üretimi, API açılımı ve runtime davranışının tümünü bu katman belirler.

cc-01-domain-layerMissing

Entity'ler ve ilişkilerle domain katmanı modeli.

2. API Tanım Katmanı: Sistemin Nasıl Sunulduğu

API katmanı, domain niyetini bir sorgu ve işlem yüzeyine çevirir. Mockomat, code-first GraphQL yaklaşımını kullanır: model tanımların otomatik olarak tamamen tipli bir GraphQL şemasına çevrilir.

Dinamik Şema Üretimi

Bir proje etkinleştirildiğinde, Mockomat anlık olarak bir GraphQL şeması üretir:

1. Model tanımlarını yükle — projeden tüm entity'leri, attribute'ları, ilişkileri ve yapılandırmayı oku.
2. GraphQL tiplerini oluştur — her entity bir GraphQL nesne tipine; her attribute tipli bir alana dönüşür.
3. Sorgu giriş noktalarını oluştur — her entity için liste ve detay sorguları üretilir.
4. Resolver'ları kaydet — alan düzeyinde resolver'lar veri getirme, eşleştirme ve ilişki aramalarını yönetir.
5. İstekleri kabul et — şema, sorguları hemen sunmaya hazırdır.

Bu, şema dosyalarını asla elle yazman gerekmediğini ifade eder. Şema her zaman modelinle senkronize olur.

Sorgu Yapısı

Her entity otomatik olarak iki sorgu türü oluşturur:

• Liste sorgusu — isteğe bağlı filtreleme ve sıralama ile sayfalandırılmış bir koleksiyon döndürür.
• Detay sorgusu — tanımlayıcısına göre tek bir öğe döndürür.

Örneğin, bir Product entity'si modellersen, oluşturulan sorgular şu şekilde görünebilir:

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

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

Filtreleme

Filtreler API tasarımında operasyon başına tanımlanır — sabit kapsam filtreleri ve çağıranın parametreleri, her biri bir operatörle:

Operatör	Açıklama	Uygulanabilir 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

Bir operasyonun tüm filtreleri AND ile birleşir; istek anında OR ya da iç içe yapı yoktur.

Sıralama

Sıralama sortField (bir attribute adı) ve sortDirection ile yapılır — artan (ASC) veya azalan (DESC).

Sayfalandırma

Mockomat sayfa tabanlı sayfalandırma kullanır:

• page — sayfa numarası, 1'den başlar (varsayılan: 1)
• pageSize — sayfa başına kayıt, en fazla 100 (varsayılan: operasyonun varsayılan sayfa boyutu, değiştirilmediyse 25)

Yanıt kayıtları items içine, total, page ve pageSize yanına koyar.

cc-02-endpoint-configMissing

API tanımı ve endpoint yapılandırma görünümü.

3. Runtime Katmanı: Davranışın Nasıl Doğrulandığı

Runtime katmanı, model ve API kararlarının gerçek sorgu yürütmesi altında test edildiği yerdir. Şu soruyu yanıtlar: sistem, niyet ettiğin şekilde davranıyor mu?

Mock Runtime Nasıl Çalışır

Mock runtime motoru, Mockomat'ın değerinin ç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 dizesini soyut bir söz dizimi ağacına (AST) ayrıştırır.
2. Query Planner — AST'yi model meta verileriyle (entity tanımları, attribute bayrakları, ilişki yapılandırmaları) birlikte analiz ederek bir yürütme planı oluşturur.
3. MongoDB Query Builder — yürütme planını bir MongoDB aggregation pipeline'ına çevirir.
4. Result Assembler — MongoDB sonuçlarını beklenen GraphQL yanıt yapısına uygun şekilde yeniden şekillendirir.

Bu pipeline her sorguda çalışır. MongoDB verileri düz (denormalize) koleksiyonlarda depoladığı için, runtime ilişkisel yapıyı simüle eder — ilişkili verileri birleştirir, iç içe alanları çözümler ve nihai yanıtı tam olarak ilişkisel bir backend'den gelmiş gibi derler.

Önizleme ve Dış Tüketim

Aynı runtime endpoint'i iki kitleye hizmet eder:

• Önizleme — modelleme sırasında sorguları test ettiğin, yanıt yapılarını incelediğin ve davranışı doğruladığın uygulama içi Runtime sayfası.
• Dış tüketiciler — aynı mock API endpoint'ini çağıran frontend uygulaman, test paketin veya CI pipeline'ın.

Her ikisi de aynı REST endpoint'ini kullanır: POST /mock/{slug}/graphql. Bu, önizlemede doğruladığın şeyin tam olarak dış tüketicilerin alacağı şey olduğu anlamına gelir.

Doğrulama Pratikte Ne Anlama Gelir

Runtime doğrulama sadece "sorgu veri döndürüyor mu" değildir. Şunları teyit eder:

• Alan yapıları — dönen türler ve yapılar beklediğin gibi mi?
• İlişki aramaları — iç içe nesneler doğru çözümleniyor mu?
• Sayfalandırma davranışı — page ve pageSize tutarlı dilimler üretiyor mu?
• Sıralama kararlılığı — bir alana göre sıralama tahmin edilebilir bir sıra üretiyor mu?
• Filtre doğruluğu — filtre ifadeleri doğru veri alt kümesini eşliyor mu?
• Null yönetimi — isteğe bağlı alanlar, veri olmadığı durumlarda doğru bir şekilde null olarak mı temsil ediliyor?

cc-03-runtime-flowMissing

Doğrulama kontrol noktalarıyla modelden runtime'a akış.

4. Veri Kaynakları ve Alan Eşleştirme

Modelindeki her attribute'un bir veri kaynağına ihtiyacı vardır. Mockomat, alan değerlerinin nereden geldiğini belirleyen üç eşleştirme türünü destekler (attribute düzenleyici Veri kaynağı ve Sabit seçeneklerini sunar; Hesaplanmış seçeneğini yalnızca zaten hesaplanmış eşleştirmesi olan attribute'larda gösterir):

SOURCE — İçe Aktarılmış Veri Seti Sütunları

Bir attribute'u ortak veri havuzundaki bir sütuna bağlar — içe aktarılmış veri setleri: doğrulanmış bir kaynağın bulunduğu yerde açık veriler, blueprint'ler için üretilmiş örnek veriler. Runtime içe aktarılmış satırları sunar ve asla değer uydurmaz.

Bunu istediğinde kullan:

• Gerçekçi isimler, adresler, ürün verileri, kategoriler veya ölçümler
• Büyük hacimlerde çeşitli veriler
• Demolarda ve testlerde otantik hissettiren veriler

CONSTANT — Sabit Değerler

Attribute'a tek bir sabit değer atar. Runtime bu değeri her satırda döndürür: içe aktarılan verilerin satırlarında da, değer havuzlarından oluşturulan satırlarda da.

Bunu istediğinde kullan:

• Varsayılan durum değerleri (örneğin "active")
• Sabit yapılandırma değerleri

COMPUTED — Türetilmiş Değerler (Değerlendirilmez)

Aynı kaydın diğer alanları üzerinde bir ifade saklar (örneğin ad ve soyaddan tam ad). Runtime ifadeleri değerlendirmez; bu yüzden hesaplanmış bir alan yanıtın parçası değildir. Attribute düzenleyici artık Hesaplanmış seçeneğini sunmaz; zaten hesaplanmış eşleştirmesi olan bir attribute bunu korur ve değerlendirilmiyor olarak işaretlenir.

cc-04-data-sourcesMissing

Farklı veri kaynağı türleriyle alan eşleştirme yapılandırması.

Veri kaynağı erişilebilirliği

Free User

Misafir oturumları dahil her planda eşleştirme türleri ve ortak veri havuzu aynıdır.

5. Proje İzolasyonu ve Çok Kiracılık

Her Mockomat projesi kendi izole bağlamında çalışır:

• Ortak, salt okunur veri havuzu — mock veriler içe aktarılmış veri setlerinden oluşan ortak bir havuzdan gelir; bir proje yalnızca bağlı olduğu tabloları okur ve havuz verilerini asla değiştirmez.
• Bağımsız şema — GraphQL şeması, projeye özgü modeline dayanarak proje bazında üretilir.
• Slug tabanlı endpoint'ler — her proje benzersiz bir URL yolu alır (/mock/{slug}/graphql).
• Tenant kapsamlandırması — modeller, üyeler ve API key'ler tek bir tenant'a aittir ve her istek buna göre kontrol edilir; böylece kuruluşlar arası sıkı izolasyon sağlanır.

Bu, birden fazla takımın farklı projeler üzerinde aynı anda veri sızıntısı veya şema çakışması riski olmadan çalışabilmesi anlamına gelir.

Kurumsal limitler

Enterprise User

İzolasyon her planda aynıdır. Enterprise satış ekibimizle kararlaştırılır: projeler, istekler ve takım büyüklüğü gibi limitler sözleşmeye göre ayarlanır.

6. AI + Mimari Birlikte

AI, oluşturmayı hızlandırır. Mockomat, gereksinimler geliştikçe yapı kalitesini ve açıklanabilirliğini korur.

Platform, AI araçlarının yerine geçmek için değil, onlarla birlikte çalışmak için tasarlanmıştır. AI kod parçalarını hızla oluşturabilirken, Mockomat, AI tarafından oluşturulan kodun genellikle eksik kaldığı yapısal bağlamı sağlar:

• Şema tutarlılığı — domain modelin, ister elle ister AI yardımı ile oluştur, tek doğru kaynak olmaya devam eder.
• Runtime doğrulama — her değişiklik, üretime ulaşmadan önce önizleme pipeline'ı aracılığıyla doğrulanabilir.
• İzlenebilir kararlar — model değişiklikleri açık ve incelenebilirdir, AI tarafından oluşturulan kodun içine gömülmez.

Entegratör bakış açısı

Developer / Integrator

Oluşturulan çıktıları başlangıç noktası olarak değerlendir, nihai gerçek olarak değil. Modeli niyet kaynağı olarak tut ve kaliteyi runtime davranışının doğrulamasına bırak. AI destekli iş akışlarını entegre ederken, Mockomat modelini AI tarafından oluşturulan tüketicilerin uyması gereken sözleşme olarak kullan.

Kurumsal bakış açısı

Enterprise User

Uzun vadeli değer, yalnızca hızlı ilk çıktıdan değil, tekrarlanabilir mimariden gelir. Domain sürekliliği, çok takımlı evrim için kontrol noktasıdır. Mockomat modellerini, bireysel sprint döngülerini aşan yönetişim varlıkları olarak kullan.