Apidog'da Koşullu Mock Veri Nasıl Döndürülür (Özel Kurallar ve Mock Scriptleri)

Akıllı mock, saniyeler içinde size sahte bir API sağlar. Uç nokta şemanızı okur ve mantıklı veriler döndürür: gerçekçi görünen bir e-posta, makul bir zaman damgası, `xJ8kQ` olmayan bir ad. Çoğu ön uç çalışması için bu, sizi engellerden kurtarmaya yeterlidir.

Ardından, Akıllı mock'un ulaşamayacağı durumla karşılaşırsınız. Bilinen bir kullanıcı için /login'in 200, aksi takdirde 401 döndürmesini istersiniz. /orders/{id}'nin bir kimlik için sevk edilmiş bir sipariş, başka bir kimlik için ise iptal edilmiş bir sipariş döndürmesini istersiniz. Hata yönetiminizin üretime geçmeden önce test edilmesi için talep üzerine bir 500 hatası zorlamak istersiniz. Akıllı mock, her uç nokta için tek bir şekil döndürdüğü için isteğe göre dallanma yapamaz. İşte bu kılavuz bu boşluğu kapatıyor.

Apidog bunu iki özellikle ele alır: kural tabanlı koşullu yanıtlar için mock beklentileri ve kuralların ifade edemediği mantık için mock komut dosyaları. Bu rehber her ikisini de somut örneklerle gösterir ve özel kurallarınızın Akıllı mock'a her zaman üstün gelmesi için öncelik sırasını açıklar. Temel konulara yeniyseniz, API mock'lama genel bakışı iyi bir başlangıçtır ve Apidog baştan sona kullanacağımız araçtır. OpenAPI Girişimi, tüm bunları mümkün kılan sözleşme öncelikli iş akışını belgeler.

Koşullu mock'lamanın gerçekte anlamı nedir

Koşullu bir mock bir kuraldır: gelen istek şöyle göründüğünde, şunu döndür. Apidog bu kuralları iki katmandan oluşturur.

İlk katman, uç nokta şemasındaki alan düzeyinde özelleştirmedir. Bir alanı sabit bir değere sabitlersiniz veya her çağrıda değişmesi için dinamik bir Faker.js ifadesi eklersiniz. Bu, bir alanın ne içerdiğini kontrol eder, ancak yine de uç nokta için tek bir yanıt şekli döndürür.

İkinci katman, tam yanıt mock beklentisidir. Bir beklenti, isteğe bağlı koşullara ve kendi yanıt gövdesi, durum kodu ve başlıklarına sahip adlandırılmış bir kuraldır. Koşulsuz bir beklenti, sabit verileri koşulsuz olarak döndürür. Koşullu bir beklenti, verilerini yalnızca istek eşleştiğinde döndürür. Bunlardan birkaçını bir araya getirdiğinizde gerçek dallanma elde edersiniz: istek A koşuluyla eşleştiğinde B yanıtı, bir başlık eksik olduğunda hata gövdesi, yol parametresi başına farklı bir yük.

Bu ikinci katman, isteğe bağlı hata durumlarını ve istek başına gövdeleri mümkün kılar. Bu kılavuzun geri kalanı orada yer almaktadır.

Önce alan düzeyinde dinamik değerler

Dallanmadan önce, tek bir alanın değerini nasıl aldığını görmek faydalıdır, çünkü koşullu yanıtlarınız aynı sözdizimini yeniden kullanacaktır.

Bir uç noktanın şeması içinde, herhangi bir dize alanı {{$category.method}} olarak yazılmış bir Faker.js ifadesi içerebilir. Apidog, her mock çağrısında, JSON Şema tanımınızın zaten belirttiği alan türlerini kullanarak bunu yeni bir şekilde çözer.

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}

Parametreli yöntemler çalışır, bu nedenle {{$number.int(min=1000,max=9999)}} değeri sınırlar ve {{$date.between(...)}} bir aralık ve format belirler. Bir alanda statik metni ve birden çok ifadeyi birleştirebilirsiniz; yukarıdaki adres bu şekilde oluşturulur. Bölgeye özgü verilere ihtiyacınız varsa, Apidog özelleştirilebilir mock yerel ayarlarını destekler, böylece adlarınız, adresleriniz ve telefon numaralarınız belirli bir dil veya ülkeyle eşleşir. Apidog'daki Faker.js referansı, tam yöntem kataloğunu kapsar.

