Sipariş arama, müşteri arama ve sipariş önizlemesi sunuyorsunuz. Birinin hatası {"error":"..."}, diğerinin {"message":"..."}, üçüncünün ise başka bir biçimde dönmesi, istemciyi üç ayrı hata okuyucu yazmaya zorlar. Ortak bir model kullanırsanız istemci aynı alanları okuyabilir; hatanın nedeni yine kendine özgü bir kodla anlaşılır.
Ortak hata projesini indir ve içe alma adımlarını izleyin. Proje kimliği help-shared-errors olur. Bu örnekte tek proje içinde üç HTTP işlemi vardır; günlük konuşmada “üç API” dediğiniz şey burada üç operation’dır.
Önce üç farklı hatayı görün
Run sonrasında API design → Try it → Running project kullanın. Accept → No preference seçin; POST gövdesi için application/json kullanın.
| İşlem | Girdi | Sonuç |
|---|---|---|
getOrder · GET /orders/{orderId} | orderId = ORD-9999 | 404, ORDER_NOT_FOUND |
getCustomer · GET /customers/{customerId} | customerId = C-999 | 404, CUSTOMER_NOT_FOUND |
previewOrder · POST /orders/preview | {"customerId":"C-100","quantity":21} | 422, ORDER_LIMIT |
İlk isteğin gövdesi şöyledir:
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"code": "ORDER_NOT_FOUND",
"detail": "The demonstration order was not found."
}Diğer iki sonuçta da aynı alanlar bulunur. Değişenler durum, iş kodu ve açıklamadır. HTTP durum kodunu ve Content-Type: application/problem+json değerini de kontrol edin. Gövdede status: 404 yazmak, HTTP yanıtını tek başına 404 yapmaz; route ikisini birlikte ayarlar.
Başarıyı da deneyin: ORD-1001 ve C-100 mevcut gösterim kayıtlarıdır. Önizlemeye {"customerId":"C-100","quantity":3} gönderirseniz 200 ve total: 75 alırsınız. Hiçbir deneme sipariş kaydetmez.
Paylaşım üç ayrı yerde yapılır
| Paylaşılan şey | Projede nerede? | Sağladığı fayda |
|---|---|---|
| Hata gövdesinin modeli | components.schemas.Problem | Alan adlarını ve türlerini bir kez tanımlarsınız. |
| Response açıklaması ve içerik türü | components.responses.BadRequest, NotFound, BusinessRule | Aynı yanıt tanımını her operation’da yeniden yazmazsınız. |
| Gerçek iş hatasını yazan adımlar | problem.camel.yaml içindeki direct:writeApiProblem | JSON üretimini ve HTTP header ayarlarını bir yerde tutarsınız. |
Şemayı paylaşmak, route kodunu paylaşmış olmanız anlamına gelmez. Route’u paylaşmak da OpenAPI belgesini otomatik güncellemez. Bu üç tanımın birbiriyle uyumunu gerçek çağrılarla kontrol edeceksiniz.
Sözleşmedeki referans zinciri
API design → Source içinde getOrder işleminin responses alanını bulun. Aşağıdaki parça yalnızca referans zincirini gösterir; tam belge ZIP içindedir:
{
"404": {"$ref": "#/components/responses/NotFound"}
}Bu referans components.responses.NotFound tanımına gider:
{
"description": "The requested demonstration resource does not exist. The code identifies the resource kind.",
"content": {
"application/problem+json": {
"schema": {"$ref": "#/components/schemas/Problem"}
}
}
}getCustomer ve previewOrder da aynı NotFound tanımını kullanır. BusinessRule başka bir açıklama ve durum için kullanılsa da yine Problem şemasını gösterir. Böylece aynı modelden yararlanmak için her hatanın açıklamasını aynı yapmak zorunda kalmazsınız.
Form → Components → Schemas → Problem içinden alanları inceleyin. type, title, status bu örneğin ortak zorunlu alanlarıdır. code, detail ve errors ise isteğe bağlıdır. Bu biçim HTTP Problem Details yaklaşımını kullanır; iş kodu ve doğrulama ayrıntıları uygulamaya ait ek alanlardır.
Çalışan ortak akış
Source → Files → api.camel.yaml içinde her iş hatası dalı dört exchange property ayarlar: problemStatus, problemTitle, problemCode, problemDetail. Ardından To → direct:writeApiProblem çağrısı gelir.
problem.camel.yaml dosyası bu değerlerden gövdeyi oluşturur:
[type: 'about:blank',
title: exchange.getProperty('problemTitle', String),
status: exchange.getProperty('problemStatus', Integer),
code: exchange.getProperty('problemCode', String),
detail: exchange.getProperty('problemDetail', String)]Akış HTTP durumunu CamelHttpResponseCode, içerik türünü Content-Type ile ayarlar; Marshal → Jackson nesneyi JSON’a çevirir. Metin birleştirmek yerine JSON serileştirmesi kullanmak, açıklamadaki tırnak ve satır sonlarını doğru yazmayı sağlar.
Content-Type ayarını dosyada Marshal’dan sonra göreceksiniz. Jackson serileştirmesi içerik türünü application/json yapabildiği için hata yanıtının application/problem+json değerini en sonda uyguluyoruz. Yalnızca gövdenin doğru görünmesi bu ayrıntıyı doğrulamaya yetmez.
Bu Direct çağrısı aynı runtime içinde çalışır ve sonucu çağıran akışa döndürür. Ayrı bir HTTP servisi veya kuyruk değildir. writeApiProblem, paths altında tanımlanmadığı için dışarıya açılan dördüncü bir API işlemi olmaz.
Şema hataları neden farklı alanlar içeriyor?
getOrder işlemine orderId = bad-id gönderin. Beklenen biçim ORD- ve dört rakamdır; istek 400 ile reddedilir. Önizlemeye quantity: 0 göndermek de bir sözleşme hatasıdır.
Bu yanıtları iş route’undaki ortak akış üretmez. Lunex’in request doğrulaması, iş mantığına girmeden reddeder ve errors listesinde konum, kural ve açıklama verir. Bu nedenle Problem içinde code zorunlu değildir: native 400 yanıtında iş kodu aramayız.
| Durum | Hatanın sahibi | İstemci neyi okur? |
|---|---|---|
| Kimliğin biçimi yanlış; miktar eksik veya sınır dışında | Request doğrulaması | HTTP durumunu ve errors[].location, rule, message alanlarını. |
| Biçim doğru ama gösterim kaydı bulunamadı | İş route’u | 404, code, detail. |
| Müşteri mevcut, miktar sözleşmeye uygun ama iş limiti aşıldı | İş route’u | 422, ORDER_LIMIT. |
code alanını bütün hatalar için Required yaparsanız gerçek 400 yanıtıyla sözleşmeniz çelişir. Response modeli tanımlamak otomatik response doğrulamasını açmaz; bu çelişkiyi yakalamak için gerçek yanıtları modelle karşılaştırmanız gerekir.
Bir değişiklik yapın, etkisini ölçün
1. Yalnızca şemaya alan ekleyin
Problem şemasına supportReference adlı, isteğe bağlı string alan ekleyin. Save → Reload sonrası üç iş hatasını yeniden gönderin.
Beklenen sonuç: gerçek gövdelerde yeni alan yoktur. Yeni şema “bu alan bulunabilir” der; bir değer üretmez. Alanı Required yapsaydınız route’ların karşılamadığı bir söz vermiş olurdunuz.
2. Ortak akışı değiştirin
problem.camel.yaml içindeki Groovy map’e supportReference: 'DEMO-HELP' ekleyin. Mevcut son alanın ardından virgül koymayı unutmayın. Dosya Saved olduktan sonra Reload yapın.
Beklenen sonuç: sipariş 404, müşteri 404 ve limit 422 gövdelerine aynı alan eklenir. Üç operation’ın hata üreten dallarını ayrı ayrı düzenlemediniz. quantity: 0 için native 400 yanıtında bu alan yine bulunmaz; bu da alanı isteğe bağlı tutmamızın nedenidir.
Deneme bittiğinde eklediğiniz alanı şemadan ve route’tan kaldırıp Save → Reload yapın. Asıl dosyalar indirdiğiniz ZIP’te bulunur.
Kendi projenize taşırken
Ortak hata yapısını koruyun; her farklı iş durumu için açıklayıcı, kararlı kod seçin. İstemci kararını detail metninin birebir eşleşmesine bağlamasın. Metni iyileştirdiğinizde iş davranışı değişmemelidir.
Bu örneğin kapsadığı yanıtlar 400, 404 ve 422’dir. Kimlik doğrulama reddi gateway’den, beklenmeyen bir teknik hata başka katmandan gelebilir. Her yanıtın JSON veya Problem olacağını varsaymadan önce HTTP durumunu ve içerik türünü okuyun. Gerçek sistemde ele alacağınız teknik istisnaları hata yönetimi ile ayrıca tasarlayın.
Üç işlem ayrı Lunex projelerindeyse buradaki yerel $ref onları birbirine bağlamaz. Referans # ile başlayan aynı OpenAPI belgesinin içindedir. Ortak sözleşme standardınızı her projede tutarlı uygulayın; başka dosya veya URL referanslarını desteklenen tek belgeye toplayın. Aynı dosyadaki tekrar kullanım ile projeler arasında ortak sürüm yönetimi farklı işlerdir.