Burak Selim Şenyurt

Birlikte OCaml Öğrenelim

2026-04-17T21:28:00+00:00

İlk programlama dilinden bu zamanlara değişen çok şey var. Üniversite yıllarım kişisel bilgisayarların ve internetin yaygınlaştığı World Wide Web devrimine denk geliyor. O vakitler bölümde gösterilen bilgisayar programlama derslerini düşünüyorum da; GW-Basic, Cobol, C ve C++ ... Çoğunda belli seviyeye kadar geldiğimizi anımsıyorum. Aynı yıllarda iş dünyasının hızlandırıcı etkisine de şahit olmuştuk. Sadece klavye ve 8 renkten oluşan siyah terminal ekranları çok uzun zamandır mouse imleçleri ile renklenmişti. Dahası artık iş süreçlerinin internet ortamından yürütülebildiği bir dönemdi. Bu dalgayla birlikte ben ve birçok arkadaşım Delphi, Java, Visual Basic gibi dillere yöneldi. Ben ağırlıklı olarak Delphi tarafına yakındım ama zamanla bu yakınlık yerini C# programlama diline bıraktı.

Anılar bir kenara dursun, yıllarca popüler dillerle uygulama geliştirmenin ardından gelen bir farkındalık, araçlara değil, o araçları var eden felsefeye odaklanmam gerektiğini öğretti. Bazı programlama dillerini iş amaçlı kullanmak için değil, atası olduğu diğer dillere kattığı özellikleri düşünerek çalışmak gerekiyor. Örneğin uzun süre uğraştığım ve sahada deneyimleme şansını çok bulamadığım için şimdilerde paslandığım Rust programlama dili, atası sayılabilecek OCaml dilinden birçok özellik almıştı(Güçlü tip sistemler, cebirsel veri tipleri - algebraic data types, hata payını azaltan örüntü eşleştirme - pattern matching, options vb) Benzer şekilde Scala, F# ve bugünlerde dikkat çeken Rocq, Gleam gibi dillere de OCaml ilham vermişti. OCaml ile herhangi bir proje geliştirmeyeceğim veya onu iş yerinde kullanmayacağım ama fonksiyonel dil paradigmasını anlamak, bir derleyicinin ya da yorumlayıcının nasıl yazıldığını temelden öğrenmek ve birçok dilin OCaml üzerinden aldığı kabiliyetleri kavramak için geç de olsa çalışmalıyım(Sen bu yazıyı okuyan bir üniversite talebesi isen, bence sen de OCaml veya benzeri bazı dilleri iyice öğrenmeye çalışmalısın.)

F# programlama dilinin tam bir türevi olduğu, Rust'ın tip güvenliği felsefesini benimsediği ve hatta ilk derleyicisinin OCaml ile yazıldığı düşünüldüğünde; OCaml öğrenmek modern programlama dillerinin genetik kodunu çözmek demektir.

Sözün özü bu tamamen kendi zihinsel yatırımım ve itiraf etmeliyim ki bu yatırımı ellili yaşlarımda değil de yirmili yaşlarımda değerlendirmem gerekirdi.

Merak Ettiklerim

İşe bu dil ile ilgili merak ettiğim sorulara bulduğum yanıtlarla başlamak isterim.

OCaml ismi nereden geliyor?: OCaml, "Objective Caml" ifadesinin kısaltması. Caml(Categorical Abstract Machine Language) diline nesne yönelimli programlama özelliklerinin eklenmiş bir versiyonu olarak düşünebiliriz ve evet, logosunda elbette ki deve var :D
Geliştiricileri kim?: INRIA(Institut National de Recherche en Informatique et en Automatique - Ulusal Bilgisayar Bilimi ve Otomasyon Araştırma Enstitüsü)'dan Xavier Leroy, Jérôme Vouillon, Damien Doligez ve Didier Rémy tarafından geliştirilmiş. Fransızlar tarafından geliştirildiği için söz dizimine yer yer Fransız kaldığım da olmadı değil :D
İlk versiyonu ne zaman çıktı?: Kaynaklara göre ilk sürüm 1996 yılında piyasaya sürülmüş. Dokümanı yazdığım an itibariyle de son sürümü 2025-10-09 tarihinde yayınlanmış olan 5.4.0 versiyonu. Son sürümde immutable diziler, labelled tuple türleri, atomik record alanları gibi yeni özellikler eklenmiş.
Dilin kullanım amacı:Genel amaçlı bir programlama dili olduğunu düşünebiliriz zira nesne yönelimli olma hali ve fonksiyonel dil özellikleri ile birlikte pragmatik yaklaşımları içeriyor. Genelleştirilmiş çöp toplayıcısı(Garbage Collector), birinci sınıf fonksiyonlar(First Citizen Functions), statik tür sistemi(Static Type System), immutable programlama taktikleri, tip çıkarımı(Type Inference), cebirsel veri türleri(Algebraic Data Types), örüntü eşleştirme(pattern matching) ve daha birçok özelliği destekleyen bir dil.
Hangi dillerden esinlenmiş: Sahip olduğu özellikler de düşünüldüğünde Caml başta olmak üzere, C, Pascal, Modula-3 ve Standard ML dillerinden esinlenildiği belirtiliyor.
Hangi dillere esin kaynağı olmuş: Bir tanesi Rust ki ben de uğraştığım için biliyorum. Wikipedia kayıtlarına göre OCaml'dan etkilenen diğer diller arasında Rocq, F#, Scala, Gleam gibi popüler diller de var.
OCaml ile kendi programlama dilini yazabilir miyim?: Teorik olarak evet, OCaml güçlü bir dil ve kendi dilinizi yazmak için gerekli araçları sağlayabilir. Zaten Rust'ın ilk sürümü bildiğim kadarıyla OCaml ile yazılıyor.
- Hangi kaynaklardan öğrenebilirim?: Real World OCaml, Functional Programming for the Masses, Anıl Madhavapeddy, Yaron Minsky, Cambridge University Press heybetli bir kitap. Gerçekten yirmili yaşlarımda olmam gerekiyor :D Bunun yanında Cornell Üniversitesinden Michael Ryan Clarkson'ın 2021 yılında yayınladığı OCaml Programming: Correct + Efficient + Beautiful kursunu da tavsiye ederim. Ben 25 yıl kadar geç başlıyorum bazı şeylere doğrudur :D Ayrıca bu yayına ait güzel bir kitap da var.

Kurulumlar

İlk olarak resmi OCaml web sitesinden gerekli kurulumları yapmak lazım. Ayrıca VS Code editörüne OCaml eklentisini yüklemekte yarar var.

Windows 11 Tarafında Sorun

Windows 11 işletim sisteminde gerekli kurulumları yapmış olmama rağmen komut satırından ocaml ile kod çalıştırmakta sorun yaşadım. Bunun kalıcı çözümü içinse aşağıdaki komutu işlettim.

Add-Content $PROFILE "`n# Initialize opam environment`n(& opam env) -split '\r?\n' | ForEach-Object { Invoke-Expression `$_ }"

#Sonrasında PowerShell'i yeniden başlattım
#Kısa bir versiyon kontrolü yaptım
ocaml -version

#ve örneğin hello-world.ml dosyasını doğrudan aşağıdaki komutla çalıştırabildim
ocaml hello-world.ml

#OCaml'ı interaktif modda kullanmak için ise aşağıdaki komutu kullanmak yeterli
ocaml

İşte ilk programın çıktısı,

WSL Tarafında Ubuntu Üzerinden Çalışmak

Nedense bu tip dilleri çalışmak için en uygun platform Linux ortamı sanırım(Emektar Ubuntu sistemim Westworld tavan arasında ama Windows'ta WSL ile bir ubuntu üzerinde çalışmak mümkün) Ben tüm çalışmalardan sonra konu tekrarları için WSL üzerinden ilerlemeye karar verdim. Hali hazırda WSL üzerinde bir Ubuntu sürümüm yüklü. Ancak değilse de,

wsl --install -d Ubuntu
# ile ubuntu'yu yükleyebiliriz.

OCaml kurulumları içinse aşağıdaki adımları takip etmek gerekiyor.

# Öncelikle apt paket yöneticisini güncelleyelim
sudo apt update
# Şimdi de apt software paketlerini güncelleyelim
sudo apt upgrade -y
# İşimize yarayacak bazı paketleri de yükleyelim
sudo apt install -y zip unzip build-essential

sudo apt install opam
opam init --bare -a -y
# Bir ihtimal opam'ın update edilmesine dair bir uyarı gelebilir. O vakit,
opam update

# Güncel bir OCaml sürümü ile çalışmak için aşağıdaki komutu kullanarak bir switch oluşturabiliriz
opam switch create ocaml-5.3 ocaml-base-compiler.5.3.0
# Terminalimizin yeni switch'i tanıması için aşağıdaki komutu çalıştırmakta fayda var
eval $(opam env)
# switch listesini görmek için
opam switch list

# Şimdi opam için gerekli paketleri yükleyelim
opam install -y utop odoc ounit2 qcheck bisect_ppx menhir ocaml-lsp-server ocamlformat

# Şu noktada ocaml universal TopLevel aracı olan utop'u kullanarak interaktif bir şekilde OCaml kodu yazabiliriz
utop

Eğer her şey yolunda giderse ubuntu ortamında utop ile doğrudan ocaml kodlamaya başlanabilir. Mesela,

# 3.1415;;
- : float = 3.1415
# #quit;;

Giriş Seviyesi

Aşağıdaki kod örnekleri için komut satırından ocaml komutu çalıştırılarak ilerlenebilir. Ayrıca utop aracı ile de çalışılabilir. Bu ikisi özellikle yazılan kodun anında çalıştırılması ve sonuçların görülmesi açısından faydalı araçlar. utop, daha gelişmiş özelliklere sahip bir TopLevel aracı olarak düşünülebilir ancak bir noktadan sonra ml uzantılı dosyalar üzerinden çalışmaya döndüğümü de belirtmek isterim. TopLevel bir nevi REPL(Read-Eval-Print Loop) aracı. Çok büyük çaplı olmayan kod parçalarını denemek için, özellikle dilin temel özelliklerini giriş seviyesinde öğrenirken oldukça kullanışlı bir araç. Yazılan bir ifadenin dil tarafından nasıl yorumlandığını anında gösteriyor.

Bazı Yararlı Utop Komutları

#help;; : Utop'ta kullanılabilecek komutları gösterir.
CTRL + L : Ekranı temizler. Bir noktadan sonra terminal ekranı çok kirlenirse silmek için ;)
#quit;; : Utop oturumunu sonlandırır.
#show {module_name};; : Belirtilen modülün içeriğini gösterir. Örneğin #show List;; komutu ile List modülünün içeriği görülebilir.
#use "filename.ml";; : Belirtilen dosyayı yükler ve içindeki kodu çalıştırır. Dosya uzantısı .ml olmalıdır. Örneğin aşağıdaki içeriğe sahip bir ml dosyamız olduğunu düşünelim. (Clarkson'un öğretisine bağlı kalarak WSL ortamında 3110 isimli bir klasör oluşturup içine bu dosyayı koydum)

let x : int = 3110;;
print_int x;;
print_string "Hello, world!\n";;

Basit aritmetik işlemler, değişken atamaları ve isimlendirmeler

Öyleyse ders notlarımıza başlayalım. İlk olarak float değerler ile ilgili aritmetik birkaç işleme bakalım. Deneyeceğim ifadeleri aşağıdaki kod bloğuna ekliyorum. Bunları utop aracından denersek çok faydalı olacaktır.

3.14 +. 2.1;;
10+2;;
10+.2;;
(* 
  Line 1, characters 0-2: 
  1 | 10+.2;;
      ^^
  Error: The constant 10 has type int but an expression was expected of type
          float
  Hint: Did you mean 10.?
*)
10. +. 2;;
(*
  Line 1, characters 7-8:
  1 | 10. +. 2;;
            ^
  Error: The constant 2 has type int but an expression was expected of type
          float
  Hint: Did you mean 2.?
*)
10. +. 2.;;
1_000_000 * 10_000;;
(2 * 5) <= 10;;
(2 * 6) <= 10;;
let xValue = 10;;
let y_value = 5;;
let result = xValue + y_value;;
let MaxUserCount = 8;;
(*
  Line 1, characters 4-16:
  1 | let MaxUserCount = 8;;
          ^^^^^^^^^^^^
  Error: Unbound constructor MaxUserCount
*)
let 7even = 7;;
(*
  Line 1, characters 4-9:
  1 | let 7even = 7;;
          ^^^^^
  Error: Invalid literal 7even
*)
let screen-width = 1024;;
(*
  Line 1, characters 11-16:
  1 | let screen-width = 1024;;
                ^^^^^
  Error: Syntax error
*)

;; ile toplevel'a ilgili satırın bir ifade olarak ele alınması, yani hemen çalıştırılması gerektiğini belirtmiş oluyoruz. (Evaluate Expression)
İki float değeri toplamak için +. operatörü kullanılmalı. Ayrıca float ve int toplanacaksa küsürat olmasa bile . işareti ile sayının float olarak ele alınacağı ifade edilmeli.
İfade çalıştırıldığında sadece sonuç değil tür bilgisi de dönülüyor.
Büyük sayılar _ karakteri ile daha okunabilir yazılabilir.
Değişkenleri let anahtar kelimesi ile tanımlayabilir, ilk değerleri atayabiliriz.
Değişken isimlendirme kurallarına göre büyük harfle, sayıyla başlayan değişken adları verilemez(MaxUserCount, 7even) gibi. Büyük harf kullanılmama sebebi, modül adlarının büyük harfle başlaması olabilir.
Hatta değişken isimlendirmelerinde - operatörü de kullanılamaz.

let'in Gücü ve Fonksiyon Tanımlamaları

Başka işlemlerle devam edelim. let çok güçlü bir operatör. Değişkenleri değerlere bağlayabildiğimiz gibi, fonksiyonları da iş yapan kod bloklarına bağlayabiliriz.

let total x y = x + y;;
total 1 5;;
total -5 5;;
(*
  Line 1, characters 0-5:
  1 | total -5 5;;
      ^^^^^
  Error: The value total has type int -> int -> int
        but an expression was expected of type int
*)
total (-5) 5;;
total 1.2 3.4;;
(*
  Line 1, characters 6-9:
  1 | total 1.2 3.4;;
            ^^^
  Error: The constant 1.2 has type float but an expression was expected of type
          int
*)
# total 128 (8 * 1024);;

Burada total isimli iki parametre alan ve varsayılan olarak int türünden değerleri toplayan bir fonksiyon tanımladık. Fonksiyon çağrılırken parametreler arasında parantez kullanımı önemli. Aksi halde eksi işareti operatör olarak algılanıyor. Ayrıca doğru türlerde işlem yapmak lazım. Yeni ifadelerle devam edelim;

let total_1 x y = x + y;;
let total_2 x y = (x * x) + (y * y);;
total_1 3 4 + total_2 5 1;;
let div x y = Float.from_int x / Float.from_int y;;
(*
  Line 1, characters 14-28:
  1 | let div x y = Float.from_int x / Float.from_int y;;
                    ^^^^^^^^^^^^^^
  Error: Unbound value Float.from_int
  Hint:   Did you mean Float.of_int or Float.to_int?
*)
let div x y = Float.of_int x / Float.of_int y;;
(*
  Line 1, characters 14-28:
  1 | let div x y = Float.of_int x / Float.of_int y;;
                    ^^^^^^^^^^^^^^
  Error: This expression has type float but an expression was expected of type
          int
*)
let div x y = Float.of_int x /. Float.of_int y;;
div 1 3 
;;
div 3.14 2. 
;;
(*
  Line 1, characters 4-8:
  1 | div 3.14 2.
          ^^^^
  Error: The constant 3.14 has type float
        but an expression was expected of type int
*)
div 3 2;;

div fonksiyonunun yorumlanma şekli dikkatinizi çekmiştir. int -> int -> float. Düşününce int,int -> float gibi bir şey yazar diye bekliyor insan değil mi?

Yukarıdaki örnekte, div isimli fonksiyonu tanımlamaya çalışıyoruz. Fonksiyondan beklenti int türünden gelen iki sayıyı bölmek ama bunları float türünden ele almasını sağlamak. İlk denemede kitaptaki fonksiyon adını unuttum ve of_int yerine from_int yazdım. Rust günlüklerim geldi aklıma, yorumlayıcı "acaba şunu mu demek istedin" derdi. Fonksiyonları düzelttikten sonra / operatörü ile /. arasındaki farka tosladım. float türler arasında bir bölme işlemi söz konusu olacağı için /. operatörünün kullanılması gerekiyormuş. Bölme operatörünün tipe özel versiyonlandığını ifade edebiliriz. Ayrıca Float bir OCaml modülüdür(Büyük harfle başlayan isimler modülleri ifade eder) ve bu modülün içinde of_int isimli bir fonksiyon var. Bu fonksiyonun görevi int türünden bir değeri float türüne çevirmek.

Burada rahatsız edici nokta belki de Float.of_int kullanımı olabilir ama bunu kolaylaştırmak için OCaml ekosisteminde yazılmış bir başka modül var. Bu modüldeki amaçlardan birisi float değerler ile çalışırken +., /. operatörleri yerine +, / ve \ ile de çalışabilmek ve bunu float-safe modda yapabilmek. Biz şu an için standart kütüphane ile devam edebiliriz. Ekosistemdeki diğer modüllere sonradan odaklanırız. Standart kütüphane aynı fonksiyonu aşağıdaki gibi yazmamıza da izin veriyor.

let div x y =
        float_of_int x /. float_of_int y
;;
div 1 5;;

Yine de Float.0 ile Çalışmak Gerekirse

Bir noktada Float.O ile çalışmak gerekirse şöyle ilerlemek gerekiyor. Öncelikle komut satırından utop başlatılır. Ardından, toplevel, Base modülünü destekleyecek şekilde başlatılır. Bu işlemin ardından ilgili fonksiyon yazılabilir. Aşağıdaki ekran görüntüsünü geleceğe not olarak bırakalım.

Burada dikkat edilmesi gereken bir nokta da Float.O ifadesindeki O'nun büyük harf O olduğudur. 0 (sıfır) değil :D

Gelecekten geldim :D WSL - Ubuntu tarafından da bir bakalım.

Zihin Yakan Bir Fonksiyon Kullanımı

Şimdi, int türünden değer dönen bir fonksiyonu parametre olarak alan ve diğer parametreden gelen int değer ile toplayan bir fonksiyon tanımlayıp çalıştıralım.

let more_add f x y = f * x + y;;
let square n = n * n;;
more_add (square 1) 1 1;;
more_add (square 2) 3 5;;

İlk olarak more_add fonksiyonuna bir bakalım. f harfinin bir fonksiyonu işaret ettiğini nereden anladı? Yorumlama kısmına baktığımızda int -> int -> int -> int şeklinde bir tanım var. `<fun\>` tabii ki bunun bir fonksiyon olduğunu ifade etmekte. f çıktısını x ile çarpıp y ile toplatıyoruz. Saçma bir fonksiyon ancak dinamiğini öğrenmek açısından kayda değer. Sonrasında square isimli bir fonksiyon daha tanımlıyoruz. Bu fonksiyon tek parametre alıyor ve karesini döndürüyor. Şimdi more_add fonksiyonunu çağırırken ilk parametre olarak square 2 ifadesini veriyoruz. Bu ifade 4 değerini döndürecek ve bu değer f parametresine bağlanacak. Sonrasında ise 3 ve 5 değerleri sırasıyla x ve y parametrelerine bağlanacak. Yani fonksiyonun işleyişi şu şekilde olacak, 4 * 3 + 5 = 12 + 5 = 17. Ancak asıl zihin yakıcı örnek kitaptaki örnekten esinlenilerek geliyor;

let condition f first_arg second_arg =
      (if f first_arg then first_arg else 0)
      +
      (if f second_arg then second_arg else 0);;
let check_point value = value > 50;;
condition check_point 28 76;;

condition isimli fonksiyonun kullandığı f parametresi bir fonksiyonu işaret etmekte ve bu fonksiyonun türü int -> bool. Yani bir int alıp bool döndüren bir fonksiyon. Peki yorumlayıcı buna nasıl karar verdi ya da bu tür tahminini(type inference) neye göre yaptı? Bunu anlamak için if koşuluna odaklanmakta fayda var. Nitekim else kısımlarında 0 değeri kullanılmakta ki bu bir int türü. Buna göre then kısımlarında da int türü döndüren ifadeler olmalı. Sonuç olarak f fonksiyonu int -> bool türünde bir fonksiyon olmalı.

OCaml uzmanlarına göre bu yazım stiline ve yorumlayıcının tip tahmini mekanizmasına alışmak zaman alabilir. Diğer yandan dilin çok güçlü bir yanını ispat eden bu yazım stiline alışamayanlar için Annotations yani tür açıklamaları ile fonksiyonları tanımlamak da mümkün. Aynı fonksiyonu aşağıdaki gibi de yazabiliriz.

let condition (f: int -> bool) (first_arg:int) (second_arg:int) : int =
      (if f first_arg then first_arg else 0)
      +
      (if f second_arg then second_arg else 0);;
let check_point value = value > 50;;
condition check_point 28 76;;

Fonksiyonlarda Generic Parametre Kullanımı

OCaml tür tahmini yapma konusundaki hünerini generic türler için de gösterir. Aşağıdaki ifadeleri deneyerek devam edelim.

let identity value = value;;
identity 1001;;
identity "PRD-0001";;
let swap (left,right) = (right,left);;
swap (4,"four");;

identity ve swap isimli fonksiyonlar tanımlandıktan sonra yorumlayıcının verdiği çıktılara dikkat edelim.(Açıkçası Rust'ı öğrenmeye başladığımda hem kavramsal olarak hem de sentaks olarak zorlandığım 'a - lifetime annotations konusu geldi aklıma) Her neyse, 'a ve 'b şeklinde yazılan ifadeler generic türler. Generic kavramına aşina olmayanlar için a ve b yerine herhangi bir tür gelebilir ve bunun için her bir türe özel olacak şekilde bu fonksiyonun farklı versiyonlarını yazmanıza gerek yoktur diyelim. Şimdi biraz daha kafa karıştırabilecek bir örnek.

let compare f arg_1 arg_2 = if f arg_1 then arg_1 else arg_2;;
let str_len string = String.length string > 8;;
compare str_len "Some..." "Something happens";;
let is_pass score = score > 70;;
compare is_pass 68 50;;
compare is_pass "Black" "And White";;
(*)
  1 | compare is_pass "Black" "And White";;
                      ^^^^^^^
  Error: This constant has type string but an expression was expected of type
          int
*)

compare isimli fonksiyonumuz bir fonksiyon alıp diğer iki argümanı da hesaba katarak bir if koşulu işletmekte. compare fonksiyonundaki parametrelerin generic 'a türü olarak yorumlandığına dikkat edelim. Sonraki adımlarda str_len ve is_pass isimli iki farklı fonksiyon daha tanımlanıyor. İlki, String modülünden length fonksiyonunu kullanarak bir değer döndürdüğü için string veri türü ile çalışacağı aşikar. Diğer fonksiyon ise sayısal bir karşılaştırma kullanıyor ve buna göre de int değerlerle çalışacağı anlaşılıyor. compare fonksiyonuna bu iki fonksiyonu parametre olarak verebiliriz ama devam eden argümanların da uygun tipler olması beklenir. Yani str_len kullanıyorsak diğer iki argümanın da string türünden olması gerekiyor.

Tuple, List ve Options veri türleri

İlk olarak tuple veri türü ile ilgili basit örneklerle ilerleyelim. Aşağıdaki ifadeleri deneyebiliriz.

let config = ("He-Man, Gölgelerin gücü adına",1920,1080,true);;
let (title,width,height,is_active) = config;;
let move (x,y) speed = (x + speed , y + speed);;
move (10,15) 1;;
let (new_x,new_y) = move (11,16) 5;;

config isimli değişken bir tuple veri yapısını işaret ediyor. Tuple veri yapısı farklı türden değerler içerebilen zengin bir model. İstersek tanımladığımız config isimli tuple içeriğini let ile başka değişkenlere çıkarabiliriz(export) Burada pattern matching özelliğinin olduğunu da görebiliriz. move isimli fonksiyon da dikkate değer. İki parametre alıyor ancak x ve y koordinatlarını ifade eden ilk parametreyi bir tuple olarak tanımlıyor. Ayrıca fonksiyondan geriye yine bir tuple türü dönmekte.

Kitapta tuple veri türü tanımında neden `*` şeklinde bir operatör kullanıldığı da vurgulanıyor. Yani bir tuple tanımlandığında yorumlayıcı bunu okurken string \* int \* int \* bool gibi bir ifade kullanıyor. Türlerin toplam kümesini işaret eden bir kartezyen çarpımı söz konusu olduğundan çarpım sembolü kullanılıyor diyebiliriz. Kıssadan hisse bugün kullandığım Rust, C# ve Zig gibi dillerden önce belki de işe OCaml ile başlamak gerekiyordu...

Eğer aynı türde verilerden oluşan bir listeye ihtiyacımız varsa, pekala List veri yapısını kullanabiliriz :D Aşağıda yine yaptığım denemelerin peşi sıra gelen ifadeleri yer alıyor. Üşenmeyip utop aracını açın, deneyin. Önemli olan ;; sonrasında OCaml yorumlayıcısının verdiği çıktıları görmek ve anlamaya çalışmak.

let colors = ["Red" ; "Green" ; "Blue"];;
let numbers = [1;2;3;4;5];;
let points = [0.40;0.25;0.55;0.45];;
let illegal = ["One";"Two";3;"Four"];;
(*
  Line 1, characters 27-28:
  1 | let illegal = ["One";"Two";3;"Four"];;
                                ^
  Error: The constant 3 has type int but an expression was expected of type
          string
*)
List.length colors;;
"Black" :: "White" :: colors;;
colors;;
let extended = "Black" :: "White" :: colors;;
extended;;
let another_list = [1,2,3,4,5,6];;
let origin = 0,0;;
"R","G","B";;
let left_side = [1;2;3];;
let right_side = [4;5;6;7;8];;
let combine = left_side @ right_side;;

colors, numbers ve points kendi veri türlerinde elemanlar taşıyan birer liste. illegal isimli liste ise farklı türden elemanlardan oluşan bir liste yapısı oluşturmak istediğimizde alacağımız hatayı üretiyor. OCaml'ın List modülünde bazı yardımcı fonksiyonlar da bulunuyor. Örnek kodlarda listenin uzunluğunu bulmak için List.length, liste başına eleman eklemek için :: operatörü(constructor operator) kullanılmakta. Dikkat edelim, orijinal liste değişmiyor! İlaveler sonrası yeni bir liste oluşuyor.

Çalışırken yaptığım hatalardan birisi de liste elemanlarını tanımlarken arada virgül kullanmaktı. Bunu yapınca bir liste yerine tek elemanlı bir tuple listesi oluşmakta. Dolayısıyla ; ile , kullanımına dikkat etmeli. Hatta bir tuple tanımlanırken parantez kullanmazsak, virgül ile ayrılmış değerler bir tuple olarak algılanıyor. @, yani add operatörünü kullanarak listeleri birleştirmek de mümkün.

Peki bir liste veri yapısında pattern matching kullanabilir miyiz? Basit bir örnek üstünden ele alalım.

let first_or_default values =
      match values with
      | first :: the_rest -> first
      | [] -> 0;;
first_or_default [];;
first_or_default [12;0;23;9;14];;

Burada tanımladığımız first_or_default isimli fonksiyon int türünden bir listenin ilk elemanını döndürüyor ancak pattern matching ile uyguladığımız bir koşul var. Boş bir liste verilirse varsayılan olarak 0 değerini döndürüyor; dolu bir liste gelirse, bunu first :: the_rest ifadesi ile eşleştirip(ilk eleman ve kalanlar anlamında düşünebiliriz) listenin ilk elemanını döndürüyor. Yorumlayıcının boş bir liste söz konusu ise 0 döndürülmesinden yola çıkarak fonksiyonun integer bir liste ile çalışacağına kanaat getirdiğine dikkat edelim. Dolayısıyla bu fonksiyonu aşağıdaki gibi yazarsak generic bir versiyon da çıkarmış oluruz.

let first_or default values =
      match values with
      | first :: the_rest -> first
      | [] -> default;;
first_or "" [];;
first_or 1 [];;
first_or 0 [12;2;6;9];;

Şimdi bir sayı listesindeki elemanların toplamını hesaplayan hem pattern matching içeren hem de recursive olan bir fonksiyon yazalım. Eh, bir döngü ile listeyi dolaşmak vardı ama Real World OCaml kitabına göre öz yinelemeli fonksiyonlar, fonksiyonel dillerin gerçekten önemli bir parçası. Doğrusu bundan güzel bir sınav sorusu olurmuş, "Herhangi bir sayı listesindeki elemanların toplamını bulacak bir fonksiyon yazın. Döngü kullanmak yasak, recursive fonksiyonellik şart" :D

let rec sum_of list =
      match list with
      | [] -> 0
      | head :: tail -> head + sum_of tail;;
sum_of [1;4;4;2;6;7];;
let numbers = [0;2;4;9;-4;-5];;
sum_of numbers;;

Bunu büyük ihtimalle unutacağım ve bakmadan yazamayacağım ama birkaç önemli noktayı kayıt altına almak isterim. sum_of fonksiyonunun kendisini referans ettiğini belirttiğimiz bir yer var, rec anahtar kelimesi. Bir fonksiyonun recursive olduğunu belirtiyor. Boş liste veya dolu liste gelmesi ihtimallerine karşı bir pattern matching kullanımı da söz konusu. Eğer boş bir liste gelirse toplamın sıfır döneceğini belirtmek aynı zamanda bu fonksiyonu integer listelerle çalışacak bir türe dönüştürüyor. İkinci match dalında head ve tail durumlarını ele alıyoruz ve fonksiyonu tekrar çağırarak sayıları birbirlerine ekliyoruz. Yani ilk sayıdan başlarsak 1 + sum_of [4;4;2;6;7] gibi bir dizilim ortaya çıkıyor. İkinci match kırılımı için tümevarımsal(inductive) yaklaşımın benimsendiğini vurgulayalım. Bu fonksiyonun işleyişine ait aşağıda bir örnekleme yer alıyor.

= 1 + sum_of [4;4;2;6;7]
= 1 + (4 + sum_of [4;2;6;7])
= 1 + (4 + (4 + sum_of [2;6;7]))
= 1 + (4 + (4 + (2 + sum_of [6;7])))
= 1 + (4 + (4 + (2 + (6 + sum_of [7]))))
= 1 + (4 + (4 + (2 + (6 + (7 + sum_of [])))))
= 1 + (4 + (4 + (2 + (6 + (7 + 0)))))
= 1 + (4 + (4 + (2 + (6 + 7))))
= 1 + (4 + (4 + (2 + 13)))
= 1 + (4 + (4 + 15))
= 1 + (4 + 19)
= 1 + 23
= 24

Piuvv! :D Parantezleri karıştırmış olabilirim. Kitapta 1;2;3 listesini toplamıştı.