Burası Akıllı mock bölgesidir. Dinamiktir, ancak koşullu değildir. İsteğe göre dallanmak için beklentilere geçersiniz.

Uygulamalı Örnek: 200 veya 401 döndüren bir giriş uç noktası

Tipik durum: POST /login, kullanıcı adı ve parola içeren bir JSON gövdesi alır. Bilinen bir kullanıcı bir belirteçle 200 almalıdır. Diğer herkes 401 almalıdır.

Doğru sekmeyi açın

Bunu nerede yapılandıracağınız çalışma modunuza bağlıdır:

• HATA AYIKLAMA (İstek öncelikli) modunda, uç noktayı açın ve **Mock** sekmesine tıklayın.

• TASARIM (Tasarım öncelikli) modunda, uç noktayı açın ve **Gelişmiş mock** sekmesine tıklayın.

Her ikisi de aynı beklenti listesine yol açar. Takip etmek isterseniz ve henüz uygulamaya sahip değilseniz, Apidog'u İndirin ve önce bir /login uç noktası içe aktarın veya oluşturun.

Başarı beklentisini ekleyin

**Yeni beklenti**'ye tıklayın. Buna login-success gibi bir **beklenti adı** verin. Şimdi bir koşul ekleyin. Kullanıcı adı JSON istek gövdesinde yer aldığından, onu bir gövde parametresi olarak eşleştirirsiniz: hedef özelliğin JSON yolunu, yani username'i ad alanına koyun ve koşulu alice@example.com'a eşit olarak ayarlayın.

Gövde parametresi koşulları yalnızca JSON'dur ve ad alanındaki JSON yolu aracılığıyla eşleştirilirler, bu nedenle iç içe geçmiş özellikler user.email gibi nokta yolları kullanır. **Yanıt verilerini** başarı yüküyle doldurun:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "alice@example.com",
    "role": "member"
  }
}

Kaydedin. Varsayılan **HTTP Durum Kodu** 200'dür, bu nedenle olumlu senaryo için başka hiçbir şeye dokunmanıza gerek yoktur.

Hata beklentisini ekleyin

Tekrar **Yeni beklenti**'ye tıklayın. Adını login-failure olarak belirleyin ve koşullarını boş bırakın, böylece her şeyi yakalayan bir durum görevi görsün. **Yanıt verilerini** hata gövdesine ayarlayın:

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}

Bu, varsayılan olmayan bir duruma ihtiyaç duyar. Beklentinin **Daha Fazla** sekmesini açın ve **HTTP Durum Kodu**'nu 401 olarak ayarlayın. Oradayken, Daha Fazla sekmesinin aynı zamanda **Yanıt Gecikmesi**'ni milisaniye cinsinden (varsayılan 0) ve herhangi bir özel yanıt başlığını ayarladığınız yer olduğunu unutmayın. 400ms'lik bir gecikme, yükleme döndürücünüzün gerçekten işlendiğinden emin olmanın ucuz bir yoludur.

Sıralama önemlidir

Beklentiler yukarıdan aşağıya doğru değerlendirilir ve ilk eşleşme kazanır. Bu nedenle login-success beklentisi login-failure beklentisinin üzerinde olmalıdır. alice@example.com adresine eşit kullanıcı adına sahip bir istek ilk kuralı eşleştirir ve belirteci döndürür. Diğer her şey koşulsuz hata kuralına düşer ve 401 alır. Sırayı tersine çevirirseniz, boş koşullu kural her şeyi eşleştirir ve başarı durumunuz asla tetiklenmezdi.

Uç noktadan mock URL'sini kopyalayın ve her iki yolu da test edin:

# bilinen kullanıcı -> belirteçle 200
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"whatever"}'

# diğer herkes -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"stranger@example.com","password":"whatever"}'

Uygulamalı Örnek: Duruma göre /orders/{id} için farklı gövdeler

İkinci yaygın durum, bir yol parametresi üzerinden dallanmadır. Kullanıcı arayüzünüzün canlı bir arka uç olmadan her durumu işleyebilmesi için /orders/{id}'nin bir kimlik için sevk edilmiş bir sipariş, başka bir kimlik için ise iptal edilmiş bir sipariş döndürmesini istersiniz.

