Use Case Diagram ve Use Case Spesifikasyonu: Actor, include, extend ve Cockburn Şablonu

Sürüm notu: Bu yazıdaki diyagramlar UML 2.5.1 notasyonuyla çizilmiştir; C# örnekleri .NET 10 ile denenmiştir.

Önce Tahmin Et

Aşağıdaki metin, Mermaid'in use case diyagramı söz dizimiyle yazılmış küçük bir parça. İzin modülünden üç use case ve aralarındaki iki ilişki var:

usecase-beta
actor Employee("Employee")
RequestLeave("Request Leave")
CheckBalance("Check Balance")
AttachReport("Attach Medical Report")
Employee -- RequestLeave
RequestLeave ..> : include CheckBalance
AttachReport ..> : extend RequestLeave

İki soru. Birincisi: "Attach Medical Report" use case'ini modelden tamamen silersen, "Request Leave" hâlâ eksiksiz bir use case midir? İkincisi: "Check Balance"'ı silersen ne olur? Okların neden ters yönlere baktığını da düşün: biri ana use case'ten çıkıyor, diğeri ana use case'e giriyor.

Use Case Diagram'ın Dört Öğesi

Use case diagram, UML (Unified Modeling Language) diyagramlarının en sade görüneni ve en çok yanlış kullanılanıdır. Sistemi dışarıdan, bir kara kutu olarak gösterir: kim kullanıyor ve hangi amaçla. İçerideki class'lar, ekranlar, sıralama burada yoktur. Dört öğeyle çizilir.

Actor, sistemle etkileşen bir kullanıcının ya da başka bir sistemin oynadığı roldür. "Rol" kelimesi önemli: Ada Lovelace bir actor değildir; Ada, izin talep ederken Çalışan rolünü, kendi ekibinin talebini onaylarken (bir gün yönetici olursa) Yönetici rolünü oynar. Actor'ın notasyonu çubuk adamdır, ama UML aynı actor'ın «actor» keyword'lü bir dikdörtgenle de gösterilebileceğini söyler; dış sistemler için bu gösterim daha okunaklıdır. Use case'i başlatan ve hedefi o use case ile karşılanan actor'a primary actor, use case'in yardımına ihtiyaç duyduğu actor'a (bizde takvim sistemi) secondary ya da supporting actor denir.

Subject, yani sistem sınırı, use case'lerin içinde durduğu dikdörtgendir ve modellediğin şeyin adını taşır. Actor'lar her zaman sınırın dışındadır. Sınırı çizmek, "bu iş bizim sistemimizin mi, başkasının mı?" sorusunu açıkça cevaplamaktır.

Use case, actor'ın sistemle gerçekleştirmek istediği ve sonunda actor'a bir değer dönen bir hedeftir. Elips içinde, fiil ve isimle adlandırılır: "İzin Talep Et", "Talebi Karara Bağla". Adı bir ekranın ya da butonun adı değil, actor'ın hedefidir.

Association, actor ile use case arasındaki düz çizgidir ve "bu actor bu use case'e katılır" demektir. Ok başı zorunlu değildir; UML bu çizgiye multiplicity de koymana izin verir, ama pratikte nadiren gerekir. Bu dördüne üç ilişki eklenir: actor'lar ve use case'ler arasında generalization, use case'ler arasında «include» ve «extend».

İzin Modülünün Diyagramını Okumak

Önceki yazıda R1–R12 maddelerinden çıkardığımız actor ve hedefleri tek bir diyagramda topladık:

