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ü:
string,number,boolean,date,json - Required bayrağı — alanın her zaman bir değere sahip olması gerekip gerekmediği
- Sortable bayrağı — alanın sonuçları sıralamak için kullanılıp kullanılamayacağı
- Searchable bayrağı — alanın arama sorgularına katılıp katılmayacağı
- Filterable bayrağı — alanın filtre işlemlerini destekleyip desteklemediği
Bu bayraklar, API katmanının verilerini nasıl sunduğunu doğrudan etkiler. sortable: true olarak işaretlenmiş bir alan, GraphQL sorgularında sıralama işlemleri için kullanılabilir hale gelir. filterable: true olarak işaretlenmiş bir alan, filtre ifadelerini destekler.
İ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.
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:
- Model tanımlarını yükle — projeden tüm entity'leri, attribute'ları, ilişkileri ve yapılandırmayı oku.
- GraphQL tiplerini oluştur — her entity bir GraphQL nesne tipine; her attribute tipli bir alana dönüşür.
- Sorgu giriş noktalarını oluştur — her entity için liste ve detay sorguları üretilir.
- Resolver'ları kaydet — alan düzeyinde resolver'lar veri getirme, eşleştirme ve ilişki aramalarını yönetir.
- İ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(offset: 0, limit: 20, filter: { ... }, sort: { ... }) {
id
name
price
category {
id
name
}
}
}
query {
product(id: "abc-123") {
id
name
price
description
}
}Filtreleme
Filtre sistemi, tip-güvenli, birleştirilebilir ifadeleri destekler:
| Operatör | Açıklama | Uygulanabilir Türler |
|---|---|---|
equals | Tam eşleştirme | Tüm türler |
notEquals | Olumsuzlama | Tüm türler |
contains | Alt dize eşleştirme | String'ler |
greaterThan / greaterThanOrEqual | Aralık (üst) | Sayılar, Tarihler |
lessThan / lessThanOrEqual | Aralık (alt) | Sayılar, Tarihler |
in | Kümedeki değer | ID'ler, Enum'lar |
isNull / isNotNull | Null kontrolü | Tüm türler |
Filtreler AND ve OR mantıksal operatörleri kullanılarak birleştirilebilir ve karmaşık ifadeler için iç içe yerleştirilebilir.
Sıralama
Domain modelinde sortable: true olarak işaretlenmiş alanlar sıralama işlemlerinde kullanılabilir. Sıralama yönü artan (ASC) veya azalan (DESC) şeklindedir.
Sayfalandırma
Mockomat offset tabanlı sayfalandırma kullanır:
offset— atlanacak öğe sayısı (varsayılan: 0)limit— döndürülecek öğe sayısı (varsayılan: 20)
Bu model basittir ve çoğu kullanım senaryosu için iyi çalışır. Yanıt, sayfalandırma meta verileriyle birlikte veri dizisini içerir.
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:
- GraphQL Request Parser — gelen sorgu dizesini soyut bir söz dizimi ağacına (AST) ayrıştırır.
- 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.
- MongoDB Query Builder — yürütme planını bir MongoDB aggregation pipeline'ına çevirir.
- 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ışı — offset ve limit 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?
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 birkaç eşleştirme türünü destekler:
OFF_FIELD — Gerçek Veri Seti Alanları
Bir attribute'u gerçek dünya veri setindeki bir alana eşler (örneğin Open Food Facts). Bu, mock API'ne üretim verisi gibi davranan gerçekçi, çeşitli veriler sağlar.
Bunu istediğinde kullan:
- Gerçekçi ürün adları, kategoriler veya ölçümler
- Büyük hacimlerde çeşitli veriler
- Demolarda ve testlerde otantik hissettiren veriler
FAKE — Üretilmiş Veriler (Faker)
Bir attribute'u gerçekçi sentetik veriler üreten bir Faker üretecine eşler: isimler, e-postalar, adresler, tarihler, fiyatlar ve daha fazlası.
Bunu istediğinde kullan:
- Kişisel veriler (isimler, e-postalar, telefon numaraları)
- Finansal veriler (fiyatlar, hesap numaraları)
- Zamana dayalı veriler (tarihler, zaman damgaları)
- Gerçek veri setleri tarafından karşılanmayan herhangi bir veri türü
CONST — Sabit Değerler
Bir attribute'u her kayıt için aynı olan sabit bir değere eşler.
Bunu istediğinde kullan:
- Varsayılan durum değerleri (örneğin
"active") - Sabit yapılandırma değerleri
- Erken modelleme sırasındaki yer tutucu veriler
COMPUTED — Türetilmiş Değerler (Gelecek)
Diğer alanlara dayalı ifadeler aracılığıyla alan değerlerinin tanımlanmasına olanak tanıyacaktır. Bu, gelecekteki bir sürüm için planlanmıştır.
Farklı veri kaynağı türleriyle alan eşleştirme yapılandırması.
5. Proje İzolasyonu ve Çok Kiracılık
Her Mockomat projesi kendi izole bağlamında çalışır:
- Ayrı veri alanı — her projenin mock veriler için kendi MongoDB koleksiyonları vardır.
- 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ı — tüm veri erişimi tenant'a göre filtrelenir ve 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.
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.