Her durum için bir beklenti oluşturun. Her biri için, yol parametresi id üzerine bir koşul ekleyin, ardından eşleşen **Yanıt verilerini** doldurun.

order-shipped beklentisi, koşul: yol parametresi id, 5001'e eşittir.

{
  "id": 5001,
  "status": "shipped",
  "total": 129.90,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

order-cancelled beklentisi, koşul: yol parametresi id, 5002'ye eşittir.

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

Koşulsuz son bir beklenti ekleyin ve bu beklenti genel bir bekleyen sipariş döndürsün, böylece diğer herhangi bir kimlik yine de geçersiz olmaktansa geçerli bir yanıt alır. Belirli kuralları her şeyi yakalayan kuralın üzerine sıralayın, kaydedin ve isteğe bağlı olarak her sipariş durumunu işleyen bir mock'unuz olur. Koşulları karıştırmak da işe yarar: yol koşulunun yanına bir başlık koşulu ekleyin ve her ikisi de geçerli olmalıdır, çünkü Apidog birden çok koşulu AND mantığıyla birleştirir (dokümanların terimleriyle koşulların bir kesişimi).

Koşullar gövde ve yolla sınırlı değildir. Sorgu parametreleri, başlık parametreleri, çerez parametreleri ve hatta IP adresleri üzerinden eşleştirme yapabilirsiniz, bu da bir test sırasında yanıtı belirli istemcilerle sınırlamanıza olanak tanır.

İsteğe bağlı olarak hata durumlarını zorlama

Bozuk yanıtları test etmek için bozuk bir arka uca ihtiyacınız yok. Bir beklenti ve **Daha Fazla** sekmesi size istediğiniz durumu verir.

Bir 500 hatası zorlamak için, koşulu istemciden kontrol edebileceğiniz bir beklenti ekleyin, örneğin server-error değerine eşit bir X-Mock-Scenario başlığı. Yanıt verilerini gerçekçi bir hata gövdesine ve HTTP Durum Kodunu Daha Fazla sekmesinde 500 olarak ayarlayın.

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}

Şimdi aynı uç nokta varsayılan olarak normal bir 200 yanıtı ve bu başlığı her gönderdiğinizde bir 500 yanıtı sunar. Aynı şeyi 404, 429 (Daha Fazla sekmesinde ayarlanmış bir Retry-After başlığı ile) veya 503 için de yapın. Ön uç hata yönetiminiz sonunda yakalayacak bir şeye sahip olur. Bu yanıtlara otomatik kontrollerde iddia ediyorsanız, API iddiaları kılavuzu bu kurulumla iyi eşleşir.

Paylaşılan projeler için bir ayrıntı: her beklenti, yerel ve bulut mock ortamları için beklenti listesinden bağımsız olarak açılıp kapatılabilir. Böylece yerel olarak bir 500 kuralını aktif tutarken, takım arkadaşlarınızın kullandığı bulut mock'unda kapalı bırakabilirsiniz.

Kurallar yeterli olmadığında: mock komut dosyaları

Beklentiler deklaratiftir. Eşleşir ve döndürürler, ancak hesaplama yapamazlar. İstekten türetilmiş bir alana, satır öğelerinden toplanan bir toplamaya veya aynı anda birkaç girdiye göre şekil değiştiren bir gövdeye ihtiyacınız olduğunda, bir mock komut dosyasına başvurursunuz.

Bir mock komut dosyası, mock yanıtına karşı çalışan JavaScript'tir. **Mock** sekmesinin altındaki **Mock Komut Dosyası bölümünde** bulunur ve bir açma/kapama anahtarıyla etkinleştirilir. Komut dosyası iki global değişkeni ifşa eder:

• $$.mockRequest: getParam(key) aracılığıyla gelen isteği okuyun, ayrıca headers, cookies, body, formdata ve urlencoded.
• $$.mockResponse: setBody(), setCode(), setDelay(), json() ve headers ve code özelliklerini kullanarak giden yanıtı şekillendirin.

İşte gönderilen satır öğelerinden bir sipariş toplamını hesaplayan ve arayanın para birimi başlığını geri yansıtan bir komut dosyası:

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});