Diyagramı soldan sağa okuyalım. Çalışan üç hedefe katılıyor: izin talep etmek, talebini iptal etmek ve bakiyesini görüntülemek. İK (İnsan Kaynakları) Uzmanı da talep iptal edebiliyor (R11'deki "izin başladıktan sonra iptali yalnız İK yapabilir" kuralı), bakiyeyi gerekçeyle düzeltebiliyor ve izin türleri ile resmi tatilleri yönetiyor. İki actor'ın aynı use case'e bağlı olması o use case'in iki farklı senaryosu olduğunu gösterir; ayrıntı spesifikasyonda yazılır.

Sağ tarafta Direktör'den Yönetici'ye giden içi boş üçgenli ok, actor generalization'dır: Direktör, Yönetici'nin yapabildiği her şeyi yapabilir, yani "Talebi Karara Bağla" use case'ine o da katılır. Direktörü ayrıca bu use case'e bağlamaya gerek kalmadı. Bunu class diagram'daki inheritance ile karıştırma: burada iki ayrı Employee tipi yok, iki ayrı rol var. Kodda bu, bir talebi karara bağlama yetkisinin hem doğrudan yöneticiye hem departman direktörüne verilmesi olarak karşılık bulur.

Takvim Sistemi, «actor» keyword'lü dikdörtgenle gösterilmiş bir secondary actor. Onaylanan izin takvime yazıldığı ve iptal edilen izin takvimden silindiği için iki use case'e bağlı. İzin modülü takvim sistemini kontrol etmiyor; onunla konuşuyor. Sınırın dışında durmasının anlamı bu.

Diyagramda "Giriş Yap", "Bildirim Gönder" ya da "İş Günü Hesapla" yok. Giriş yapmak bir actor'ın hedefi değil, başka bir hedefe ulaşmak için ön koşul. Bildirim göndermek sistemin yaptığı bir iş; hiçbir actor portala "bugün bir bildirim göndereyim" diye girmiyor. İş günü hesabı da "İzin Talep Et"in bir adımı. Bunlar spesifikasyonda adım olarak yer alır.

«include» ve «extend»: Ok Hangi Yöne?

Önce Tahmin Et'in cevabı: "Attach Medical Report"u silersen "Request Leave" eksiksiz kalır, "Check Balance"'ı silersen kalmaz. Bu fark, iki ilişkinin bütün anlamını taşır.

«include», UML 2.5.1'e göre dahil edilen use case'in davranışının, dahil eden use case'in davranışının içine yerleştirilmesidir. Ok, dahil edenden dahil edilene gider, çünkü bağımlılık o yöndedir: "İzin Talep Et", bakiye kontrolü olmadan tamamlanamaz ve her çalıştığında o kontrolü yapar. Bizde aynı kontrol "Talebi Karara Bağla"da da gerekiyor (R8: onay anında bakiye yeniden kontrol edilir), o yüzden onu ayrı bir use case'e çıkarıp iki yerden dahil ettik. Include'un var olma nedeni tekrar eden, zorunlu bir davranışı tek bir yerde tanımlamaktır.

«extend» ise ters yönde çalışır. Genişleten use case ("Rapor Ekle"), ana use case'in ("İzin Talep Et") belirli bir noktasında, belirli bir koşul doğruysa devreye giren ek davranış tanımlar. O noktaya extension point denir ve ana use case'in elipsinde, ayrı bir bölmede adıyla listelenir. Koşul, extend ilişkisine bağlanan bir notta yazılır: bizde {izin türü = Hastalık}. Ok genişletenden ana use case'e gider, çünkü bilen taraf genişletendir: "İzin Talep Et" kendi başına eksiksizdir ve kendisini kimlerin genişlettiğinden habersizdir.

Kodda bu iki ilişki farklı yerlere düşer. Include genellikle doğrudan bir çağrıdır: Submit içinde bakiye kontrolü yapan bir service çağrısı. Extend ise ana akışın dokunulmadan genişletilebildiği bir noktadır: ayrı bir endpoint, bir event handler ya da yalnızca belirli izin türlerinde açılan bir form bölümü. SOLID (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion) serisinde konuştuğumuz Open/Closed Principle'ı hatırlatıyorsa, tesadüf değil; extend, ana use case'i değiştirmeden genişletmenin requirement seviyesindeki adıdır.

Diyagram Tek Başına Az Şey Söyler

Diyagrama tekrar bak ve şu soruları cevaplamaya çalış: bakiye yetersizse ne olur? Çakışan bir talep varsa? Yönetici tanımlı değilse? Talep gönderildikten sonra kim, neyi garanti ediyor? Diyagram bunların hiçbirini söylemiyor. Use case'in asıl içeriği metindir; diyagram yalnızca içindekiler sayfasıdır. Use case kavramını 1980'lerin sonunda ortaya koyan Ivar Jacobson da, sonradan onu en iyi anlatan kitabı yazan Alistair Cockburn da bunu vurgular.

Cockburn'ün 2000 tarihli "Writing Effective Use Cases" kitabı, use case metnini üç ayrıntı seviyesinde yazmayı önerir: brief (tek paragraf özet), casual (birkaç paragraf, ana akış ve önemli sapmalar) ve fully dressed (bütün alanları doldurulmuş şablon). Her use case'i fully dressed yazmak gerekmez; yüksek riskli, birden fazla ekibi ilgilendiren ya da para veya yasal yükümlülük taşıyan use case'ler için bu emeğe değer. İzin talebi bakiye, bordro ve mevzuata dokunduğu için o grupta.

Cockburn ayrıca hedefleri üç seviyeye ayırır ve bunları deniz metaforuyla anlatır. Summary seviyesi (bulutlar) birden fazla oturuma yayılan büyük hedeflerdir: "çalışanın yıllık izin sürecini yönet". User goal seviyesi (deniz seviyesi) actor'ın bir oturuşta tamamlayıp memnun ayrıldığı hedeftir: "izin talep et". Subfunction seviyesi (deniz altı) bir hedefin parçasıdır: "bakiyeyi kontrol et". Diyagramdaki use case'lerin çoğu deniz seviyesinde olmalı; include ile ayırdığımız "Bakiyeyi Kontrol Et" bilinçli olarak bir subfunction.

"İzin Talep Et" Spesifikasyonu

Cockburn'ün fully dressed şablonunun alanlarıyla UC-01'i yazalım (UC, use case'in kısaltması; numaraları önceki listedeki sırayla verdik). Önce başlık alanları:

Precondition ile minimal guarantee arasındaki farka dikkat et. Precondition, sistemin kontrol etmeyeceği, doğru olduğunu varsayacağı şeydir; use case bunun doğru olduğunu kabul ederek başlar. Minimal guarantee ise use case başarısız bitse bile sistemin söz verdiği şeydir. "Bakiye değişmez" cümlesi, ileride bir transaction sınırına ya da bir unit test'e dönüşecek bir sözdür.

Ana başarı senaryosu (main success scenario) her şeyin yolunda gittiği tek bir akıştır ve numaralı adımlarla yazılır:

1. Çalışan izin türünü, başlangıç ve bitiş tarihini ve isteğe bağlı açıklamayı girer.

2. Sistem tarihleri doğrular ve talebi taslak olarak kaydeder.

3. Çalışan talebi gönderir.

4. Sistem hafta sonlarını ve resmi tatilleri hariç tutarak iş günü sayısını hesaplar.

5. Sistem bakiyeyi kontrol eder (Bakiyeyi Kontrol Et dahil edilir).

6. Sistem aynı tarihlerle çakışan aktif bir talep olmadığını doğrular.

7. Sistem talebi yönetici onayına alır ve yöneticiye bildirim gönderir.

Extensions bölümü ana akıştan sapmaları, bağlı oldukları adımın numarası ve bir harfle yazar. Yıldız, "herhangi bir adımda" demektir:

1a. İzin türü Hastalık İzni: "Belge eki" extension point'inde Rapor Ekle devreye girer, sonra 2. adıma dönülür.

2a. Bitiş tarihi başlangıçtan önce: sistem hatayı gösterir, çalışan 1. adıma döner.

4a. Aralıkta hiç iş günü yok: sistem talebi göndermez, use case başarısız biter.

5a. Yıllık izinde kalan bakiye yetersiz: sistem kalan ve istenen gün sayısını gösterir; çalışan tarihleri değiştirir (1. adım) ya da vazgeçer.

6a. Çakışan aktif talep var: sistem çakışan talebi gösterir, use case başarısız biter.

*a. Çalışan herhangi bir adımda vazgeçer: girilen bilgiler taslak olarak kalır.

Bu listeyi yazmak, diyagramı çizmekten çok daha fazla soru doğurur. 4a'yı yazarken "yalnızca resmi tatile denk gelen bir talep anlamlı mı?" diye sorduk; 6a'yı yazarken R4'ün "aktif" kelimesinin taslakları kapsayıp kapsamadığını İK'ya sorduk (kapsamıyor). Extensions bölümü, test senaryolarının da en zengin kaynağıdır: her satır en az bir test demek.

Use Case'ten User Story'ye ve API Endpoint'ine

Use case ile user story rakip değil, farklı ayrıntı seviyeleridir. User story, Connextra ekibinin yaygınlaştırdığı "As a ... I want ... so that ..." kalıbıyla, bir hedefi tek cümlede ve bir sohbetin başlangıcı olarak ifade eder. Use case ise o sohbetin sonunda varılan anlaşmanın yazılı hâlidir. User story yazmanın kendisi ilerideki Requirements Analysis serisinin konusu; burada eşlemeye bakıyoruz:

Tablodan iki ders çıkıyor. Birincisi, use case ile endpoint arasında birebir eşleme yok: UC-01 iki endpoint'e bölündü, çünkü taslak kaydetmek (1–2. adımlar) ile göndermek (3–7. adımlar) farklı anlarda olan iki istek. İkincisi, include edilen subfunction'ın kendi endpoint'i olmayabilir; o bir use case'in içinde çağrılan bir davranış. Kısaltılmış bir Minimal API (Application Programming Interface) ile UC-01'in iki ucu şöyle görünüyor:

using System.Collections.Concurrent;
using System.Text.Json.Serialization;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.ConfigureHttpJsonOptions(o => o.SerializerOptions.Converters.Add(new JsonStringEnumConverter()));
WebApplication app = builder.Build();

ConcurrentDictionary<int, LeaveRequest> requests = new();
Dictionary<int, int> remainingAnnualDays = new() { [1001] = 8 };
int nextId = 41;

RouteGroupBuilder leave = app.MapGroup("/leave-requests");

// UC-01 İzin Talep Et, adım 1-2: çalışan formu doldurur, sistem taslağı kaydeder
leave.MapPost("/", (CreateLeaveRequest body) =>
{
    LeaveRequest request = new(Interlocked.Increment(ref nextId), body.EmployeeId, body.LeaveTypeCode, body.Start, body.End);
    requests[request.Id] = request;
    return TypedResults.Created($"/leave-requests/{request.Id}", request);
});

// UC-01 adım 3-7: gönder; adım 5 <<include>> Bakiyeyi Kontrol Et; uzantı 5a bakiye yetersiz
leave.MapPost("/{id:int}/submit", IResult (int id) =>
{
    if (!requests.TryGetValue(id, out LeaveRequest? request))
        return TypedResults.NotFound();

    int workingDays = WorkingDays.Count(request.Start, request.End);
    int remaining = remainingAnnualDays.GetValueOrDefault(request.EmployeeId);
    if (request.LeaveTypeCode == "ANNUAL" && remaining < workingDays)
        return TypedResults.Problem(
            title: "Insufficient leave balance",
            detail: $"Requested {workingDays} working days, remaining balance is {remaining}.",
            statusCode: StatusCodes.Status409Conflict);

    LeaveRequest submitted = request with { WorkingDays = workingDays, Status = LeaveStatus.PendingManagerApproval };
    requests[id] = submitted;
    return TypedResults.Ok(submitted);
});

app.Run();

public sealed record CreateLeaveRequest(int EmployeeId, string LeaveTypeCode, DateOnly Start, DateOnly End);

public sealed record LeaveRequest(int Id, int EmployeeId, string LeaveTypeCode, DateOnly Start, DateOnly End)
{
    public int WorkingDays { get; init; }
    public LeaveStatus Status { get; init; } = LeaveStatus.Draft;
}

public enum LeaveStatus { Draft, PendingManagerApproval, PendingDirectorApproval, Approved, Rejected, Cancelled }

public static class WorkingDays
{
    public static int Count(DateOnly start, DateOnly end)
    {
        int count = 0;
        for (DateOnly day = start; day <= end; day = day.AddDays(1))
        {
            if (day.DayOfWeek is not (DayOfWeek.Saturday or DayOfWeek.Sunday))
                count++;
        }
        return count;
    }
}

Uygulamayı çalıştırıp Ada'nın iki talebini gönderdim. İlki 21–25 Aralık (5 iş günü), ikincisi 14–25 Aralık (10 iş günü); Ada'nın kalan bakiyesi 8:

curl -s -X POST http://127.0.0.1:5731/leave-requests -H 'Content-Type: application/json' -d '{"employeeId":1001,"leaveTypeCode":"ANNUAL","start":"2026-12-21","end":"2026-12-25"}'
{"id":42,"employeeId":1001,"leaveTypeCode":"ANNUAL","start":"2026-12-21","end":"2026-12-25","workingDays":0,"status":"Draft"}

curl -s -X POST http://127.0.0.1:5731/leave-requests/42/submit
{"id":42,"employeeId":1001,"leaveTypeCode":"ANNUAL","start":"2026-12-21","end":"2026-12-25","workingDays":5,"status":"PendingManagerApproval"}

curl -s -i -X POST http://127.0.0.1:5731/leave-requests/43/submit
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{"type":"https://tools.ietf.org/html/rfc9110#section-15.5.10","title":"Insufficient leave balance","status":409,"detail":"Requested 10 working days, remaining balance is 8."}

Son yanıtın başlıklarından yalnızca ikisini bıraktım. Spesifikasyondaki 5a uzantısı burada bir 409 Conflict ve ProblemDetails gövdesi olarak karşılık buldu; minimal guarantee'deki "girilen bilgiler taslak olarak kalır" sözü de tutuldu, çünkü 43 numaralı talep Draft olarak duruyor. Kısa tutmak için resmi tatilleri, 6. adımdaki çakışma kontrolünü ve kimlik doğrulamayı (authentication) bu örneğe koymadım; ASP.NET Core Web API serisinin "Status Code ve Response" ve "Minimal API" yazıları bu parçaların ayrıntısını anlatıyor. Asıl gösterilmek istenen şu: her endpoint'in üstündeki yorum, onu hangi use case adımının doğurduğunu söylüyor. Bir endpoint'in hangi requirement'tan geldiğini bilmek, bir yıl sonra onu değiştirirken en çok ihtiyaç duyacağın bilgi.

Diagrams-as-Code: Mermaid ile Aynı Diyagram

Figürdeki diyagramı elle çizdim. Aynı modeli metin olarak tutmak istersen Mermaid'in use case desteği var, ama 12.x sürümünde hâlâ beta (usecase-beta başlığıyla) ve söz dizimi geriye uyumsuz biçimde değişebilir. Aşağıdaki kaynağı yerelde kurduğum Mermaid CLI (Command Line Interface) 12.2.0 ile render ettim:

usecase-beta
direction LR
actor Employee("Employee")
actor HrSpecialist("HR Specialist")
actor Manager("Manager")
actor Director("Director")
actor Calendar("Calendar System")
systemBoundary leave["HR Portal - Leave Module"]
  RequestLeave("Request Leave")
  Decide("Decide on Leave Request")
  Cancel("Cancel Leave Request")
  ViewBalance("View Leave Balance")
  AdjustBalance("Adjust Leave Balance")
  ManagePolicies("Manage Leave Policies")
  CheckBalance("Check Balance")
  AttachReport("Attach Medical Report")
end
Director --|> Manager
Employee -- RequestLeave
Employee -- Cancel
Employee -- ViewBalance
Manager -- Decide
HrSpecialist -- Cancel
HrSpecialist -- AdjustBalance
HrSpecialist -- ManagePolicies
Decide -- Calendar
Cancel -- Calendar
RequestLeave ..> : include CheckBalance
Decide ..> : include CheckBalance
AttachReport ..> : extend RequestLeave
note for AttachReport "condition: leave type = SICK"

Render çıktısı doğru ilişkileri ve «include», «extend» etiketlerini gösteriyor, ama iki notasyon sapması var: include ve extend çizgilerinin uçları UML'in istediği açık ok başı yerine dolu üçgen olarak çiziliyor, ve extension point'ler elipsin içinde ayrı bölme olarak gösterilemiyor; koşulu ancak use case'e bağlı bir notla yazabildim. Sketch için yeterli, notasyonun kendisini öğretmek için değil. PlantUML'in use case desteği daha olgun, ama Java gerektiriyor; diagrams-as-code araçlarını serinin sonundaki iki yazıda karşılaştıracağız.

Sık Düşülen Tuzaklar

Use case'i menü ağacı gibi çizmek. "İzin İşlemleri"nin altına "Talep Formunu Aç", "Tarih Seç", "Kaydet" gibi use case'ler dizip hepsini include ile bağlamak, ekranların fonksiyonel ayrıştırmasıdır. Ortaya çıkan diyagram ne actor'ın hedefini söyler ne de ekrandan bağımsızdır. Bir use case'in adını okuyunca "bu bitince actor ne kazandı?" sorusunun cevabı yoksa, o bir adımdır.

Her adımı include ile ayırmak. Include, birden fazla use case'in paylaştığı zorunlu bir davranış için vardır. Tek bir use case'in adımlarını include'la küçük elipslere bölmek, spesifikasyonda numaralı bir satır olması gereken şeyi diyagrama taşır.

Extend okunu ters çizmek. En sık görülen notasyon hatası budur: ok, ana use case'ten genişletene doğru çizilir. Doğrusu genişletenden ana use case'e. "Kim kimi biliyor?" diye sor: genişleten, ana use case'i ve onun extension point'ini bilir; tersi doğru değildir.

Actor'ı unvanla ya da kişiyle karıştırmak. "Ahmet Bey" ya da "İK Müdürü" bir actor değildir; actor, sistemle etkileşimdeki rolü adlandırır. Aynı kişi birden fazla rol oynayabilir ve aynı rolü birçok kişi oynayabilir.

"Yönet" ile biten dev use case'ler. "Talepleri Yönet" gibi bir use case aslında oluşturma, güncelleme, iptal ve listeleme gibi birkaç farklı hedefi saklar ve spesifikasyonu yazılamaz. Biz "İzin Kurallarını Yönet"i bilinçli olarak tek bıraktık, çünkü İK için bu bir bakım işi ve ayrıntısı iş birimini ilgilendirmiyor. Bir use case'i ancak bu tür bilinçli bir kararla CRUD (Create, Read, Update, Delete) paketi olarak bırak.

Diyagramla yetinmek. Spesifikasyonu yazılmamış bir use case diagram'ı, başlıkları olan ama sayfaları boş bir kitap gibidir. En azından kritik use case'lerin extensions bölümünü yaz; asıl iş kuralları oradadır.

Küçük Bir Deneme

★☆☆ UC-03 Talebi İptal Et için brief seviyesinde, tek paragraflık bir use case metni yaz. R11'deki üç durumu (onay bekleyen, onaylanmış ve başlamamış, başlamış) nasıl ifade ettin?

★★☆ UC-02 Talebi Karara Bağla'yı fully dressed şablonla yaz. Direktör onayını ana akışta mı, extension olarak mı yazdın? Gerekçesiz red ve onaycının 2 iş günü içinde karar vermemesi (R10) hangi extension satırları oldu?

★★★ Örnek API'ye 6. adımı ekle: aynı çalışanın, iptal ya da reddedilmemiş ve tarihleri çakışan bir talebi varsa submit 409 dönsün. Önce 6a uzantısını tekrar oku ve "taslaklar aktif sayılmaz" kararını koda nasıl yansıttığını bir yorum satırıyla belirt; sonra iki çakışan talep gönderip çıktıyı kontrol et.

Sonraki yazıda sistemin içine giriyoruz: class diagram. Class kutusunun üç bölmesi, attribute ve operation söz dizimi, visibility işaretleri, multiplicity ve stereotype'lar; her birinin C# karşılığıyla birlikte.