Bugünkü terapide son olarak option veri yapısına bakıyorum. Bir değer vardır veya yoktur sorusuna cevap veren bir veri yapısı. Şahsen Rust dilinde Option türü çok işe yarıyor(Rust'ı geliştiren Graydon Hoare'un OCaml'den esinlendiği birçok yerde belirtiliyor) Aşağıdaki kod parçasında en basit kullanım şekli yer alıyor.

let div x y = if y = 0 then None else Some (x/y);;
div 10 0;;
div 10 2;;

Eğer y sıfır ise None dönüyor değilse bölme işlemi gerçekleştiriliyor. Dikkat edileceği üzere yorumlayıcı fonksiyonun dönüş türünü int option olarak belirledi. Bu son derece normal zira 7 değerinin 0 olup olmadığı kontrol ediliyor. Sıfırın varsayılan olarak int olarak kabul edildiği düşünülürse int option olarak yorumlanması son derece doğal. Bu arada None ve Some ifadeleri rastgele isimlendirmeler değil birer constructor olarak kabul ediliyor.

Record Veri Yapısı ve Variant Tipler

Pek tabii var olan türler dışında karma türler de tanımlayabiliriz. Kendi veri yapılarımızı tasarlarken kullanabileceğimiz enstrümanlardan birisi record türüdür.

type address = {host:string; port:int; route:string};;

let cust_get ={host = "localhost"; port = 5001; route = "api/v1/customer/get"};;

type service = {name : string; is_active : bool; kind : string; path : address};;

let customer_service = {name = "Get customers"; is_active = true; kind = "REST"; path = cust_get};;

Yukarıdaki kod parçasında iki record türü yer alıyor, address ve service. Dikkat edileceği üzere service record yapısındaki path alanı address veri yapısı türünden. cust_get ve customer_service isimli değişkenler ise bu türlere ait nesneleri işaret ediyor. Açıkça belirtmesek de eşitliğin sağ tarafından yapılan atamalar otomatik olarak cust_get'in bir address türü olmasını sağlıyor. Benzer şekilde customer_service değişkeni de service türünden bir nesne olarak tanımlanıyor. utop ekran görüntüsünde olduğu gibi çıktılara mutlaka bakmak lazım. type inference mekanizmasının nasıl çalıştığını görmek açısından önemli.

Şimdi bir de variant tanımlamayı deneyelim. Bu tür ile birden fazla nesneyi(object) tek bir tip altında birleştirmek mümkün. Aşağıdaki örnek kod parçası ile anlamaya çalışalım.

type location = { x : float; y : float }
type button = { title: string; position: location }
type label = { title: string; position: location }
type drop_down = { items: string list; position: location; is_enabled: bool }

type component =
  | Button of button
  | Label of label
  | DropDown of drop_down
;;

Bu kod parçasında button, label, drop_down gibi farklı türden nesneleri tek bir component türünde birleştirdik. Bu sayede component türünden bir değişken tanımladığımızda söz konusu değişken button, label veya drop_down türlerinden herhangi birini işaret edebilir. Aralarda pipe işareti olduğuna dikkat etmemiz gerekiyor ve hatta `|` sonrası gelen isimlendirmede büyük harfle başlama zorunluluğu var, aksi halde syntax error hatası alınıyor. drop_down isimli record türünde bir string list kullanılıyor. Dolayısıyla birden fazla string öğe barındırabilir. Kitaptaki örnekten de esinlenerek bu variant türünü bir fonksiyona parametre olarak geçebiliriz.

let get_item_count (c : component) : int =
  match c with
  | Button _ -> 0
  | Label _ -> 0
  | DropDown d -> List.length d.items
;;

let left_menu = DropDown {
  items = ["Save"; "Load"; "Exit"];
  position = {x = 10.0; y = 20.0};
  is_enabled = true
}
;;

get_item_count left_menu;;

Bu fonksiyon component türünden bir parametre alıyor ve bu parametrenin hangi türde olduğunu pattern matching ile kontrol ediyor. Eğer button veya label ise 0 döndürüyor, ancak drop_down ise içindeki items listesinin uzunluğunu döndürüyor.

Farklı bir fonksiyon daha yazalım. Örneğin bileşen detaylarını gösteren bir versiyon.

let show_component_details (c : component) : unit =
  match c with
  | Button b -> 
      Printf.printf "Button: %s\n" b.title
  | Label l -> 
      Printf.printf "Label: %s\n" l.title
  | DropDown d ->
      Printf.printf "DropDown containing:\n";
      List.iter (fun item -> Printf.printf " - %s\n" item) d.items
;;

show_component_details left_menu;;

Fonksiyonumuz parametre olarak component isimli variant türünden bir nesne alıyor. Bu nesnenin hangi türde olduğunu pattern matching ile kontrol ediyoruz. Eğer button veya label ise başlık bilgisini yazdırıyoruz. Ancak drop_down ise içindeki items listesini dolaşıp her bir öğeyi yazdırıyoruz. List.iter fonksiyonu, verilen bir fonksiyonu listenin her bir elemanına uygulamak için kullanılmakta.

Mutable Olma Hali

Varsayılan olarak immutable ama gerekirse mutable. Rust'ın açık bir şekilde benimsediği bir yaklaşım. Varsayılan olarak immutable olmak aslında bir şeylerin yanlışlıkla değiştirilmesini engellemek açısından anlamlı. Diğer yandan imperative yaklaşımın ele alındığı sayaçlar(counters) ve durum otomatı(state machine) gibi kodlar yazmanın önü de açık.

OCaml'ın safkan bir fonksiyonel dil olduğu belirtiliyor. Yani, kodun çalışmasının bir parçası olarak değişkenlerin değerlerini değiştirmek normalde mümkün değil. Programın durumu immutable veri yapılarıyla temsil ediliyor. Buna karşın imperative programlama paradigmasını da destekliyor. Bir başka deyişle mutable veri yapıları da mevcut. Örneğin Array veri yapısı bunlardan birisi. Bunun haricinde record türünün kendisi immutable olsa dahi üyeleri mutable olarak tanımlanabilir. Şimdi yine beni zorlayacak yazım stilleriyle bir array tanımlayalım ve kullanalım. Hatta sonrasında mutable üyeler içeren bir record yazalım.

(* float sayılardan oluşan bir array tanımı*)
let points = [| 45.50; 30.25; 60.75; 48.90; 80.; 0.; |];;

(* array operatörlerine erişim *)
Printf.printf "First point: %.2f\n" points.(0);;
Printf.printf "Second point: %.2f\n" points.(1);;

(* Bir array elementini değiştirmek istersek şöyle yapabiliriz *)
points.(0) <- 51.00;;
Printf.printf "Updated first point to: %.2f\n" points.(0);;

(* Array'in tamamını görüntülemek için *)
points;;

(* 
Belki bir döngü yardımıyla array elemanlarını görüntülemek isteyebiliriz
Hatta döngü içinde pattern match kullanıp dersten geçti, kaldı vs diyebiliriz
*)
for i = 0 to Array.length points - 1 do
  match points.(i) with
  | p when p >= 50.0 -> Printf.printf "Student %d passed with %.2f\n" (i + 1) p
  | p -> Printf.printf "Student %d failed with %.2f\n" (i + 1) p
done;;

Bu örnekte points isimli bir array tanımladık. Array elemanlarına erişmek için .(index), bir array elemanını değiştirmek için ise <- operatörünü kullandık. Sonrasında array'in tamamını görüntüledik ve bir döngü yardımıyla her bir elemanı kontrol ederek öğrencinin dersten geçme/kalma durumunu ekrana yazdırdık.

Öyleyse bir de mutable üyeler içeren bir record tanımlayalım. Burada dikkat edilmesi gereken noktalardan birisi de <- operatörünün unit () döndürmesidir. Bu, yapılan atama işleminin bir hesaplama(calculation) olmadığını, bir aksiyon(action) olduğunu belirtir. Yani, points.(0) <- 51.00 ifadesi bir değer döndürmez, sadece points array'inin ilk elemanını 51.00 olarak günceller.

(* 
  Varsayılan olarak immutable olan record üyeleri mutable yapılabilir.
  Şöyle anlamlı bir örnek düşünelim. Bir oyuncunun adı genellikle oyun sırasında değiştirilmez
  ancak canı, bulunduğu konum gibi bilgiler anlık olarak değişebilir.
*)

type player = {
  name: string;
  mutable health: int;
  mutable position: (int * int);
};;

let she_ra = { name = "She-Ra"; health = 100; position = (0, 0) };;

(* Bir fonksiyon ile de örneğin oyuncu hasar aldığında health bilgisini güncelleyebiliriz *)
let take_damage player amount = 
  player.health <- player.health - amount;
  Printf.printf "%s took %d damage and now has %d health.\n" player.name amount player.health
;;

take_damage she_ra 30;;

(* Oyuncunun pozisyonunu güncellemek için de benzer şekilde bir fonksiyon yazabiliriz *)
let move_player player new_position =
  player.position <- new_position;
  Printf.printf "%s moved to position (%d, %d).\n" player.name (fst new_position) (snd new_position)
;;

move_player she_ra (5, 10);;

Şimdi burada durup OCaml dilinin bu varsayılan immutable felsefesini düşünmek lazım. Normalde yukarıdaki gibi bir senaryo varsayılan olarak aşağıdaki gibi ifade edilir.

(* 
  OCaml'ın immutable felsefesini anlamak için bu örneği varsayılan durumda ele alalım
  Aşağıda görüldüğü gibi normal bir record tanımı yaptık.
*)
type player = {
  name: string;
  health: int;
  position: (int * int);
};;

let she_ra = { name = "She-Ra"; health = 100; position = (0, 0) };;

(* take_damage fonksiyonu artık player record'ünün health üyesini değiştiremez.
  Bu yüzden yeni bir player record'ü oluşturarak güncellenmiş bilgileri içeren bir record döndürmemiz gerekir.
  Tabii bu durumda var olan player record' unun bir kopyasını oluşturmuş oluruz.

  Örnekte update_player oluşturulurken health bilgisi güncelleniyor,
  burada with keyword kullandığımıza dikkat edelim. in ise yeni record'ün oluşturulacağı scope'u belirtiyor.
*)
let take_damage player amount = 
  let updated_player = { player with health = player.health - amount } in
  Printf.printf "%s took %d damage and now has %d health.\n" player.name amount updated_player.health;
  updated_player
;;

let she_ra = take_damage she_ra 8;;

(* 
  Bir fonksiyon tanımlamadan değer değiştirmek istersek bu durumda aşağıdaki gibi ilerleyebiliriz. 
  Söz gelimi pozisyonu değiştirelim.
*)
Printf.printf "%s is currently at position (%d, %d).\n" she_ra.name (fst she_ra.position) (snd she_ra.position);;
let she_ra = { she_ra with position = (25, 50) };;

Printf.printf "%s moved to position (%d, %d).\n" she_ra.name (fst she_ra.position) (snd she_ra.position);;

Burada fst ve snd ifadeleri aslında birer fonksiyon. Bir tuple'ın ilk ve ikinci elemanına erişmek için kullanılırlar. Yani, fst new_position ifadesi new_position adlı tuple'ın ilk elemanını döndürürken, snd new_position ifadesi ikinci elemanını döndürmektedir. Yukarıdaki kod parçasında gerekli açıklamalar yer alıyor. Belki de hangisini ne zaman seçmek gerekir üzerine düşünmek lazım. Ne zaman immutable yerine mutable tercih edelim ya da tam tersi?

Varsayılan olarak immutable olmak, concurrency ve karmaşık mantık içeren kodlarda hataların önüne geçmek açısından avantajlı olabilir. Zira değişken değerlerinin beklenmedik şekilde değişmesi engellenmiş olur. Söz gelimi buradaki player'ın immutable olan versiyonunu bir fonksiyona geçtiğimizde, onun ilgili fonksiyon içinde değişmeyeceğinden emin oluruz.
Mutable veri yapıları ise veriyi kopyalamadan değiştirme imkanı sağlar ve bazı durumlarda, örneğin state değiştirmek veya gerçek zamanlı güncellemeler yapmak istediğimizde daha performanslı olabilir. Ancak mutable veri yapılarını kullanırken dikkatli olmak gerekir, çünkü yanlışlıkla veriyi değiştirmek veya beklenmedik yan etkiler oluşturmak mümkündür. Bu konuda sanıyorum en sık verilen örnek sayaç mekanizması. OCaml ile basit bir counter tasarlayalım.

(*
  Bir sayaç gerçek zamanlı güncellemeyi gerektirir. Bu nedenle immutable olarak kullanmak,
  sürekli yeni bir kopya oluşturmaya neden olabilir ve bu da performans açısından iyi değildir.
  Dolayısıyla OCaml gibi varsayılan olarak immutability felsefesini benimsemiş diller için,
  sayaç mekanizması güzel bir mutable olma örneğidir.
*)
type counter = {
  mutable count: int;
};;

let tick_counter = { count = 0 };;

let increment (crt: counter) =
  crt.count <- crt.count + 1
;;

increment tick_counter;;
increment tick_counter;;
increment tick_counter;;

Printf.printf "Current count: %d\n" tick_counter.count;;

Refs

Tekil bir mutable değişken oluşturmak için ref enstrümanı da kullanılabilir. ref esasında standart kütüphanede tanımlanmış bir tip ve hatta bir record türü. İçinde contents isimli bir alan içeriyor. Hatta stdlib.ml dosyasına bakarsak aşağıdaki gibi tanımlandığını görürüz.

! ve := şeklinde tanımlanmış fonksiyonlar dikkatinizi çekmiştir. ! operatörü bir ref'in içindeki değere erişmek için kullanılırken, := operatörü ise bir ref'in içindeki değeri değiştirmek için kullanılır. Yine incr ve decr fonksiyonları yardımıyla değer artırma ve azaltma işlemleri de yapılabilir. OCaml komut satırından bir deneme yapabiliriz.

let counter = ref 0;;
!counter;;
counter := !counter + 1;;
!counter;;
counter := !counter + 1;;
!counter;;
counter := !counter + 1;;
!counter;;

Bu arada istersek ref türünü kendimiz de tasarlayabiliriz. Hatta kitap bunu gayet güzel bir şekilde örnekliyor. Bir deneyelim.

(*
  İstersek buradaki ref record yapısını kendimiz de yapabiliriz.
  Burada polimorfik bir record yapısı tanımlayarak herhangi bir türdeki değeri mutable olarak tutabiliriz.

  'a ifadesi, OCaml'da polimorfik tür parametresini temsil eder. 
  Bu, mutable_ref türünün herhangi bir türdeki değeri tutabileceği anlamına gelir. 
  x ile başlatılan mutable_ref fonksiyonu, verilen değeri mutable_ref türünde bir record olarak döndürür.
*)
type 'a mutable_ref = {
  mutable value: 'a;
};;
let mutable_ref x = { value = x };;
let get r = r.value;;
let set r x = r.value <- x;;
let incr r = r.value <- r.value + 1;;
let decr r = r.value <- r.value - 1;;

(* Deneyelim bakalım *)
let my_counter = mutable_ref 0;;
Printf.printf "My Counter: %d\n" (get my_counter);;
incr my_counter;;
Printf.printf "My Counter: %d\n" (get my_counter);;
set my_counter 10;;
Printf.printf "My Counter: %d\n" (get my_counter);;
decr my_counter;;
Printf.printf "My Counter: %d\n" (get my_counter);;

ref türü iterasyonlarda değiştirilebilir(mutable) state tutarken de kullanışlı olabilir. Örneğin bir listedeki elemanların ortalamasını hesaplamak için aşağıdaki gibi bir fonksiyon geliştirelim.

let avrage lst =
  let sum = ref 0 in
  let count = ref 0 in
  List.iter (fun x -> sum := !sum + x; count := !count + 1) lst;
  if !count = 0 then None else Some (!sum / !count)

let numbers = [1; 2; 3; 4; 5; 10;];;
Printf.printf "Average: %d\n" (match avrage numbers with Some avg -> avg | None -> 0);;

average isimli fonksiyon içerisinde yer alan sum ve count değişkenleri mutable olarak tanımlanmıştır ve List.iter fonksiyonu kullanılarak listenin her bir elemanı üzerinde işlem yaparken bu değişkenlerin değerleri güncellenmektedir. Tabii iter fonksiyonuna verilen anonim fonksiyon içerisinde ! operatörünü kullanarak ref'lerin içindeki değerlere erişiyoruz ve := operatörünü kullanarak bu değerleri güncelliyoruz. Bir de in operatörü ile karşılaştık tabii ki. Bu operatör sum ve count değişkenlerinin bulundukları fonksiyon bloğunda geçerli olduğunu belirtmek için kullanılmakta. Yani scope belirlemek için kullanılır. in kullanımının farkını anlamak için özellikle Utop ekranında aşağıdaki gibi bir deneme yapalım.

let value = 12;;
let point = 90 in point + 10;;
value;;
point;;
(*
  Line 1, characters 0-5:
  1 | point;;
      ^^^^^
  Error: Unbound value point
*)

value isimli değişken global scope'ta tanımlanmış ve bu nedenle herhangi bir yerden erişilebilir durumda. Ancak point isimli değişken in operatörünün kullanıldığı fonksiyon bloğu içerisinde tanımlanmış ve bu nedenle sadece o blok içerisinde geçerli. Dolayısıyla point değişkenine global scope'tan erişmeye çalıştığımızda Unbound value hatası alıyoruz.

Döngüsüz Olmaz Tabii(for, while loops)

En basit örneklerle başlayalım. Bir sayaç fonksiyonunu hem for hem de while döngüsü kullanarak yazalım.

let count_for n =
  for i = 1 to n do
    Printf.printf "%d," i
  done;
  Printf.printf "\n"

let count_while n =
  let i = ref 1 in
  while !i <= n do
    Printf.printf "%d," !i;
    i := !i + 1
  done;
  Printf.printf "\n"
;;

count_for 5;;
count_while 10;;

Şimdi örneklerimizi biraz daha eğlenceli hale getirelim. Örneğin, tamsayılardan oluşan bir listeyi Random modülünden de yararlanarak belli aralıktaki rastgele sayılarla dolduralım.

let average arr = 
  let sum = ref 0 in
  for i = 0 to Array.length arr - 1 do
    sum := !sum + arr.(i)
  done;
  float_of_int !sum /. float_of_int (Array.length arr)

let arr = generate_random_list 10 |> Array.of_list;;

Printf.printf "Random numbers (while): %s\nAverage: %f\n" 
  (String.concat "; " (List.map string_of_int (Array.to_list arr))) 
  (average arr);;

generate_random_list fonksiyonu n değerine göre bir liste döndürmekte. Bu listenin elemanları 0 ile 99 arasındaki rastgele sayılarla dolduruluyor. Örnekte Random isimli bir modül kullanıyoruz(Galiba her dilde bu modül mevcut :D) Dikkat edilmesi gereken noktalardan birisi self_init() çağrısı. Bunu yapmadığımız takdirde her seferinde aynı rastgele sayıların üretildiğini görürüz. Üretilen rastgele sayılar :: operatörü yardımıyla numbers isimli listeye ekleniyor. Sonrasında !numbers ifadesiyle de oluşturulan liste döndürülüyor. Kodun son satırında ise bu listeyi ekrana bastırmak için String.concat ve List.map fonksiyonlarından yararlanıyoruz. List.map fonksiyonu, verilen bir fonksiyonu listenin her bir elemanına uygulayarak yeni bir liste oluşturur. Bu örnekte, string_of_int fonksiyonunu kullanarak her bir tamsayıyı string'e dönüştürüyoruz. Ardından String.concat fonksiyonu ile bu string'leri "; " ile birleştirerek tek bir string elde ediyoruz ve bunu ekrana yazdırıyoruz. Aynı fonksiyonu bir de while döngüsü kullanarak yazalım.

let generate_random_list_while n =
  Random.self_init ();
  let numbers = ref [] in
  let i = ref 1 in
  while !i <= n do
    let random_number = Random.int 100 in
    numbers := random_number :: !numbers;
    i := !i + 1
  done;
  !numbers

let random_numbers_while = generate_random_list_while 10;;

Printf.printf "Random numbers (while): %s\n" (String.concat "; " (List.map string_of_int random_numbers_while));;

Bu fonksiyon da aynı şekilde n değerine göre bir liste döndürüyor ancak bu kez while döngüsünü kullandık. Döngü içerisinde i değişkeni 1'den başlayarak n'ye kadar artırılır ve her iterasyonda rastgele bir sayı üretilerek numbers listesine eklenir. Her iki fonksiyonun çalışma zamanına ait bir çıktıyı da ekleyelim.

Örneklerimize devam edelim. Parametre olarak gelen Array içindeki sayıların ortalamasını bulup döndüren bir fonksiyonu hem for hem de while döngüsü kullanarak yazalım.

let average arr = 
  let sum = ref 0 in
  for i = 0 to Array.length arr - 1 do
    sum := !sum + arr.(i)
  done;
  float_of_int !sum /. float_of_int (Array.length arr)

let arr = generate_random_list 10 |> Array.of_list;;
Printf.printf "Average: %f\n" (average arr);;

average isimli fonksiyon, arr isimli bir parametre almakta. Tabii bunun bir Array olduğunu varsayıyoruz. sum isimli değişkeni mutable olarak tanımladık zira bir toplam değerine ihtiyacımız var. Sonrasında bir for döngüsü yardımıyla dizi elemanlarını arka arkaya toplatıyoruz. ! operatörü ile sum dizisi içindeki değere erişiyoruz ve := operatörünü kullanarak bu değeri güncelliyoruz. Döngü tamamlandıktan sonra toplam değeri dizi uzunluğuna bölerek ortalamayı hesaplıyoruz. Dikkat edelim, bölme işlemi sırasında tam sayı bölmesi yapmamak için hem toplamı hem de dizi uzunluğunu float_of_int fonksiyonu ile float türüne dönüştürüyoruz. Sonrasında bu fonksiyonu kullanarak bir dizi oluşturup ortalamasını ekrana yazdırıyoruz.

Peki bu fonksiyona alakasız bir veri türü göndersek ne olur, örneğin metinsel bir ifade...

let himm = "Bu örneklerde for ve while döngülerini kullanarak listeler ve diziler üzerinde işlemler yaptık.";;
let avg = average himm;;

VS Code arabiriminden baktığımızda da çalışma zamanında denediğimizde de bir hata ile karşılaşırız.

Sıradaki fonksiyonumuz iki boyutlu bir matris üretiyor. Her bir elemanı 0 veya 1 olabilen bir matris. Basit bir oyun sahasının iki boyutlu görünümünde duvar veya yol kararını vermeyi kolaylaştırabilecek çok basit bir örnek.

let generate_matrix row_count col_count =
  Random.self_init ();
  let matrix = Array.make_matrix row_count col_count 0 in
  for i = 0 to row_count - 1 do
    for j = 0 to col_count - 1 do
      matrix.(i).(j) <- Random.int 2
    done;
  done;
  matrix

let matrix = generate_matrix 5 8;;
Printf.printf "Generated Matrix:\n";
Array.iter (fun row ->
  Array.iter (fun value -> Printf.printf "%d " value) row;
  Printf.printf "\n"
) matrix;;

Burada yardımcı birkaç fonksiyon da kullandık. Örneğin iki boyutlu bir matris dizisini oluşturmak için make_matrix fonksiyonuna başvurduk. İki boyutlu dizinin elemanlarını satır sütun bazında dolaşmak içinse klasik iç içe for döngüsü kullandık. Doğrudan dizinin elemanlarına atama yapıldığından <- operatörü ile 0 ve 1 şeklinde üretilen rastgele sayıları atarız. Random.int fonksiyonuna 2 değerini verdiğimizde sadece 0 veya 1 değerleri üretilebilir. Fonksiyon çıktısı olan matrisi ekrana yazdırmak için yine iç içe for döngüsü kullanabiliriz ama fonksiyonel bir yaklaşımla ilerlemek de oldukça şık. Nitekim Array modülünde yer alan iter fonksiyonu ile dizinin her bir elemanına uygulanacak bir fonksiyon çalıştırabiliriz. Dolayısıyla dış iterasyon, row'u parametre olarak alan ve dolayısıyla kolonları dolaşmayı sağlayacak anonim bir fonksiyon kullanıyor. İç iterasyon ise value'yu parametre olarak alan ve bu değeri ekrana yazdıran bir anonim fonksiyon. Her satırın sonunda ise yeni bir satır başlatmak için Printf.printf "\n" ifadesi yer almakta. Aşağıda çalışma zamanına ait örnek bir görüntü yer alıyor.

Derleyerek Çalıştırmak

Real World OCaml kitabı bir sonraki bölüme geçmeden önce "A Complete Program" başlığında basit bir program örneği anlatıyor. Bu örnekte ocaml kodunun derlenerek çalıştırılması söz konusu. Derleme işlemi için dune(Gezegen olan değil :D) aracını kullanıyor. Burada temel amaç tek başına çalıştırılabilir(standalone) bir program oluşturmak. Öncelikle kodlarımızı oluşturalım. Bu amaçla standalone isimli bir klasör oluşturdum ve içerisine rand_10.ml isimli bir dosya ekledim. Kolaya kaçarak daha önceden ele aldığımız bir fonksiyonu değerlendirebiliriz. Rastgele sayılardan oluşan 10 elemanlı bir liste oluşturuyoruz.

let generate_random_list n =
  Random.self_init ();
  let numbers = ref [] in
  for _ = 1 to n do
    let random_number = Random.int 100 in
    numbers := random_number :: !numbers
  done;
  !numbers

let () = 
  let random_numbers = generate_random_list 10 in
  Printf.printf "Random numbers: %s\n" (String.concat "; " (List.map string_of_int random_numbers))

Tabii program kodunda dikkat etmemiz gereken şeyler de var. Öncelikle artık ;; operatörünü kullanmadığımıza dikkat edelim. Diğer yandan bir de let () = ifadesi var. Bunu programın giriş noktası olarak düşünebiliriz. Yani, program çalıştığında ilk olarak bu kısım çalışacaktır.

Derleme işleminden önce bu klasörde oluşturmamız gereken iki dosya daha var; dune ve dune-project. İkisinin de uzantısı yoktur ve derlenecek programla ilgili birtakım konfigürasyon bilgilerini içerirler(Tahmin edileceği üzere). dune içeriğini şöyle oluşturabiliriz.

(executable
 (name rand_10))

Kod dosyasının adı rand_10.ml olduğu için name kısmına da rand_10 yazdık. dune-project dosyasının içeriği ise oldukça basit.

(lang dune 3.0)

Bu dosya ile dune aracının hangi sürümünün kullanılacağını belirtiyoruz. Bu adımlardan sonra kodu derleyip çalıştırabiliriz. Normalde sadece dune build komutu yeterli olur ancak derleme sırasındaki detayları da görmek istersek verbose argümanını kullanabiliriz. Programı çalıştırmak için yine dune aracından yararlanıyoruz.

# Derleme işlemi ve detaylar
dune build --display=verbose
# Programın çalıştırılması
dune exec ./rand_10.exe

ve işte çalışma zamanı çıktılarımız.

Örneği ubuntu platformunda da benzer şekilde derleyebiliriz. Ben WSL üzerinden denedim ve aşağıdaki gibi bir çıktı aldım.

Alcotest ile Birim Test Yazmak

OCaml kodlarını test etmek için birkaç yöntem var. Bunlardan birisi () ile oluşturulan program giriş noktasında klasik terminal çıktıları ile ilerlemek. Ancak birim test(unit test) yazmak elbette ki daha profesyonel bir yaklaşım ama daha da önemlisi bir standart. Bu amaçla dune ile entegre çalışabilen Alcotest isimli bir kütüphane bulunuyor. Öncelikle bu aracı opam ile sisteme yüklemek gerekiyor(Windows veya Linux fark etmez).

opam install alcotest

Evet yanlış görmüyorsunuz, terminalde sevimli bir deve emojisi var :D

Genel yaklaşım library haline getirilmiş kod dosyaları için test kelimesi ile başlayan ocaml dosyaları oluşturmak. Örneğin testing isimli bir klasör içerisinde math.ml isimli bir modül oluşturduğumuzu, bu modülü bir kütüphane olarak tasarlayıp birim testlerini yazmak istediğimizi düşünelim. Örnek olarak math modülünde aşağıdaki iki basit fonksiyona yer verebiliriz.

(* Faktöriyel hesaplama fonksiyonu *)
let rec factorial n =
  if n < 0 then failwith "Negative input not allowed for factorial"
  else if n = 0 then 1
  else n * factorial (n - 1)

(* Üs alma fonksiyonu *)
let rec power base exp =
  if exp < 0 then failwith "Negative exponent not allowed"
  else if exp = 0 then 1
  else base * power base (exp - 1)

Öncelikle bu kütüphanenin bir library olarak ele alınması lazım ve ayrıca test dosyalarının da bu kütüphaneyi kullanabilmesi için yapılandırılması gerekiyor. Bu nedenle dune dosyasının içeriğini aşağıdaki gibi hazırlamalıyız. Burada math modülünü bir kütüphane olarak tanımlıyoruz. modules ile başlayan kısımlar kütüphaneye dahil edilecek modülleri de belirtmekte. Ayrıca Alcotest kütüphanesini test kısmında kullanmak üzere libraries kısmında bildiriyoruz.

(library
 (name math)
 (modules math))

(test
 (name test_math)
 (modules test_math)
 (libraries math alcotest))

Şimdi de birim testleri içeren test_math.ml dosyasını oluşturalım. Burada olası tüm durumları test etmekte yarar var elbette ki ancak ben örnek olması açısından birkaç tanesine yer verdim.

let test_factorial () =
  let value = 5 in
  let expected = 120 in
  let result = Math.factorial value in
  Alcotest.(check int) "factorial of 5" expected result

let test_power () =
  let base = 2 in
  let exp = 3 in
  let expected = 8 in
  let result = Math.power base exp in
  Alcotest.(check int) "power of 2^3" expected result

let test_factorial_negative () =
  let value = -1 in
  Alcotest.check_raises "factorial of negative number" (Failure "Negative input not allowed for factorial")
    (fun () -> ignore (Math.factorial value))

let () =
  let open Alcotest in
  run "Math Tests" [
    "Math Tests", [
       test_case "factorial of 5" `Quick test_factorial;
       test_case "power of 2^3" `Quick test_power;
       test_case "factorial of negative number" `Quick test_factorial_negative;   
    ];
  ];

Testleri çalıştırmak için tek yapmamız gereken aşağıdaki terminal komutunu işletmek.

dune runtest

İşte bu da Ubuntu çıktısı.

Burada dikkate değer bir durum daha var. Dune, Incremental Build ve caching mekanizmaları sayesinde sadece değişen dosyaları derleyerek testleri çalıştırır. Dolayısıyla kod tabanında değişiklik olmadığında testler tekrardan çalıştırılmaz. Yani kodun aynı olması testlerin de aynı kalacağı anlamına gelir ki bu durumda kaynakları boşa israf etmenin de bir alemi yoktur. Burada dune kod dosyalarının imzalarını takip ederek bir karara varır. Ancak yine de testleri koşmaya zorlayabiliriz. Bunun için --force argümanını kullanmak yeterlidir.

dune runtest --force
# veya
dune runtest -f

Biraz da Felsefe

En zor kısım burası. Şöyle bir soru soralım. Neden bazı diller Method Overloading kabiliyeti sunarken bazıları sunmuyor? Yazının bundan sonraki kısmında bu soruya cevap aramayacağız ama gerçekten dilin genleri ve felsefesi ile alakalı konuları kavramaya çalışacağız. Tipler ile başlayalım.

Hata Yapmayı İmkansız Kılan Tip Desteği(Type Safety değil Type Expressiveness)

Verinin alabileceği tüm durumlar ilişkili olduğu tip tarafından tanımlanır. Çok klasik bir örnek üzerinden ilerleyelim(Rust tarafında da kullandığım bir teori ki OCaml'dan geliyormuş :D )

type payment_type =
  | Cash
  | CreditCard of string * float
  | Crypto of string * bool (*Vault adresi ile ağ onayını tutar*)

let process_payment pay_t =
  match pay_t with
  | Cash -> "Processing cash payment"
  | CreditCard (number, amount) -> Printf.sprintf "Processing credit card payment of %.2f for card %s" amount number
  | Crypto (address, confirmed) ->
      if confirmed then
        Printf.sprintf "Processing crypto payment to address %s" address
      else
        Printf.sprintf "Crypto payment to address %s is pending confirmation" address

let bills_payment = CreditCard ("1234-5678-9012-3456", 150.00);;
let () = 
  process_payment bills_payment
  |> print_endline

Önce çalışma zamanına bir bakalım.

payment_type içerisinde kullandığımız CreditCard tipini ele alalım. Kredi kartından bahsedebilmemiz için string ve float türünde iki bilgiye daha ihtiyacımız vardır. Bir başka deyişle CreditCard sadece bir etiket değil aynı zamanda bu iki bilgiyi de içeren bir yapıdır. Dolayısıyla CreditCard'ı kullanarak bir ödeme işlemi gerçekleştirebilmek için bu iki bilgiyi de sağlamamız gerekir. Sadece böyle bir durumda o veriye erişebiliriz. Bir başka mesele de pattern match kullanımıdır. Örneğin herhangi bir varyantı yazmazsak derleyici kızacaktır.

Bir başka deyişle derleyici tasarımımızın bir ortağı gibi hareket eder. Bir varyantı unutmamıza izin vermez. Rust dili açısından bakarsak bu yapının bence çok daha şık bir şekli olan enum yapısı var. Üstelik Options/Result gibi türler de bu felsefeyi(anlatabildim mi veya anlayabildim mi işte bütün mesele bu :D) çok güzel bir şekilde ortaya koyuyor. O zaman mottomuzu söylüyoruz; Tip güvenliği değil tip ifade gücü(type expressiveness).

Olabildiğince Fonksiyonel

OCaml mümkün olduğunca fonksiyonel olmayı hedefler. Yani her şeyi immutable yazmayı önerir. Lakin performans veya mantık gerektiren şeyler söz konusuysa imperative araçları da emrimize amade eder. Bu noktada Haskell gibi dillerden önemli ölçüde ayrıldığı söylenir ki tartışmaya açıktır(Neden, çünkü Haskell ile hiç tecrübem yok) Örnek kodlarda ele aldık ama sayaç artırıcı meselesini tekrar masaya yatırabiliriz. Aşağıdaki kod parçasını ele alalım.

(*Saf fonksiyonel yaklaşım*)
let rec sum list = function 
  | [] -> list 
  | x :: xs -> sum (list + x) xs

(* Pragmatik yaklaşım *)
let incrementer () =
  let count = ref 0 in
  fun () -> 
    count := !count + 1;
    !count

let () =
  let inc = incrementer () in
  print_endline (string_of_int (inc ()));
  print_endline (string_of_int (inc ()));
  print_endline (string_of_int (inc ()));

İlk önce çalışma zamanını bir değerlendirelim.

sum için tam bir fonksiyonel yaklaşımın söz konusu olduğunu söyleyebiliriz. Hatta tam anlamıyla matematiksel bir zarafet sunar. Zira mutable bir state yoktur, recursive çalışan fonksiyon her çağrıda yeni bir değer döndürür ve bunlar arka arkaya toplanır. incrementer fonksiyonunda kullanılan ref keyword bir referans kutusu oluşturur ve := operatörü ile bu kutunun içindeki değeri değiştirebiliriz. Bir başka deyişle bu fonksiyon state değiştiren bir fonksiyondur ve bu nedenle fonksiyonel değil, pragmatik bir yaklaşım sergiler.

Aslında buradaki felsefeyi şöyle düşünebiliriz. Bazı senaryolarda her şeyin saf bir fonksiyon ile yazılması mümkün değildir. Örneğin, milyonlarca finansal işlemin yapıldığı gerçek zamanlı bir uygulamada(Bence tam bu noktada Jane Street'in hikayesine bakılabilir) veya çok oyunculu bir oyunda mutable state'lere ihtiyaç duyar ve hatta performans ararız. OCaml böyle durumlara da hazırlıklıdır ve sağladığı mutable araçları kullanarak pragmatik bir şekilde ilerleyebiliriz. Ancak mümkün olduğunca fonksiyonel bir yaklaşım benimsemek kodun daha temiz, anlaşılır ve hatasız olmasına da yardımcı olabilir. Bu nedenle OCaml, fonksiyonel programlama paradigmalarını teşvik ederken aynı zamanda pragmatik ihtiyaçlara da cevap verebilecek esneklikte tasarlanmıştır. Rust açısından bakarsak gerçekten de benzer bir felsefeye sahiptir. Her şey varsayılan olarak immutable'dır ve mutable olması gerekiyorsa bu açıkça belirtilmelidir. Ancak Rust'ın sahip olduğu ownership ve borrowing mekanizmaları sayesinde mutable state'ler üzerinde daha sıkı kontrol sağlanır ve bu da güvenli bir şekilde mutable state'ler kullanmamıza olanak tanır ki bu Rust'ı çekici kılan bir başka şeydir.

Konuyu pekiştirmek adına bir başka örneğe bakalım.

let big_data = [|10.4; 20.5; 30.6; 1.0; 3.14 |]

let scale_data factor data =
  for i = 0 to Array.length data - 1 do
    data.(i) <- data.(i) *. factor
  done

let () =
  print_endline "Original data:";
  Array.iter (Printf.printf "%.2f ") big_data;
  print_endline "\nScaling data by a factor of 2.0...";
  scale_data 2.0 big_data;
  print_endline "Scaled data:";
  Array.iter (Printf.printf "%.2f ") big_data;
  print_endline ""

Tabii bu çok küçük bir veri kümesini ele alıyor. Elimizde milyon elemanlı bir veri de olabilirdi. Vektörel sayıların olduğu bir dizi mesela. Tek bir değeri güncellemek gerekiyorsa bile diziyi kopyalamak fonksiyonel yaklaşım açısından çok maliyetlidir. Dolayısıyla dizinin elemanını olduğu yerde değiştirmek gerekir. Yukarıdaki kod parçasında OCaml'ın bunu nasıl sağladığını bir kere daha görüyoruz. OCaml, Array ve Bytes gibi yapıları doğrudan mutable olarak tasarlamıştır. <- operatörü tam anlamıyla emirsel(imperative) bir şekilde çalışır ve dizinin elemanlarını doğrudan değiştirmemize olanak tanır. Yani yerinde veriyi değiştirmemiz mümkündür.

Buradan şu sonuca varabiliriz; belki de yazacağımız algoritma imperative yaklaşım gerekleri ile daha hızlı çalışıyordur. OCaml buna destek verir. Dolayısıyla elimizde yüksek seviyeli dillerin zarifliğine sahip(her ne kadar sentaksı zorlayıcı olsa da kavramsal olarak öyle) ama gerektiğinde düşük seviyeli dillerin sunduğu bellek performansına yakın destek veren bir programlama dili var ve Rust bence bu özellikleri bir üst noktaya taşıyıp bellek tarafında gerçekten güvenli kalabilmenin yolunu da açmış durumda.

Tony Hoare Anısına

Yazı yazmamdan kısa bir süre önce aramızdan ayrılan, bilgisayar bilimlerinin efsane ismi Tony Hoare'ın milyar dolarlık hata olarak da isimlendirdiği Null Pointer Exception, programlama dillerinde sıkça karşılaşılan ve ciddi sorunlara yol açabilen bir durumu anlatır. Uğraştığımız pek çok programlama dilinde null diye bir kavram var. Kısaca, bir değişkenin değeri yoksa ona null atayabiliriz şeklinde ifade etsek yeridir. Diğer yandan bu durum kodu yazarken bir null kontrolü yapmamızı da gerektirir(null değer taşıyabilen bir referansın kullanıldığı her yerde null olup olmadığını kontrol ederek hareket etmek). OCaml bu konuya şöyle bir felsefe ile yaklaşıyor; "Eğer bir hata oluşacaksa çalışma zamanında değil derleme zamanında olmalıdır". Hımmm... Yani... O zaman null değer yoktur diyebiliriz. Evet, gerçekten de null diye bir kavram **OCaml** dilinde yok. Bunun yerine programcıya sunulan bir seçenek var; Option...

Şöyle bir senaryo üzerinden ilerleyelim. Bir identity değerine göre kullanıcı aradığımızı varsayalım. Bunu şöyle yorumlamalıyız; "Kullanıcı ya vardır ya da yoktur"

(*  Aboneleri bir Record tipi olarak tanımladık *)
type subscriber ={
  id:int;
  name:string;
  email:string;
}

(* 
  Liste türünden hayali bir veritabanı ya da mock liste.
*)
let database = [
  {id=1001; name="John Doe"; email="john.doe@azon.com"};
  {id=1002; name="Jane Doe"; email="jane.doe@azon.com"};
  {id=1003; name="Mario"; email="mario@azon.com"};
]

(*
  Abone ID'sine göre abone arayan bir fonksiyon.
  Eğer abone bulunursa Some subscriber döner, bulunmazsa None döner.

  Özellikle fonksiyonun dönüş tipine dikkat edelim: subscriber option. 
  Bu, fonksiyonun ya bir subscriber döndüreceği ya da hiçbir şey döndürmeyeceği anlamına gelir.
*)
let rec find_subscriber_by_id id subscribers =
  match subscribers with
  | [] -> None
  | current :: rest ->
      if current.id = id then Some current
      else find_subscriber_by_id id rest

(*
  Burada derleyici bizi tüm senaryolara bakmaya zorlar.
*)
let say_hello id = let result = find_subscriber_by_id id database in
  match result with
  | Some subscriber -> Printf.sprintf "Hello, %s!" subscriber.name
  | None -> "Subscriber not found."

(* Test *)
let () =
  let message1 = say_hello 1002 in
  let message2 = say_hello 9999 in
  print_endline message1;  (* Output: Hello, Jane Doe! *)
  print_endline message2   (* Output: Subscriber not found. *)

Öncelikle kodun çalışma zamanı çıktısına bakalım.

Rust tarafından buraya geçmek gerçekten çok enteresan bir deneyim. Zira yıllardır Rust dilinde Option, Result gibi önemli veri yapılarını hangi felsefeden geldiğini çok da anlamadan kullanmışım. Pişmanım :D Neyse neyse... Kodda bir abone listesinden id bazlı kullanıcı araması yaptığımız recursive bir fonksiyon bulunuyor. Kodun sentaksına bakarken çok fazla bir şey anlamayabiliriz ama VS Code ya da Utop fonksiyon imzasında option döndüğünü açıkça ilan eder.

En önemli parça say_hello fonksiyonunda yer alan match ifadesidir. Burada result değişkeninin ya bir abone içerdiği ya da hiçbir şey içermediği durumlar ele alınır. Velev ki match ifadesini eksik yazdık. İşte gelen tepkiler...

Görüldüğü üzere kaçma şansımız yok. None olasılığını da mutlaka kod içerisinde değerlendirmemiz gerekiyor. Buradan hareketle bir değerin olmayışının aslında somut bir veri tipi olduğunu söyleyebiliriz. Yani bir değerin olmayışı da bir durumdur, bu durumun bir tipi vardır ve bu tipin adı option'dır. Diğer yandan, find_subscriber_by_id fonksiyonu bize bir abone döndirmez esasında. Bunun yerine içinde abone olabilecek bir kutu(Some veya None) döndürür. Bir match bloğu kullanmadan bir başka deyişle None ihtimalini ele almadan kutunun içindeki name bilgisine erişmemize derleyici fiziken müsaade etmez. Bu da geliştiricilerin "burada Null gelmez, ı ıhhh, mümkün değil" diyerek hareket etmesini engeller(Burası ciddi bir kurum asker. İyimserliğe yer yok! Marş marş... :D) Derleyici olası tüm ihtimalleri değerlendirmemizi bekler. Tabii bu yaklaşımın en güzel yanlarından birisi de huzurlu bir gece uykusudur. Çünkü rüyalarımıza girebilecek herhangi bir NullReferenceException öcüsü yoktur.

Rust programlama dilindeki `Option<T>` ve hata yönetimi için kullanılan `Result<T,E>` kavramları bu felsefeden gelir. Diğer yandan örneğin C# programlama dili çok sonradan Nullable Type yeteneği kazanmıştır fakat dilin temel felsefesinde halen null diye bir kavram olduğu için bu sonradan eklenmiş bir özellik olarak kabul edilir, bir başka deyişle dilin genlerine işlenmiş matematiksel bir güvence yoktur. Burada genel olarak ifade edilen bir sorunun cevabı da bulunabilir; Neden modern diller gün geçtikçe OCaml'a benzemeye çalışıyor?

Yüksek Matematik Lisanslı Derleyici

Programlama dillerini birçok açıdan ayrıştırabiliriz. Performans ve hıza odaklanıp bazı güvenli alanları kenara bırakanlar, iş modellerini gerçeğe yakın organize edip performanstan ödün verenler gibi. Ancak bir de akademik ve endüstriyel olanlar şeklinde iki ana kategoriye de ayrılabilirler. Söz gelimi öğrenmesi görece daha zor olan Haskell, Lisp gibi diller matematiksel açıdan kusursuza yakındır ancak gerçek dünya problemlerini modellemeye çalıştığımızda bizi daha da zorlayabilir. Diğer yandan C++, Java, Go gibi iş bitirici türden yani endüstriyel çözümlere daha yatkın olan diller de vardır ancak bunlarda kritik hataların oluşmasına müsait dillerdir. Kaynaklar OCaml programlama dilinin akademik titizliğe sahip ve endüstriyel olarak da güçlü olduğuna vurgu yaparlar.

Konuyu biraz daha açmaya çalışalım. OCaml derleyicisi Hindley-Milner olarak bilinen bir tip sistemini kullanır. Bu aslında bazı matematiksel enstrümanları ve ispatları barındıran bir yapıdır. Evet evet yanlış duymadınız, matematiksel ispatları dedim :D Hindley-Milner tip sistemini baz alan derleyici kodları okuduktan sonra bunları hemen makine diline çevirmez. Öncesinde sembolik mantık ve küme teorisine göre bazı denklemler çözer. Bu çözümler yazılan kodun mantıksal olarak tutarlı olduğunun matematiksel ispatı için işletilir. Dolayısıyla kod derleniyorsa matematiksel olarak doğrudur(Akademik anlamda güvenilirdir). Bununla birlikte derleyici optimize edilmiş endüstriyel makine kodu üretir.(Şu an için ne sizi ne de kendimi bu formüllerle boğmak istemiyorum ama bir ara bu konuyu derinlemesine ele alacağım)

Bu tip sistemi aklımızın bir köşesinde dursun ve gelin bir örnekle konuyu pekiştirmeye çalışalım. Finansal operasyonların her adımı son derece kritiktir. Büyük bir finans sisteminde farklı türden para birimlerinin olması da kesindir. Örneğin Dolar, Sterlin, Euro gibi para birimlerini göz önüne alalım. Tümü float türünden olsalar da bunları birbiriyle yanlışlıkla toplamak faciaya neden olabilir. 1000 Dolar ile 1000 Euro'nun toplanabildiğini düşünün, korkunç... OCaml ile bu sorunu nasıl aşabiliriz gelin örnek kod parçası ile bakalım.

(*
  CURRENCY isimli bir modül tanımladık ama bunu bir sözleşme/contract gibi düşünelim.

  Bu sözleşmeye göre var olan bir t tipi için,
  create fonksiyonu float türünden bir değer alarak t türünden bir değer döndürmeli,
  value fonksiyonu t türünden bir değer alarak float türünden bir değer döndürmeli,
  add fonksiyonu ise iki t türünden değer alarak t türünden bir değer döndürmeli.

  Biraz generic constraint'leri hatırlatıyor gibi ;)
*)
module type CURRENCY = sig
  type t
  val create : float -> t
  val value : t -> float
  val add : t -> t -> t
end

(*
  Para birimi için CURRENCY isimli bir sözleşmemiz var.
  Buna göre Euro, Dolar ve Sterlin implementasyonları yapabiliriz.
*)
module Euro : CURRENCY = struct
  type t = float
  let create x = x
  let value x = x
  let add x y = x +. y
end

module Dollar : CURRENCY = struct
  type t = float
  let create x = x
  let value x = x
  let add x y = x +. y
end

module Sterlin : CURRENCY = struct
  type t = float
  let create x = x
  let value x = x
  let add x y = x +. y
end

(*
  Şimdi bu para birimlerinden birkaç değer tanımlayalım
  birbirleriyle toplama işlemi yapmaya çalışalım.
*)
let payment_limit = Euro.create 1000.0
let payment_limit2 = Dollar.create 750.0 
let payment_limit3 = Sterlin.create 650.0

(* Aşağıdaki satır derlenmeyecektir çünkü farklı türler birbirleriyle toplanamaz *)
let total_payment = Euro.add payment_limit payment_limit2

Son satırda kasıtlı olarak farklı para birimleri toplanmaya çalışılmaktadır. Bakalım derleyici nasıl tepkiler vermiş.

VS Code ortamından bir görüntü,

ve terminalden derlemenin sonucu.

OCaml derleyicisi tüm para birimleri float veri türünü kullanıyor olsalar da, CURRENCY modülünden yapılan implementasyonlar sebebiyle farklı türlerin toplanmasına izin vermeyecektir(Domain Driven Design tarafında Value Object türleri ile de benzer bir tedbir alınabilir değil mi? Bi düşünün ;) ) Buradaki felsefe şudur; hataları testler yazarak değil tip sistemini kullanarak derleme zamanında engelle. Endişe edeceğimiz noktalardan birisi belki de performans kaybıdır ancak burada Zero Cost Abstraction söz konusudur. Zira derleyici makine kodunu üretirken Dollar.t, Euro.t gibi ayrımları silip doğrudan float toplama işlemini ele alır.

Bu genler Rust diline de geçmiştir ve hatta çok daha şık bir şekilde. Rust dili de Zero Cost Abstraction felsefesini benimser ve hatta parasal bir birimi şu şekilde yazmamıza izin veren Newtype desenini sunar.

struct Dollar(f64);

C# tarafından olaya baktığımızda sanıyorum en yakın çözüm record struct gibi bir türden yararlanmak olacaktır. Nitekim C# ve Java gibi dillerde bu tür bir korumayı sağlamak için sınıflara başvurduğumuzda bellekte ekstra nesneler oluşmasına neden olup gereksiz GC döngülerine sebebiyet verebiliriz. Ancak bu söylediklerimi ispat edebilir miyim, ımmmm, hayır :D

Modüller Birinci Sınıfı Vatandaştır(First Class Citizen)

Rahmetli babam çok uzun yıllar Almanya'da çalışmıştı. Savaş sonrası kalkınmaya çalışan Almanya'ya erken dönem gidenler arasındaydı. Orada edindiği dostluklar yurda temelli döndükten sonra da devam etmişti. Öyle ki beni çok seven birçok arkadaşı ne zaman onu ziyaret için ülkeye gelse küçük ya da büyük lego setleri getirirdi. Taa o zamanlarda kalma bir Lego sevgisi vardır içimde. Halen daha yapıyorum demek isterdim ama malum fiyatlar :|

OCaml açısından olaya bakacak olursak dilin en güçlü özelliklerinden birisi lego parçalarına benzettiğim modülleri birinci sınıf vatandaş olarak ele almasıdır. Bu, bazı dillerde kullandığımız paket(package), isim alanı(namespace) gibi kavramlardan çok farklı bir anlayıştır. Dahası var; modüller birbirlerine birer değişken gibi bağlanabilir, iç içe geçebilir ve functor adı verilen yapılarla bir modülden başka bir modül üretilebilir. Bir başka deyişle modül deyip geçmemek lazım :D

Şimdi konuyu koda döküp felsefesine gelmeye çalışalım. C# ve Java gibi dillerde bileşenler arasındaki bağımlılıklar hep başa dert olmuştur. Bunları yönetmek için Dependency Injection gibi desenler ortaya çıkmıştır. Bağımlılıklar genellikle soyutlamalar üzerinden(interface, abstract class) yönetilir ve diğer bileşenlere yapıcı metotlar, özellikler veya servis sağlayıcılar aracılığıyla enjekte edilir. Ne var ki bu işlem çalışma zamanında gerçekleşir ve doğal olarak bir ısınma maliyeti(Warm-up cost) vardır. Tahmin edin, OCaml'da bu nerede çözülür ;)

Klasik bir kod loglama işlevini ele alalım.

(*
  Öncelikle bir loglayıcının nasıl olması gerektiğini tarifleyelim.
  Bunu bir modül tanımı aracılığı ile yapabiliriz.
  Sözleşme üç fonksiyonu içeriyor: info, error ve warning.
  Ve üretilen diğer modüllerin bu fonksiyonları yazması gerekiyor.
*)
module type LOGGER = sig (* sig kelimesi signature'ın kısaltması *)
  val info : string -> unit
  val error : string -> unit
  val warning : string -> unit
end

(*
  Şimdi bu loglayıcıdan örnek iki loglayıcı hazırlayalım.
  Aslında LOGGER modülünden bir başka modül türetiyoruz gibi.

  ConsoleLogger bir struct 
  İçinde info, error ve warning isimli fonksiyonların asıl iş yapan sürümleri var.
*)
module ConsoleLogger : LOGGER = struct
  let info message = Printf.printf "[INFO] %s\n" message
  let error message = Printf.printf "[ERROR] %s\n" message
  let warning message = Printf.printf "[WARNING] %s\n" message

end

(*
  Aşağıdaki FileLogger modülü de LOGGER sözleşmesini uygulayan bir başka modül
  ve bu sefer log mesajlarını bir dosyaya yazacak şekilde tasarlanmış durumda.
*)
module FileLogger : LOGGER = struct
  let log_file = "log.txt"

  let log message =
    let oc = open_out_gen [Open_append; Open_creat] 0o666 log_file in
    output_string oc (message ^ "\n");
    close_out oc

  let info message = log ("[INFO] " ^ message)
  let error message = log ("[ERROR] " ^ message)
  let warning message = log ("[WARNING] " ^ message)
end

(*
  Elimizde bir soyutlama modülü ve bunu uygulayan iki farklı modül var.
  Öyleyse başka bir modüle bu bağımlılığı enjekte edelim.

  AppTracer, FUNCTOR (Fabrika) modülüdür. Bir Logger modülünü 
  parametre olarak alır ve bir servis verir.
*)
module AppTracer (L : LOGGER) = struct
  let log_data message =
    L.info ("Processing data: " ^ message);
    (* Veri işleme kodları burada olabilir *)
    L.info "Data processed successfully."
end

(*
  Şimdi bu servisi ConsoleLogger ve FileLogger ile çalıştırabiliriz.
  Burada modül bazında gerekli birleştirmeler yapılır ama çalışma zamanında değil
  derleme zamanında gerçekleşir.
*)
module ConsoleAppTracer = AppTracer(ConsoleLogger)
module FileAppTracer = AppTracer(FileLogger)

let () =
  ConsoleAppTracer.log_data "This is a console log message.";
  FileAppTracer.log_data "This is a file log message."

Örnekte terminal ekranına ve log.txt dosyasına basit log mesajları bırakan bir kod akışına yer veriliyor. Bir önceki örnektekine benzer şekilde bir sözleşme tanımlayarak işe başlıyoruz. Bu sözleşme gerçekten de bir imza(signature) tanımlıyor. ConsoleLogger ve FileLogger modülleri bu sözleşmeyi uygulayan iki farklı modül olarak ortaya çıkıyor. Daha sonra AppTracer adında bir functor tanımlanıyor. Fabrika görevi üstlenen bu modül, bir LOGGER modülünü parametre olarak alıyor ve bu loglayıcıyı kullanarak veri işleme sürecini izleyen bir servis sağlıyor. Yani bağımlılıkları enjekte ettiğimiz yer olarak düşünebiliriz. Son olarak, bu servisi hem ConsoleLogger hem de FileLogger ile çalıştırmak için gerekli modül bazında birleştirmeler yapılır. Tüm bu işlemler derleme zamanında gerçekleşir. Ayrıca yeni bir loglama yönetimi gerekirse, mevcut kodu bozmadan SOLID'in Open/Closed prensibine uygun olarak yeni bir modül tanımlayıp onu da AppTracer'a enjekte edebiliriz. Bu esneklik ve genişletilebilirlik, modüllerin birinci sınıf vatandaş olarak ele alınmasının önemli avantajlarından biridir.

Bağımlılıkların derleme zamanında çözülmesi, çalışma zamanındaki maliyetten kurtulmamızı sağlar(Zero Cost Dependency Injection). Yani derleyici AppTracer(ConsoleLogger) ifadesini gördüğünde, ConsoleLogger modülünün içeriğini AppTracer'ın içine yerleştirerek makine kodu üretir ve böylece çalışma zamanında herhangi bir soyutlama ya da arayüz çağrısına gerek kalmaz. Rust dilinde benzer şekilde trait'ler aracılığıyla bağımlılıkların derleme zamanında çözülmesi sağlanır. Dolayısıyla Rust'ın OCaml dilindeki signature ve modül sisteminden genetik izler taşıdığını söyleyebiliriz. Diğer yandan C# veya Java dillerindeki generic yapıların ve interface'lerin OCaml'daki functor'ların daha zayıf bir versiyonu olduğu ifade edilir. Bunu şöyle açıklamak mümkün; OCaml functor'ları kullanarak davranışlar bütününü soyutlarken C# daha çok parametreleri soyutlar. Örneğin C# dilinde generic bir sınıf tanımlarken bu sınıfın hangi türde çalışacağını belirtiriz(`<T>` kullanımı) ancak bu türün hangi davranışlara sahip olması gerektiği konusunda daha az kontrolümüz olur. OCaml'da ise functor'lar aracılığıyla sadece türleri değil aynı zamanda bu türlerin sahip olması gereken fonksiyonları da tanımlarız. Dolayısıyla daha güçlü bir soyutlama ve daha sıkı bir tip güvenliği sağlamış oluruz.

Sonuç

Bir merakla başladığım OCaml yolculuğumdaki hedefim bir programlama dili geliştirmek için gerekli becerileri öğrenmekti. Henüz bu noktanın çok uzağında olmakla birlikte, severek kullandığım Rust'ın genlerini aldığı bu dille uğraşmak bir başka meydan okumaydı ama değdi. Öğrenmeye devam; umarım sizlere de yeni bir şeyler öğrenmek için ilham veren bir çalışma olmuştur. Bir başka çalışmada görüşmek üzere, hoşça kalın.

Bu çalışmadaki örneklere ve biraz daha fazlasına github reposundan ulaşabilirsiniz

Hangi Localization Tekniği

2026-04-11T08:47:00+00:00

Tartışmanın konusu, çooooook uzun zamandır dünyamızda var olan çoklu dil desteği(Multi-Language Support). Kimi zaman veritabanı üzerinden, kimi zaman fiziki dosyalardan(resx gibi) yönetmeye çalıştığımız bir mevzu. Sürekli değişip genişleyebilenler bir yana, nadiren değişip genellikle statik kalanlardan oluşan veri kümeleri de cabası. Aslında temel amaç, bir program arayüzünün veya kullanıcı ile etkileşimde olan taraflarının farklı dillerde destek vermesini sağlamak. Teori basit; değişmez sabit bir kavram(key diyelim) karşılığında, kullanılan dile göre farklı değerler tutulmasını sağlamak.

Örneğin müşteri bilgilerini kaydetme ekranında kullandığımız button kontrolünün başlığını save_button şeklinde bir key ile sabitleyip, değerlerini ana dilimizde kaydet, İngilizce'de save, İspanyolca'da Ahorrar şeklinde tutabiliriz. Bunun için ister tablo tasarımı kullanalım ister bir key:value koleksiyonu; verinin okunması, değiştirilmesi, aynı anda erişilmesi gibi konular başka soruları da gündeme getirir. Nerede tutsak iyi olur, hangi teknik bizi ne kadar yavaşlatır ya da hızlandırır, eş zamanlı(concurrent) çağrılarda değişenlerin güncelliğini nasıl koruruz, race-condition oluşur mu, ön belleğe(cache) alsak ne zaman tazelemek gerekir, koca veriyi ön belleğe alma maliyeti nedir vb.

Çoklu dil desteği aslında çözülmemiş bir problem değil. Birçok yazılım firması zaten çoktandır ideal çözümler üzerinden ilerlemekte. Bu çalışmadaki amacım veritabanı(kuvvetle muhtemel PostgreSQL), Redis, in-memory cache veya hibrit çözümler arasında bir benchmark değerlendirmesi yapmak. Neticede aşağıdaki tabloda belirtilen sonuçları ispatlamaya ya da gerçeği yansıtıp yansıtmadığını bulmaya çalışacağız.

Yaklaşım	Read	Cold Start Maliyeti	Hot Read Maliyeti
PostgreSQL (doğrudan kullanım)	Network + Disk	High	High
Redis	Network + RAM	Medium	Low
IMemoryCache (in-process)	RAM	Low (after warmup)	Lowest
Hybrid (DB → Redis → MemCache)	Layered	Warm on demand	Lowest after L1
JSON (resx gibi dosyalarda)	Disk	Low	Very Low

Hazırlıklar

Öncelikle birkaç yaklaşımımız olduğunu belirtelim. Çoklu dil desteği için dikeyde büyüyen bir tabloyu PostgreSQL üzerinde tutacağız. Bir diğer yaklaşımda dağıtık sistemler dünyasının en karizma veri tabanlarından olan Redis ile ilerleyeceğiz. .NET'in dahili bellek kullanımı da yabana atılır türden değil. Dolayısıyla o da işin içerisine giriyor. Bir başka tercih de içeriği disk üzerinde JSON veya YAML gibi bir formatta tutmak ama bunu bu senaryoda ele almayacağız. Son olarak en hızlı teknikten en yavaşa doğru farklı seviyeleri ele alan hibrit bir yaklaşımımız da olacak.

Docker Setup

Düzeneğimizi .NET 10 platformunda kurgulayabiliriz. PostgreSQL ve Redis enstrümanları için her zaman olduğu gibi bir docker-compose dosyası iş görecektir. En azından aşağıdaki içeriğe sahip olmasında yarar var.(PgAdmin çok şart değil zira community sürümü bulunan DBeaver gibi araçlarla da veritabanına bağlanıp işlemler yapabiliriz ki ben onu tercih ettim)

services:

  postgres:
    image: postgres:latest
    container_name: locally-postgres
    environment:
      POSTGRES_USER: johndoe
      POSTGRES_PASSWORD: somew0rds
      POSTGRES_DB: postgres
    ports:
      - "5435:5432"
    volumes:
      - postgres_data:/var/lib/postgres/data
    networks:
      - locally-network

  pgadmin:
    image: dpage/pgadmin4:latest
    container_name: locally-pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: scoth@tiger.com
      PGADMIN_DEFAULT_PASSWORD: 123456
    ports:
      - "5050:80"
    depends_on:
      - postgres
    networks:
      - locally-network

  redis:
    image: redis:latest
    container_name: locally-redis
    ports:
      - "6379:6379"
    # Burada persistance storage'ı devre dışı bırakıyoruz ve pure in-memory modda çalıştırıyoruz. 
    # Nitekim benchmark sırasında disk IO işlemleri performansı etkileyebilir.
    command: redis-server --save "" --appendonly no --maxmemory 256mb --maxmemory-policy allkeys-lru
    networks:
      - locally-network

volumes:
  postgres_data:

networks:
  locally-network:
    driver: bridge

Solution İskeleti

Solution içeriğinde birkaç proje yer alacak. Farklı provider türlerimiz olacağı için çok basit soyutlamalar kullanmakta, benchmark ölçümleri için ayrı bir proje açmakta ve testleri bir Web API üzerinden icra etmekte yarar var. Yani farklı provider'lar için class library'ler, çoklu dil veri setlerine ulaşmak için bir Web API ve performans ölçümleri için bir console uygulaması şimdilik işimizi görecektir. Son aşamada birde yük testi(load test) için adım atacağız. Başlangıç senaryosuna göre solution içeriği ve gerekli nuget paketlerini aşağıdaki gibi hazırlayabiliriz.

mkdir LocalizationChallenge
cd LocalizationChallenge

dotnet new sln

dotnet new classlib -n LocalizationChallenge.Core
dotnet sln add LocalizationChallenge.Core/

dotnet new classlib -n LocalizationChallenge.Infrastructure
dotnet add LocalizationChallenge.Infrastructure/LocalizationChallenge.Infrastructure.csproj package Npgsql
dotnet add LocalizationChallenge.Infrastructure/LocalizationChallenge.Infrastructure.csproj package StackExchange.Redis
dotnet add LocalizationChallenge.Infrastructure/LocalizationChallenge.Infrastructure.csproj package Microsoft.Extensions.Hosting.Abstractions
dotnet sln add LocalizationChallenge.Infrastructure/

dotnet new console -n LocalizationChallenge.Benchmarks
dotnet add LocalizationChallenge.Benchmarks/LocalizationChallenge.Benchmarks.csproj package BenchmarkDotNet
dotnet add LocalizationChallenge.Benchmarks/LocalizationChallenge.Benchmarks.csproj package Npgsql
dotnet add LocalizationChallenge.Benchmarks/LocalizationChallenge.Benchmarks.csproj package StackExchange.Redis
dotnet sln add LocalizationChallenge.Benchmarks/

dotnet new webapi -n LocalizationChallenge.Api
dotnet add LocalizationChallenge.Api/LocalizationChallenge.Api.csproj package Npgsql
dotnet add LocalizationChallenge.Api/LocalizationChallenge.Api.csproj package StackExchange.Redis  
dotnet sln add LocalizationChallenge.Api/

# Gerekli proje referansların eklenmesi
dotnet add LocalizationChallenge.Infrastructure/LocalizationChallenge.Infrastructure.csproj reference LocalizationChallenge.Core/LocalizationChallenge.Core.csproj
dotnet add LocalizationChallenge.Api/LocalizationChallenge.Api.csproj reference LocalizationChallenge.Core/LocalizationChallenge.Core.csproj
dotnet add LocalizationChallenge.Api/LocalizationChallenge.Api.csproj reference LocalizationChallenge.Infrastructure/LocalizationChallenge.Infrastructure.csproj
dotnet add LocalizationChallenge.Benchmarks/LocalizationChallenge.Benchmarks.csproj reference LocalizationChallenge.Core/LocalizationChallenge.Core.csproj
dotnet add LocalizationChallenge.Benchmarks/LocalizationChallenge.Benchmarks.csproj reference LocalizationChallenge.Infrastructure/LocalizationChallenge.Infrastructure.csproj

Kod tarafında ilerledikçe projelerimizin kullanım amacı biraz daha netleşecek.

PostgreSQL Tarafı

Veritabanı tarafında bir tabloya ve onu en azından örnek verilerle tohumlamaya(seeding) ihtiyacımız var. İlk etapta aşağıdaki sql script'ini kullanabiliriz.(İlerleyen aşamada bir trigger ekleyip olası değişimleri dış dünyaya push'layacağımız bir mekanizmayı da ele alacağız ki cache-invalidation noktasında gerekli olacak)

CREATE TABLE IF NOT EXISTS localizations (
    id           SERIAL       PRIMARY KEY,
    culture      VARCHAR(10)  NOT NULL,
    resource_key VARCHAR(255) NOT NULL,
    value        TEXT         NOT NULL,
    updated_at   TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
    CONSTRAINT uq_culture_key UNIQUE (culture, resource_key)
);

CREATE INDEX IF NOT EXISTS idx_loc_culture_key ON localizations (culture, resource_key);

-- Sample data
INSERT INTO localizations (culture, resource_key, value) VALUES
  ('en-US', 'welcome_message',    'Welcome to our application'),
  ('en-US', 'farewell_message',   'Goodbye, see you soon'),
  ('en-US', 'error_not_found',    'The requested resource was not found'),
  ('en-US', 'error_unauthorized', 'You are not authorized to perform this action'),
  ('en-US', 'button_save',        'Save'),
  ('en-US', 'button_cancel',      'Cancel'),
  ('en-US', 'button_delete',      'Delete'),
  ('tr-TR', 'welcome_message',    'Uygulamamıza hoş geldiniz'),
  ('tr-TR', 'farewell_message',   'Güle güle, yakında görüşürüz'),
  ('tr-TR', 'error_not_found',    'İstenen kaynak bulunamadı'),
  ('tr-TR', 'error_unauthorized', 'Bu işlemi gerçekleştirme yetkiniz yok'),
  ('tr-TR', 'button_save',        'Kaydet'),
  ('tr-TR', 'button_cancel',      'İptal'),
  ('tr-TR', 'button_delete',      'Sil'),
  ('de-DE', 'welcome_message',    'Willkommen in unserer Anwendung'),
  ('de-DE', 'farewell_message',   'Auf Wiedersehen, bis bald'),
  ('de-DE', 'error_not_found',    'Die angeforderte Ressource wurde nicht gefunden'),
  ('de-DE', 'error_unauthorized', 'Sie sind nicht berechtigt, diese Aktion durchzuführen'),
  ('de-DE', 'button_save',        'Speichern'),
  ('de-DE', 'button_cancel',      'Abbrechen'),
  ('de-DE', 'button_delete',      'Löschen')
ON CONFLICT (culture, resource_key) DO NOTHING;

SQL içeriğini pgadmin arabirimi üzerinden ekleyebileceğimiz gibi komut satırından bu dosyayı container içerisine alarak da çalıştırabiliriz. Bunun için kendi Windows 11 sistemimde izleyen komutlarla ilerledim.

# Öncelikle sql dosyasını container içerisine kopyalayalım
docker cp seed.sql locally-postgres:/seed.sql
# Şimdi de çalıştırarak verileri ekleyelim
docker exec locally-postgres psql -U johndoe -d postgres -f /seed.sql
# Verilerin eklenip eklenmediğini kontrol edelim
docker exec locally-postgres psql -U johndoe -d postgres -c "SELECT * FROM localizations WHERE culture = 'tr-TR';"

Redis

Redis tarafına da örnek veri tohumlarını aktarmakta yarar var. PostgreSQL için kullandığımız veri kümesinin aynısını Redis için de değerlendirebiliriz. Tabii verileri aktarmak için kullanabileceğimiz birkaç yol var. Bunlardan birisi, docker ortamındaki Redis container'ına terminal açmak ve örneğin aşağıdaki içeriğe sahip bir shell script dosyasını kopyalayıp işletmek. Burada her bir dil kümesini bir HashSet olarak eklediğimizi görebilirsiniz. Veritabanındaki tek tablo düzeneği yerine burada dil bazlı farklı hashset kullanımları söz konusu. (Bu sadece bir tercih meselesi, tek bir hashset de kullanabiliriz ama bu şekilde daha düzenli duruyor diye düşünüyorum)

redis-cli -h localhost -p 6379 HSET loc:en-US \
  welcome_message    "Welcome to our application" \
  farewell_message   "Goodbye, see you soon" \
  error_not_found    "The requested resource was not found" \
  error_unauthorized "You are not authorized to perform this action" \
  button_save        "Save" \
  button_cancel      "Cancel" \
  button_delete      "Delete"

redis-cli -h localhost -p 6379 HSET loc:tr-TR \
  welcome_message    "Uygulamamıza hoş geldiniz" \
  farewell_message   "Güle güle, yakında görüşürüz" \
  error_not_found    "İstenen kaynak bulunamadı" \
  error_unauthorized "Bu işlemi gerçekleştirme yetkiniz yok" \
  button_save        "Kaydet" \
  button_cancel      "İptal" \
  button_delete      "Sil"

redis-cli -h localhost -p 6379 HSET loc:de-DE \
  welcome_message    "Willkommen in unserer Anwendung" \
  farewell_message   "Auf Wiedersehen, bis bald" \
  error_not_found    "Die angeforderte Ressource wurde nicht gefunden" \
  error_unauthorized "Sie sind nicht berechtigt, diese Aktion durchzuführen" \
  button_save        "Speichern" \
  button_cancel      "Abbrechen" \
  button_delete      "Löschen"

echo "Mission accomplished."

Yukarıdaki betiği çalıştırmak için aşağıdaki gibi bir yol izleyebiliriz (Ben denemelerimi Windows 11 ortamında Command Prompt üzerinden yaptım)

# Öncelikle redis-seed dosyasını container içerisine kopyalayalım
docker cp redis-seed.sh locally-redis:/redis-seed.sh
# Ardından çalıştırarak verileri ekleyelim
docker exec locally-redis sh /redis-seed.sh

# Verilerin eklenip eklenmediğini kontrol edelim
docker exec locally-redis redis-cli -h localhost -p 6379 HGETALL loc:tr-TR

Kod Tarafı

Şimdi adım adım kodlarımızı geliştirmeye başlayabiliriz. Birden fazla projede yapacağımız önemli değişiklikler var.

Core Kütüphanesi

LocalizationChallenge.Core isimli class library projesini ele alalım. Farklı türden çoklu dil mekanizmaları kullanacağımız için bunu aşağıdaki arayüz soyutlaması ile bir sözleşme(contract) haline getirebilriz. Böylece web api gibi runtime'larda DI Container sistemiyle ilgili bileşenleri servislere enjekte edebiliriz. Hazırlıklı olmakta yarar var :D

namespace LocalizationChallenge.Core;

public interface ILocalizationProvider
{
    string ProviderName { get; }
    ValueTask<string> GetLocalizedStringAsync(string key, string culture, CancellationToken cancellationToken = default);
}

ProviderName alanı(field) adı üstünde hangi tekniği kullandığımızı belirtmekte. GetLocalizedStringAsync metodu ise kobay olarak kullandığımız davranışı tanımlıyor. Amacımız bir terimin belirtilen dildeki karşılığını döndürecek fonksiyonu tanımlamak. Veri okuma ile ilgili operasyonlar için bu davranış şu an için yeterli. Dolayısıyla asıl provider nesnelerinin bu arayüzü(interface) implemente etmesini bekliyoruz.

Diğer yandan süre ölçümlemelerini tutacağımız bir veri nesnesi de işimize yarar. BenchmarkResult isimli bu tipi aşağıdaki gibi türetilemez(sealed) bir record türü şeklinde tasarlayabiliriz.

namespace LocalizationChallenge.Core;

public sealed record BenchmarkResult(
    string ProviderName,
    string? Value,
    double ElapsedMicroseconds,
    bool CacheHit
);

Tipik olarak ölçüme konu olan provider enstrümanını, elde edilen değeri(veriyi kontrol etmek için), mikro saniye türünden ölçüm değerini ve cache üzerinden tedarik edilip edilemediği bilgisini tutuyoruz.

Infrastructure Kütüphanesi

Hakiki provider bileşenlerimiz ise LocalizationChallenge.Infrastructure isimli class library projesinde yer alacak. Postgres, Redis, In-Memory ve hibrit teknikleri için birer provider sınıfı yazarak devam edelim. Tahmin edileceği üzere bunlar Core kütüphanesindeki ILocalizationProvider arayüzünü implemente etmeliler. İlk olarak postgres tarafı ile başlayalım.

using LocalizationChallenge.Core;
using Npgsql;

namespace LocalizationChallenge.Infrastructure;

public sealed class PostgresLocalizationProvider(NpgsqlDataSource dataSource)
    : ILocalizationProvider
{
    public string ProviderName => "Postgres";

    public async ValueTask<string> GetLocalizedStringAsync(string key, string culture, CancellationToken cancellationToken = default)
    {
        await using var command = dataSource.CreateCommand(
            "SELECT value FROM localizations WHERE resource_key = @key AND culture = @culture LIMIT 1"
        );
        command.Parameters.AddWithValue("key", key);
        command.Parameters.AddWithValue("culture", culture);

        var result = await command.ExecuteScalarAsync(cancellationToken);
        return result as string ?? string.Empty;
    }
}

Oldukça basit bir sınıf. key ve culture bilgilerini parametre olarak alan bir SQL sorgusu işletiliyor ve sonuç geriye string olarak dönülüyor. Tabii bir null check kontrolümüz de var. Hiç vakit kaybetmeden redis bileşenimizi geliştirerek devam edelim.

using LocalizationChallenge.Core;
using StackExchange.Redis;

namespace LocalizationChallenge.Infrastructure;

public sealed class RedisLocalizationProvider(IConnectionMultiplexer connectionMultiplexer)
    : ILocalizationProvider
{
    private readonly IDatabase database = connectionMultiplexer.GetDatabase();
    public string ProviderName => "Redis";

    public async ValueTask<string> GetLocalizedStringAsync(string key, string culture, CancellationToken cancellationToken = default)
    {
        var value = await database.HashGetAsync($"loc::{culture}", key);
        return value.HasValue ? value.ToString() : string.Empty;
    }
}

Redis üzerinden ilgili hashSet'e ulaşıp key değerini geri döndürüyoruz(bulamazsak da boş bir değer)

Sıradaki bileşen .NET'in in-memory cache özelliğini kullanıyor. Örneğimizde ele aldığımız çoklu dil verilerinin çok sık değişmeyeceğini düşünürsek yeni tip bir koleksiyon türünü de göz önüne alabiliriz. .NET 8 ile gelen ama .NET 10 tarafında önemli performans iyileştirmeleri içeren ve özellikle lookup türündeki dictionary veri kümelerinde *%20 ile %40* arasında daha hızlı olduğu iddia edilen FrozenDictionary sınıfını ele almak için iyi bir fırsat(Bu koleksiyonu ve özelliklerini ayrıca çalışmam gerekiyor zira read-only ve performans kritik senaryolar için biçilmiş kaftan olduğu iddia edilmekte)

using LocalizationChallenge.Core;
using Microsoft.Extensions.Hosting;
using Npgsql;
using System.Collections.Frozen;

namespace LocalizationChallenge.Infrastructure;

public sealed class MemoryCacheLocalizationProvider(NpgsqlDataSource dataSource)
    : ILocalizationProvider, IHostedService
{
    // Değişmeyen veri yapılarında, thread-safe olan ve hızlı erişim sağlayan FrozenDictionary bileşenini kullanarak önbellek oluşturuyoruz.
    // volatile bildirimi ile cache değişkenine yapılan atamaların tüm thread'ler tarafından görünür olması sağlanır.
    // Böylece StartAsync metodunda cache güncellendiğinde, diğer thread'ler de bu güncellemeyi görebilir.
    private volatile FrozenDictionary<string, FrozenDictionary<string, string>> cache = FrozenDictionary<string, FrozenDictionary<string, string>>.Empty;
    public string ProviderName => "InMemoryCache";

    public ValueTask<string> GetLocalizedStringAsync(string key, string culture, CancellationToken cancellationToken = default)
    {
        if (cache.TryGetValue(culture, out var dict) && dict.TryGetValue(key, out var val))
            return ValueTask.FromResult<string?>(val);

        return ValueTask.FromResult<string?>(null);
    }

    // Bileşenimizi başlatırken, veritabanından tüm lokalizasyon verilerini çekip, hızlı erişim için önbelleğe yüklememiz gerekiyor.
    // Bunun için IHostedService arayüzü implementasyonunu kullandık.
    // Api tarafındaki DI container'ına bu bileşeni singleton olarak eklerken, aynı zamanda IHostedService olarak da kaydedeceğiz.
    // Böylece uygulama başladığında StartAsync metodu tetiklenecek ve önbellek doldurulacak.
    public async Task StartAsync(CancellationToken cancellationToken)
    {
        await using var cmd = dataSource.CreateCommand(
            "SELECT culture, resource_key, value FROM localizations");
        await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);

        var staging = new Dictionary<string, Dictionary<string, string>>(StringComparer.OrdinalIgnoreCase);

        while (await reader.ReadAsync(cancellationToken))
        {
            var culture = reader.GetString(0);
            var resourceKey = reader.GetString(1);
            var value = reader.GetString(2);

            if (!staging.TryGetValue(culture, out var dict))
            {
                dict = new Dictionary<string, string>(StringComparer.Ordinal);
                staging[culture] = dict;
            }
            dict[resourceKey] = value;
        }

        cache = staging.ToFrozenDictionary(
            kvp => kvp.Key,
            kvp => kvp.Value.ToFrozenDictionary(StringComparer.Ordinal),
            StringComparer.OrdinalIgnoreCase);
    }

    public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}

Tabii bu sınıfın kod içeriği diğerlerine göre biraz daha karmaşık. Nitekim sadece ILocalizationProvider sözleşmesini değil, IHostedService arayüzünü de uyguluyor. Buradaki amaç DIC(Dependency Injection Container) tarafında bu bileşen ayağa kalkarken(bir başka deyişle örneğimizdeki Web API canlanırken) Start metodunun devreye girmesi ve SQL tarafında tutulan çoklu dil veri setlerinin FrozenDictionary içerisine alınmasını sağlamak. Böylece bir verinin belli bir dildeki karşılığı için bellekte tutulan yüksek performanslı dictionary kullanılacak.

Son olarak hibrit çalışan provider sınıfımızı yazalım. Bu bileşenimiz diğer teknikleri harmanlar nitelikte ama önemli bir strateji de barındırıyor.

using LocalizationChallenge.Core;
using StackExchange.Redis;

namespace LocalizationChallenge.Infrastructure;

public sealed class HybridLocalizationProvider(
    MemoryCacheLocalizationProvider level1,
    RedisLocalizationProvider level2,
    PostgresLocalizationProvider level3,
    IConnectionMultiplexer redis) : ILocalizationProvider
{
    private readonly IDatabase redisDb = redis.GetDatabase();

    public string ProviderName => "Hybrid";

    public async ValueTask<string> GetLocalizedStringAsync(string key, string culture, CancellationToken cancellationToken = default)
    {
        var value = await level1.GetLocalizedStringAsync(culture, key, cancellationToken);
        if (value is not null) return value;

        value = await level2.GetLocalizedStringAsync(culture, key, cancellationToken);
        if (value is not null) return value;

        value = await level3.GetLocalizedStringAsync(culture, key, cancellationToken);
        if (value is not null)
        {
            _ = redisDb.HashSetAsync($"loc:{culture}", key, value);
        }

        return value;
    }
}

Yapıcı metod(constructor) üzerinden dört bileşen enjekte edilmekte. Diğer çoklu dil desteği sağlayan provider bileşenleri ve Redis tarafına erişmek için bir referans. GetLocalizedStringAsync metodunun akışını inceleyelim. Herhangi bir culture için aranan key:value çifti öncelikle in-memory provider'dan karşılanmaya çalışılır ki herhangi bir network maliyeti olmadığından ve veri RAM üzerinde tutulduğundan en hızlı modeldir. Eğer veri level 1 olarak isimlendirilen bu aşamada bulunamazsa ikinci seviyeye inilir(level 2) ve bu kez daha yavaş olan(çünkü arada çıkılması gereken bir network ortamı vardır) Redis provider bileşeni üzerinden aranır. İkinci seviyede de aranan çift bulunamazsa son seviyeye inilir ve PostgreSQL provider kullanılır. Burada disk okuma maliyeti olduğu için diğerlerine göre çok daha yavaş bir akış söz konusudur.

Diğer yandan üçüncü seviye sonrasındaki if bloğuna dikkat etmekte yarar var. Veri bu seviyede bulunduysa bir fire and forget çağrısı yapılarak aranan key:value bilgisinin ilgili culture adına Redis ortamına yazılması sağlanır. Böylece çok kısa süre sonra gelen aynı key:value isteği üçüncü seviyeye inilmeden ikinci seviyeden yani Redis üzerinden karşılanabilir. Bu strateji Cache Promotion olarak da ifade edilmektedir.

IDatabase arayüzü üzerinden çağırılan HashSetAsync metodundan gelen Task sonucu, _ operatörü ile görmezden gelinmiştir(discard) ve hatta dikkat edileceği üzere await bile kullanılmamıştır. Bu tamamen bilinçli bir harekettir zira aranan ve ancak seviye üçte bulunan verinin sonraki çağrılarda yine veritabanından gelmesi yerine Redis'ten gelmesi sağlanır. Bu durum veritabanına yeni veriler eklendiğinde henüz Redis'te olmayan değerlerin eklenmesi açısından da önemlidir. (Çalışmada henüz cache invalidation tarafı için bir şey yapmadık. Yazının ilerleyen kısmında o da var)

Infrastructure projemizde epey bir bileşen oldu. Bu bileşenler çalışma zamanında diğer uygulamalar(bizim senaryoda Web API olacak) tarafından Dependency Injection Container üzerinden kullanılacaklar ve hatta birçok konfigürasyon ayarını da çalışma zamanına almamız gerekecek. Dolayısıyla taktik belli; IServiceCollection arayüzünü genişleterek bu bağımlılıkları infrastructure kütüphanesi üstünden yüklemek. Bu amaçla projeye DependencyInjection isimli aşağıdaki sınıfı ekleyerek devam edelim.

using LocalizationChallenge.Core;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Npgsql;
using StackExchange.Redis;

namespace LocalizationChallenge.Infrastructure;

public static class DependencyInjection
{
    public static IServiceCollection AddLocalizationProviders(this IServiceCollection services, IConfiguration configuration)
    {
        var pgDataSource = NpgsqlDataSource.Create(configuration.GetConnectionString("Postgres"));
        services.AddSingleton(pgDataSource);

        var redis = ConnectionMultiplexer.Connect(configuration.GetConnectionString("Redis"));
        services.AddSingleton<IConnectionMultiplexer>(redis);

        services.AddSingleton<MemoryCacheLocalizationProvider>();
        services.AddSingleton<RedisLocalizationProvider>();
        services.AddSingleton<PostgresLocalizationProvider>();

        services.AddSingleton<ILocalizationProvider>(sp => sp.GetRequiredService<MemoryCacheLocalizationProvider>());
        services.AddSingleton<ILocalizationProvider>(sp => sp.GetRequiredService<RedisLocalizationProvider>());
        services.AddSingleton<ILocalizationProvider>(sp => sp.GetRequiredService<PostgresLocalizationProvider>());
        services.AddSingleton<ILocalizationProvider, HybridLocalizationProvider>();

        services.AddHostedService(sp => sp.GetRequiredService<MemoryCacheLocalizationProvider>());

        return services;
    }
}

Servis(API) Projesi

Şimdi de API servisimizi geliştirmeye başlayalım. Servisimizin amacı provider'ların API yoluyla çalıştığını test edebilmek. Burası doğrudan üretime çıkabilecek türden bir servis olarak düşünülebilir. Minimal API olarak geliştirebiliriz. Çalışma zamanı için gerekli konfigürasyon ayarlarını da eklememiz lazım. Bu amaçla appsettings.json dosyamıza aşağıdaki içeriğe sahip ConnectionStrings bölümünü ekleyerek devam edelim.

{
  "ConnectionStrings": {
    "Postgres": "Host=localhost;Port=5435;Database=postgres;Username=johndoe;Password=somew0rds",
    "Redis": "localhost:6379"
  }
}

Program kodlarını da aşağıdaki gibi yazabiliriz.

using LocalizationChallenge.Core;
using LocalizationChallenge.Infrastructure;
using Microsoft.AspNetCore.Mvc;
using System.Diagnostics;

var builder = WebApplication.CreateBuilder(args);

// Postgres ve Redis için connection string bilgileri alınıyor.
var postgresConnStr = builder.Configuration.GetConnectionString("Postgres") ?? throw new InvalidOperationException("Postgres connection string is not configured.");
var redisConnStr = builder.Configuration.GetConnectionString("Redis") ?? throw new InvalidOperationException("Redis connection string is not configured.");

// Localization provider'lar DI container'a ekleniyor.
builder.Services.AddLocalizationProviders(builder.Configuration);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

// Adettendir "api ayakta mı?" kontrolü
app.MapGet("api/health", () => Results.Ok("Healthy"));

// Belli bir provider, culture ve key için lokalize edilmiş string değeri döndüren endpoint.
app.MapGet("api/localization/{provider}/{culture}/{key}", async (
    string provider,
    string culture,
    string key,
    [FromServices] IEnumerable<ILocalizationProvider> providers,
    CancellationToken cancellationToken) =>
{
    // [FromServices] ile tüm ILocalizationProvider implementasyonlarını alıyoruz ve istenen provider adına sahip olanı buluyoruz.
    var target = providers.FirstOrDefault(p => p.ProviderName.Equals(provider, StringComparison.OrdinalIgnoreCase));
    if (target is null) return Results.NotFound(new { error = $"Provider '{provider}' not found." });

    // Performans ölçümü için Stopwatch kullanarak, lokalize string alma işleminin ne kadar sürdüğünü hesaplıyoruz.
    var timer = Stopwatch.GetTimestamp();
    var value = await target.GetLocalizedStringAsync(key, culture, cancellationToken);
    var elapsed = Stopwatch.GetElapsedTime(timer);

    // Ölçüm sonuçlarını dönüyoruz
    return Results.Ok(new
    {
        Provider = target.ProviderName,
        Culture = culture,
        Key = key,
        Value = value,
        ElapsedMicroseconds = elapsed.TotalMicroseconds
    });
}).WithDescription("Get localized string by provider, culture, and key.");


// Tüm provider'lar için belli bir culture ve key'e karşılık gelen string değerleri döndüren endpoint.
// Bunu tüm provider'ların aynı key için aynı değeri döndürüp döndürmediğini kontrol etmek ve performans karşılaştırması yapmak için kullanabiliriz.
app.MapGet("api/benchmark/{culture}/{key}", async (
    string culture,
    string key,
    [FromServices] IEnumerable<ILocalizationProvider> providers,
    CancellationToken cancellationToken) =>
{
    var results = new List<BenchmarkResult>();

    // DI Container'a kayıtlı tüm provider'lar için, verilen culture ve key'e karşılık gelen lokalize string değerini alıp,
    // performans ölçümü yaparak sonuçları topluyoruz.
    foreach (var provider in providers)
    {
        var timer = Stopwatch.GetTimestamp();
        var value = await provider.GetLocalizedStringAsync(key, culture, cancellationToken);
        var elapsed = Stopwatch.GetElapsedTime(timer);

        results.Add(new BenchmarkResult(
            provider.ProviderName,
            value,
            elapsed.TotalMicroseconds,
            CacheHit: value is not null));
    }

    return Results.Ok(new
    {
        Culture = culture,
        Key = key,
        MeasuredAt = DateTime.UtcNow,
        Results = results.OrderBy(r => r.ElapsedMicroseconds)
    });
}).WithDescription("Benchmark all providers for a given culture and key.");

await app.RunAsync();

Bu noktaya kadar her şey doğru ilerlediyse, en azından API'nin başarılı şekilde çalıştığını ve birkaç key:value değerini sorgulayabildiğimizi görmeliyiz. Bunun için curl veya Postman gibi araçlardan yararlanabiliriz. benchmark endpoint adresine yaptığım Postman çağrısının bir çıktısını aşağıda görebilirsiniz.

Dolayısıyla tasarladığımız altyapının çoklu dil desteği sağladığını garanti etmiş olduk. Şimdi asıl amacımız olan performans ölçümlerine geçebiliriz.

Benchmark Projesi

Benchmark projemiz bir console uygulaması ve içerisinde BenchmarkDotNet kütüphanesini kullanarak farklı provider'ların performansını ölçmeye yarayacak kodları barındıracak. Bu projenin Web API projemizle pek alakası yok. Servis projemiz, ilgili provider'ları API üzerinden dış dünyaya açtığımız bir hizmet sadece.

Tekrar benchmark projemize dönelim. İlk olarak BenchmarkDotNet çalışma zamanı ile ilgili bazı konfigürasyon ayarlarını yapmamız gerekiyor. Bu amaçla ManualConfig tipinden türeyen aşağıdaki sınıfı ekleyerek ilerleyelim.

using BenchmarkDotNet.Columns;
using BenchmarkDotNet.Configs;
using BenchmarkDotNet.Diagnosers;
using BenchmarkDotNet.Environments;
using BenchmarkDotNet.Jobs;
using BenchmarkDotNet.Exporters;
using BenchmarkDotNet.Loggers;
using BenchmarkDotNet.Order;

namespace LocalizationChallenge.Benchmarks;

// BenchmarkDotNet konfigürasyonu için özel bir sınıf oluşturuyoruz. 
// Bu sınıf, benchmark'larımızın nasıl çalışacağını ve hangi ölçümleri yapacağını belirlemekte
public class BenchmarkConfig
    : ManualConfig
{
    public BenchmarkConfig()
    {
        AddJob(Job.Default
            .WithRuntime(CoreRuntime.Core10_0) // Testlerimiz .NET 10 çalışma zamanında koşulacak
            .WithWarmupCount(3) // Her benchmark için 3 kez ısınma turu yapılacak, 
            // böylece JIT derlemesi ve diğer başlangıç maliyetleri hesaplamalara katılmaz. 
            .WithIterationCount(10) // Isınma turları bittikten sonra her benchmark için 10 ölçüm turu yapılacağını belirtmiş oluruz
            .WithInvocationCount(112)); // Her bir iterasyonda (turda) ilgili metotlar arka arkaya 112 kez çağrılacak.(Sadece 6nın katı olması gerektiğini belirten bir hata mesajına istinaden böyle yaptım)

        AddLogger(ConsoleLogger.Default); // Terminal ekranına log basılmasını sağlar.
        AddExporter(MarkdownExporter.GitHub); // Test sonuçlarını GitHub Markdown formatında dışa aktarılmasını sağlar.
        AddDiagnoser(MemoryDiagnoser.Default); // Sadece çalışmas süresinin değil, ne kadar RAM tüketildiğinin ve Garbage Collector'un ne kadar meşgul edildiğinin bilgileri de toplanır.
        AddColumnProvider(DefaultColumnProviders.Instance); // Rapor çıktısına eklenecen kolon adlarını belirler. (Örneğin, ortalama süre, standart sapma, bellek kullanımı gibi)
        Orderer = new DefaultOrderer(SummaryOrderPolicy.FastestToSlowest); // Sonuç tablosu en hızlı metotdan en yavaşa doğru sıralanır.
        Options |= ConfigOptions.JoinSummary;
    }
}

Aslında performans ölçümleri için gerekli ayarların belirlendiği bir sınıf. Detaylı açıklamaları koddaki yorum satırlarında bulabilirsiniz. Tabii birde test edilecek fonksiyonların koşturulması gerekiyor. Bu işi kodları aşağıda görülen LocalizationBenchmark sınıfı üstlenecek.

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Order;
using LocalizationChallenge.Infrastructure;
using Npgsql;
using StackExchange.Redis;

namespace LocalizationChallenge.Benchmarks;

[Config(typeof(BenchmarkConfig))]
[MemoryDiagnoser]
[Orderer(SummaryOrderPolicy.FastestToSlowest)]
public class LocalizationBenchmarks
{
    private PostgresLocalizationProvider _postgres = null!;
    private RedisLocalizationProvider _redis = null!;
    private MemoryCacheLocalizationProvider _memory = null!;
    private HybridLocalizationProvider _hybrid = null!;

    /*
        Testimi sadece tek bir metin için değil 6 farklı senaryo için koşulacak.
        3 culture * 2 key olarak düşünebiliriz.
        Yani çalışma zamanında benchmark buradaki parametrelere göre olası tüm kombinasyonları işletecektir.
    */
    [Params("tr-TR", "en-US", "de-DE")]
    public string Culture { get; set; } = "tr-TR";

    [Params("welcome_message", "button_save")]
    public string Key { get; set; } = "welcome_message";

    /*
        Setup metodu sadece bir kez çalışır. Sonuçta benchmark ölçümlerinde
        sistem ayağa kaklarken veritabanı bağlantısının oluşturulması, redis'e bağlanılması 
        ve provider nesnelerinin bunları kullanarak oluşturulması gibi işlemler de dahil olmak 
        üzere tüm hazırlıkların yapılması gerekir.
        Bunlar ölçümlerimizi etkilememli zira ölçmek istediğimi konu bu hazırlık safhası değil.
    */
    [GlobalSetup]
    public async Task Setup()
    {
        const string postgresConn = "Host=localhost;Port=5435;Database=postgres;Username=johndoe;Password=somew0rds";
        const string redisConn = "localhost:6379,abortConnect=false";

        var dataSource = NpgsqlDataSource.Create(postgresConn);
        var redisDb = await ConnectionMultiplexer.ConnectAsync(redisConn);

        _postgres = new PostgresLocalizationProvider(dataSource);
        _redis = new RedisLocalizationProvider(redisDb);
        _memory = new MemoryCacheLocalizationProvider(dataSource);
        _hybrid = new HybridLocalizationProvider(_memory, _redis, _postgres, redisDb);

        await (_memory).StartAsync(CancellationToken.None);
    }

    /*
        Burası yarışmacıların tanımlandığı kısımdır.
        Buradaki metotların her biri 10 tur boyunca 112şer kez çağrılacak. 
    */
    [Benchmark(Baseline = true, Description = "PostgreSQL (no cache)")]
    public ValueTask<string?> PostgreSQL() => _postgres.GetLocalizedStringAsync(Culture, Key);

    [Benchmark(Description = "Redis (single key)")]
    public ValueTask<string?> Redis() => _redis.GetLocalizedStringAsync(Culture, Key);

    [Benchmark(Description = "MemoryCache (FrozenDictionary)")]
    public ValueTask<string?> MemoryCache() => _memory.GetLocalizedStringAsync(Culture, Key);
    [Benchmark(Description = "Hybrid ( Level1 -> Level 2 -> Level 3, warm)")]
    public ValueTask<string?> Hybrid_Warm() => _hybrid.GetLocalizedStringAsync(Culture, Key);
}

Son olarak bu sınıfın çalıştırılması lazım :D Bunu da Program.cs dosyasına aşağıdaki kodları ekleyerek yapabiliriz.

using BenchmarkDotNet.Running;

namespace LocalizationChallenge.Benchmarks;

public class Program
{
    public static void Main()
    {
        BenchmarkRunner.Run<LocalizationBenchmarks>(new BenchmarkConfig());
    }
}

Çalışma Zamanı ve Test Çıktıları

Kurgumuz neredeyse hazır. Çalışma zamanı performanslarını merak ettiğimiz provider bileşenleri, bunları dış dünyaya açan API endpoint'leri ve benchmark'ları çalıştıracak bir console uygulamamız var. Benchmark projesine dahil olan yarışmacıların maratonunu başlatmak için projeyi release modda çalıştırmamız gerekiyor. Bunun için terminalden aşağıdaki komutu verebiliriz.

dotnet run -c Release --project LocalizationChallenge.Benchmarks/LocalizationChallenge.Benchmarks.csproj

Yaptığımız ayarlara göre benchmark sonuçları projenin kök dizinindeki BenchmarkDotNet.Artifacts/results klasörünün içerisinde markdown formatında bir dosya olarak kaydedilecektir. Bu dosyayı açarak sonuçları inceleyebiliriz ama ben tabloyu hemen buraya da ekliyorum.

BenchmarkDotNet v0.15.8, Windows 11 (10.0.26200.8117/25H2/2025Update/HudsonValley2)
12th Gen Intel Core i7-1255U 1.70GHz, 1 CPU, 12 logical and 10 physical cores
.NET SDK 10.0.201
  [Host]     : .NET 10.0.5 (10.0.5, 10.0.526.15411), X64 RyuJIT x86-64-v3
  Job-RLSDCR : .NET 10.0.5 (10.0.5, 10.0.526.15411), X64 RyuJIT x86-64-v3

Runtime=.NET 10.0  InvocationCount=112  IterationCount=10  
WarmupCount=3

ve sonuç tablosu: (Makalede okunması için HTML table'a dönüştürüldü)

Method	Culture	Key	Mean	Error	StdDev	Ratio	RatioSD	Allocated	Alloc Ratio
'MemoryCache (FrozenDictionary)'	de-DE	button_save	42.68 ns	1.394 ns	0.922 ns	0.000	0.00	-	0.00
'Hybrid ( Level1 -> Level 2 -> Level 3, warm)'	de-DE	button_save	270.24 ns	6.048 ns	3.599 ns	0.000	0.00	-	0.00
'Redis (single key)'	de-DE	button_save	733,373.93 ns	294,165.710 ns	194,572.404 ns	0.704	0.19	496 B	0.16
'PostgreSQL (no cache)'	de-DE	button_save	1,051,584.71 ns	205,259.996 ns	107,354.947 ns	1.009	0.14	3022 B	1.00

'MemoryCache (FrozenDictionary)'	de-DE	welcome_message	52.68 ns	6.997 ns	4.164 ns	0.000	0.00	-	0.00
'Hybrid ( Level1 -> Level 2 -> Level 3, warm)'	de-DE	welcome_message	314.29 ns	41.261 ns	24.554 ns	0.000	0.00	-	0.00
'Redis (single key)'	de-DE	welcome_message	659,207.09 ns	264,839.730 ns	157,601.875 ns	0.711	0.18	504 B	0.16
'PostgreSQL (no cache)'	de-DE	welcome_message	939,895.63 ns	190,529.039 ns	113,380.775 ns	1.014	0.17	3170 B	1.00

'MemoryCache (FrozenDictionary)'	en-US	button_save	45.27 ns	8.443 ns	5.585 ns	0.000	0.00	-	0.00
'Hybrid ( Level1 -> Level 2 -> Level 3, warm)'	en-US	button_save	221.43 ns	6.580 ns	3.442 ns	0.000	0.00	-	0.00
'Redis (single key)'	en-US	button_save	474,298.21 ns	112,236.560 ns	66,790.177 ns	0.669	0.11	496 B	0.14
'PostgreSQL (no cache)'	en-US	button_save	716,641.16 ns	125,565.800 ns	83,054.002 ns	1.012	0.15	3523 B	1.00

'MemoryCache (FrozenDictionary)'	en-US	welcome_message	64.58 ns	21.730 ns	12.931 ns	0.000	0.00	-	0.00
'Hybrid ( Level1 -> Level 2 -> Level 3, warm)'	en-US	welcome_message	242.96 ns	19.798 ns	11.781 ns	0.000	0.00	-	0.00
'Redis (single key)'	en-US	welcome_message	611,825.98 ns	158,720.398 ns	104,983.716 ns	0.540	0.14	504 B	0.17
'PostgreSQL (no cache)'	en-US	welcome_message	1,179,268.21 ns	371,467.479 ns	245,702.737 ns	1.040	0.30	2985 B	1.00

'MemoryCache (FrozenDictionary)'	tr-TR	button_save	40.67 ns	7.082 ns	4.214 ns	0.000	0.00	-	0.00
'Hybrid ( Level1 -> Level 2 -> Level 3, warm)'	tr-TR	button_save	290.38 ns	59.079 ns	35.157 ns	0.000	0.00	-	0.00
'Redis (single key)'	tr-TR	button_save	618,747.50 ns	177,637.174 ns	117,495.992 ns	0.733	0.15	496 B	0.14
'PostgreSQL (no cache)'	tr-TR	button_save	852,865.62 ns	129,511.326 ns	85,663.723 ns	1.010	0.14	3533 B	1.00

'MemoryCache (FrozenDictionary)'	tr-TR	welcome_message	32.84 ns	1.458 ns	0.868 ns	0.000	0.00	-	0.00
'Hybrid ( Level1 -> Level 2 -> Level 3, warm)'	tr-TR	welcome_message	278.27 ns	4.919 ns	2.927 ns	0.000	0.00	-	0.00
'Redis (single key)'	tr-TR	welcome_message	517,565.18 ns	164,111.238 ns	108,549.423 ns	0.749	0.16	504 B	0.14
'PostgreSQL (no cache)'	tr-TR	welcome_message	693,429.66 ns	66,129.158 ns	39,352.401 ns	1.003	0.08	3540 B	1.00

Tablo çok güzel oluştu evet harika ama ne anlama geliyor bunca şey :D Nasıl okumak, ne şekilde değerlendirmek lazım. Bizim için önemli olacak terimlerle başlayalım.

Mean: Ortalama süre olarak düşünebiliriz. İşlemin ne kadar sürdüğü konusunda bilgi verir. Tabii süreler oldukça mikro seviyededir. Bir saniye aslında yazılım dünyası için çooooooook uzundur! 1 saniye = 1.000 milisaniye (ms) = 1.000.000 mikrosaniye (μs) = 1.000.000.000 nanosaniye (ns) olarak ifade edilir. Örneğin, button_save için FrozenDictionary kullandığımızda 42.68 ns ortalamada veriye ulaştığımızı görüyoruz.
Ratio: Kıyaslama için kullanılan oran bilgisidir. LocalizationBenchmark sınıfında PostgreSQL seçeneği için kullandığımız Benchmark niteliğinde(attribute), baseline değerini true olarak belirlemiştik. Boşuna değildi. Onu 1 değeri olarak sabitlediğimizi ve diğer ölçümlerin yüzdesel olarak ne kadar farklı olduğunu ratio değerleri ile anlarız. Örneğin, Redis senaryosunda bu değer yer yer 0,50 seviyesine yaklaşsa da 0,70 civarında. Yani Redis seçeneği, PostgreSQL seçeneğine göre neredeyse %30 daha hızlı şeklinde yorumlayabiliriz.
Allocated: Bellek üzerinde garbage collector'a konu olacak yer tahsislerini ifade eder. Büyük değerler çok doğal olarak GC'nin çok daha fazla yorulması anlamına gelir zira toplaması gereken bellek miktarı fazladır. Burada görmek isteyeceğimiz değer genelde - işaretidir :D Sıfır tüketim maliyeti. Dikkat ederseniz senaryolarımız arasında hibrit ve FrozenDictionary esaslı in-memory cache kullanımları bunu karşılar türdendir.

Sonuçlar çok şaşırtıcı olmasa gerek. Disk üzerinden ciddi anlamda operasyon maliyeti olan Postgres modeli doğal olarak en yavaş çalışan tekniktir. Bununla birlikte kalıcılık(persistence) açısından ve hatta SQL gibi domain odaklı bir dil ile içerik ulaşılabilirliği açısından avantajlıdır. Lakin bizim senaryomuzda iddia, bu teknikler arasındaki erişim hızı farklılıkları üzerine. Dolayısıyla bellek kullanımı daha ideal bir seçenek haline geliyor. Dağıtık veritabanı sistemlerinin in-memory çalışan en iyi örneklerinden birisi olan Redis, PostgreSQL kullanımına göre elbette daha hızlı(0,6 milisaniye civarında ve %30 daha hızlı). Ayrıca bellek kullanımı açısından da avantajlı(3 Kilobyte'a 500 byte gibi). Ancak onun da bir network maliyeti olduğunu ve dayanıklılık(resilience) problemlerini de hesaba katmamızı gerektirdiğini unutmayalım. Bu iki seçenek bir yana FrozenDictionary kullanılan senaryoda işlemler nanosaniyeler mertebesinde gerçekleşebiliyor zira burada fiziki disk operasyonları veya network ortamlarına git-gel döngüleri söz konusu değil. Her şey process'in yürütüldüğü makine belleğinde gerçekleşmekte. Tabii ölçeklenebilir bir sisteme gittiğimizde senkronizasyonu sağlamak da düşünülmesi gerekenler arasında. Dördüncü seçeneğimiz bilindiği üzere hibrit model. Hibrit modelin, in-memory seçeneğine göre biraz daha yavaş olması son derece normal zira yürütücü metot içerisinde birçok null check kontrolü var. Ancak o da veriyi level 1 mertebesinde FrozenDictionary avantajları ile karşılıyor. Hem hibrit hem de tek başına in-memory modeli, bellek yer tahsisatı(allocation) konusunda da çok verimliler.

Hibrit model sahip olduğu strateji gereği tercih edilecek yöntem gibi duruyor. Sadece makul erişim süreleri olarak değil, veriyi farklı seviyelerde ele alma biçimi de dayanıklı kalma, network gecikmelerini absorbe etme gibi avantajlar sağlıyor. Ancak henüz bilmecenin önemli bir parçası olan cache invalidation tarafını ele almadık. Şimdi bu konuya geçelim.

Değişiklikleri Algılama Servisi (Cache Invalidation)

Müşteriye özel terzi dikimi iş çözümlerinden ürünleşmiş olanlarına kadar neredeyse bütün uygulamalarda nadiren de olsa statik veri kümelerinin değişimi ya da yenilerinin eklenmesi söz konusudur. Örneğin müşteri ihtiyaçları doğrultusunda geliştirilen yeni bir özellikteki kullanıcı mesajları, iletiler, bildirimler çoklu dil desteği için yeni kelimelerin girilmesini ya da değiştirilmesini gerektirebilir. Hatta bazı senaryolarda cümlelerin çoklu dil desteğine göre hazırlanması da mümkündür. "Ödemeniz başarıyla gerçekleştirildi" cümlesinin çoklu dil desteğine göre eklenmesi(Almancacı şöyle, "Ihre Zahlung wurde erfolgreich durchgeführt") veya "Ödemeniz başarılı bir şekilde gerçekleştirildi." şeklinde değiştirilmesi söz konusudur. Tüm bu hareketlilik cache'lenen verilerin tekrardan çekilmesini gerektirir.

Bizim çalışmamızda Cache-Invalidation önemli bir yere sahip. Örneğin hibrit metodolojimizde Level 3'te yani veritabanı seviyesinde bir güncelleme olduğunda önceden yüklenen değerler Level 1 ve Level 2 seviyesinde yaşamaya devam edecek ve sistemdeki kullanıcılar eski değere erişecek. Dolayısıyla cache üzerindeki veriyi çeşitli bildirimler ile güncellememiz gerekiyor.

Senaryomuzda çoklu dil desteğinin ana kaynağı, PostgreSQL üzerinde tuttuğumuz localizations isimli veritabanı tablosu. Buradaki değişikliklere göre cache üzerinde yenileme veya düşürme gibi işlemleri nasıl ele alabileceğimize bir bakalım. İlk olarak veri tabanı tarafına gerekli enstrümanları ekleyelim.

CREATE OR REPLACE FUNCTION notify_loc_change()
    RETURNS TRIGGER LANGUAGE plpgsql AS $$
BEGIN
    PERFORM pg_notify('loc_changed', NEW.culture || ':' || NEW.resource_key);
    RETURN NEW;
END;
$$;

CREATE OR REPLACE TRIGGER trg_loc_change
    AFTER INSERT OR UPDATE OR DELETE ON localizations
    FOR EACH ROW EXECUTE FUNCTION notify_loc_change();

localizations tablosundaki satırlarda veri ekleme, güncelleme veya silme işlemleri gerçekleştirildiğinde trg_loc_change isimli trigger tetiklenir. Bu trigger içerisinden de notify_loc_change isimli fonksiyon çağırılır. Fonksiyonumuzda PostgreSQL içerisine gömülü olan pg_notify isimli bir başka fonksiyon çağırılmaktadır. Aslında bu basit bir pub/sub sisteminin tetikleyicisidir. Fonksiyon tetiklendiğinde değişen satırdaki culture ve resource_key bilgileri(ki NEW ile ifade edilir) kanala gönderilir. Bir nevi broadcast yayını söz konusudur. Dolayısıyla burayı dinleyen aboneler bu değişikliği yakalar.

Background Service ile Değişiklikleri Algılama

PostgreSQL tarafı üzerine düşen görevi yapacak ve değişiklik olduğunda bunu broadcast yayını ile ortama fırlatacak. Altyapı işlerini tuttuğumuz projemize bir BackgroundService türevi ekleyerek devam edelim.

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Npgsql;
using StackExchange.Redis;

namespace LocalizationChallenge.Infrastructure;

public class LocalizationCacheSenseService(
    NpgsqlDataSource dataSource,
    IConnectionMultiplexer redis,
    MemoryCacheLocalizationProvider memCacheProvider,
    ILogger<LocalizationCacheSenseService> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken cancellationToken)
    {
        // Bir iptal isteği gelene kadar, PostgreSQL veritabanına bağlanarak "loc_changed" kanalını dinliyoruz.
        while (!cancellationToken.IsCancellationRequested)
        {
            try
            {
                await using var conn = await dataSource.OpenConnectionAsync(cancellationToken);

                // Notification event'ine abone olarak, veritabanında bir değişiklik olduğunda tetiklenecek kod bloğu.
                conn.Notification += async (_, args) =>
                {
                    // Eğer bir değişiklik varsa (update,delete, insert) event metodun içerisine düşmemiz lazım
                    logger.LogInformation("Localization changed: {Payload}", args.Payload);
                    // postgresql tarafından gönderilen payload'u "culture:resourceKey" formatında bekliyoruz.
                    // Bu bilgiyi kullanarak, ilgili cache kaydını Redis'ten siliyoruz.
                    var parts = args.Payload.Split(':', 2);
                    if (parts.Length == 2)
                    {
                        var culture = parts[0];
                        var resourceKey = parts[1];
                        var db = redis.GetDatabase();
                        await db.HashDeleteAsync($"loc:{culture}", resourceKey);
                    }
                    // Ayrıca bellekte duran cache'i de güncellemek adına
                    // MemoryCacheLocalizationProvider'ın StartAsync metodunu çağırıyoruz
                    // Dolayısıyla debug ederken oraya da gidebiliyor olmamız lazım
                    await memCacheProvider.StartAsync(CancellationToken.None);
                };

                // PostgreSQL'de LISTEN komutunu kullanarak loc_changed kanalını dinlememiz gerekiyor.
                // Zira oradaki trigger içerisinden tetiklenen fonksiyon bu isimle bir yayın yapmakta
                await using var cmd = conn.CreateCommand();
                cmd.CommandText = "LISTEN loc_changed";
                await cmd.ExecuteNonQueryAsync(cancellationToken);

                logger.LogInformation("Listening for localization changes on PostgreSQL channel loc_changed");

                while (!cancellationToken.IsCancellationRequested)
                    await conn.WaitAsync(cancellationToken);
            }
            catch (OperationCanceledException)
            {
                break;
            }
            catch (Exception ex)
            {
                logger.LogWarning(ex, "Localization invalidation connection lost. Reconnecting in 5s...");
                await Task.Delay(TimeSpan.FromSeconds(5), cancellationToken);
            }
        }
    }
}

Tabii eklediğimiz bu servisi Infrastructure projemizdeki DependencyInjection sınıfına da eklememiz gerekiyor.

services.AddHostedService<LocalizationCacheSenseService>();

Artık testlerimizi yapabiliriz. API projesini ayağa kaldırdığımızda, Infrastructure projesinden DIC'ye eklenen servisler de ayağa kalkar. Dolayısıyla PostgreSQL tarafındaki değişiklikleri dinleyen LocalizationCacheSenseService de çalışmaya başlar. Ardından pgAdmin ya da DBeaver ile tablo üzerinde değişiklikler yapabiliriz. Bunu debug modda denemenizi şiddetle tavsiye ederim. Zira, değişiklikleri commit edince Visual Studio ortamında ilgili event metodunun tetiklendiğini ve cache'in temizlendiğini görebilirsiniz. Sonrasında Postman üzerinden aynı key ve culture bilgileriyle API çağrısı yapıp, değişikliklerin yansıyıp yansımadığını kontrol edebiliriz.

NBomber ile Yük Testi

Şu ana kadar yaptıklarımızı bir değerlendirelim. Hedefimiz çoklu dil desteği senaryolarında farklı yaklaşımlar arasındaki hız farkını incelemekti. Ana kaynak olarak bir veritabanı sistemi kullandık ancak özellikle hibrit sistemimiz buradaki veriyi level 2 ve level 1 olmak üzere daha hızlı noktalardan da karşılar oldu. Bununla birlikte çoklu dil kümelerine doğrudan API çağrıları ile de erişebiliyoruz. Gerçek hayat senaryolarında dil bağımlı büyük bir veri setinin veya parçalarının servisler yoluyla çekilmesi pekala söz konusu olabilir. Hal böyle olunca bir yük testi(load test) ve sonrasında ortaya çıkacak tablonun da incelenmesi gerekiyor. Bu amaçla NBomber isimli .NET kütüphanesini kullanarak bir deneme yapabiliriz. Çözümümüze yeni bir console uygulaması ekleyip gerekli nuget paketlerini yükleyelim.

# Console projesi oluşturuluyor
dotnet new console -n LocalizationChallenge.LoadTest
# NBomber ile ilgili eklentiler
dotnet add LocalizationChallenge.LoadTest/LocalizationChallenge.LoadTest.csproj package NBomber
dotnet add LocalizationChallenge.LoadTest/LocalizationChallenge.LoadTest.csproj package NBomber.Http

dotnet sln add LocalizationChallenge.LoadTest

Sırada NBomber kullanımı için gerekli kodlarımız var.

using NBomber.Contracts;
using NBomber.CSharp;
using NBomber.Http.CSharp;
using System.Text.Json;

namespace LocalizationChallenge.LoadTest;

class Program
{
    static void Main()
    {
        var postgresMetric = Metric.CreateGauge("postgres_read_us", unitOfMeasure: "us");
        var redisMetric = Metric.CreateGauge("redis_read_us", unitOfMeasure: "us");
        var memoryMetric = Metric.CreateGauge("memory_read_us", unitOfMeasure: "us");
        var hybridMetric = Metric.CreateGauge("hybrid_read_us", unitOfMeasure: "us");

        var cultures = new[] { "tr-TR", "en-US", "de-DE" };
        var keys = new[] { "welcome_message", "farewell_message", "button_save", "error_not_found" };

        var handler = new HttpClientHandler
        {
            ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
        };
        var httpClient = new HttpClient(handler);

        var scenario = Scenario.Create("ramp_up_scenario", async context =>
        {
            var culture = cultures[Random.Shared.Next(cultures.Length)];
            var key = keys[Random.Shared.Next(keys.Length)];

            var request = Http.CreateRequest("GET", $"https://localhost:7092/api/benchmark/{culture}/{key}");
            var response = await Http.Send(httpClient, request);

            if (response.StatusCode != "OK" || response.Payload.Value == null)
            {
                return Response.Fail(statusCode: response.StatusCode);
            }

            try
            {
                using var httpResponse = response.Payload.Value;
                await using var stream = await httpResponse.Content.ReadAsStreamAsync();
                using var jsonDoc = await JsonDocument.ParseAsync(stream);

                if (jsonDoc.RootElement.TryGetProperty("results", out var results))
                {
                    foreach (var result in results.EnumerateArray())
                    {
                        var provider = result.GetProperty("providerName").GetString();
                        var elapsed = result.GetProperty("elapsedMicroseconds").GetDouble();

                        switch (provider)
                        {
                            case "Postgres": postgresMetric.Set(elapsed); break;
                            case "Redis": redisMetric.Set(elapsed); break;
                            case "InMemoryCache": memoryMetric.Set(elapsed); break;
                            case "Hybrid": hybridMetric.Set(elapsed); break;
                        }
                    }
                }

                return Response.Ok(statusCode: response.StatusCode);
            }
            catch (Exception ex)
            {
                context.Logger.Error(ex, "JSON parse error has been occured.");
                return Response.Fail(statusCode: response.StatusCode, "Parse Error");
            }
        })
        .WithWarmUpDuration(TimeSpan.FromSeconds(5))
        .WithLoadSimulations(
            Simulation.RampingConstant(copies: 100, during: TimeSpan.FromSeconds(30)),
            Simulation.KeepConstant(copies: 100, during: TimeSpan.FromSeconds(60)),
            Simulation.RampingConstant(copies: 0, during: TimeSpan.FromSeconds(10))
        );

        NBomberRunner
            .RegisterScenarios(scenario)
            .Run();
    }
}

Tabii testler sırasında bazı beklenmedik durumlar da oldu. Örneğin bu kadar çok isteğin PostgreSQL veritabanına gitmesi "53300: sorry, too many clients already" şeklinde bir çalışma zamanı istisnası(runtime exception) oluşmasına neden oldu. Bu problemi aşmak için havuzda duracak maksimum ve minimum bağlantı sayısını ayarlamak gerekiyor. Dolayısıyla ilgili connection string bilgisine Maximum Pool Size ve Minimum Pool Size parametrelerini eklemeliyiz.

"ConnectionStrings": {
    "Postgres": "Host=localhost;Port=5435;Database=postgres;Username=johndoe;Password=somew0rds;Maximum Pool Size=20;Minimum Pool Size=5"
  }

Önemli Not: NBomber bireysel olarak ücretsiz kullanılabilen bir araç ancak üretim ortamlarında lisanslama gerektirebilir. Detaylar için NBomber sayfasını incelemekte yarar var. Ya da hafifsiklet bir load test aracını kendimiz yazabiliriz de.

LoadTest isimli konsol uygulaması çalıştırdığımızda reports isimli klasör içerisinde ölçümlere ait dosyalar oluşur. HTML, markdown, text ve csv formatlarında oluşan bu dosyalar içerisinde tabiri caizse ne ararsak var :D

Hatta şuraya markdown dosyasındaki ölçüm değerlerini içeren tabloları da ekleyelim. Ancak benim önerim özellikle HTML sayfasını incelemeniz yönünde olacak.

step	ok stats
name	global information
request count	all = 197178, ok = 197178, RPS = 1971.78
latency (ms)	min = 1.68, mean = 40.39, max = 267.74, StdDev = 19.29
latency percentile (ms)	p50 = 39.17, p75 = 51.42, p95 = 73.54, p99 = 94.4

status code	count	message
OK	197178

Load Test Sonuçlarını Nasıl Yorumlamalıyız?

Burada ağ gecikmelerini (Network Latency), Kestrel sunucusunun tepkisini, routing işlemlerini ve elde edilen sonuçların JSON olarak işlenip geri döndürülmesini kapsayan uçtan uca bir ölçümleme yapılmakta. Yani benchmark testlerinden daha farklı bir durum söz konusu.

Benim elde ettiğim sonuçlar 100 saniyelik zaman diliminde(1 dakika 40 saniye) gerçekleşmiş durumda. Bu aralıkta 200 bine yakın talep yollanmış ve 0 hata alınmış. Saniyede ortalama 2000 talep işlenmiş. Bir kullanıcı isteğinin API tarafına ulaşması, işlenmesi ve geri dönmesi de ortalama 40 milisaniye sürmüş. Bununla birlikte latency percentile sekmesinde p50, p75, p95 ve p99 şeklinde bazı değerler yer aldığını görebilirsiniz. Bu değerleri de şöyle yorumlayalım; Her 100 kullanıcıdan 99'u cevabını 94.4 milisaniyenin altında almış. Yani 100 kullanıcıdan 1 tanesi cevabını 94.4 milisaniyeden daha geç almış. Buna göre 100 kullanıcıdan 95'i cevabını 73.54 milisaniyenin altında bir sürede alırken 5 tanesi cevabını 73.54 milisaniyeden daha geç almış. Dolayısıyla p yüzdeliklerini bu mantıkta okuyabiliriz. Aslında görsel anlatımı çok daha etkili ne yalan söyleyeyim(Bir resim bin kelimeye bedel mi?) O yüzden HTML raporunu incelemenizi öneririm :D

Diğer yandan kod içerisinde birer Gauge olarak tanımladığımız özel metriklerde çalışma sürelerine dair ölçümler yer alır ve HTML dosyasından ulaşılabilir.

Böylece geldik bir çalışmamızın daha sonuna. Benim için uzun ama epey eğitici oldu. En azından bir test düzeneğini örnek bir senaryo ile ele alma şansı buldum. Umarım sizler için de faydalı olmuştur. Tekrardan görüşünceye dek hepinizi mutlu günler dilerim.

Çalışmaya ait örnek kodlara GitHub üzerinden ulaşabilirsiniz.

Smart Enums

2026-04-01T16:53:00+00:00

Yazılım geliştirme galaksisinin en zorlu yolculuklarından birisi sanıyorum ki Domain Driven Design(DDD) rotasında ilerlemek. Büyük çaplı kurumsal projelerde hangi mimari ile çalışacağımıza karar vermek bir yana dursun domain sınırlarını belirlemek, model nesneleri kurgulamak, ortak jargonu çıkarmak ve bu jargonu kod içerisinde nasıl temsil edeceğimize karar vermek gibi pek çok zorluğu beraberinde getiren bir yolculuk. Gerçekten farklı yetkinlikler gerektiğine inandığım bu yaklaşımda gün geçmiyor ki yeni bir konuyu tartışalım. İşte henüz gerçekleştirdiğimiz bir tartışma:

Problem

Diyelim ki sipariş talep formlarını(OrderForm olarak ifade edelim) ele aldığımız bir çerçevede çalışıyoruz. Üzerinde duracağımız konu bir sipariş formunun herhangi bir andaki durumunu nasıl temsil edeceğimiz. Söz gelimi C# gibi nesne yönelimli bir dil kullanıyorsak bir enum türü ile bunu pekala sağlayabiliriz. Zira sipariş formu statüleri çoğunlukla bellidir ve değişmez(Approved, Rejected, Canceled vb) Tam o sırada bir arkadaşımız şöyle seslenir; "Bu ürünü farklı firmalar alacak ve bu firmaların ele alacağı senaryolarda var olan statülerin genişletilmesi gerekebilir". Örneğin sipariş formu statüleri arasında "Müdür Onayı Gerekiyor" (ManagerApprovalRequired) gibi farklı bir statü varsa... Bu durumda ne yapacağız? Ürünümüzün doğası gereği çekirdek domain modelimizi korumamız gerekiyor ama aynı zamanda müşterinin ihtiyacına göre de genişletilmesi. Enum yapısı bu esnekliği sağlayabilir mi? Rust ile geliştiriyor olsaydık farklı bir şekilde değerlendirebilirdik durumu ancak C# açısından konuya bakarsak belki de bu durumu sadece enum türü ile değil bir başka Value Object tasarlayarak ele almak gerekecek.

Bu problemde birkaç noktaya da dikkat etmemiz gerekiyor.

Öncelikle kodumuzun yeni statüler eklenmesine izin verecek şekilde açık olmasını sağlamak ama mevcut domain kurallarının da değiştirilmesini engellemek istiyoruz. Bir nevi Open/Closed Principle vakasıyla karşı karşıya olduğumuzu ifade edebiliriz.
Kuvvetle muhtemel bu ürün ilişkisel bir veritabanı sistemi kullanacak ve statü gibi enum benzeri yapıları saklarken metinsel bir değer yerine sayısal karşılıklarını kullanacağız. Öyle bir yaklaşıma gitmeliyiz ki örneğin veri tabanında TenantId, Name, CoreStatusId gibi bir tablo kullanabilelim.
Ayrıca, bu statülerin iş mantığı ile nasıl etkileşime gireceğini de düşünmemiz gerekiyor. Örneğin, belirli bir statüye geçişin hangi koşullarda mümkün olduğunu ve bu geçişlerin nasıl yönetileceğini ayarlamalı, genişletilen statülerin de bu kurallara uymasını sağlamamız lazım.

ve daha aklıma gelmeyen başka başka sorunlar...

Çözüm Yolu

Domain Driven Design açısından olaya bakarsak değişmezler olarak çevirebileceğimiz invariants önemli bir role sahiptir. OrderForm gibi aslında bir Aggregate Root olarak tanımlayabileceğimiz bir nesne modeli söz konusu olduğunda, bu modelin durumunu temsil eden statülerin de belirli değişmez değerlere sahip olması beklenir. Zira verinin her zaman tutarlı ve kurallara uygun(geçerli) bir durumda kalması sağlanmalıdır. Firmaların kendi statülerini eklemelerine izin verdiğimizde, temel domain üzerinde konuşlandırdığımız iş kurallarının ihlal edilme riski ortaya çıkar. Örneğin, "sadece onaylandı statüsündeki siparişlerin iptal edilebileceği" gibi bir kuralımız varsa ve ürünümüzü kullanan firma "Üst Yönetici İncelemesinde(ManagerApprovalRequired)" şeklinde yeni bir statü eklerse domain'imiz gelen yeni statünün iptal edilebilir olup olmadığını bilemeyecektir. Bu sorunu şöyle çözebiliriz.

Domain tarafından kesinlikle bilinmesi gereken statüleri yine bir Enum türü ile tanımlayabiliriz. Örneğin OrderFormStatus isimli bir enum kullanılabilir. Bunlar ana statülerdir ve domain'in temel iş kurallarına göre hareket ederler.
Müşteri yeni bir statü ekleyecekse bu statü mutlaka bir OrderFormStatus'a bağlanmalıdır. Yani bir nevi mapping yapısı kurgularız.

C# Yaklaşımı

Bu kadar laf kalabalığından sonra gelin C# tarafında çok basit bir şekilde durumu ele alalım. İlk olarak çekirdek Enum türümüzü tanımlayalım.

public enum OrderFormStatus
{
    Draft,
    Canceled,
    Completed,
    Processing
}

Şimdi standart statüleri ve müşteriye özel statüleri tutabileceğimiz değer türü nesnemizi(Value Object) tasarlayalım ki bunu Smart Enum olarak isimlendirebiliriz.

public class OrderFormTenantStatus // : ValueObject
{
    public Guid Id { get; }
    public Guid TenantId { get; }
    public string Name { get; }
    public OrderFormStatus CoreStatus { get; }

    private OrderFormTenantStatus(Guid id, Guid tenantId, string name, OrderFormStatus coreStatus)
    {
        if (string.IsNullOrEmpty(name))
            throw new ArgumentException("Name cannot be null or empty.", nameof(name));

        Id = id;
        TenantId = tenantId;
        Name = name;
        CoreStatus = coreStatus;
    }

    public static readonly OrderFormTenantStatus Draft = new(Guid.NewGuid(), Guid.Empty, "Draft", OrderFormStatus.Draft);
    public static readonly OrderFormTenantStatus Processing = new(Guid.NewGuid(), Guid.Empty, "Processing", OrderFormStatus.Processing);
    public static readonly OrderFormTenantStatus Completed = new(Guid.NewGuid(), Guid.Empty, "Completed", OrderFormStatus.Completed);
    public static readonly OrderFormTenantStatus Canceled = new(Guid.NewGuid(), Guid.Empty, "Canceled", OrderFormStatus.Canceled);

    public static OrderFormTenantStatus Create(Guid id, Guid tenantId, string name, OrderFormStatus mappedCoreStatus)
    {
        return new OrderFormTenantStatus(id, tenantId, name, mappedCoreStatus);
    }
}

Ne güzel tek bir enum değerine bağlayarak devam edecektik değil mi? :D Ama işte gerçek dünya senaryolarında durum böyle olmuyor. Nihayetinde taban sistem ve genişleyebildiği dünya açısından baktığımızda bir sipariş formunun durumunu belirtmek, onu sayısal, metinsel ve dönüşebileceği diğer statülerle ilişkilendirdiğimiz daha yetenekli bir nesne modeline ihtiyaç duyuyor. Denklem işin içerisine Tenant kavramının girmesiyle değişiyor. Tanımladığımız OrderFormTenantStatus sınıfı, çekirdek statüleri temsil eden OrderFormStatus enum'ına bağlanarak müşterinin istediği kadar yeni statü ekleyebilmesine olanak tanır.

Aynı zamanda domain kurallarını da korumaya devam eder. Müşteri yeni bir statü eklediğinde, bu statünün hangi çekirdek statüye karşılık geldiğini belirtmesi gerekir ve böylece domain'in temel iş kurallarının ihlal edilmesini engelleriz. Varsayılan statülerde tenant id değerleri bilerek boş bırakılır ki bunların en üst noktada bağımsız statüler olduğu anlaşılabilsin. Senaryoyu basit tutabilmek adına buradaki üst türev sınıf veya bazı domain kurallarını göz ardı ettik. Şimdi de OrderForm isimli aggregate root modelinde bu enstrümanları nasıl kullanacağımıza bir bakalım.

public class OrderForm
{
    public Guid Id { get; private set; }
    public Guid TenantId { get; private set; }
    public OrderFormTenantStatus Status { get; private set; }

    public OrderForm(Guid id, Guid tenantId, OrderFormTenantStatus initialStatus)
    {
        Id = id;
        TenantId = tenantId;
        
        if (initialStatus.CoreStatus != OrderFormStatus.Draft)
            throw new ArgumentException("Initial status must be Draft.", nameof(initialStatus));

        Status = initialStatus;
    }

    public void UpdateStatus(OrderFormTenantStatus newStatus)
    {
        if (newStatus.TenantId != Guid.Empty && newStatus.TenantId != TenantId)
            throw new InvalidOperationException("Cannot change status to a status from a different tenant.");

        OrderFormStatus currentCoreStatus = Status.CoreStatus;
        OrderFormStatus newCoreStatus = newStatus.CoreStatus;

        if (currentCoreStatus == OrderFormStatus.Draft && newCoreStatus != OrderFormStatus.Processing)
            throw new InvalidOperationException("Draft status can only transition to Processing.");

        if (currentCoreStatus == OrderFormStatus.Processing && newCoreStatus == OrderFormStatus.Draft)
            throw new InvalidOperationException("Processing status cannot transition back to Draft.");

        Status = newStatus;
    }
}

Evet zihinler karışmış kafamızın üst kısmında dumanlar yükseliyor olabilir. OrderForm kendi içinde statüleri OrderFormTenantStatus türünden tutuyor. Bu tür varsayılan çekirdek değerlerin oluşturulmasına static readonly alanlar üzerinden izin verirken aynı zamanda müşterinin istediği kadar yeni statü ekleyebilmesine de olanak tanıyor. Ayrıca statü değişikliği yapmak istediğimizde özel statüler de bağlandıkları statüler gereğince çekirdek iş kurallarına tabii oluyor. Yalnız burada dikkat edilmesi gereken bir şey daha var; yeni bir statü oluştururken id,name, tenantId değerleri ile müşteri nezdinde özelleşen statüyü bir OrderFormStatus değeri ile içeriye almak zorunda oluşumuz. Yani tenant'lar bir sipariş formunda kendi statülerini kullanmak isterse mutlaka baz statüde karşılık bulmuş bir statü örneği ile eklemeliler. Dilerseniz durumu örnek bir senaryo ile pekiştirelim zira ben de ortalığı karıştırmış olabilirim. En güzel sözü kod söyleyecek.

Müşterimizin kullanmak istediği üç farklı statü olsun; Parça bekleniyor(WaitingForParts), Montaj Hattında(AssemblyLine) ve Terzide(InTailor). Yine müşteri açısından değerlendirdiğimiz bu statülerin hepsi domain açısından Processing statüsüne karşılık geliyor olsun. Buna göre OrderForm nesnemizi örneklemeye ve statü güncellemeleri yapmaya çalışalım.

public class Program
{
    public static void Main()
    {
        Guid myTenantId = Guid.NewGuid();

        var waitingForPartsStatus = OrderFormTenantStatus.Create(Guid.NewGuid(), myTenantId, "Waiting for Parts", OrderFormStatus.Processing);
        var assemblyLineStatus = OrderFormTenantStatus.Create(Guid.NewGuid(), myTenantId, "Assembly Line", OrderFormStatus.Processing);
        var inTailorStatus = OrderFormTenantStatus.Create(Guid.NewGuid(), myTenantId, "In Tailor", OrderFormStatus.Processing);

        var order = new OrderForm(Guid.NewGuid(), myTenantId, OrderFormTenantStatus.Draft);
        Console.WriteLine($"Initial Order Status: {order.Status.Name}");
        
        order.UpdateStatus(waitingForPartsStatus);
        Console.WriteLine($"Updated Order Status: {order.Status.Name}");
        
        order.UpdateStatus(assemblyLineStatus);
        Console.WriteLine($"Updated Order Status: {order.Status.Name}");
        
        order.UpdateStatus(inTailorStatus);
        Console.WriteLine($"Updated Order Status: {order.Status.Name}");
        
        order.UpdateStatus(OrderFormTenantStatus.Canceled);
        Console.WriteLine($"Updated Order Status: {order.Status.Name}");
    }
}

Çalışma zamanı çıktısına bir bakalım mı?

O sırada dinlediğim şarkı bir yana statüler arasında sorunsuzca geçiş yapabildiğimizi görebiliriz. Yani Draft statüsünden itibaren olması gerektiği gibi sırasıyla Processing ve Canceled statülerine geçiş yapabildik. Müşterinin eklediği statüler de domain kurallarına uygun şekilde hareket ettik. Tabii burada iş kurallarını ihlal eden vakaları da denememiz lazım. Bu güzide görevleri de sizlere bırakıyorum :D

Rust'ın Şık Yaklaşımı

Tabii tüm bu sorular üzerinde ilerlerken insan ister istemez Rust dilinin zengin enum veri yapılarını düşünüyor. Evet tam anlamıyla nesne yönelimli bir dil değil ama ortak paydada soyutlamaları karşılama şekli değişse de aynı pratiği ele alabiliriz diye düşünüyorum. Rust'ın enum veri yapısı Algebraic Data Types olarak bilinir ve her bir enum varyantı kendi içinde farklı veri taşıyabilir. Bu da bize çok daha esnek ve güçlü bir şekilde statüleri tanımlama imkanı verir. Ayrıca null diye bir kavram olmaması bu tip kontrolleri yapacağımız kısımlarda Option gibi çok daha güvenli bir türden yararlanmamıza vesile olur. Şimdi de aynı senaryoyu Rust tarafında ele alalım. Sadece guid kullanımı için uuid crate'ini eklememiz gerekecek.

cargo add uuid -F v4

İşe OrderFormStatus enum veri yapısını tanımlayarak başlayalım. Bu en çekirdek statüleri tutacağı için dümdüz bir enum.

use uuid::Uuid;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OrderFormStatus {
    Draft,
    Cancelled,
    Completed,
    Processing,
}

Şimdi işin en azından bana göre sanata dönüştüğü bir kısım geliyor. Bir statü ya sistemin kendi statüsüdür ya da içine veri gömülmüş bir özel statüdür. Bunu yaparken sınıf hiyerarşisine bağlı kalmadan hareket edebiliriz. Nasıl mı? İşte böyle;

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum OrderFormTenantStatus {
    System(OrderFormStatus),
    Custom {
        id: Uuid,
        tenant_id: Uuid,
        name: String,
        core_status: OrderFormStatus,
    },
}

impl OrderFormTenantStatus {
    pub fn core_status(&self) -> OrderFormStatus {
        match self {
            OrderFormTenantStatus::System(core) => *core,
            OrderFormTenantStatus::Custom { core_status, .. } => *core_status,
        }
    }

    pub fn tenant_id(&self) -> Option<Uuid> {
        match self {
            OrderFormTenantStatus::System(_) => None,
            OrderFormTenantStatus::Custom { tenant_id, .. } => Some(*tenant_id),
        }
    }

    pub fn name(&self) -> String {
        match self {
            OrderFormTenantStatus::System(core) => format!("{:?}", core),
            OrderFormTenantStatus::Custom { name, .. } => name.clone(),
        }
    }

    pub fn new(
        id: Uuid,
        tenant_id: Uuid,
        name: &str,
        core_status: OrderFormStatus,
    ) -> Result<Self, &'static str> {
        if name.trim().is_empty() {
            return Err("Statü adı boş olamaz.");
        }
        Ok(OrderFormTenantStatus::Custom {
            id,
            tenant_id,
            name: name.to_string(),
            core_status,
        })
    }
}

Gördüğünüz gibi OrderFormTenantStatus enum'ı iki varyant içerir. İlki System varyantıdır ki çekirdek statüleri taşıyabilir, ikincisi ise Custom varyantıdır ve müşteriye özel statüleri temsil eder. impl bloğunda birçok fonksiyon bulunmakta. new fonksiyonu yeni bir statü oluşturmak için kullanılır ve geçersiz bir isimle karşılaşırsa hata döner. Diğer fonksiyonlar ise statünün çekirdek statüsünü, tenant id'sini ve adını almak için kullanılır. Bu fonksiyonlarda pattern matching tekniğini kullandığımız için kod oldukça temiz ve anlaşılır kalır diyebilirim. Evet yer yer bizi düşündüren kısımlar da yok değil. Örneğin new fonksiyonuna eklediğimiz deneysel iş kuralı ihlal edilirse Result türü statik yaşam ömründe bir literal döner. Burada kolay kaçtığımı itiraf edebilirim. Belki de statü oluşturulurken iş kurallarını ihlal eden bir durum varsa bunu compile time'da yakalayabileceğimiz bir yapıya gitmek daha doğru olurdu. Ancak bu örnekteki gibi runtime'da kontrol etmek de mümkün olabilir. Neyse neyse... Dağılmayalım ve OrderForm struct'ını yazarak devam edelim.

pub struct OrderForm {
    pub id: Uuid,
    pub tenant_id: Uuid,
    status: OrderFormTenantStatus,
}

impl OrderForm {
    pub fn new(
        id: Uuid,
        tenant_id: Uuid,
        initial_status: OrderFormTenantStatus,
    ) -> Result<Self, &'static str> {
        if initial_status.core_status() != OrderFormStatus::Draft {
            return Err("Sipariş sadece Draft statüsü ile başlayabilir.");
        }

        Ok(Self {
            id,
            tenant_id,
            status: initial_status,
        })
    }

    pub fn status(&self) -> &OrderFormTenantStatus {
        &self.status
    }

    pub fn update_status(&mut self, new_status: OrderFormTenantStatus) -> Result<(), &'static str> {
        if let Some(status_tenant_id) = new_status.tenant_id() {
            if status_tenant_id != self.tenant_id {
                return Err("Farklı bir firmaya ait statü bu siparişe atanamaz.");
            }
        }

        let current_core = self.status.core_status();
        let new_core = new_status.core_status();

        if current_core == OrderFormStatus::Draft && new_core != OrderFormStatus::Processing {
            return Err("Draft statüsü sadece Processing'e geçebilir.");
        }

        if current_core == OrderFormStatus::Processing && new_core == OrderFormStatus::Draft {
            return Err("Processing statüsü tekrar Draft'a dönemez.");
        }

        self.status = new_status;
        Ok(())
    }
}

Rust tarafındaki OrderForm veri yapımızda C#'takine benzer şekilde çeşitli kuralları işletebilir ve statü güncellemelerini yönetir. new fonksiyonu sipariş formu oluştururken başlangıç statüsünün Draft olması gerektiğini kontrol eder. update_status fonksiyonu ise yeni statünün aynı tenant'a ait olup olmadığını ve geçiş kurallarını kontrol eder. Eğer herhangi bir kural ihlal edilirse hata dönülür. Aksi takdirde statü başarılı bir şekilde güncellenir. Şimdi bu yapıyı nasıl kullanacağımıza bakalım.

fn main() -> Result<(), &'static str> {
    let firm_tenant_id = Uuid::new_v4();

    let waiting_for_parts = OrderFormTenantStatus::new(
        Uuid::new_v4(),
        firm_tenant_id,
        "Waiting for Parts",
        OrderFormStatus::Processing,
    )?;
    let assembly_line = OrderFormTenantStatus::new(
        Uuid::new_v4(),
        firm_tenant_id,
        "Assembly Line",
        OrderFormStatus::Processing,
    )?;
    let in_tailor = OrderFormTenantStatus::new(
        Uuid::new_v4(),
        firm_tenant_id,
        "In Tailor",
        OrderFormStatus::Processing,
    )?;

    let mut order = OrderForm::new(
        Uuid::new_v4(),
        firm_tenant_id,
        OrderFormTenantStatus::System(OrderFormStatus::Draft),
    )?;

    println!("Initial Order Status: {}", order.status().name());

    order.update_status(waiting_for_parts)?;
    println!("Updated Order Status: {}", order.status().name());

    order.update_status(assembly_line)?;
    println!("Updated Order Status: {}", order.status().name());

    order.update_status(in_tailor)?;
    println!("Updated Order Status: {}", order.status().name());

    order.update_status(OrderFormTenantStatus::System(OrderFormStatus::Cancelled))?;
    println!("Updated Order Status: {}", order.status().name());

    Ok(())
}

Ve çalışma zamanı çıktısı;

Sonuç

Domain Driven Design ilkeleri ile zorlayıcı ancak bir programlama dilinin bazı yeteneklerini daha iyi benimsemek adına harika pratikler vaat ediyor. Rust bir kenara tam anlamıyla nesne yönelimli dil paradigmalarını düşündüğümüzde dümdüz veri yapıları tasarlamanın ötesine geçtiğimiz bir hatta ilerlemeye zorluyor. Bu çalışmada müşteri açısından kıymetli olan bir gereksinimin çekirdek kurguyu bozmadan uyarlanabilmesi adına bazı hamleler yapmaya çalıştık. En ideal yol mudur tartışılır ama ziyadesiyle önemli dil kabiliyetlerini kullandık diyebiliriz. Adettendir bitirirken C# ve Rust açısından da bir kıyas yapalım.

Bir statüyü nesne olarak oluştururken OrderFormStatus.Draft gibi kullanımlar söz konusu. Bu tahminimce bellekte bir yer tahsisine(allocation) neden olabilir. Rust tarafında OrderFormTenantStatus::System(OrderFormStatus::Draft) şeklinde bir kullanım var. Bu da enum'un kendi içinde veri taşıyabilmesi sayesinde mümkün. Buna göre gereksiz yer tahsisi yok desek doğru olur mu emin değilim :D Bunu ispatlamam en azından şimdilik zor.
Boş guid kullanımında C# tarafında Guid.Empty şeklinde bir yaklaşımımız oldu. Rust tarafında Option türüne sahip olduğumuz için None ile tenant bağımsız statüleri temsil edebilir durumdayız. Daha tip güvenli(type safe) bir yaklaşıma sahip olduğumuzu ifade edebiliriz. C# tarafında bunun için çaresiz miyiz, asla. Pekala kendi generic Option türümüzü de yazabiliriz ama dilin doğasında bunun olması farklı bir şey.
Option gibi yine Rust açısından güçlü olan bir başka enstrüman da generic Result türüdür. C# tarafında domain kural ihlallerini genellikle Exception fırlatarak cezalandırdık ama Rust tarafında Result türü kullandığımız için try/catch bloklarına ihtiyaç duymadan hataları yönetebiliriz. Yine pattern matching ile Result içeriğini yakalayarak hataları daha temiz bir şekilde ele alabiliriz. Pek tabii C# tarafında da belki result pattern ile aynı şeyi karşılamak mümkün olabilir.

Bu anlamsız karşılaştırma bir yana dursun asıl vurgulamam gereken şey şu; Kurumsal ölçekte bir yazılımda domain driven design pratiklerini ele alacaksak ürünü Rust ile yazmayız. Zira, bağımlılık yönetimi(dependency injection) gibi kritik konularda nesne yönelimli bir dilde kalmak kodu yazmak ve bakımı açısından daha kolay olabilir. Lakin bu sistemin ihtiyaç duyduğu yüksek performans isteyen ve görev kritik olan birçok senaryoda Rust ile ilerleyebiliriz. Bu tamamen kendimce yapmış olduğum bir yorum ;)

Bu çalışmada ele aldığımız örneklere github reposundan erişebilirsiniz. Böylece geldik bir çalışmamızın daha sonuna. Tekrardan görüşünceye dek hepinize mutlu günler dilerim.

Pi(π) Sayısını Hesaplama Yolunda

2026-03-26T19:21:00+00:00

Matematiksel yöntemlerden bazılarını ele alarak belli bir basamağa kadar pi(π) sayısını hesaplamaya çalışacağım. Doğru bir basamak değerine ulaşmak ve burada yüksek sürate çıkmak hedeflerim arasında. Önce en amele yöntemlerden başlayarak daha sonra daha karmaşık yöntemlere geçmek niyetindeyim ama yol beni farklı bir rotaya sürükledi diye de özet geçeyim :D Diğer modellere geçemeden kendimi diller arasında performans hesaplamaları, optimizasyonlar ve senkronizasyon sorunlarıyla uğraşırken buldum. O yüzden bu yazıda sadece Monte Carlo yöntemini ele alacağım.

Kapsam

- [x] Dart oynamayı severiz. Monte Carlo ile başlayalım.
- [x] Paralel hesaplama yöntemlerini kullanarak performansı artırmaya çalışalım.
- [x] Race Condition'ları ve diğer senkronizasyon sorunlarını ele alarak kodumuzu optimize edelim.
- [ ] Chudnovsky algoritması ve ardından Gauss-Legendre algoritmasını deneyelim.

Sistem

Çalışmadaki deneyleri aşağıdaki özelliklere sahip bir sistemde gerçekleştirdim.

Donanım	Detaylar
CPU	12th Gen Intel(R) Core(TM) i7-1255U, 1700 Mhz, 10 Core(s), 12 Logical Processor(s)
Bellek	32 Gb
OS	Windows 11 Pro

Önce Kısa bir Matematika ve Monte Carlo Seyahati

Pi(π), bir dairenin çevresinin çapına oranı olarak ifade edilebilir. Yaklaşık olarak ve genelde ezberlediğim değeri 3.14159 olarak bilinir ancak aslında sonsuz bir ondalık dizisine sahiptir ve tam değeri bilinmemektedir. Pi(π) sayısını kutlamak için özel bir gün bile vardır: 14 Mart, yani 3/14...

Bir çılgınlık yaparak kodlarımızı deterministik olmayan bir metodoloji ile yazabiliriz. Monte Carlo yöntemine göre pi sayısının hesaplanması için bir çembere ve rastgele iki double değere ihtiyacımız var. Rastgele değerlerin bir bileşimi çemberin içine düşerse, pi(π) sayısının yaklaşık değeri için bir tahmin yapılabilir. Tabii burada kullanmamız gereken bir formül ve iterasyon sayısı var. Öyleyse vakit kaybeden kodlamaya başlayalım.

Temiz, Sequential Versiyon

İşte en amatöründen bir C#** kod örneği.

using System.Diagnostics;

public class Program
{
    public static void Main()
    {
        long totalIterations = 100_000_000;
        Stopwatch stopwatch = Stopwatch.StartNew();
        for (int i = 0; i < 10; i++)
        {
            stopwatch.Restart();
            int inCircle = (int)PiEstimatorV1(totalIterations);
            Console.WriteLine($"Estimated value of π: {4.0 * inCircle / totalIterations} in {stopwatch.ElapsedMilliseconds} ms");
        }
    }

    public static long PiEstimatorV1(long iterations)
    {
        long inCircle = 0;
        var random = new Random();

        for (int i = 0; i < iterations; i++)
        {
            double x = random.NextDouble();
            double y = random.NextDouble();
            if (x * x + y * y <= 1.0)
            {
                inCircle++;
            }
        }
        return inCircle;
    }
}

Kendi sistemimde normal dotnet run koşusuyla elde ettiğim sonuçlar şöyle(Özellikle dotnet run komutuna dikkat çekmek isterim. İlerleyen bölümlerde release modun nasıl farklar yarattığını göreceğiz):

Yaklaşık 1000 milisaniye civarında bir sürede 3.14 etrafında dolandığımızı söyleyebilirim. Burada gayet senkron bir şekilde tek thread kullanarak hesaplama yapıyoruz. Devam etmeden önce rastgele değerlerin çember içerisinde kalıp kalmama formüllerini daha şık yazabilirmiyim diye düşündüm ve Math sınıfının Pow metodunu kullanarak kodu biraz daha okunabilir hale getirdim.

if (Math.Pow(x, 2) + Math.Pow(y, 2) <= 1.0)
{
    inCircle++;
}

Biraz göreceli de olsa Math sınıfının statik Pow metodunu kullanmak kodun okunabilirliğini artırıp amacını daha şık ifade etse de süreler neredeyse üç kata kadar arttı. Yol yakınken geri dönme vakti.

Iterasyon Sayısı Artıyor, Paralel Çalışma Geliyor

İlk metodolojimize göre 100 milyon iterasyon bu sistemde kabul edilebilir bir ortalama çalışma süresi yakaladı ancak daha yüksek ve tutarlı bir hesaplama için iterasyon sayısını artırmak yerinde olur. Bu yüzden 1 milyar iterasyonu deneyebiliriz. İşte sonuçlar.

"Gerçekten bu kadar süre bekledin mi?" diye sorabilirsiniz. Evet, bekledim :D İterasyon sayısının büyümesi hesaplama süresini çok daha dramatik olarak artırdı(ama hala dotnet'i debug modda işletiyoruz onu da belirtelim) Dolayısıyla bir şeyleri paralel hale getirmenin ve pek tabii bunu da güvenli(thread-safe) ve race condition sorunlarından kaçınarak yapmanın zamanı geldi. Aslında for döngüsünü paralel hale getirebiliriz ve tahminen oluşabilecek race condition sorununu da Interlocked sınıfını kullanarak çözebiliriz. İşte paralel hale getirilmiş ve güvenli bir şekilde sayaç artırdığını düşündüğüm kod parçası.

public static long PiEstimatorV2(long iterations)
{
    long inCircle = 0;
    var random = new Random();

    Parallel.For(0, iterations, i =>
    {
        double x = random.NextDouble();
        double y = random.NextDouble();

        if (x * x + y * y <= 1.0)
        {
            Interlocked.Increment(ref inCircle);
        }
    }
    );
    return inCircle;
}

Japon bir kılıç ustasının sakince kata yaparken ki ruh haline bürünüp sabırla beklesem de ilk iki çalışma süresini görünce programın çalışmasını sonlandırdım.

Bir şeylerin ters gittiği hatalı kodlama yaptığım gün gibi ortada. Hatta işin çok daha enterasan yani paralel for döngüsünü bir kenara bırakıp sadece Interlocked nesnesini kullanınca ortaya çıktı.

public static long PiEstimatorV3(long iterations)
{
    long inCircle = 0;
    var random = new Random();

    for (int i = 0; i < iterations; i++)
    {
        double x = random.NextDouble();
        double y = random.NextDouble();

        if (x * x + y * y <= 1.0)
        {
            Interlocked.Increment(ref inCircle);
        }
    }
    return inCircle;
}

Şaşılacak şey ama sadece Interlocked sınıfını kullanarak sayaç artırmaya çalışmak daha iyi sonuçlar verdi. Fakat bu sefer de paralel çalışmanın avantajını tam olarak kullanmadık/kullanamdık.

Thread-Local Random ve Daha İyi Paralel Çalışma

Sanki doğru yolda ilerliyor gibiyim ama tam olarak değil. Interlocked sınıfı thread'ler arası güvenli bir şekilde sayacı artırmamızı sağlasa da, paralel çalışacak her bir iterasyonda bu işlemi yapmak ciddi bir performans kaybına neden oluyor gibi. Çünkü her bir thread'in sayaç değerini güncellemesi gerektiğinde diğer thread'lerin de bu değere erişmeye çalışması bir tür beklemeye sebep oluyor. Dolayısıyla her bir thread'in kendi sayaç değerini tutması ve en sonunda bu değerleri birleştirmek daha doğru olacak. O zaman birde aşağıdaki kod parçasını deneyelim.

public static long PiEstimatorV4(long iterations)
{
    long inCircle = 0;
    using var tlRandom = new ThreadLocal<Random>(() => new Random());

    Parallel.For(
        0L,
        iterations,
        () => 0L,
        (_, _, localCount) =>
        {
            var rng = tlRandom.Value!;
            double x = rng.NextDouble();
            double y = rng.NextDouble();
            return x * x + y * y <= 1.0 ? localCount + 1 : localCount;
        },
        localCount => Interlocked.Add(ref inCircle, localCount)
    );

    return inCircle;
}

tlRandom isimli ThreadLocal sınıfını kullanarak her bir thread'in kendi rastgele sayı üreteci örneğine sahip olmasını sağlıyoruz. Bu sayede her bir thread'in kendi sayaç değerini tutması ve sonunda bu değerleri güvenli bir şekilde birleştirmesi mümkün hale geliyor. Paralel for döngüsü bu örnekte tam beş parametre almakta. Dile kolay tam beş, iki tane daha alsa Sonarqube'e takılır herhalde :D

İlk iki parametre iterasyon aralığını tanımlarken(0'dan maksimum iterasyon değerine kadar), üçüncü parametre her bir thread için hesaplama değerinin başlangıç değerini belirliyor. Dördüncü parametre her bir iterasyonda çalışacak olan metodu temsil ediyor ki burada Monte Carlo simülasyonu yapılmakta ve bu metod her bir thread'in kendi sayaç değerini güncelliyor. Son parametre ise tüm thread'lerin sayaç değerlerini güvenli(thread-safe) bir şekilde birleştirmek için kullanılan metodu işaret ediyor.

Peki ya çalışma zamanı çıktısı...

Gerçek Çekirdek Sayısına Göre Bölme

Not bad, not bad! Hesaplama süreleri daha makul bir noktaya geldi. Ancak daha şık bir tasarıma veya modele gidebilir miyiz diye de düşünüyorum. Paralel for döngüsünde kalıp makinedeki çekirdek sayısını da hesaba katarak ilerlemek mantıklı olabilir. Yani her çekirdeğin kendi sayaç değerini tutması ve sonunda bu değerlerin birleştirilmesi gibi bir yaklaşım daha verimli olabilir. Bu amaçla aşağıdaki kod parçasını ele alabiliriz.

public static long PiEstimatorV5(long iterations)
{
    int coreCount = Environment.ProcessorCount;
    long chunkSize = iterations / coreCount;
    long inCircle = 0;

    var tasks = Enumerable.Range(0, coreCount).Select(id => Task.Run(() =>
    {
        var rng = new Random();
        long localCount = 0;
        long start = id * chunkSize;
        long end = id == coreCount - 1 ? iterations : start + chunkSize;

        for (long i = start; i < end; i++)
        {
            double x = rng.NextDouble();
            double y = rng.NextDouble();
            if (x * x + y * y <= 1.0)
                localCount++;
        }

        Interlocked.Add(ref inCircle, localCount);
    })).ToArray();

    Task.WaitAll(tasks);
    return inCircle;
}

Bu sefer işlemcideki çekirdek sayısına göre iterasyonları bölüyor ve her çekirdek için ayrı bir görev nesnesi(Task) oluşturuyoruz. Her görev kendi rastgele sayı üretecine sahip ve kendi sayaç değerini tutuyor. Görevler tamamlandığında sayaç değerleri güvenli bir şekilde toplanıyor. Bu, bir önceki versiyona göre performansı biraz daha artırdı diyebilirim. İşte sonuçlar,

Tabii burada "attığımız taş ürküttüğümüz kurbaya değdi mi?" özlü sözünü hatırlamakta fayda var. En başta senkron olarak çalışan versiyonu bu son iterasyon sayısı ile tekrar denediğimde aşağıdaki sonuçlara ulaştım. Evet paralel çalışmada sonuçlar daha iyi ama bu sanki yüksek iterasyon sayıları için geçerli bir durum. Düşük aralıklarda bu maliyete girmeyebilirizde ve hatta daha kısa sürmesi gerekirken daha uzun çalışma süreleride ortaya çıkabilir.

Monte Carlo C# Turunun Değerlendirmesi

Buraya kadarki örnek kod versiyonlarını daha iyi karşılaştırmak için aşağıdaki tabloyu ele alabiliriz.

Kriter	V0	V1	V2	V3	V4	V5
Paralellik	Yok	Yok	Var	Yok	Var	Var
Thread-Safe Random	Var	Var	Yok ve race-condition riski var	Var	ThreadLocal ile Var	Var(kendi instance'ı üzerinden)
Math.Pow Lüksü	Yok	Çok yavaş	Çok yavaş	Yok	Yok	Yok
Iterasyon başına Interlocked	Yok	Yok	Var	Var	Yok	Yok
Çekirdek sayısına göre bölme	Yok	Yok	Yok	Yok	Yok	Var
Lock-free döngü	Var	Var	Yok	Yok	Var	Var

ve şu ana kadar ki Monte Carlo uyarlamaları için şunları da söyleyebiliriz:

V0: Basit, hızlı ama tek thread ile çalışıyor. Iterasyon sayısı arttıkça süreler dramatik şekilde artıyor.
V1: Math.Pow kullanımı performansı ciddi şekilde düşürüyor. Okunabilirlik artarken süreler kabul edilemez seviyelere çıkıyor.
V2: Paralel for döngüsü içeriyor ama iki kritik sorunu var. Random paylaşımlı olduğu için race condition riski var ve her iterasyonda Interlocked kullanımı ciddi performans kaybına neden oluyor.
V3: Interlocked.Increment ilginç bir şekilde sıralı bir döngüye ekleniyor gibi. Hesaplama V0 gibi hızlı olsa da paralel çalışmanın avantajını tam olarak kullanamıyor.
V4: ThreadLocal kullanarak her thread'in kendi Random örneğine sahip olması ve sayaç değerlerini güvenli bir şekilde birleştirmesi performansı önemli ölçüde artırıyor. Ancak paralel for döngüsünün getirdiği bir yük hala var gibi görünüyor.
V5: Çekirdek sayısına göre iterasyonları bölerek her çekirdeğin kendi görevini yapması ve sonunda güvenli bir şekilde birleştirmesi performansı daha da artırıyor.

Peki Ya Aynı Paralel Çalışmayı Rust Dili ile Yapsaydık?

Pek tabii bu tip yüksek performans gerektiren hesaplamalar söz konusu olunca aklıma ilk gelen Garbage Collector mekanizmasını aradan çıkarmak hatta managed environment kullanmayan bir dilde ilerlemek oluyor. Birkaç yıl olsa da ilgilenme fırsatı bulduğum rust ve çok kısa bir süre baktığım zig ile aynı senaryoyu deneyebiliriz. Önce rust tarafı ile başlayalım.

İşlemci çekirdeklerinden maksimum fayda sağlamak adına rayon küfesi biçilmiş kaftan. Tabii rastgele sayı üretimi için de rand küfesini(crate) kullanmayı tercih edeceğim. Bunları projeye cargo ile ekleyebiliriz.

cargo add rayon rand

main.rs dosyasına da aşağıdaki kod parçasını ekleyerek devam edelim.

use rand::rngs::SmallRng;
use rand::RngExt;
use rayon::prelude::*;

fn main() {
    let total_iterations = 1_000_000_000;

    for _ in 0..10 {
        let start_time = std::time::Instant::now();
        let pi_estimate = calculate_pi(total_iterations);
        let elapsed = start_time.elapsed();
        println!("Estimated Pi: {} in {:?}", pi_estimate, elapsed);
    }
}

fn calculate_pi(total_iterations: u64) -> f64 {
    let in_circle: u64 = (0..total_iterations)
        .into_par_iter()
        .map_init(
            || rand::make_rng::<SmallRng>(),
            |rng, _| {
                let (x, y): (f64, f64) = rng.random();

                if x * x + y * y <= 1.0 {
                    1_u64
                } else {
                    0_u64
                }
            },
        )
        .sum();

    4.0 * (in_circle as f64) / (total_iterations as f64)
}

calculate_pi metodunu 10 kez çalıştırıp süre ölçümlemesi yaptırmaktayız. into_par_iter() ile paralel bir iterasyon ve devamında kullanılan map_init ile her bir thread için ayrı bir rastgele sayı üreteci oluşturuluyor. map_init kod bloğunda f64 türünden rastgele x ve y değerleri üretiliyor ve çember içinde olup olmadıkları kontrol ediliyor. En sonunda da sum yardımıyla in_circle sayısı toplanarak pi değer tahmini yapılıyor ve bulunan sonuç döndürülüyor. Öncelikle bu kodu derleme modunda çalıştırarak süreleri gözlemleyelim.

C# programımıza göre çok daha kötü bir performans sergileniyor. Aslında bu sonucu normal karşılamak gerekir zira cargo run komutu varsayılan olarak debug modunda çalışır ve bu mod cidden yavaş çalışır. Yani release modda çalıştırıp bir kıyaslama yapmak daha doğru olur(Evet kabul ediyorum nitro modunu açtık ve bir hile yaptık)

cargo run --release

"Hımmm... Ama hile yapıyorsun hocam oldu mu şimdi?" :D .Net tarafında yazdığımız son paralel kodu da release modda çalıştırarak bir kıyaslama yapmak şimdi çok daha doğru olacak. Öyleyse...

dotnet run -c Release

dotnet run ile doğrudan çalıştırdığımıza göre daha iyi sonuçlar aldık ama rust tarafına nazaran o kadar da iyi sayılmaz. Fakat şartlar yine eşit değil! Burada Just-in Time derleyicisinin optimizasyonları ile bir performans artışı sağlandı. Lakin .Net 8 sonrası gelen Native AOT desteği ile rust tarafına daha yakın sonuçlar elde etmek mümkün olabilir. O zaman programımızı birde Native AOT ile çalıştıralım. Bu amaçla ben aşağıdaki komutu denedim. Hem işlemci mimarisi hem de işletim sistemine uygun bir release çıktısı hazırlanıyor. Sonrasında tabii bu exe'yi çalıştırmamız gerekiyor.

dotnet publish -c Release -r win-x64 --self-contained true /p:PublishAot=true
cd .\bin\release\net10.0\win-x64\publish\
.\CalculatePi.exe

İyileşme olmadığı gibi süreler bir noktadan sonra uzayıp aynı seyirde devam etti gibi. Belki ilk çalışmaya başladığında işlemci ısındı ve donanımın bir gerçeği olarak süreler uzayıp aynı seyirde kaldı. Bunu ölçümlemek için daha iyi bir monitoring sistemi kurgulamak gerekiyor ama bu beni şu an için aşacak gibi duruyor. Kod tarafında kesin atladığım bir şey var ve emin olmak adına C# uygulamasını belki de SIMD(Single Instruction, Multiple Data) desteği ekleyerek denemek daha doğru olur. SIMD konusunu da kısaca izah etmek isterim, en azından anladığım kadarıyla.

Monte Carlo yönteminde çembere isabet etme durumunu tespit edereken bir formül kullanıyoruz. x*x + y*y <= 1.0 şeklinde. İşlemcinin her bir sayı çifti için tek tek bu işlemi yaptığını düşünelim. Ancak SIMD desteği ile işlemcinin bazı register'larını kullanıp aynı anda 4 double veya 8 float işlemin tek bir saat vuruşunda(clock cycle) yapılması sağlanabilir. Yani tek bir işlemle 4 veya 8 sayı çifti için `x*x + y*y <= 1.0` kontrolü yapılabilir. İşin matematiği beni şu an için aşıyor ancak .Net'in System.Runtime.Intrinsics kütüphanesinde yer alan Vector256, Vector<T> gibi türler ile bu tür bir optimizasyonu deneyebiliriz. Tür adlarından da anlaşılacağı üzere burada hesaplamaların vektör karşılıklarının bulunduğu bir senaryo var. Ancak işimizi zorlaştıracak bir kısım var ki o da rastgele sayı üretimi. NextDouble metodunun tekil(kaynaklarda scalar olarak ifade ediliyor) çalıştığı ve SIMD ile doğrudan vektör halinde çalışacak bir karşılığının olmadığı iddia ediliyor. Bu, rastgele sayıları bu şekilde kullanırsak donanımsal avantajlardan yararlanamayacağımız anlamına gelmekte. Genellikle XorShift, PCG(Permuted Congruential Generator) gibi algoritmaların kullanılması ya da rastgele sayıları önce devasa bir diziye doldurup SIMD ile bu diziden vektörler halinde çekilmesi gibi yöntemler öneriliyor. Bunun kodunu yazmak için biraz daha araştırma yapmam şart ki repoda denemesini yapacağım.

Tekrardan rust tarafına dönelim ve uygulama kodumuzu aşağıdaki gibi değiştirelim.

use rand::rngs::SmallRng;
use rand::RngExt;
use rayon::prelude::*;

fn main() {
    let total_iterations = 1_000_000_000;

    for _ in 0..10 {
        let start_time = std::time::Instant::now();
        let pi_estimate = calculate_pi(total_iterations);
        let elapsed = start_time.elapsed();
        println!("Estimated Pi: {} in {:?}", pi_estimate, elapsed);
    }
}

fn calculate_pi(total_iterations: u64) -> f64 {
    let chunk_size = 4; // SIMD için 4'lü gruplar halinde işlem yapacağız
                        // çünkü AVX2 256-bit genişliğinde ve 4 adet f64 (64-bit) değeri aynı anda işleyebilir.
    let loop_count = total_iterations / chunk_size;

    let in_circle: u64 = (0..loop_count)
        .into_par_iter()
        .map_init(
            || rand::make_rng::<SmallRng>(),
            |rng, _| {
                let x_values: [f64; 4] = rng.random(); // random'un güzel yanlarından birisi. Tek çağrıda arka arkaya 4 sayı üretip diziye atar.
                let y_values: [f64; 4] = rng.random();

                get_circle_value(&x_values, &y_values)
            },
        )
        .sum();

    4.0 * (in_circle as f64) / (total_iterations as f64)
}

// x_values ve y_values elemanları 4 boyutlu dizi olduğunda derleyici bunların kesinlikle sabit boyutlu olduğunu bilecek.
// Buna göre kod doğrudan AVX2 SIMD komutuna çevrilebilir.
#[inline(always)]
// Bunu eklediğimiz için derleyici bu fonksiyonu çağırmak yerine doğrudan kodun içerisine gömer.
pub fn get_circle_value(x_values: &[f64; 4], y_values: &[f64; 4]) -> u64 {
    let mut count = 0;

    for i in 0..4 {
        if x_values[i] * x_values[i] + y_values[i] * y_values[i] <= 1.0 {
            count += 1;
        }
    }

    count
}

Haydaaa! :D SIMD dedik daha hızlı çalışır dedik ancak bir önceki rust kodumuza göre neredeyse 3.5 kat daha yavaş çalışma zamanı süreleri gördük, oldu mu şimdi! Aslında elde ettiğimiz süreler iki uygulama biçimi içinde oldukça iyi. Milisaniyeler mertebesinde 1 milyarlık iterasyonları tamamladık. Hatta ilk rust kodumuz gayet sade ve anlaşılır. Yine de SIMD metodolojimiz beklediğimiz şekilde çalışmadı. Buradaki kritik nokta maliyetin nerede olduğunu tespit edebilmek. Büyük ihtmalle rastgele sayı üretimi işi beklenenden uzun sürüyor ve doğru şekilde bir vektörleme gerçekleşmiyor. SIMD için "veriler zaten devasa bir dizide ve bellekte hazır bekliyorsa" gibi bir durum olduğu ifade ediliyor(Yani böyle bir hazırlık sonrası daha çok işe yarar deniyor) Lakin bizim örneğimizde veriyi her adımda sıfırdan üretiyoruz ve üretim maliyeti hesaplama maliyetinin üzerine çıkıyor. Dikkat edelim rastgele sayı üretiminden 4 elemanlık bir dizi çıkartmayı kolaylaştırdık kolaylaştırmasına ama 4erli gruplama için altına girdiğimiz bu maliyet hesaplama süresini ciddi şekilde artırdı. Ciddi şekilde dediğime bakmayın, .Net kodumuza nazaran burada milisaniyeler mertebesinde konuşabiliyoruz(Tabii C# program kodumuzu da SIMD ile çalışır hale getirip bir değerlendirme yapmamız lazım)

O Zaman Kontrolü Biraz Daha Elimize Alalım. Zig ile Deneyelim

Zig programlama dili, gizli ya da bilinçsiz kontrol akışlarına müsama göstermiyor. Yani bildiğim kadarı ile hazır bir Paralle.For elimizde yok, threar'leri ve bellek tahsislerini doğrudan bizim yapmamız lazım ki bellek tahsisi(allocation) konusunda da çok hassas bir dil. Buna göre her thread'in kendi yerel sayacını artıracağı, işi bitince bu değerleri ana sayaca ekleyeceği bir akış kurgulamak gerekiyor. Aşağıdaki kod parçası ile başlayalım öyleyse. Eğer çok iyi süreler elde edersek belki de daha da iyileştirmeye çalışmayız :P

const std = @import("std");

// Monte Carlo yöntemiyle Pi değeri hesaplanan fonksiyon
// ilk parametre iterasyon sayısını alır ki bizim örneğimizde 1 milyar / işlemci-çekirdek sayısı kadardır.
// İkinci parametre pointer olarak gelir ve in_circle değişkenine atomik olarak ekleme yapar.
// Atomik seviyede ekleme yapmak hızlıdır çünkü doğrudan işlemci instruction'larıyla yapılır ve kilitlenmeye gerek kalmaz.
fn monteCarloCalculation(iterations: usize, result: *usize) void {
    var seed: u64 = undefined;
    std.crypto.random.bytes(std.mem.asBytes(&seed)); // Rastgele bir seed oluşturuyoruz, böylece her çalıştırmada farklı sonuçlar elde edebiliriz.

    // Xoshiro256 türünden bir PRNG-Pseudo Random Number Generator- başlatıyoruz
    // Bu epey hızlı çalışır
    var rng = std.Random.DefaultPrng.init(seed);
    const random = rng.random();

    var localCount: usize = 0;
    var i: usize = 0;

    // normal iterasyon döngümüz
    while (i < iterations) : (i += 1) {
        // f64 yerine f32 kullanarak işlemci üzerindeki yükü yarı yarıya düşürebiliriz.
        const x = random.float(f32);
        const y = random.float(f32);
        // çember içinde olup olmadığını kontrol ediyoruz
        if (x * x + y * y <= 1.0) {
            localCount += 1;
        }
    }

    // İşlem bitince tek bir atomik yazma işlemi
    // İlk parametre veri türü, ikinci parametre hedef değişken,
    // üçüncü parametre çağırılacak instruction komutu,
    // dördüncü parametre eklenecek değer
    // ve en nihayetinde beşinci parametre bellek sıralama türü
    _ = @atomicRmw(usize, result, .Add, localCount, .monotonic);
}

pub fn main() !void {
    const totalIterations: usize = 1_000_000_000;
    const threadCount = try std.Thread.getCpuCount(); // işlemci çekirdek sayısını alıyoruz

    const iterPerThread = totalIterations / threadCount; // thread başına iterasyon değeri

    // Allocator'sız olmaz :D GPA nispeten daha iyi performans gösterir
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit(); // tedbir amaçlı deinit çağırıyoruz, böylece program sonunda kaynaklar düzgün şekilde serbest bırakılır
    const allocator = gpa.allocator();

    // thread'ler için bellek ayırıyoruz, her thread monteCarloCalculation fonksiyonunu çalıştıracak
    const threads = try allocator.alloc(std.Thread, threadCount);
    defer allocator.free(threads); // Yine tedbir amaçlı thread'ler için ayrılan belleği serbest bırakıyoruz

    // Standart deney döngümüz. 10 kez çalıştırılacak
    for (0..10) |_| {
        var in_circle: usize = 0;

        const start = std.time.nanoTimestamp();

        // Her test adımında thread'ler oluşturup, monteCarloCalculation fonksiyonunu çalıştırıyoruz
        for (threads) |*thread| {
            thread.* = try std.Thread.spawn(
                .{},
                monteCarloCalculation,
                .{ iterPerThread, &in_circle },
            );
        }

        // Burada thread'lerin bitmesini bekliyoruz,
        // her thread'in join edilmesi gerekiyor ki sonuçlar doğru şekilde toplanabilsin
        // Burası aynı zamanda en son çalışma zamanının neden yüksek çıktığının bir sebebi olabilir
        for (threads) |thread| {
            thread.join();
        }

        const elapsed_ns = std.time.nanoTimestamp() - start;
        const elapsed_ms = @divTrunc(elapsed_ns, std.time.ns_per_ms);

        const pi = 4.0 * @as(f64, @floatFromInt(in_circle)) / @as(f64, @floatFromInt(totalIterations));
        std.debug.print("Pi = {d:.6}  ({d} ms)\n", .{ pi, elapsed_ms });
    }
}

Uygulamayı aşağıdaki gibi cpu'nun tüm yeteneklerini de işin içerisine dahil ederek release modda çalıştırabiliriz.

zig run .\program.zig -O ReleaseFast -mcpu=native

Rust'ın ilk versiyonundaki release moddaki sürelere ulaşamadık belki ama yine de hızlı çalıştı diyebiliriz. Dikkat çekici noktalardan birisi ilk başlangıçtaki sürenin sonradan yükselmesi, belli bir ortalamada devam etmesi ve en sonda neredeyse iki katı kadar yavaş tamamlanması. Son süre ölçümünün bu kadar yüksek çıkmasının bir sebebi kuvvetle muhtemele paralel çalışan thread'lerin tamamının bitmesini bekleyen join çağrıları olsa gerek.

Diğer yandan for döngümüz her adımda işletim sisteminden yeni thread'ler talep edip sonrasında bunları yok etmekte. İşletim sistemi bu talep et-yürüt-yok et sürecinde yorulabilir ve bellek üzerinde parçalanmalar(fragmentation) oluşabilir. Bu parçalanmalar yeni thread'ler için alan tahsislerini geciktirebilir. Aslında burada bir thread-pool yapısı kurgulamadığımız için de böyle bir durum oluşuyor diye düşünüyorum.

Zig kodu çok daha iyi yazılabilir belki de ancak kaynaklardan öğrenebildiğim şimdilik bu kadar.

Sonuç Değerlendirmesi

Aslında bu çalışmada amacım Pi(π) sayısını hesaplarken monte carlo yöntemi ile ilerlemek ve sonrasında daha tutarlı sonuçlara ulaşmak için farklı matematik yöntemlere geçmekti. Bunu yaparken en çok aşina olduğum programlama dili C# ile işe başlamak istedim. Küçük iterasyonlarda hızlı sonuçlar aldım ama yüksek iterasyonlara gelince hesaplama süreleri ciddi anlamda uzamaya başladı. Dolayısıyla yöntem değişikliklerine gitmem yeni şeyler keşfetmem gerekti.

Özellikle çok yüksek iterasyonlarda paralel çalışmanın fark yarattığını gözlemedim. Derken rust ve zig dillerini işin içerisine katmak istedim. Release modda rust'ın epey iyi sonuçlar aldığını belirtmem lazım ki fark bu kadar açılınca release derlemeleri ve hatta AOT(Ahead-Of-Time) eklemeleri ile .net kodumuzu daha da hızlandırmaya çalıştım. Burada tek açık kapı .Net kodunu SIMD(Single Instruction, Multiple Data) desteği ile işletip süre hesaplaması yapmamış olmam.

Monte carlo doğru pi rakamlarına ulaşmak için iyi bir tercih değil. Bunu değiştirip farklı bir matematik model ile ilerlemek lazım ama tüm kodlarımız için şu anda aynı yöntem söz konusu. Dolayısıyla çalışma sürelerini kıyaslamak ve bir özet tablo hazırlamak iyi olabilir.

Ortalık tabii çok karıştı. Hatta çalışma sırasında C# metodunun eski versiyonunu tekrar çalıştırdığımı fark ettim. Dolayısıyla üç dilinde en son karar kıldığım kod versiyonlarını aynı iterasyonlar sayıları ile ve release modda derleyerek çalıştırmaya karar verdim. Süreler milisaniye cinsindendir ve toplamda 10 çalıştırma üzerinden ortalama süreler hesaplanmıştır.

Dil	Yöntem	Komut	İlk Süre	Son Süre	En Çabuk Süre	En Yavaş Süre	Ortalama Süre
C#	Paralel for, Task, Çekirdek Sayısı kadar	dotnet run -c Release	1029 ms	2252 ms	1029 ms	3103 ms	2119.1 ms
Rust	Rayon	cargo run --release	255.427 ms	254.023 ms	247.887 ms	257.314 ms	251.564 ms
Zig	std.Thread	zig run .\program.zig -O ReleaseFast -mcpu=native	474 ms	1097 ms	474 ms	1121 ms	637 ms

Böylece geldik bir anlamsız maceranın daha sonunda :D Ben bir yol gösterdim ancak siz daha iyisini yapabilirsiniz. Örneğin C# kodu için SIMD deneyip sonuçları kıyaslayabilirsiniz. Farklı donanımlarda, benchmark kütüphaneleri ile bu testleri yapabilir, standart sapmaları ve anlık koşulları işin içerisine katıp hangi senaryoda hangisi ile ilerlemek daha doğru olur araştırabilirsiniz. Şimdilik benden bu kadar. Tekrardan görüşünceye dek hepinize mutlu günler dilerim.

C# Kod Örneği, Rust Kod Örneği, Zig Kod Örneği

Hexagonal Architecture 101

2026-03-13T19:31:00+00:00

Kurumsal uygulamaları göz önüne aldığımızda zaman içerisinde birçok yazılım mimarisinin ortaya çıktığını görüyoruz. Programlama dillerinin gelişimi, framework'lerin ortaya çıkması ve değişen müşteri ihtiyaçları sonucunda bu kavram çok daha büyük önem kazandı. Belki de her şey üç katmanlı(3-tier) yaklaşımla başlamıştı. Geldiğimiz zaman diliminde ise monolit sistemlerin modüler hale getirildiğiği Modulith'lerden mikro servislere, soğan halkaları benzetmesi ile popülerleşen Onion mimariden servis odaklı(Service-Oriented) yaklaşıma kadar birçok stil var. Bazı kaynaklarda yazılım mimarileri katmanlı(Layered) ve dağıtık sistemler(Distributed) olmak üzere iki ana kategoriye ayrılmakta. Üzerinde uzun uzun konuşulacak olan bu kavramları elbette deneyimleyerek görmek en güzeli. Bende bir süredir bakmak istediğim Hexagonal mimari yaklaşımını öğrenmeye karar verdim ve işte karşınızdayım. Gelin .net platformunda bu mimariyi çok temel seviyede de olsa uygulamalı olarak anlamaya çalışalım.

Yazıdaki uygulama kodlarına github reposu üzerinden de erişebilirsiniz.

Bu mimari bazı kaynaklarda "Ports and Adapters" olarak da geçiyor. Orijini Alistair Cockburn'ın şuradaki yazısına dayanıyor. Kaynaklara göre 2005 yılından beri hayatımızda olan bir tasarım. Tabii işin özünde çok temel yazılım kavramları ve ilkeleri var. Her şey uygulama domain'i içerisindeki iş kurallarının dış dünyadan tamamen izole edilmesi fikrine dayanıyor. Bu zaten bir çok modern mimari yaklaşımın ana noktalarından birisi ancak uygulama biçimleri farklılık gösterebiliyor.

Sonuçta gevşek bağlılık(Loose Coupling), sorumlulukların doğru ayrılması(Separation of Concerns), bağımlılıkların tersine çevrilmesi(Inversion of Control), bağımlılıkların dışarıdan sağlanması(Dependency Injection), zengin nesneler(Rich Entity - yazılım prensibi diyemesek de DDD'nin izlerinden birisi olarak mimaride yer bulabilir) kullanılması gibi temel kavramlar üzerine kurulu bir mimari yaklaşım. Bu prensipler sayesinde uygulama domain'i içerisindeki iş kuralları(Business Specific Domain Rules), dış dünyadan gelen veri kaynaklarından, kullanıcı arayüzünden, diğer sistemlerle entegrasyonlardan tamamen izole edilebilmekte. Böylece uygulama domain'i içerisindeki kodun test edilebilirliği, sürdürülebilirliği ve esnekliği daha da artmakta.

Bu mimari internette genellikle aşağıdakine benzer bir görsel ile 50bin feet yükseklikten anlatılmaya çalışılır. (Çizim Excalidraw.io üzerinde tamamen insan eliyle oluşturulmuştur :P)

Grafiği şöyle özetlemeye çalışalım. İş kuralları ve domain yapısı tamamen Application katmanında yer alır. Bunu adaptörlerin oluşturduğu bir başka katman sarar. Adaptörler, uygulama domain'ini dış dünyaya bağlayan bir köprü görevi görürler. Dış dünya ise kullanıcı arayüzü, veri tabanı ve diğer sistemlerle entegrasyonlar gibi unsurları içerir. Adaptörler portlara bağlanarak uygulama domain'ine erişim sağlarlar. Portlar ise uygulama domain'inin dış dünyaya açılan kapılarıdır. Bu sayede uygulama domain'i tamamen izole edilmiş olur ve dış dünyadan gelen değişikliklerden etkilenmez. Böyle anlatınca ne güzel değil mi? Soyut soyut :D Pek tabii uygulamayı yazıp, avantaj ve dezavantajlarını görmeden mimariyi anlamamız pek mümkün değil.

Mimarinin ana sloganı şudur: Seperating Business Logic from Infrastructure with Ports and Adapters. Yani iş kurallarını altyapıdan portlar ve adaptörler ile ayırmak.

Burada kafa karıştıcı bazı meseleler olabiliyor. Örneğin adaptörlerin Inbound ve Outbound olarak ikiye ayrılması, portların ne olduğu, adaptörlerin portlara nasıl bağlandığı vb. Ben bu konuları mümkün olduğunca basit senaryolar üzerinden uygulamalı olarak incelemek istiyorum. Bu çalışmadaki temel amacım bu...

Senaryo

Kısır bir senaryo ile başlayalım. Stok takibi yapmak istediğimiz ürünler var. Buradaki basit iş kurallarını hexagonal mimarisine göre ele almaya çalışacağız. Uygulama kodlarını .Net platformunda C# ile yazacağım. Elbette bu mimariyi uygulamaya uygun farklı bir platform veya programlama dili de seçilebilir. Sonuçta mimarinin prensipleri değişmeyecektir.

Geliştirme Aşamaları

1. Solution ve Proje Yapısının inşa Edilmesi

Solution yapısını başlangıçta aşağıdaki gibi oluşturabiliriz.

HexagonalAdventure.Domain bir class library ve domain nesneleri ile iş kurallarını içeriyor.
HexagonalAdventure.Application yine bir class library ve In/Out port nesnelerini içeriyor. Inbound Port'lar dış dünyanın çekirdeğe ulaşmak için kullanacağı sözleşmeler olarak düşünülebilir. Outbound Port nesneleri ise çekirdeğin dış dünyadan yaptırmak istediği işler için kullanılan sözleşmedir.
HexagonalAdventure.Adapters ise şu anda iki proje içeriyor. Bunlardan birisi Class Library ve Outbound Adapter olarak düşünülebilir. Örneğin Entity Framework tabanlı bir Repository uyarlaması burada yer alır. Outbound Port'ta tanımlanan sözleşmenin somut olarak uygulandığı yerdir. Diğer proje ise bir Web Api'dir ve Inbound Adapter olarak düşünülebilir. Dış dünyandan gelen isteği alır ve Inbound Port üstünden sistemi tetikler. Hatta web api projesindeki program sınıfı Composition Root görevini üstlenir. Yani uygulama başlarken port ve adaptörlerin eşleştirilip birbirine bağlandığı yerdir. Bu sayede uygulama domain'i içerisindeki kodun dış dünyaya olan bağımlılığı tamamen ortadan kalkar.

2. Domain Modelinin Oluşturulması

Şimdi domain katmanına gelip rich entity modunda bir Product sınıfı oluşturalım. Bu sınıf ürünün temel özelliklerini ve iş kurallarını içerecek şekilde aşağıdaki gibi tasarlanabilir.

namespace HexagonalAdventure.Domain;

public class Product
{
    public Guid Id { get; private set; }
    public string Title { get; private set; }
    public decimal ListPrice { get; private set; }
    public string Category { get; private set; } // Category ayrı bir entity olabilir, şimdilik string olarak bıraktım
    public int StockQuantity { get; private set; } // Sonrasında Value Object olarak refactor edilebilir

    public Product(Guid id, string title, decimal listPrice, string category, int initialStock)
    {
        Id = id;
        Title = string.IsNullOrWhiteSpace(title) ? throw new ArgumentException("Title cannot be empty") : title;
        ListPrice = listPrice > 0.0M ? listPrice : throw new ArgumentException("List price must be greater than 0.0");
        Category = string.IsNullOrWhiteSpace(category) ? throw new ArgumentException("Category cannot be empty") : category;
        StockQuantity = initialStock >= 0 ? initialStock : throw new ArgumentException("Initial stock cannot be negative");
    }

    public void IncreaseStock(int quantity)
    {
        if (quantity <= 0) throw new ArgumentException("Quantity to increase must be greater than 0");

        StockQuantity += quantity;
    }

    public void DecreaseStock(int quantity)
    {
        if (quantity <= 0) throw new ArgumentException("Quantity to decrease must be greater than 0");
        if (StockQuantity - quantity < 0) throw new InvalidOperationException("Insufficient stock to decrease by the specified quantity");

        StockQuantity -= quantity;
    }
}

Şimdilik birçok detayı atladık. Sadece ürün stok bilgisinin temel iş kurallarını ele alacağımız bir senaryo ile ilerleyeceğiz.

3. Portların Tanımlanması

Çok doğal olarak ve büyük bir ihtimalle ürünler veritabanında tutulacaktır. Core'da yer alan domain katmanının veritabanı teknolojilerinden bihaber olması gerekir. İletişimi sadece bir sözleşme üzerinden yapmalıdır, yani bir Interface(veya mimarideki adıyla port) Bu amaca hizmet eden enstrüman Outbound Port olarak isimlendiriliyor. Solution yapımızı düşünecek olursak bizim için gerekli sözleşme tipini HexagonalAdventure.Application projesinde Ports/Outbond klasöründe aşağıdaki gibi tanımlayabiliriz.

using HexagonalAdventure.Domain;

namespace HexagonalAdventure.Application.Ports.Outbound;

public interface IProductRepository
{
    void AddProduct(Product product);
    Product GetById(Guid id);
}

Senaryomuz gereği sadece iki fonksiyonellik tanımladık. Birisi ürün eklemek, diğeri ise ürünü Id bilgisine göre çekmek için. Burada bir interface tanımı söz konusu ve dikkat edileceği üzere ne tür bir kütüphane ile, hangi veritabanına nasıl erişileceğine dair hiçbir detay da yer almıyor. Domain katmanı bu sözleşmeyi aslında aşağıdaki gibi kullanıyor;

Lütfen bana şu Id'ye sahip ürünü getir.
Lütfen bilgilerini verdiğim ürünü ekle.

4. Uygulama Servisi ve Use Case'in Tanımlanması

Merkez domain nesnesinde temel iş kurallarımız ve dışarıya açılan bir sözleşmemiz hazır. Şimdi bu iki enstrümanı kullanarak asıl iş akışını yönetecek olan uygulama servisini(Application Service) yazmamız gerekiyor. Bu servis sınıfı dışarıdan gelen isteği alacak ve ilgili domain nesnesini oluşturup güncelleyecek. Burada bir port'da kullanması gerekecek. Tipik olarak bir orkestrasyon yapacak diyebiliriz. Bu servis sınıfını HexagonalAdventure.Application projesindeki Services klasöründe aşağıdaki gibi yazabiliriz.

using HexagonalAdventure.Application.Ports.Outbound;
using HexagonalAdventure.Domain;

namespace HexagonalAdventure.Application.Services;

public class ProductService(IProductRepository productRepository)
{
    private readonly IProductRepository _productRepository = productRepository;

    public Guid CreateProduct(string title, decimal price, string category, int stock)
    {
        // Domain nesnesi oluşturulur ve orada tanımlı iş kuralları da yürütülür.
        var product = new Product(Guid.NewGuid(), title, price, category, stock);
        // Outbound port olarak tanımladığımız arayüz üzerinden ürün ekleme işlevi çağırılır
        _productRepository.AddProduct(product);
        return product.Id;
    }
}

Böylece uygulamanın dışarıya veri gönderen kısmını da yazmış olduk. Şimdilik stok artırma ve azaltma işlemlerini eklemedik. Önce genel hatları ile inşa etmeye çalışalım. Daha yapılacak çok iş var.

5. Inbound Adaptörün Yazılması ve Entegrasyonu

Az önce bir uygulama servisi yazdık. Dış sistemler tarafından nasıl kullanılacağına bir bakalım. Bunun için Web Api projesini kobay olarak ele alacağız. Dikkat etmemiz gereken şey API projesindeki Controller nesnesinin(ki adaptör görevini üstlenecek) ProductService'e doğrudan bağımlı olMAmasını sağlamak. Veritabanı tarafında nasıl bir outbound port tanımladıysak burada da dış dünyanın çekirdek ile konuşması için bu sefer ters yönlü bir inbound port enstrümanı hazırlayacağız. Tabii eksik olan birkaç şey daha var. Örneğin somut repository sınıfını yazmalıyız ve pek tabii program sınıfında gerekli dependency injection tanımlamalarını da yapmalıyız. Ancak öncelikle inbound port tanımını yaparak işe başlayalım.

Bu yüzden öncelikle HexagonalAdventure.Application projesindeki Ports/Inbound klasörüne aşağıdaki kod içeriğine sahip sözleşme tipini eklememiz gerekiyor.

namespace HexagonalAdventure.Application.Ports.Inbound;

public interface IProductService
{
    Guid CreateProduct(string title, decimal price, string category, int stock);
}

Controller'ın, ProductService'e doğrudan bağımlı olMamasını bu sözleşmeyi ProductService sınıfına implemente ederek sağlayabiliriz. Dolayısıyla bir önceki adımda tanımladığımız ProductService sınıfını aşağıdaki gibi güncelleyerek ilereyelim.

public class ProductService(IProductRepository productRepository)
    : IProductService
{
    // DİĞER KODLAR
}

Şimdi de asıl adaptör görevini üstlenen controller sınıfını ekleyelim. Bu sınıfı da aşağıdaki gibi geliştirebiliriz.

using HexagonalAdventure.Application.Ports.Inbound;
using Microsoft.AspNetCore.Mvc;

namespace HexagonalAdventure.Adapters.In.WebApi.Controllers;

[ApiController]
[Route("api/[controller]")]
public class ProductsController(IProductService productService)
    : Controller
{
    private readonly IProductService _productService = productService;

    [HttpPost]
    public IActionResult Create([FromBody] CreateProductRequest request)
    {
        var productId = _productService.CreateProduct(request.Title, request.Price, request.Category, request.Stock);
        return Ok(new { Id = productId });
    }
}

public record CreateProductRequest(string Title, decimal Price, string Category, int Stock);

Burada dikkat etmemiz gereken nokta adaptör görevini üstlenen controller sınıfının ProductService'i bir arayüz üzerinden kullanmasıdır. Böylece controller sınıfı ProductService'in somut implementasyonundan bağımsız hale gelmiş olur. Tabii bir şeye daha ihtiyacımız olacak. O da somut repository sınıfı. İlk senaryoda verileri bellekte bir dictionary koleksiyonu olarak tutabiliriz. Bu amaçla HexagonalAdventure.Adapters.Out.InMemory isimli sınıf kütüphanesini kullanabiliriz. Burada outbound adapter görevini üstlenecek olan InMemoryProductRepository isimli bir sınıf pekala işimiz görür.

using HexagonalAdventure.Application.Ports.Outbound;
using HexagonalAdventure.Domain;

namespace HexagonalAdventure.Adapters.Out.InMemory;

public class InMemoryProdutRepository
    : IProductRepository
{
    private readonly Dictionary<Guid, Product> _products = [];
    public void AddProduct(Product product)
    {
        _products.Add(product.Id, product);
    }

    public Product GetById(Guid id)
    {
        _products.TryGetValue(id, out var product);
        return product;
    }
}

Artık Web Api tarafındaki son aşamayı tamamlayabiliriz. Program.cs sınıfını aşağıdaki gibi kodlayarak ilerleyelim.

using HexagonalAdventure.Adapters.Out.InMemory;
using HexagonalAdventure.Application.Ports.Inbound;
using HexagonalAdventure.Application.Ports.Outbound;
using HexagonalAdventure.Application.Services;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

// Dependency Injection tanımlamaları
builder.Services.AddSingleton<IProductRepository, InMemoryProdutRepository>(); // Tüm uygulama boyunca tek bir instance kullanılır
builder.Services.AddScoped<IProductService, ProductService>();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

await app.RunAsync();

Şu haliyle Web api projesini ayağa kaldırıp aşağıdaki örnek http talebi ile deneyebiliriz.

@HexagonalAdventure.Adapters.In.WebApi_HostAddress = http://localhost:5144

POST {{HexagonalAdventure.Adapters.In.WebApi_HostAddress}}/api/products
Content-Type: application/json
Accept: application/json

{  
  "title": "Learning OCAML",
  "category": "Book",
  "price": 19.99,
  "stock": 10
}

En azından aşağıdaki ekran görüntüsünde olduğu gibi bir yanıt almamız gerekiyor.

Yeni Deneyimler

Kaba taslak mimariyi uyguladık gibi görünüyor. Şimdi farklı senaryolar ile devam edelim.

Örneğin veritabanı tarafında Postgresql kullanan bir Outbound Adapter eklemeye çalışalım. Entity Framework olur ya da Dapper olur. (Yeni adaptör ekleme senaryosu)
Farklı bir dış sistemi dahil edelim. Söz gelimi bir Console uygulaması. (Console uygulaması Web Api'yi kullanmayacak elbette)
Biraz da test ekleyelim ve test edilebilirliği görmeye çalışalım. (Test ekleme senaryosu)

6. Entity Framework Tabanlı Yeni Adapter Eklenmesi

Adettendir her repomda olduğu gibi veritabanı söz konusu ise genellikle bir docker-compose dosyasında postgresql ve pg-admin servislerini konuşlandırarak işe başlarım. Kendi sistemimdeki docker-compose içeriği aşağıdaki gibi.

services:

  postgres:
    image: postgres:latest
    container_name: hex-postgres
    environment:
      POSTGRES_USER: johndoe
      POSTGRES_PASSWORD: somew0rds
      POSTGRES_DB: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgres/data
    networks:
      - hex-network

  pgadmin:
    image: dpage/pgadmin4:latest
    container_name: hex-pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: scoth@tiger.com
      PGADMIN_DEFAULT_PASSWORD: 123456
    ports:
      - "5050:80"
    depends_on:
      - postgres
    networks:
      - hex-network

volumes:
  postgres_data:

networks:
  hex-network:
    driver: bridge

Container'ları ayağa kaldırmak için;

docker-compose up -d

Şimdi de HexagonalAdventure.Adapters.Out.EF isimli yeni bir class library oluşturarak devam edebiliriz. Bu projeyi de Adapters isimli solution folder altında oluşturursak, iskelete baktığımızda görsel olarak daha anlaşılır olacaktır. Entity Framework kullanacağımız için bir DbContext türevine de ihtiyacımız olacak. Tabii gerekli nuget paketlerini de eklemeyi unutmayalım. Microsoft.EntityFrameworkCore ve Microsoft.EntityFrameworkCore.Design. Şimdi isminden şu an için şüphe ettiğim DeppoDbContext sınıfını yazarak devam edelim.

using HexagonalAdventure.Domain;
using Microsoft.EntityFrameworkCore;

namespace HexagonalAdventure.Adapters.Out.EF;

public class DeppoDbContext(DbContextOptions<DeppoDbContext> options)
    : DbContext(options)
{
    public DbSet<Product> Products { get; set; }
}

Oldukça klasik bir DbContext sınıfı yazdık. İçinde sadece ürünler için bir DbSet özelliği yer alıyor. Şimdi de IProductRepository arayüzünü implemente eden EfProductRepository sınıfını yazalım. Hatırlayacağınız üzere IProductRepository, uygulama katmanında bir outbound port olarak tanımlanmıştı. Şimdi bu portu somut olarak uygulayan bir adapter yazacağız. Örneğin şöyle bir sınıf olabilir.

using HexagonalAdventure.Application.Ports.Outbound;
using HexagonalAdventure.Domain;

namespace HexagonalAdventure.Adapters.Out.EF;

public class EfProductRepository(DeppoDbContext deppoDbContext)
    : IProductRepository
{
    public void AddProduct(Product product)
    {
        deppoDbContext.Products.Add(product);
        deppoDbContext.SaveChanges();
    }

    public Product GetById(Guid id)
    {
        return deppoDbContext.Products.FirstOrDefault(p => p.Id == id);
    }
}

Artık Web api açısından olaya bakabiliriz. Hatırlarsanız program.cs sınıfında IProductRepository'nin hangi somut sınıf tarafından implemente edileceğini tanımlamamız gerekiyordu ve ilk örneğimizde in-memory çalışan bir repository sınıfını kullanmıştık. Web api'nin yeni adaptör ile çalışması için tek yapmamız gereken Dependency Injection Container'daki bağımlılık tanımını değiştirmekten ibaret. Aynen aşağıda görüldüğü gibi.

using HexagonalAdventure.Adapters.Out.EF;
// using HexagonalAdventure.Adapters.Out.InMemory;
using HexagonalAdventure.Application.Ports.Inbound;
using HexagonalAdventure.Application.Ports.Outbound;
using HexagonalAdventure.Application.Services;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();

// EF Postgresql kullanımı için de middleware'e bir şeyler eklememiz lazım
builder.Services.AddDbContext<DeppoDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DeppoConnectionString")));

// Dependency Injection tanımlamaları
// builder.Services.AddSingleton<IProductRepository, InMemoryProdutRepository>(); // Tüm uygulama boyunca tek bir instance kullanılır

// EF Core kullanan yeni outbound port implementasyonu
builder.Services.AddScoped<IProductRepository, EfProductRepository>();
builder.Services.AddScoped<IProductService, ProductService>();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

await app.RunAsync();

Tabii burada bazı konfigürasyonları da yapmamız gerekiyor. Örneğin appsettings.json dosyasına Postgresql bağlantı bilgisini de eklememiz gerekiyor. Aşağıdaki gibi bir içerik olabilir.

{
  "ConnectionStrings": {
    "DeppoConnectionString": "Host=localhost;Port=5432;Database=deppo;Username=johndoe;Password=somew0rds"
  }
}

Ayrıca yine gelenek olduğu üzere bir migration planı hazırlayıp çalıştıralım. Bunun için dotnet komut satırı aracını aşağıdaki gibi kullanabiliriz.

# Sistemde ef tool'unun yüklü olması gerekiyor. Eğer yüklü değilse aşağıdaki komutla yükleyebiliriz.
dotnet tool install --global dotnet-ef

# Varsa da güncellemek gerekebilir. O zaman da şu komut işe yarar
dotnet tool update --global dotnet-ef

# Migration planının hazırlanması
dotnet ef migrations add InitialCreate --project HexagonalAdventure.Adapters.Out.EF --startup-project HexagonalAdventure.Adapters.In.WebApi

# Migration planının işletilmesi
dotnet ef database update --project HexagonalAdventure.Adapters.Out.EF --startup-project HexagonalAdventure.Adapters.In.WebApi

Eğer her şey yolunda gittiyse aşağıdaki ekran görüntüsünde olduğu bu sefer ürün bilgisinin veritabanına kaydedildiğini görebiliriz.

Dikkat edileceği üzere sisteme yeni bir adapter ekledik fakat uygulama domain'ine hiç dokunmadık. Dış sistem entegrasyonunda sadece yeni eklediğimiz adapter'ı var olan port'a bağladık. Böylece uygulama domain'inin dış dünyaya olan bağımlılığını tamamen ortadan kaldırmış olduk.

7. Farklı Bir Dış Sistem Entegrasyonu: Console Uygulaması

Senaryomuzu şimdi biraz daha genişletelim ve farklı bir dış sistem entegrasyonu yapalım. Web Api'ye ek olarak bir de Console uygulaması geliştirelim. Console uygulaması Web Api'yi kullanmayacak elbette. Doğrudan uygulama servislerini kullanarak çalışacak. Böylece farklı bir adaptörün var olan port'a nasıl bağlandığını göreceğiz. Bir başka deyişle console uygulaması farklı bir Inbound Adapter olacak. Console uygulamasında da dikkate almamız gereken şeyler var. Örneğin burada da bir Composition Root kullanmamız mimariye uygunluk açısından önemli. Yani bir Depdendency Injection Container hazırlayıp port ve adaptörleri birbirine bağlayacağız.

Solution'daki Adapters klasörüne HexagonalAdventure.Adapters.In.ConsoleHexagonalAdventure.Adapters.In.Console isimli yeni bir Console projesi oluşturup gerekli kütüphaneleri ekledikten sonra aşağıdaki program kodları ile devam edelim.

using HexagonalAdventure.Adapters.Out.InMemory;
using HexagonalAdventure.Application.Ports.Inbound;
using HexagonalAdventure.Application.Ports.Outbound;
using HexagonalAdventure.Application.Services;
using Microsoft.Extensions.DependencyInjection;

var serviceProvider = new ServiceCollection()
    .AddSingleton<IProductRepository, InMemoryProdutRepository>()
    .AddScoped<IProductService, ProductService>()
    .BuildServiceProvider();

Console.WriteLine("Add a new product");

Console.Write("Title: ");
string title = Console.ReadLine();

Console.Write("Price: ");
decimal price = decimal.Parse(Console.ReadLine());

Console.Write("Category: ");
string category = Console.ReadLine();

Console.Write("Stock: ");
int stock = int.Parse(Console.ReadLine());

var productService = serviceProvider.GetRequiredService<IProductService>();
var newProductId = productService.CreateProduct(title, price, category, stock);

Console.WriteLine("Product created with ID: " + newProductId);
Console.ReadLine();

Console projesi sadece Application ve InMemory Adapter projelerini referans eder. API projesini veya doğrudan Domain projesini kullanmaz. Örneğin mümkün mertebe basit olması açısından console projesi in-memory veritabanı kullanacak şekilde tasarlanmıştır. Diğer yandan web api bağımlılığı olmadığı için bir network servis bağımlılığı da yoktur. Doğrudan uygulama katmanındaki port'ları ve gerekli dış adaptörü bir kompozisyon altında birleştirerek kullanır. Senaryonun bir özeti de şudur; Uygulamanın domain katmanına dokunmadan hem verinin yazıldığı yeri hemde geldiği yeri değiştirebildik.

Tam şu anda solution içeriğine bakarsak aşağıdaki gibi bir iskelet oluştuğunu gözlemleyebiliriz.

Testler

Onion Architecture, Clean Architecture gibi diğer mimari yaklaşımlarda olduğu gibi hexagonal mimaride de test edilebilirlik önemli bir avantaj olarak öne çıkar. Uygulama domain'i dış dünyadan tamamen izole edildiği için bu katmandaki kodun test edilmesi son derece kolaydır. Diğer yandan port ve adaptörler üzerinden yapılan entegrasyonları da kolayca test edebiliriz. Bu noktada da devreye genellikle mock nesneler girer. Bu sayede gerçek veritabanı veya diğer dış sistemlere ihtiyaç duymadan uygulama iş kurallarını doğrulayabiliriz.

Yine basit adımlarla ilerleyelim. İlk olarak Domain katmanı için birkaç birim test(unit test) yazalım. Şu anda kobay olarak kullandığımız Product sınıfının çok fonksiyonelliği olmasa da temel iş kurallarını içeren bir sınıf olduğu için yine de testlerini yazmak gerekir.

Test yazmayı sadece kodun doğruluğunu kontrol etmek için değil, aynı zamanda kodun nasıl kullanılacağını göstermek ve kodun kendisiyle ilgili bazı önemli bilgileri belgelemek için de kullanabiliriz. Bu yüzden testler sadece doğruluk kontrolü değil, aynı zamanda bir tür dokümantasyon görevi de görürler. Ayrıca kodun kalitesini artırmak ve gelecekteki değişikliklere karşı korumak için de önemli bir araçtırlar. Birçok statik kod analiz aracı özellikle Code Coverage oranını baz alarak bir skor hesaplaması yapar. Code Coverage oranı, yazdığımız testlerin kodun ne kadarını kapsadığını gösteren bir metriktir. Yüksek bir Code Coverage oranı genellikle daha iyi test kapsamına işaret eder fakat bu sizi yanıltmasın kodun kalitesi için tek başına yeterli ölçü değildir. Testlerin kalitesi ve doğruluğu da önemlidir. Bu yüzden sadece yüksek bir Code Coverage oranına odaklanmak yerine, testlerin gerçekten kodun doğru çalıştığını ve beklenen sonuçları verdiğini doğrulamak önemlidir.

8. Domain Katmanı için Birim Testler

Bu kadar laf kalabalığını bir kenara bırakalım ve dilerseniz ilk birim testlerimizi yazalım. HexagonalAdventure.Domain.UnitTests isimli yeni bir test projesi(xUnit şablonundan) oluşturarak işe başlayabiliriz. İçerisine ProductTests isimli bir test sınıfı metotlarını aşağıdaki gibi düzenleyelim.

namespace HexagonalAdventure.Domain.UnitTests;

public class ProductTests
{
    [Fact]
    public void DecreaseStock_When_StockIsEnough()
    {
        // Arrange (Hazırlık safhası)
        var product = new Product(Guid.NewGuid(), "Optical Mouse", 29.99m, "Electronics", 10);

        // Act (Eylem safhası)
        product.DecreaseStock(5);

        // Assert (Doğrulama safhası)
        var expectedStock = 5;
        Assert.Equal(expectedStock, product.StockQuantity);
    }

    [Fact]
    public void DecreaseStock_When_StockIsNotEnough_ShouldThrowException()
    {
        // Arrange
        var product = new Product(Guid.NewGuid(), "Mechanical Keyboard", 79.99m, "Electronics", 3);

        // Act & Assert
        Assert.Throws<InvalidOperationException>(() => product.DecreaseStock(5));
    }

    [Fact]
    public void IncreaseStock_ShouldIncreaseStockQuantity()
    {
        // Arrange
        var product = new Product(Guid.NewGuid(), "Gaming Headset", 49.99m, "Electronics", 5);

        // Act
        product.IncreaseStock(10);

        // Assert
        var expectedStock = 15;
        Assert.Equal(expectedStock, product.StockQuantity);
    }

    [Fact]
    public void IncreaseStock_When_AmountIsNegative_ShouldThrowException()
    {
        // Arrange
        var product = new Product(Guid.NewGuid(), "USB-C Hub", 39.99m, "Electronics", 8);

        // Act & Assert
        Assert.Throws<ArgumentException>(() => product.IncreaseStock(-5));
    }
}

Şu an için sadece stok miktarını artıran ve azaltan metotları test ettik. Bu test projesi Domain katmanı dışındaki hiçbir projeyi referans etmez, hiçbir dış bağımlılık da içermez. Sadece bir Test Framework kullanır. Yazdığımız testleri kod editörleri üzerinden test edebileceğimiz gibi komut satırından da koşturabiliriz.

# Solution içindeki tüm test projelerini çalıştırmak için
dotnet test

# Belli bir test projesini çalıştırmak içinse
dotnet test HexagonalAdventure.Domain.Tests

Sonuç olarak yazdığımız testlerin başarılı olduğunu görebiliriz.

9. Uygulama Katmanı için Birim Testler (Mock Nesnelerle)

Şimdi de uygulama katmanını göz önüne alalım. Örneğin buradaki ProductService sınıfı için birim testler ekleyelim. Tabii burada dikkat edilmesi gereken bir başla konu var. Bu sefer ProductService sınıfının kullanmak için içerisine enjekte edilen IProductRepository sözleşmesine dayalı bir bağımlılık(Dependency) bulunuyor. Birim testlerde bu tip bağımlılıklarda somut implementasyonları kullanmak yerine genellikle mock nesneler tercih edilir. Mock nesneler, gerçek nesnelerin davranışlarını taklit eden sahte yapılar olarak düşünülebilir. Bu sayede gerçek veritabanı veya diğer dış sistemlere ihtiyaç duymadan uygulama iş kurallarını doğrulayabiliriz.

Bu amaçla Solution içinde HexagonalAdventure.Application.UnitTests isimli yeni bir test projesi oluşturarak devam edelim. Tabii bu projede Moq gibi bir mocking framework kullanarak bağımlılıkları taklit etmemiz gerekiyor. Gerekli nuget paketlerini ekledikten sonra ProductServiceTests isimli test sınıfını aşağıdaki gibi yazarak ilerleyelim.

Pratik bilgi: Mock nesneleri gibi dış bağımlılıkları taklit eden enstrümanlarda testlerin gerçekten bir veritabanına veya bir servise daha doğrusu ağ üzerinde bir yerlere gitmediğinden emin olmak için kullanılabilecek ilkel yollardan birisi test projesindeki appsettings.json dosyasına geçersiz bağlantı bilgileri eklemek olabilir. Böylece yanlışlıkla gerçek bir veritabanına bağlanmaya çalıştığımızda testlerimiz başarısız olur ve bu durum bize bir şeylerin yanlış gittiğine dair bir sinyal verir ya da bağlantılar uzak sunucularda ise interneti testler sırasında kapatmak da benzer bir etki yaratır. Tabii bunlar ilgili testleri kendi makinemizde koşturmak istediğimiz durumlar için geçerlidir. Nihayetinde gerçekten de veritabanına gidiliyorsa bunu CI/CD süreçlerinde acı bir şekilde öğrenmek yerine local ortamda öğrenmek daha iyi olabilir.

namespace HexagonalAdventure.Application.UnitTests;

using Moq;
using HexagonalAdventure.Application.Ports.Outbound;
using HexagonalAdventure.Application.Services;
using HexagonalAdventure.Domain;

public class ProductServiceTests
{
    [Fact]
    public void CreateProduct_ShouldReturnValidGuid()
    {
        // Arange
        var mockRepo = new Mock<IProductRepository>();
        mockRepo.Setup(r => r.AddProduct(It.IsAny<Domain.Product>()));

        // Act
        var service = new ProductService(mockRepo.Object);
        var actualGuid = service.CreateProduct("AyBiEm Laptop i7", 1500m, "Electronics", 10);

        // Assert
        Assert.NotEqual(Guid.Empty, actualGuid);

        // Verify (Gerçekten de dış bağımlılıktaki AddProduct metodunun çağrıldığını doğrulamak için)
        mockRepo.Verify(r => r.AddProduct(It.IsAny<Domain.Product>()), Times.Once);
    }

    [Fact]
    public void CreateProduct_ShouldPassCorrectDataToRepository()
    {
        // Arange
        var mockRepo = new Mock<IProductRepository>();
        Product capturedProduct = null;
        mockRepo.Setup(r => r.AddProduct(It.IsAny<Product>()))
                .Callback<Product>(p => capturedProduct = p);

        // Act
        var service = new ProductService(mockRepo.Object);
        var actualGuid = service.CreateProduct("AyBiEm Laptop i7", 1500m, "Electronics", 10);

        // Assert
        Assert.NotNull(capturedProduct);
        Assert.Equal("AyBiEm Laptop i7", capturedProduct.Title);
        Assert.Equal(1500m, capturedProduct.ListPrice);
        Assert.Equal("Electronics", capturedProduct.Category);
        Assert.Equal(10, capturedProduct.StockQuantity);
    }

    [Fact]
    public void CreateProduct_WhenTitleIsEmpty_ShouldThrowException()
    {
        // Arange
        var mockRepo = new Mock<IProductRepository>();

        // Act
        var service = new ProductService(mockRepo.Object);

        // Assert
        Assert.Throws<ArgumentException>(() => service.CreateProduct("", 1500m, "Electronics", 10));
    }

    [Fact]
    public void CreateProduct_WithNegativeStockQuantity_ShouldThrowException()
    {
        //Arange
        var mockRepo = new Mock<IProductRepository>();
        var service = new ProductService(mockRepo.Object);

        //Act & Assert
        var exception = Assert.Throws<ArgumentException>(() => service.CreateProduct("AyBiEm Laptop i7", 1500m, "Electronics", -5));

        //Verify
        mockRepo.Verify(r => r.AddProduct(It.IsAny<Product>()), Times.Never);
    }
}

Şimdi buradaki test metodları hakkında biraz konuşalım. CreateProduct_ShouldReturnValidGuid testinde CreateProduct fonksiyonunun geçerli bir Guid döndürüp döndürmediğini doğruluyoruz. CreateProduct_ShouldPassCorrectDataToRepository test metodunda ise CreateProduct fonksiyonunun IProductRepository'nin AddProduct metodunu doğru verilerle çağırıp çağırmadığını. Zira CreateProduct metodunun doğru çalışması sadece geriye geçerli bir Guid değer döndürdüğü ile ölçülemez. Gerçekten gönderdiğimiz ürün bilgilerinin AddProduct metoduna gittiğinden de emin olmalıyız. Bunun için setup metodunu kullanırken callback fonksiyonunda bir Product nesnesi kullandık. Sonuçta CreateProduct metodu içindeki AddProduct çağrılmadan önce bir Product nesnesi örnekleniyor. Dolayısıyla CreateProduct parametreleri ile oluşan Product nesne örneği değerlerinin, Callback ile dönen Product nesne örneği değerlerine eşit olması gerekir.

CreateProduct_WhenTitleIsEmpty_ShouldThrowException ve CreateProduct_WithNegativeStockQuantity_ShouldThrowException isimli testlerde ise geçersiz girdilerle CreateProduct fonksiyonunun beklenen şekilde istisna(Exception) fırlatıp fırlatmadığını doğruluyoruz. CreateProduct metodu içinde doğrudan bir exception fırlatımı söz konusu olmasa da, Product sınıfı içinde tanımlı domain kurallarımız var ve bunlar exception döndürüyor. Buna ek olarak CreateProduct_WithNegativeStockQuantity_ShouldThrowException testinde, geçersiz bir stok miktarıyla ürün oluşturulmaya çalışıldığında, AddProduct metodunun hiç çağrılmadığını da doğruluyoruz. Böylece hem iş kurallarının hem de dış bağımlılıklara yapılan çağrıların doğruluğunu test etmiş olduk.

Eklediğimiz son testleri de çalıştıralım.

10. Entegrasyon Testleri (Adapter Katmanı Testleri)

Özellikle veritabanı veya harici servis gibi dış bağımlılıkların yer aldığı adaptör katmanı tipik olarak entegrasyon testleri ile denetlenebilir. Burada amaç kodun dış dünya ile uyumlu bir şekilde çalışıp çalışmadığını kontrol etmektir. Mesela outbound adapter olarak entity framework yardımıyla postgresql veritabanına gerçekten kayıt atabiliyor muyuz ya da inbound adapter olarak kullandığımız ProductController gerçekten http isteğine 200 OK dönebiliyor mu gibi durumları test edebiliriz. Entegrasyon testlerinde mock nesnelerden ziyade ortamları taklit eden yapılara ihtiyaç duyarız. Mesela docker tarafı için Testcontainers ya da entity framework tarafı için bir in-memory veri sağlaycısı düşünülebilir. Şimdi HexagonalAdventure.Adapters.IntegrationTests şeklinde yine xUnit türünden yeni bir proje ekleyerek devam edelim.

İlk olarak entity framework aracılığıyla kayıt atıp atamadığımız bakalım. Burada mock nesne yerine iki yaklaşımı tercih ederek ilerleyebiliriz. Bunlardan birisi Test Container diğeri ise In-Memory Provider kullanmaktır. Microsoft.EntityFrameworkCore.InMemory paketini kullanarak devam edelim. Buna göre veri yazma sürecini bellek üzerinden kontrol edeceğimizi ifade edebiliriz.

using HexagonalAdventure.Domain;
using HexagonalAdventure.Adapters.Out.EF;
using Microsoft.EntityFrameworkCore;

namespace HexagonalAdventure.Apdaters.IntegrationTests;

public class EFProductRepositoryTests
{
    [Fact]
    public void Add_ShouldSaveProductToDatabase_And_GetById_ShouldReturnIt()
    {
        // Arrange
        var options = new DbContextOptionsBuilder<DeppoDbContext>()
            .UseInMemoryDatabase(databaseName: Guid.NewGuid().ToString())
            .Options;

        using var context = new DeppoDbContext(options);
        var repository = new EfProductRepository(context);
        var productId = Guid.NewGuid();
        var productToSave = new Product(productId, "Learning the Hexagonal Architecture", 29.99m, "Books", 2);

        // Act
        repository.AddProduct(productToSave);

        // Assert
        var retrievedProduct = repository.GetById(productId);
        Assert.NotNull(retrievedProduct);
        Assert.Equal(productId, retrievedProduct.Id);
        Assert.Equal("Learning the Hexagonal Architecture", retrievedProduct.Title);
        Assert.Equal(29.99m, retrievedProduct.ListPrice);
        Assert.Equal("Books", retrievedProduct.Category);
        Assert.Equal(2, retrievedProduct.StockQuantity);
    }
}

Test metodumuz, EfProductRepository nesnemizin ihtyiaç duyduğu DbContext örneği için In-Memory bir veritabanı sağlayacak şekilde yapılandırılıyor. Böylece gerçek bir veritabanına ihtiyaç duymadan repository'nin işlevselliğini test edebiliriz. Testte önce bir ürün oluşturup kaydediyoruz, ardından aynı ürünü GetById metodu ile çekip kaydettiğimiz ürünle eşit olup olmadığını doğruluyoruz.

Diyelim ki DbContext türevini uygularken SaveChanges metodunu yazmayı atlamışız. Bu durumda GetById metodunu çağırdığımızda null değer dönecektir. Dolayısıyla testimiz başarısız olur. Kısaca sadece kodun çalışıp çalışmadığını değil entity framework ayarlarını da kontrol etmiş oluruz. Bu test tam olarak Domain -> Service -> Interface -> Adapter akışını takip etmekte. Böylece uygulamayı gerçek çalışma ortamına oldukça yakın bir seviyede test etmiş olduk diyebiliriz.

Elbette yeterli değil. Diğer adaptörler için de benzer testler ekleyebiliriz. Örneğin ProductController için de bir entegrasyon testi yazabiliriz. Bu sefer HTTP Post isteği gönderdiğimizde her şeyin uçtan uca doğru çalıştığını görmeyi amaçlayabiliriz. Burada da WebApplicationFactory gibi bir nesne kullanarak gerçek bir HTTP istemcisi üzerinden API'ye istek gönderip yanıt almayı deneme şansımız var. Yine aynı test projesinde bu sefer ProductControllerTests isimli yeni bir test sınıfı oluşturarak çalışmamıza devam edelim.(WebApplicationFactory nesnesini kullanabilmek içinse test projemize Microsoft.AspNetCore.Mvc.Testing nuget paketini eklememiz gerekiyor)

using HexagonalAdventure.Adapters.In.WebApi.Controllers;
using Microsoft.AspNetCore.Mvc.Testing;
using System.Net;
using System.Net.Http.Json;

namespace HexagonalAdventure.Apdaters.IntegrationTests;

public class ProductControllerTests(WebApplicationFactory<Program> factory)
    : IClassFixture<WebApplicationFactory<Program>>
{
    // Program sınıfı Web API projesindeki sınıfımızdır.
    // WebApplicationFactory, bu sınıfı kullanarak testler için bir test sunucusu oluşturur.
    private record CreateProductResponse(Guid Id);

    [Fact]
    public async Task CreateProduct_ShouldReturn200OkWithProductId()
    {
        // Arrange
        var client = factory.CreateClient(); // Test sunucusuna istek göndermek için fabrikadan bir HttpClient oluşturulur.
        var request = new CreateProductRequest("Pragmatic Programmer", 42.99m, "Books", 4);

        // Act
        var response = await client.PostAsJsonAsync("/api/products", request); // POST isteği gönderilir ve yanıt alınır.

        // Assert
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
        var responseData = await response.Content.ReadFromJsonAsync<CreateProductResponse>();
        Assert.NotNull(responseData);
        Assert.NotEqual(Guid.Empty, responseData.Id);
    }
}

Öncelike bu test sınıfında neler yaptığımıza bir bakalım. Sınıfımız, IClassFixture arayüzünü implemente ediyor ve primary constructor üzerinden de generic WebApplicationFactory türünden bir nesne alıyor. Buradaki amacımız birim test metotları çağırılmadan önce Web API uygulamasının gerçek bir örneğinin bir seferliğine ayağa kaldırılmasını sağlamak. Buna göre CreateProduct_ShouldReturn200OkWithProductId isimli test metodumuzda önce bir HTTP istemcisi oluşturuyoruz, ardından CreateProductRequest türünden bir nesne örneği hazırlayıp API'ye gönderiyoruz. Son olarak da dönen yanıtın durum kodunun 200 OK olduğunu ve gelen cevapta geçerli bir Guid(ki product ID olarak ele alınıyor) olup olmadığını doğruluyoruz.

Bu testi koştururken dikkat etmemiz gereken noktalardan birisi gerçek bir web sunucusunu gerçekten ayağa kaldırmayışımız olması. Ayrıca bu test ile dış dünyadan gelen bir isteğin(ki burada HTTP isteği), inbound adapter vasıtasıyla sisteme girişini, iş kurallarından geçişini ve sonunda outbound adapter üzerinden kaydedilişini doğrulamaya çalışıyoruz. Yalnız burada dikkat etmemiz gereken bir nokta daha var. Web Api tarafında program sınıfımız gerçekten de Postgesql'e kayıt atacak şekilde bir repository bileşeni kullanıyor. Yani testi bu şekilde çalışıtırırsak test verisi veritabanına da yazılır. Dolayısıyla bir önceki entegrasyon testinde olduğu gibi bir in-memory veritabanı ile çalışmak daha mantıklıdır. WebApplicationFactory bu noktada bize önemli esneklikler sağlar. Program sınıfındaki kurguyu ezebiliriz. Buna göre az önce yazdığımız test metodunu aşağıdaki hale getirerek devam edelim.

using HexagonalAdventure.Adapters.In.WebApi.Controllers;
using HexagonalAdventure.Adapters.Out.EF;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Infrastructure;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using System.Data.Common;
using System.Net;
using System.Net.Http.Json;

namespace HexagonalAdventure.Apdaters.IntegrationTests;

public class ProductControllerTests(WebApplicationFactory<Program> factory)
    : IClassFixture<WebApplicationFactory<Program>>
{
    private record CreateProductResponse(Guid Id);

    [Fact]
    public async Task CreateProduct_ShouldReturn200OkWithProductId()
    {
        // Arrange
        // Program sınıfımızdaki DI servisi, DbContext türevini Postgresql ile çalışacak şekilde yapılandırıyor.
        // Tabbi EF kullandığımız için beraberinde de birçok servis enjekte ediliyor. Bu yüzden DbContext ile ilgili
        // ne kadar kayıtlı bileşen varsa kaldırıyoruz.
        var client = factory.WithWebHostBuilder(builder =>
        {
            builder.ConfigureServices(services =>
            {
                services.RemoveAll(typeof(IDbContextOptionsConfiguration<DeppoDbContext>)); // Program sınıfında AddDbContext'in kaydettiği Npgsql yapılandırma kaynağını kaldırır.
                services.RemoveAll(typeof(DbContextOptions<DeppoDbContext>)); // DbContext ile ilgili tüm servisleri kaldırır.
                services.RemoveAll(typeof(DbConnection)); // Varsa DbConnection ile ilgili tüm servisleri kaldırır. Örneğin veritabanı kayıtları silinir.

                services.AddDbContext<DeppoDbContext>(options =>
                {
                    options.UseInMemoryDatabase("DbTest_" + Guid.NewGuid().ToString());
                });
            });
        }).CreateClient();
        var request = new CreateProductRequest("Pragmatic Programmer", 42.99m, "Books", 4);

        // Act
        var response = await client.PostAsJsonAsync("/api/products", request); // POST isteği gönderilir ve yanıt alınır.

        // Assert
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
        var responseData = await response.Content.ReadFromJsonAsync<CreateProductResponse>();
        Assert.NotNull(responseData);
        Assert.NotEqual(Guid.Empty, responseData.Id);
    }
}

Testlerimizdeki nihai durumu aşağıdaki görselle özetleyebiliriz.

11. TestContainer ile Entegrasyon Testleri

Son entegrasyon testlerinde in-memory veritabanı kullanarak ilerledik ancak kurumsal çaptaki çözümlerde genellikle Test Container' lar tercih ediliyor. Bunun en büyük sebebi in-memory veritabanı rolünü üstlenen enstrümanın aslında gerçekten bir veritabanı olmaması. Zira SQL'e veye PostgreSQL'e özgü birçok özellik desteklenmez. Misal JSONB veri kolonları veya stored procedure'ler. Hoş iş süreçlerindeki kuralların stored procedure'lere yazılması pek de iyi bir fikir değildir ama yine de bazı durumlarda böyle bir şeyle karşılaşmak mümkün olabilir. Bu yüzden gerçek bir veritabanı kullanmak daha sağlıklı sonuçlar verecektir.

Bir Test Container kullanarak testler sırasında geçici olarak ayağa kaldırılan gerçek bir veritabanı ile entegrasyon sağlayabiliriz. Test Container teorik olarak arka planda bir docker container ayağa kaldırır. Dolayısıyla sisteminizde docker kurulu olduğunu varsayıyorum. Bizim senaryomuzda ben Postgresql kullandığım için Testcontainers.PostgreSql isimli nuget paketini kullanarak devam edeceğim. Şimdi test projesine aşağıdaki kod içeriğine sahip olan yeni WebApplicationFactory türevini ekleyelim.

using HexagonalAdventure.Adapters.Out.EF;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Infrastructure;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
using System.Data.Common;
using Testcontainers.PostgreSql;

namespace HexagonalAdventure.Apdaters.IntegrationTests;

public class PostgresWebApplicationFactory
    : WebApplicationFactory<Program>, IAsyncLifetime
{
    // Testler başlamadan önce ve bittikten sonra yapmamız gereken kaynak yönetim işlemleri olacağından
    // bu sınıfa IAsyncLifetime arayüzünü de uyguladık.

    private readonly PostgreSqlContainer _container = new PostgreSqlBuilder()
        .WithDatabase("DeppoTestDb")
        .WithUsername("postgres")
        .WithPassword("P@ssw0rd1234")
        .Build();
    public async Task InitializeAsync()
    {
        // Docker üzerinden postgresql konteynırını başlatır. Testler bu veritabanını kullanacak.
        await _container.StartAsync();
    }

    async Task IAsyncLifetime.DisposeAsync()
    {
        await _container.DisposeAsync(); // Testler tamamlandıktan sonra konteynırı durdurur ve kaynakları temizler.
    }

    // Burada da WebApplicationFactory'den gelen ConfigureWebHost metodunu eziyoruz(override)
    // Burada klasik olarak program sınıfındaki servislerin temizlenmesi ve container db'nin context'e eklenmesi gibi işlemler yapılıyor.
    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureServices(services =>
        {
            services.RemoveAll(typeof(IDbContextOptionsConfiguration<DeppoDbContext>)); // Program sınıfında AddDbContext'in kaydettiği Npgsql yapılandırma kaynağını kaldırır.
            services.RemoveAll(typeof(DbContextOptions<DeppoDbContext>)); // DbContext ile ilgili tüm servisleri kaldırır.
            services.RemoveAll(typeof(DbConnection)); // Varsa DbConnection ile ilgili tüm servisleri kaldırır. Örneğin veritabanı kayıtları silinir.

            services.AddDbContext<DeppoDbContext>(options =>
            {
                options.UseNpgsql(_container.GetConnectionString()); // Artık Npgsql, container'ın sağladığı db'ye bağlanacak
            });

            // Tabii şimdi bir konteynır kullanıyor olsa da gerçek veritabanına ihtiyacımız var.
            // Dolayısıyla migration prosedürünü yürütmemiz lazım ki gerekli tablolar da oluşsun.
            var serviceProvider = services.BuildServiceProvider();
            using var scope = serviceProvider.CreateScope();
            var dbContext = scope.ServiceProvider.GetRequiredService<DeppoDbContext>();
            dbContext.Database.EnsureCreated();
        });
    }
}

Buna göre tek yapmamız gereken test sınıfına WebApplicationFactory yerine PostgresWebApplicationFactory türünden bir nesne örneğini enjekte etmek olacak. Bu çalışmadaki diğer test metodu ile karışmaması adına yeni bir test sınıfı ve metod ile devam etmeye karar verdim.

using HexagonalAdventure.Adapters.In.WebApi.Controllers;
using System.Net;
using System.Net.Http.Json;

namespace HexagonalAdventure.Apdaters.IntegrationTests;

public class ProductControllerTests(PostgresWebApplicationFactory factory)
    : IClassFixture<PostgresWebApplicationFactory>
{
    private record CreateProductResponse(Guid Id);

    [Fact]
    public async Task CreateProduct_WhenUsingContainer_ShouldReturn200OkWithProductId()
    {
        // Arrange
        var client = factory.CreateClient();
        var request = new CreateProductRequest("Pragmatic Programmer", 42.99m, "Books", 4);

        // Act
        var response = await client.PostAsJsonAsync("/api/products", request);

        // Assert
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
        var responseData = await response.Content.ReadFromJsonAsync<CreateProductResponse>();
        Assert.NotNull(responseData);
        Assert.NotEqual(Guid.Empty, responseData.Id);
    }
}

Sadece bu testi çalıştırarıp gerçekten de docker tarafında bir container ayağa kalkıyor mu ve testler bu container'daki veritabanına bağlanarak çalışıyor mu diye kontrol edebiliriz.

Burada dikkat edilmesi gereken nokta söz konusu container'ın test tamamlanmadan önce başlatılması ve test bittikten sonra da kaldırılmasıdır. İlk ısınma sırasında(warm-up diyelim) testin süresi biraz uzayabilir zira container'ın ayağa kalkması ve veritabanının hazır hale gelmesi zaman alabilir. Ancak kullanmak istediğimiz veritabanı özellikleri düşünülürse bu maliyete değebilir.

12. Mimari Uygunluk Testleri

Pek çok mimari yaklaşım bileşener arası bağımlılıkların ve izolasyonların doğru yönetilmesi konusunda hassastır. Örneğin bu çalışmada ele aldığımız hexagonal mimaride uygulama domain'inin dış dünyaya olan bağımlılığını tamamen ortadan kaldırmak önemli bir prensiptir. Örneğin domain katmanında bir şekilde entity framework ile konuşmaya başladığımız an mimarinin temel prensiplerinden biri olan bağımsızlık ilkesini ihlal etmiş oluruz.

Bu tür durumları tespit etmek için mimari uygunluk testleri yazılabilir. Microsoft .Net tarafından bakacak olursak bu kontrolü kolayca icra etmemizi sağlayan NetArchTest.Rules isimli bir nuget paketi vardır. Mimari testleri ayrı bir projede ele alalım ve bu amaçla HexagonalAdventure.Architecture.Tests isimli yeni bir test projesi oluşturarak konunuza devam edelim. Projeye NetArchTest.Rules paketini ekledikten sonra da aşağıdaki gibi bir test sınıfı yazalım.

using HexagonalAdventure.Application.Services;
using HexagonalAdventure.Domain;
using NetArchTest.Rules;

namespace HexagonalAdventures.Architecture.Tests;

public class DomainLayerTests
{
    [Fact]
    public void DomainLayer_ShouldNotHaveDependencyOnOtherLayers()
    {
        // Arrange
        var domainAssembly = typeof(Product).Assembly;

        // Act
        var result = Types.InAssembly(domainAssembly)
            .ShouldNot()
            .HaveDependencyOnAny(
            "HexagonalAdventure.Application",
            "HexagonalAdventure.Adapters",
            "Microsoft.EntityFrameworkCore"
            )
            .GetResult();

        // Assert
        Assert.True(result.IsSuccessful, "Domain layer should not have dependencies on Application, Adapters, or EF Core.");
    }

    [Fact]
    public void ApplicationLayer_ShouldNotHaveDependencyOnAdapters()
    {
        // Arrange
        var appAssembly = typeof(ProductService).Assembly;
        
        // Act
        var result = Types.InAssembly(appAssembly)
            .ShouldNot()
            .HaveDependencyOn("HexagonalAdventure.Adapters")
            .GetResult();

        // Assert
        Assert.True(result.IsSuccessful, "Application layer should not have dependencies on Adapters.");
    }
}

Bu testlere göre örneğin HexagonalAdventure.Application öneki içeren namespace'lerin olduğu projelerin Domain katmanına sızmasını engellemiş oluyoruz(Entity Framework ile birlikte tabii). Ben burada sadece birkaç temel kontrol ekledim ancak mimari uygunluk testlerini çok daha detaylı hale getirmek mümkün olabilir. Örneğin domain katmanında sadece domain entity'lerin bulunması gerektiği gibi bir kural veya application katmanında sadece servislerin bulunması gerektiği gibi bir kural da ekleyebiliriz. Güncel olarak geldiğimiz noktada projemizdeki tüm testlerin başarılı bir şekilde çalıştığını görebiliriz.

Genel Görünüm

Solution içeriğinde birçok proje ve harici nuget bağımlılıkları var. Gelinen noktada neler olduğunu kabaca aşağıdaki diagramda olduğu gibi özetleyebiliriz.

Yazının bu kısmına kadar geldiyseniz size canı gönülden teşekkür ederim. Umarım bilgilendirici ve denediğinize değer bir makale olmuştur. Burada ele aldığımız uygulama kodlarına elbette github reposu üzerinden erişebilirsiniz. Hatta DDD'ye özgü bir takım yenilikler de eklemeye çalışacağım. Event'ler gibi. Tekrardan görüşünceye dek hepinize mutlu günler dilerim.