İş akışı şöyledir: Akıllı mock ilk yanıtı oluşturur, komut dosyanız $$.mockRequest'i ve mevcut $$.mockResponse'i okur, mantığını uygular, $$.mockResponse.setBody() (ve gerektiğinde setCode, setDelay veya headers) çağırır ve motor nihai sonucu döndürür. Dizi yöntemleri veya tarih matematiği ile mantığı daha da ileriye taşımak isterseniz MDN JavaScript referansı sağlam bir yol arkadaşıdır.

İnsanları yanıltan tek kural

Mock komut dosyaları yalnızca Akıllı mock ile çalışır. Mock beklentilerine veya yanıt örneklerine uygulanmazlar. İçselleştirilmesi gereken en önemli şey şudur: bir mock komut dosyasını beklenti tabanlı bir yanıtla birleştiremezsiniz. Bir beklenti isteği eşleştirirse, komut dosyası asla çalışmaz. Bu nedenle her uç nokta için bir yol seçin. Sabit koşullara göre dallanırken ve önceden hazırlanmış gövdeler döndürürken beklentileri kullanın. Akıllı mock'un oluşturduğu temelden hesaplanmış çıktıya ihtiyacınız olduğunda bir mock komut dosyası kullanın.

Öncelik sırası nasıl çözülür

Hepsini bir araya getirdiğinizde, Apidog'un herhangi bir mock isteği için izlediği sıra şudur:

1. Beklentilerinizi yukarıdan aşağıya doğru kontrol eder. Tüm koşulları eşleşen ilk beklenti kazanır ve yanıtı döndürülür. Özel kuralların Akıllı mock'u yenmesinin nedeni budur: eşleşen bir beklenti, altındaki her şeyi kısa devre yapar.
2. Hiçbir beklenti eşleşmezse, Apidog, **Proje Ayarları - Özellik Ayarları - Mock Ayarları**'nda ayarladığınız **Mock yöntem önceliği**'ne geri döner. Burası, Akıllı mock'un (ve ona bağlı herhangi bir mock komut dosyasının) yanıtı ürettiği katmandır.

Zihinsel model basittir: önce belirli kurallar, sonra üretilen veriler. Beklentilerinizi en spesifik olandan en aza doğru sıralayın, garantili bir eşleşme istiyorsanız en altta boş koşullu bir her şeyi yakalayan kural tutun ve geriye kalan her şeyi Akıllı mock'un halletmesine izin verin. Her bir katmana ne zaman güveneceğinize dair daha derin bir tur için, API mock'lama kullanım senaryoları kılavuzu yaygın senaryoları özelliklere eşler.

Yayınlamadan önce bilmeniz gereken tuzaklar

Birkaç kısıtlama, kafa karıştırıcı bir hata ayıklama oturumundan sizi kurtaracaktır:

• Parametre koşulları {{değişkenleri}} desteklemez. Apidog proje ve ortam değişkenleri mock beklentileri içinde kullanılamaz, bu nedenle koşullarınıza sabit değerler girin.
• Gövde parametresi koşulları yalnızca JSON'dur, XML değildir ve ad alanındaki JSON yolu aracılığıyla eşleştirilmelidir.
• Bir koşuldaki istek gövdesi formatı API belirtimiyle eşleşmelidir. Bir form-data uç noktası, JSON ile değil, form-data yerleşimiyle mock edilmelidir.
• Mock komut dosyalarında günlük kaydı işlevi yoktur, pm nesnesi kullanılamaz (test komut dosyalarından farklı bir yürütme ortamıdır) ve Apidog değişkenleri kullanılamaz. Komut dosyası mantığını kendi içinde tutun.

Bu özelliklerin hiçbiri dokümanlarda plan sınırlaması taşımaz. Tek yerel-bulut ayrımı işlevseldir: daha önce açıklanan ortam başına bağımsız açma/kapama düğmesi, bir ödeme duvarı değil.

İş akışını Apidog CLI ile otomatikleştirin

Apidog'da mock'lama bir GUI ve bulut yeteneğidir. Mock motoru, uç noktalarınızı yerel ve bulut mock URL'lerinden sunar ve çalışan bir mock sunucusunu ayağa kaldıran bir CLI komutu yoktur. Apidog CLI'ın eklediği şey, bu mock'ların oluşturulduğu kaynaklar üzerindeki kontroldür.

