Giderek büyüyen handler imzası: minimal API'lerde [AsParameters] kullanımı
Bir ASP.NET Core minimal API endpoint'inde query parametreleri altıya çıkınca handler imzası okunamaz hale geliyor ve enjekte edilen servisler kalabalıkta kayboluyor. Yazar, gevşek parametreleri [FromQuery] nitelikli bir record struct içinde toplayan [AsParameters] özelliğini anlatıyor; curl yanıtlarını ve üretilen OpenAPI dokümanını karşılaştırarak istemci tarafında hiçbir şeyin değişmediğini gösteriyor.
Kilit noktalar
- `[AsParameters]` ile gevşek query parametreleri `[FromQuery]` nitelikli tek bir `record struct` içinde toplanır.
- Handler iki argümana iner: istek modeli ve enjekte edilen servis, böylece pozisyonel argümanların karışması riski azalır.
- İstemci sözleşmesi değişmez: aynı query string aynı yanıtı verir ve OpenAPI dokümanında parametreler yine düz listelenir.
- Gruplanmış sürümde parametre adları record property'lerinden geldiği için PascalCase olur; binding büyük/küçük harfe duyarsızdır.
- Yaklaşık dörtten fazla query parametresi olduğunda veya iki endpoint aynı filtre şeklini paylaştığında kullanılması öneriliyor.
- Maliyeti: endpoint'in kabul ettiği parametreleri görmek için ayrı bir tipi açmak gerekir.
Yazar, ürün arama endpoint'ine sıralama yönü eklerken handler'ın altı gevşek parametreye ulaştığını ve `ProductCatalog` gibi enjekte edilen servislerin kalabalık içinde kaybolduğunu fark ediyor. Çözüm, query değerlerini `[FromQuery]` ile işaretlenmiş bir `record struct` içinde toplamak ve handler'da `[AsParameters]` ile tek argüman olarak almak; geriye istek modeli ve dependency kalıyor.
İki endpoint aynı query string ile birebir aynı yanıtı veriyor; üretilen OpenAPI dokümanında da altı parametre query'de düz şekilde listeleniyor. Tek görünen fark, isimlerin record property'lerinden geldiği için PascalCase olması; binding harf duyarsız olduğundan mevcut küçük harfli çağrılar bozulmuyor. Yazar bunu yaklaşık dört parametreden sonra öneriyor; maliyeti ise kabul edilen parametreleri görmek için ayrı bir tipi açmak.
Gerçek dünyada kullanımı
- Ürün arama, listeleme veya raporlama endpoint'lerinde filtre, sıralama ve sayfalama parametreleri birlikte büyüdüğünde
- Aynı filtre şeklini paylaşan birden fazla endpoint'i (örneğin ürün ve sipariş aramaları) tek bir tip üzerinden beslemek
- Enjekte edilen servis ile istek değerlerinin karıştığı handler'larda parametre sırası hatalarını önlemek
Neden önemli
Bu, davranışı değil okunabilirliği değiştiren bir refactor: endpoint imzası sadeleşir ve pozisyonel argüman karışıklığından kaynaklanan sessiz hatalar azalır, istemciler ise hiçbir şeyin değiştiğini görmez.