Bir şey beklediğiniz gibi çalışmadığında çoğu zaman eksik olan yeni bir ayar değil, hangi katmanın ne yaptığını ayırmaktır. Aşağıdaki sorular indirilebilir örnekler üzerinde de denenebilir.
OpenAPI dosyasını yükledim. Servisim hazır mı?
Çağrının sözleşmesi hazırdır. Her operation için iş mantığını taşıyan direct:<operationId> consumer’ı da gerekir. Örneğin operationId: getOrder, direct:getOrder girişine bağlanır. Route dosyasının adının getOrder olması bu bağı kurmaz. Run/Reload ve gerçek istekle çalışmayı doğrulayın. Operation ve route bağı hangi isimlerin nerede kullanıldığını gösterir.
Aynı hata şemasını kullanınca üç işlem aynı hatayı mı döndürür?
Aynı biçimi kullanırlar; nedenleri ve değerleri farklı olabilir. ORDER_NOT_FOUND ile CUSTOMER_NOT_FOUND aynı Problem modeli içinde ayrı kodlardır. Hatta bu gövdelerin gerçekten ortak biçimde üretilmesini de route’ta sağlamanız gerekir. Ortak hata projesi bunun iki tarafını birlikte gösterir.
Request doğrulandıysa Unmarshal neden gerekiyor?
Doğrulama, verinin sözleşmeye uygunluğunu kontrol eder. Route’un body değerini otomatik olarak iş nesnesine dönüştürdüğünü varsaymayın. JSON alanlarıyla hesap yapacağınız örnekte Unmarshal → Jackson, sonucu JSON’a yazarken Marshal → Jackson kullanılır. Sipariş önizlemesindeki adımları izleyin.
Şemaya alan ekledim. Yanıtta neden yok?
Response schema alanı tarif eder, üretmez. Route’un döndürdüğü nesne veya metin de güncellenmelidir. Aynı biçimde şemayı değiştirmek response doğrulamasını otomatik etkinleştirmez. Özellikle Required alanlarda gerçek yanıtı kontrol edin. Ortak hata örneğindeki supportReference deneyi bu farkı gösterir.
Mock başarılı. Gerçek isteğin de başarılı olacağını söyleyebilir miyim?
Mock, sözleşmedeki örnek veya üretilen örnek gövdeyi gösterir; route’u ve dış sistemi çalıştırmaz. Sipariş önizlemesinde miktarı 2 yerine 3 yapın. Mock açık örnekteki 50 değerini koruyabilir; çalışan route 75 hesaplar. Sonuç kaydınızda hangi hedefi kullandığınızı belirtin.
Save yaptım ama davranış değişmedi. Nereden başlayayım?
Önce Save’in tamamlandığını kontrol edin. Sayısal schema alanından Tab ile çıkmadıysanız değer bekleyen düzenleme olarak kalabilir. Sonra Reload ile geliştirme runtime’ına uygulayın ve Running project hedefinde aynı isteği tekrarlayın. Hâlâ eski sonucu görüyorsanız doğru proje, operation ve runtime’ı incelediğinizden emin olun. Kalıcı deployment’ın değişmesi için kendi build ve dağıtım adımları gerekir.
Müşteri bulunamadı. Bu 400 mü, 404 mü olmalı?
Ortak hata örneğinde bad-id şemanın beklediği biçime uymadığı için 400; C-999 doğru biçimli ama bulunmayan müşteri olduğu için 404 döner. Bu, örneğin bilinçli tasarım kararıdır. Kendi API’nizde sözleşmeye ve işlemin anlamına uygun durum seçin; istemcinin hangi girdiyi düzelteceğini açıklayın. Her başarısızlığı tek bir “hata oldu” gövdesine indirgemeyin.
Path parametresini URL’nin tamamı olarak mı girmeliyim?
Try it içinde orderId alanına yalnızca ORD-1001 yazın; /orders/ORD-1001 veya origin eklemeyin. Operation yolu ve taban adresi ayrı belirlenir. Dış istemci için bütün adresi projenizden kopyalayın. Örnek ZIP kimliğiyle elle oluşturduğunuz projenin kimliği farklı olabilir.
API exposure kapalıyken Try it neden çalışıyor?
Running project, geliştiricinin çalışan projeyi denediği hedeftir. API exposure, dışarıya sunulan API erişimini yönetir. Örnek ZIP’ler ilk deneme için dış erişimi kapalı getirir. API access hazırlığı ve gerçek gateway çağrısı için erişim rehberine geçin.
JWT seçersem kullanıcının her müşterinin siparişini görmesini engeller miyim?
Token’ın kabul edilmesi ile belirli kayda erişim hakkı ayrı kontrollerdir. Siparişin hangi kullanıcıya veya kuruma ait olduğunu bilmek ve bu ilişkiyi denetlemek iş tasarımınızın parçasıdır. URL’deki customerId değerini kimlik kanıtı saymayın. Kimlik doğrulama ve yetkilendirme bölümünü bu ayrım için okuyun.
Kod ürettirirken veya birinden yardım isterken ne vermeliyim?
Yalnızca “sipariş API’si yaz” demek önemli kararları belirsiz bırakır. Bir çalışma arkadaşına veya yapay zekâya mevcut sözleşmeyi, Direct girişlerini, istediğiniz sonucu ve çalıştırma bağlamını verin. Gerekli dosyaları paylaşırken credential değerlerini dışarıda bırakın. Ajanla geliştirilen projelerde beklenen sonuçların kalıcı yeri projenin kabul listesi, yani acceptance.md dosyasıdır; aşağıdaki “Beklenenler” gibi satırlar orada tutulur ve değişiklikle birlikte güncellenir.
Aşağıdaki örnek, ortak hata projesinde somut bir değişiklik istemek içindir:
Lunex'te help-shared-errors örneğini düzenliyorum.
Mevcut openapi.json, api.camel.yaml ve problem.camel.yaml dosyaları ekte.
Amaç: previewOrder için en çok 10 birim kabul etmek.
Miktarın JSON türü integer kalacak. Şema hâlâ 1–100 kabul edecek;
10 sınırı bu örneğin iş kuralı olacak.
Bağ: POST /orders/preview → operationId previewOrder → direct:previewOrder.
Ortak iş hatası direct:writeApiProblem tarafından yazılıyor.
API exposure kapalı; Try it → Running project ile deniyorum.
Beklenenler:
- C-100, quantity 10 → HTTP 200, total 250.
- C-100, quantity 11 → HTTP 422, code ORDER_LIMIT.
- C-100, quantity 0 → native HTTP 400 ve errors listesi.
- Diğer iki operation'ın mevcut sonuçları korunacak.
İlgili route'u, sözleşmenin açıklama/örneklerini ve deneme listesini
birlikte güncelle. Dosyaları kaydettikten sonra Reload yapacağım.
Projede olmayan bir bağlantı, veri deposu veya API ayarı varsayma.Bu istek, “maksimumu 10 yap” cümlesindeki belirsizliği giderir: şemadaki Maximum mu, iş kuralı mı? İkisinin hata sonucu farklıdır. Üretilen değişikliği yalnızca açıklamasından değerlendirmeyin; yazdığınız kabul örneklerini gerçek hedefte çalıştırın.
Sorun bildiriyorsanız beklenen ve gelen sonucu da ekleyin. Faydalı bir kayıt; proje ve operation, Mock/Running project seçimi, son Save/Reload durumu, gönderilen örnek girdi, HTTP kodu, içerik türü ve hata gövdesini içerir. “Çalışmıyor” yerine “Running project’te quantity 11, Reload sonrasında hâlâ 200 dönüyor” demek incelemeyi doğrudan doğru yere taşır.