Mock yanıtları uç nokta şemasından üretilir, bu nedenle mock'unuzun doğruluğu, spesifikasyonunuzun doğruluğunu takip eder. CLI ve onu yönlendiren yapay zeka kodlama ajanları (Cursor, Claude Code, Trae, Codex), projenizdeki uç noktaları ve şemaları oluşturabilir ve güncelleyebilir. Sözleşmeyi kodda değiştirin, senkronize edin ve mock çıktısı, kimsenin uygulamayı yeniden açmasına gerek kalmadan doğru kalır.

Mock ön uç çalışmasını çözdükten sonra, aynı projenin test senaryoları, mock'un tanımladığı sözleşmeye karşı gerçek arka ucu doğrulamak için CI'da başsız olarak çalışır:

apidog run -t <scenario_id> -e <env_id> -r cli

Bu tek komut, test senaryolarınızı yürütür ve sonuçları raporlar, böylece mock ve doğrulama tek bir doğruluk kaynağını paylaşır. Apidog CLI kurulum kılavuzu kurulumu kapsar ve GitHub Actions'taki Apidog CLI rehberi onu bir işlem hattına bağlar.

Sıkça Sorulan Sorular

Koşul doğru görünse bile beklentim neden göz ardı ediliyor? Neredeyse her zaman sıralama veya format uyumsuzluğu. Beklentiler yukarıdan aşağıya doğru değerlendirilir ve ilk eşleşme kazanır, bu nedenle belirli bir kuralın üzerinde yer alan geniş, boş koşullu bir kural isteği yutacaktır. Ayrıca gövde formatının spesifikasyonla eşleştiğini doğrulayın (JSON gövdeleri için JSON yolu, form uç noktaları için form-data yerleşimi). Yeniden kontrol etmek isterseniz API mock'lama genel bakışı kurulum temellerini kapsar.

Aynı yanıt üzerinde bir mock komut dosyası ve bir mock beklentisi kullanabilir miyim? Hayır. Mock komut dosyaları yalnızca Akıllı mock ile çalışır. Mock beklentileri ve yanıt örnekleri tarafından göz ardı edilirler. Bir beklenti eşleşirse, komut dosyası asla yürütülmez, bu nedenle uç nokta başına bir yaklaşım seçin: kural tabanlı dallanma için beklentiler, hesaplanmış çıktı için komut dosyaları.

Varsayılan 200'ü bozmadan nasıl 401 veya 500 döndürebilirim? İstemciden kontrol ettiğiniz bir koşula sahip (bir başlık iyi çalışır) özel bir beklenti ekleyin, ardından Daha Fazla sekmesini açın ve HTTP Durum Kodunu ayarlayın. Varsayılan yanıt 200 olarak kalır; hata yalnızca koşul eşleştiğinde tetiklenir.

Koşullar ortam değişkenlerimi kullanabilir mi? Hayır. Apidog {{değişken}} değerleri mock beklentileri içinde kullanılamaz ve parametre koşulları {{değişkenleri}} desteklemez. Koşullarda sabit değerler kullanın.

Hiçbir beklenti eşleşmezse ne olur? Apidog, Akıllı mock'un şemanızdan bir yanıt ürettiği Proje Ayarları - Özellik Ayarları - Mock Ayarları'ndaki Mock yöntem önceliğine geri döner. Bunun yerine belirli bir geri dönüşü garanti etmenin yolu, boş koşullu bir her şeyi yakalayan beklenti eklemektir.

Özetliyor

Akıllı mock, yaygın durumu ele alır ve mock beklentileri, içinde bir 'eğer' bulunan her şeyi ele alır: bilinen bir kullanıcı için 200, aksi takdirde 401, duruma göre farklı bir sipariş gövdesi, isteğe bağlı 500. Hesaplanan çıktıya ihtiyacınız olduğunda ve kuralların bunu ifade edemediği durumlarda yalnızca bir mock komut dosyasına başvurun ve yalnızca Akıllı mock'a karşı çalıştığını unutmayın. Öncelik sırasını (önce belirli beklentiler, sonra üretilen veriler) aklınızda tutun, böylece mock'larınız gerçek API'lerin yaptığı gibi dallanacaktır. İlk koşullu mock'unuzu oluşturmak için Apidog'u ücretsiz indirin, kredi kartı gerekmez.