Yazılım geliştirmede hata yönetimi kritik bir konudur. Geleneksel olarak, özellikle C# gibi dillerde, hata durumlarını belirtmek için istisnalar (exceptions) kullanılır. Ancak istisnalar, beklenmedik ve programın akışını bozan istisnai durumlar için tasarlanmıştır. "Kullanıcı bulunamadı", "E-posta zaten kayıtlı" veya "Stok yetersiz" gibi durumlar, uygulamanın normal işleyişi içinde öngörülebilen ve beklenen başarısızlık senaryolarıdır.

Bu tür beklenen hataları istisnalarla yönetmek birkaç soruna yol açar:

1. Performans Maliyeti: İstisna fırlatmak ve yakalamak (try-catch), normal kod akışına göre oldukça maliyetli bir operasyondur.

2. Anlamsal Kargaşa: Kodun okunabilirliğini düşürür ve "hangi metodun ne tür bir beklenen hata fırlatabileceği" bilgisini metodun imzasından gizler.

3. Kontrol Akışı Anti-Pattern'i: İstisnaları bir goto gibi kontrol akışı için kullanmak, kodun takibini zorlaştırır.

Result Pattern, bu sorunlara zarif bir çözüm sunar. Bir metodun sonucunu, başarı durumunda bir değer (value) ya da başarısızlık durumunda bir hata (error) içerebilen tek bir nesne içinde döndürmemizi sağlar.

Bu rehberde, ProblemDetails (RFC 7807) standardını kullanarak hem API'ler için tutarlı hem de servis katmanında esnek bir desen oluşturacağız.

Bölüm 1: Mimarinin Temel Taşları

Desenimizi oluşturacak temel sınıfları ve yardımcı yapıları adım adım inşa edelim.

1.1. ProblemDetails ve Standart Hata Fabrikası (Errors Sınıfı)

Hata nesnelerimizi standart hale getirmek için ASP.NET Core'un yerleşik ProblemDetails sınıfını kullanacağız. Bu, API'lerimizin RFC 7807 standardına uygun, tutarlı ve makine tarafından okunabilir hatalar üretmesini sağlar.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

public static class Errors
{
    // 404 Not Found
    public static ProblemDetails NotFound(string title, string detail) =>
        new()
        {
            Status = StatusCodes.Status404NotFound,
            Type = "https://tools.ietf.org/html/rfc7231#section-6.5.4",
            Title = title,
            Detail = detail
        };

    // 400 Bad Request (özellikle validasyon hataları için)
    public static ProblemDetails BadRequest(string title, string detail, IReadOnlyDictionary<string, string[]>? validationErrors = null)
    {
        var problemDetails = new ProblemDetails
        {
            Status = StatusCodes.Status400BadRequest,
            Type = "https://tools.ietf.org/html/rfc7231#section-6.5.1",
            Title = title,
            Detail = detail,
        };

        if (validationErrors is not null)
        {
            problemDetails.Extensions.Add("validationErrors", validationErrors);
        }

        return problemDetails;
    }

    // 409 Conflict
    public static ProblemDetails Conflict(string title, string detail) =>
        new()
        {
            Status = StatusCodes.Status409Conflict,
            Type = "https://tools.ietf.org/html/rfc7231#section-6.5.8",
            Title = title,
            Detail = detail
        };
}

1.2. Değer Döndürmeyen Sonuç: Result Sınıfı

void metotlar (örn: Update, Delete) için operasyonun sadece başarılı veya başarısız olduğunu bildiren temel sınıftır.

public class Result
{
    public bool IsSuccess { get; }
    public bool IsFailure => !IsSuccess;
    public ProblemDetails? Error { get; }

    protected Result(bool isSuccess, ProblemDetails? error)
    {
        if (isSuccess && error is not null || !isSuccess && error is null)
        {
            throw new InvalidOperationException("Invalid result state.");
        }
        IsSuccess = isSuccess;
        Error = error;
    }

    public static Result Success() => new(true, null);
    public static Result Failure(ProblemDetails error) => new(false, error);
    public static implicit operator Result(ProblemDetails error) => Failure(error);
}

1.3. Değer Döndüren Sonuç: Result<TValue> Sınıfı

Başarılı olduğunda bir değer taşıyan generic versiyondur.

public class Result<TValue> : Result
{
    private readonly TValue? _value;

    public TValue Value => IsSuccess
        ? _value!
        : throw new InvalidOperationException("Cannot access the value of a failed result.");

    private Result(TValue value) : base(true, null) => _value = value;
    private Result(ProblemDetails error) : base(false, error) => _value = default;

    public static Result<TValue> Success(TValue value) => new(value);
    public new static Result<TValue> Failure(ProblemDetails error) => new(error);

    // Implicit operator'ler sayesinde kod daha akıcı hale gelir.
    public static implicit operator Result<TValue>(TValue value) => Success(value);
    public static implicit operator Result<TValue>(ProblemDetails error) => Failure(error);

    // Sonucu fonksiyonel bir şekilde işlemek için Match metodu
    public TResponse Match<TResponse>(
        Func<TValue, TResponse> onSuccess,
        Func<ProblemDetails, TResponse> onFailure) =>
        IsSuccess ? onSuccess(Value) : onFailure(Error!);
}

Bölüm 2: Kullanım Senaryoları

Şimdi bu yapıları gerçekçi bir servis katmanı senaryosunda kullanalım.

2.1. Servis Arayüzü ve Modeller

public record Product(Guid Id, string Name, decimal Price, int Stock);
public record CreateProductRequest(string Name, decimal Price, int Stock);
public record UpdatePriceRequest(Guid Id, decimal NewPrice);

public interface IProductService
{
    Result<Product> GetById(Guid id);
    Result<Product> Create(CreateProductRequest request);
    Result UpdatePrice(UpdatePriceRequest request);
    Result Delete(Guid id);
}

2.2. ProductService Implementasyonu

public class ProductService : IProductService
{
    private static readonly List<Product> _products = [];

    public Result<Product> GetById(Guid id)
    {
        var product = _products.FirstOrDefault(p => p.Id == id);
        return product is not null
            ? product // Implicit conversion to Result<Product>.Success
            : Errors.NotFound("Product Not Found", $"Product with ID '{id}' was not found.");
    }

    public Result<Product> Create(CreateProductRequest request)
    {
        // 1. Validasyon
        var validationErrors = new Dictionary<string, string[]>();
        if (string.IsNullOrWhiteSpace(request.Name))
        {
            validationErrors.Add(nameof(request.Name), ["Product name cannot be empty."]);
        }
        if (request.Price <= 0)
        {
            validationErrors.Add(nameof(request.Price), ["Price must be positive."]);
        }
        if (validationErrors.Count > 0)
        {
            return Errors.BadRequest(
                "Validation Failed", 
                "One or more validation errors occurred.", 
                validationErrors);
        }

        // 2. İş Kuralı Kontrolü
        if (_products.Any(p => p.Name.Equals(request.Name, StringComparison.OrdinalIgnoreCase)))
        {
            return Errors.Conflict("Duplicate Product", $"A product with the name '{request.Name}' already exists.");
        }

        // 3. Başarılı Durum
        var newProduct = new Product(Guid.NewGuid(), request.Name, request.Price, request.Stock);
        _products.Add(newProduct);

        return newProduct;
    }

    public Result UpdatePrice(UpdatePriceRequest request)
    {
        // 1. Varlık kontrolü
        Result<Product> getResult = GetById(request.Id);
        if (getResult.IsFailure)
        {
            return getResult.Error!; // Varlık bulunamadı hatasını aynen geri döndür.
        }

        // 2. Validasyon
        if (request.NewPrice <= 0)
        {
            return Errors.BadRequest("Invalid Price", "New price must be a positive value.");
        }

        // 3. Başarılı Durum
        var existingProduct = getResult.Value;
        var updatedProduct = existingProduct with { Price = request.NewPrice };

        _products.Remove(existingProduct);
        _products.Add(updatedProduct);

        return Result.Success();
    }

    public Result Delete(Guid id)
    {
        var product = _products.FirstOrDefault(p => p.Id == id);
        if (product is null)
        {
            return Errors.NotFound("Product Not Found", $"Cannot delete. Product with ID '{id}' was not found.");
        }

        _products.Remove(product);
        return Result.Success();
    }
}

Bölüm 3: API Katmanı Entegrasyonu

Servis katmanından dönen Result nesnelerini standart HTTP yanıtlarına çevirelim.

3.1. Yaklaşım 1: Minimal API'ler (Modern ve Hafif)

Result'ı IResult'a dönüştüren bir yardımcı metot ve endpoint tanımları:

// Helper Class
public static class ApiExtensions
{
    public static IResult ToHttpResult<TValue>(this Result<TValue> result) =>
        result.Match(
            onSuccess: value => Results.Ok(value),
            onFailure: problem => Results.Problem(problem)
        );

    // Yeni oluşturulan kaynaklar için 201 Created yanıtı
    public static IResult ToCreatedHttpResult<TValue>(this Result<TValue> result, string location) where TValue : Product =>
        result.Match(
            onSuccess: value => Results.Created($"{location}/{value.Id}", value),
            onFailure: problem => Results.Problem(problem)
        );

    public static IResult ToHttpResult(this Result result)
    {
        if (result.IsFailure) return Results.Problem(result.Error!);
        // Başarılı Update/Delete işlemleri için genellikle 204 No Content döndürülür.
        return Results.NoContent();
    }
}

// Program.cs
// ... (Service registration)
builder.Services.AddScoped<IProductService, ProductService>();
// Route registration
app.MapGet("/products/{id:guid}", ([FromRoute] Guid id,[FromService] IProductService service) => service.GetById(id).ToHttpResult());
app.MapPost("/products", ([FromBody] CreateProductRequest req,[FromService] IProductService service) => service.Create(req).ToCreatedHttpResult("/products"));
app.MapPut("/products/price", ([FromBody] UpdatePriceRequest req,[FromService] IProductService service) => service.UpdatePrice(req).ToHttpResult());
app.MapDelete("/products/{id:guid}", ([FromRoute] Guid id,[FromService] IProductService service) => service.Delete(id).ToHttpResult());

app.Run();

3.2. Yaklaşım 2: MVC Controller'lar (Geleneksel ve Güçlü)

Tüm controller'ların miras alacağı bir ApiControllerBase oluşturarak tekrarı önleyebiliriz.

[ApiController]
public abstract class ApiControllerBase : ControllerBase
{
    protected IActionResult HandleResult<TValue>(Result<TValue> result) =>
        result.IsSuccess
            ? Ok(result.Value)
            : Problem(result.Error!);

    protected IActionResult HandleCreatedResult<TValue>(Result<TValue> result) where TValue : Product =>
        result.IsSuccess
            ? CreatedAtAction(nameof(GetProduct), new { id = result.Value.Id }, result.Value) // GetProduct metoduna referans verir
            : Problem(result.Error!);

    protected IActionResult HandleResult(Result result) =>
        result.IsSuccess
            ? NoContent()
            : Problem(result.Error!);

    // Bu, HandleCreatedResult'ın çalışması için gerekli.
    // Gerçek bir controller'da olması gerekir. Örnek olarak burada.
    [HttpGet("{id:guid}", Name = "GetProduct")]
    public virtual IActionResult GetProduct(Guid id) => throw new NotImplementedException();
}

[Route("api/[controller]")]
public class ProductsController(IProductService productService) : ApiControllerBase
{
    [HttpGet("{id:guid}")]
    public override IActionResult GetProduct(Guid id) =>
        HandleResult(productService.GetById(id));

    [HttpPost]
    public IActionResult CreateProduct(CreateProductRequest request) =>
        HandleCreatedResult(productService.Create(request));

    [HttpPut("price")]
    public IActionResult UpdatePrice(UpdatePriceRequest request) =>
        HandleResult(productService.UpdatePrice(request));

    [HttpDelete("{id:guid}")]
    public IActionResult DeleteProduct(Guid id) =>
        HandleResult(productService.Delete(id));
}

Sonuç ve Tasarımın Avantajları

Bu desen, uygulamanızın hata yönetimi stratejisini kökten iyileştirir:

1. Öngörülebilir Kod: Metot imzaları (Result<T>), bir metodun hem başarılı bir değer hem de bir hata döndürebileceğini açıkça belirtir. Sürpriz istisnalar ortadan kalkar.

2. Temiz Mimariler: Servis katmanı (iş mantığı) sunum katmanından (API) tamamen habersizdir. Sadece operasyonun sonucunu bildirir. API katmanı ise bu sonucu alıp HTTP dünyasına çevirmekle sorumludur. Bu, Clean Architecture ve DDD prensipleriyle mükemmel uyum sağlar.

3. Standart ve Tutarlı API'ler: ProblemDetails kullanımı sayesinde tüm hatalarınız standart bir formatta olur, bu da istemci (frontend, mobil, diğer servisler) geliştirmeyi çok kolaylaştırır.

4. Yüksek Performans: Beklenen hatalar için istisna fırlatma maliyetinden kaçınılır.

5. Geliştirici Dostu: Implicit operator'ler ve yardımcı metotlar, deseni kullanmayı son derece kolay ve akıcı hale getirir. return product; veya return Errors.NotFound(...); gibi ifadelerle kodunuz temiz kalır.

Ek Bölüm: Örnek Proje Mimarisi ve Klasör Yapısı

Bu bölümde, anlattığımız Result Pattern'in ve ilgili sınıfların, modern, test edilebilir ve sürdürülebilir bir .NET projesinde nasıl organize edilebileceğini göreceğiz. Önerilen yapı, katmanların sorumluluklarını net bir şekilde ayıran Clean Architecture (Temiz Mimari) prensiplerini temel almaktadır.

Projenin Genel Klasör Yapısı (ASCII Tree)

/ResultPattern.sln
│
├── 📂 src/
│   │
│   ├── 📁 ResultPattern.Domain/
│   │   └── 📦 Entities/
│   │       └── 📜 Product.cs
│   │
│   ├── 📁 ResultPattern.Application/
│   │   ├── 📦 Abstractions/
│   │   │   └── 📜 IProductService.cs
│   │   ├── 📦 Core/
│   │   │   └── 📜 Result.cs             // Result ve Result<TValue> sınıfları
│   │   ├── 📦 DTOs/
│   │   │   ├── 📜 CreateProductRequest.cs
│   │   │   └── 📜 UpdatePriceRequest.cs
│   │   └── 📦 Services/
│   │       └── 📜 ProductService.cs
│   │
│   ├── 📁 ResultPattern.Infrastructure/
│   │   └── 📦 Persistence/
│   │       └── 📜 AppDbContext.cs       // Örnek: Entity Framework Core context'i
│   │       └── 📦 Repositories/
│   │           └── 📜 ProductRepository.cs  // IProductRepository implementasyonu
│   │
│   └── 📁 ResultPattern.Api/ (Presentation)
│       ├── 📦 Common/
│       │   ├── 📜 ApiExtensions.cs
│       │   └── 📜 Errors.cs             // ProblemDetails üreten fabrika sınıfı
│       ├── 📦 Controllers/
│       │   └── 📜 ProductsController.cs   // MVC yaklaşımı için
│       └── 📜 Program.cs                // Minimal API endpoint'leri ve servis kayıtları
│
└── 📂 tests/
    │
    ├── 📁 ResultPattern.Application.Tests/
    │   └── 📜 ProductServiceTests.cs
    │
    └── 📁 ResultPattern.Domain.Tests/
        └── 📜 ProductTests.cs

Katmanların Açıklamaları ve Sorumlulukları

1. 📖 ResultPattern.Domain

• Amacı: Uygulamanızın kalbidir. İş kurallarını ve varlıkları (entities) içerir. Diğer hiçbir projeye bağımlılığı yoktur; tamamen saf ve bağımsızdır.

• İçerik:

  • Entities/Product.cs: Uygulamanın temel iş nesnesi olan Product kaydı burada yer alır.

2. ⚙️ ResultPattern.Application

• Amacı: Uygulamanın iş mantığını (use case'leri) yönetir. Domain katmanındaki varlıkları kullanarak operasyonları gerçekleştirir. Altyapı (Infrastructure) ve sunum (Api) katmanlarından habersizdir.

• İçerik:

  • Core/Result.cs: Result ve Result<TValue> sınıfları burada bulunur. Çünkü bu yapılar, uygulama katmanındaki servislerin dönüş tipini belirleyen temel bir araçtır.

  • Abstractions/IProductService.cs: Servislerin kontratları (arayüzler) burada tanımlanır.

  • Services/ProductService.cs: IProductService arayüzünün somut implementasyonu. Örnekte statik bir liste kullansak da, gerçek bir projede bu sınıf veritabanı işlemleri için IProductRepository gibi bir arayüze bağımlı olurdu.

  • DTOs/: CreateProductRequest gibi, sunum katmanından uygulama katmanına veri taşımak için kullanılan Veri Transfer Nesneleri (Data Transfer Objects) burada yer alır.

3. 🔌 ResultPattern.Infrastructure

• Amacı: Veritabanları, harici servisler, dosya sistemleri gibi dış dünyayla ilgili tüm detayları içerir. Application katmanında tanımlanan arayüzleri uygular.

• İçerik:

  • Persistence/: Entity Framework Core, Dapper veya başka bir ORM ile ilgili tüm kodlar burada bulunur. AppDbContext ve repository implementasyonları bu katmanın parçasıdır.

4. 💻 ResultPattern.Api (Sunum Katmanı)

• Amacı: Dış dünyadan gelen istekleri (örn: HTTP istekleri) kabul edip uygulama katmanına yönlendiren ve uygulama katmanından dönen sonuçları dış dünyaya uygun bir formatta (örn: JSON yanıtı) sunan katmandır.

• İçerik:

  • Program.cs: Minimal API endpoint'lerinin tanımlandığı, servislerin (DI) kaydedildiği ve uygulamanın konfigürasyonunun yapıldığı yerdir.

  • Common/ApiExtensions.cs: Result<T> nesnesini IResult'a (HTTP yanıtına) dönüştüren ToHttpResult gibi extension metotları içerir. Bu, tamamen sunum katmanına ait bir sorumluluktur.

  • Common/Errors.cs: ProblemDetails nesneleri üreten ve HTTP durum kodlarına sıkıca bağlı olan Errors sınıfı için en uygun yer burasıdır.

  • Controllers/ProductsController.cs: Eğer Minimal API yerine MVC yaklaşımını tercih ediyorsanız, controller'larınız bu klasörde yer alır.

Proje Referansları (Dependency Flow)

Bu mimarideki en önemli kural, bağımlılıkların her zaman merkeze doğru olmasıdır.

Api ➡️ Application ➡️ Domain

• Api projesi, Application projesine referans verir.

• Infrastructure projesi, Application projesine referans verir.

• Application projesi, Domain projesine referans verir.

• Domain projesi hiçbir projeye referans vermez.

Bu yapı, Result Pattern'in "sorumlulukları ayırma" felsefesini proje geneline yayarak esnek, test edilebilir ve bakımı kolay bir uygulama geliştirmenizi sağlar.

Cevap, .NET'in bize sunduğu zarif bir desende gizli: Options Pattern.

Bu yazıda, .NET 9'da Options Pattern'i sıfırdan ele alacağız. Sadece nasıl çalıştığını değil, aynı zamanda ayarlarımızı daha en başından nasıl doğrulanabilir ve kurşun geçirmez hale getirebileceğimizi bolca örnekle öğreneceğiz. Arkanıza yaslanın, çünkü appsettings.json karmaşasına son veriyoruz!

Neden Options Pattern'e İhtiyacımız Var?

Eski yöntemleri hatırlayalım: Kod içinde sihirli string'ler (configuration["Smtp:Server"]), tip dönüşümüyle uğraşma, test yazmanın zorluğu... Bunların hepsi hem hata yapmaya çok açık hem de kod kalitesini düşüren alışkanlıklardı.

Options Pattern bu sorunları kökünden çözer:

• Güçlü Tip Desteği (Strongly-Typed): String'lerle değil, bildiğiniz C# nesneleriyle (POCO) çalışırsınız.

• Merkezi Yönetim: Ayarlarınız tek bir yerden yönetilir ve uygulamanın her yerine kolayca dağıtılır.

• Test Edilebilirlik: Ayarlarınızı taklit etmek (mock) ve testler yazmak çocuk oyuncağı haline gelir.

• Güvenilirlik: Ayarlarınızı uygulama başlarken doğrulayarak (validate) hataları anında yakalarsınız.

Hadi modern bir .NET projesinde bu deseni nasıl uygulayacağımıza bakalım.

Adım Adım Modern Options Pattern Kullanımı

Senaryomuz basit: Uygulamamızın bir e-posta gönderme özelliği var ve SMTP ayarlarını appsettings.json dosyasından güvenli bir şekilde okumak istiyoruz.

Adım 1: appsettings.json Dosyasını Hazırlama

Her şeyin başladığı yer! Projenizin appsettings.json dosyasına ayarlarımızı ekleyelim.

{
  "Logging": {
    // ...
  },
  "AllowedHosts": "*",
  "SmtpSettings": {
    "Server": "smtp.example.com",
    "Port": 587,
    "Username": "user@example.com",
    "Password": "gizli-bir-sifre",
    "EnableSsl": true
  }
}

Burada SmtpSettings adında, sınıfımızın (class) adıyla aynı olacak şekilde bir bölüm oluşturduk. Bu isimlendirme standardı birazdan çok işimize yarayacak.

Adım 2: Ayar Sınıfını (POCO) ve Kurallarını Tanımlama

Şimdi JSON yapısıyla eşleşen ve doğrulama kurallarını içeren C# sınıfımızı oluşturalım. System.ComponentModel.DataAnnotations kütüphanesinden gelen attribute'ları burada kullanacağız.

// Models/SmtpSettings.cs

using System.ComponentModel.DataAnnotations;

public class SmtpSettings
{
    [Required(ErrorMessage = "SMTP Sunucusu boş olamaz.")]
    public string Server { get; set; }

    [Range(1, 65535, ErrorMessage = "Port numarası 1 ile 65535 arasında olmalıdır.")]
    public int Port { get; set; }

    [Required]
    [EmailAddress]
    public string Username { get; set; }

    [Required]
    [MinLength(6)]
    public string Password { get; set; }

    public bool EnableSsl { get; set; }
}

Gördüğünüz gibi, sadece property'leri tanımlamakla kalmadık, aynı zamanda hangi alanın zorunlu olduğunu, hangisinin bir e-posta formatında olması gerektiğini de belirttik. Kuralları verinin kendisine en yakın yere koymuş olduk.

Adım 3: Servisleri Modern Yöntemle Konfigüre Etme (Program.cs)

İşte sihrin gerçekleştiği yer! .NET'e ayarlarımızı nasıl okuyacağını, bağlayacağını ve en önemlisi nasıl doğrulayacağını tek bir akıcı (fluent) kod bloğuyla söyleyeceğiz.

Projenizin Program.cs dosyasını açın ve aşağıdaki satırları ekleyin:

// Program.cs

var builder = WebApplication.CreateBuilder(args);

// --- Options Pattern Yapılandırması ---
builder.Services.AddOptions<SmtpSettings>()
    .BindConfiguration(nameof(SmtpSettings))
    .ValidateDataAnnotations()
    .ValidateOnStart();
// -------------------------------------------

// Örnek bir servis ekleyelim
builder.Services.AddScoped<IEmailService, EmailService>();

// Kalan servisleriniz...

var app = builder.Build();

// ... (kalan kod)

Bu zincirleme yapı ne anlama geliyor? Tek tek inceleyelim:

• .AddOptions<SmtpSettings>(): Options Pattern sürecini başlatır ve SmtpSettings sınıfı için bir yapılandırma oluşturucu (OptionsBuilder) döndürür.

• .BindConfiguration(nameof(SmtpSettings)): En temiz kısım burası! appsettings.json dosyasında, sınıfın adıyla ("SmtpSettings") eşleşen bölümü bulur ve tüm değerleri otomatik olarak SmtpSettings nesnesine bağlar. nameof() kullandığımız için "string" derdinden kurtuluruz.

• .ValidateDataAnnotations(): .NET'e "Az önce SmtpSettings sınıfında tanımladığım [Required], [Range] gibi kuralları dikkate al!" der.

• .ValidateOnStart(): İşte bu bizim sigortamız! Uygulama başlar başlamaz, ValidateDataAnnotations ile belirtilen kuralları çalıştırır. Eğer ayarlarda herhangi bir kural ihlali varsa (örneğin Port değeri eksikse), uygulama başlamadan çöker ve size sorunun ne olduğunu açıkça söyleyen bir hata fırlatır.

Adım 4: Ayarları Kullanma (Dependency Injection)

Yapılandırmamız artık hazır ve güvenli. Şimdi onu bir serviste kullanalım.

// Services/EmailService.cs

using Microsoft.Extensions.Options;

public interface IEmailService
{
    void SendEmail(string to, string subject, string body);
}

public class EmailService(IOptions<SmtpSettings> smtpSettings) : IEmailService
{
    // Primary constructor'dan gelen parametreyi kullanarak
    // sınıf içinde kullanacağımız private field'ı hemen burada başlatıyoruz.
    private readonly SmtpSettings _settings = smtpSettings.Value;

    public void SendEmail(string to, string subject, string body)
    {
        Console.WriteLine("E-posta gönderiliyor...");
        Console.WriteLine($"Server: {_smtpSettings.Server}:{_smtpSettings.Port}");
        Console.WriteLine($"Kullanıcı: {_smtpSettings.Username}");
        Console.WriteLine($"SSL Aktif: {_smtpSettings.EnableSsl}");
        // Burada e-posta gönderme kodu olacak.
    }
}

Gördüğünüz gibi, ayarları kullanma şeklimiz değişmedi. EmailService, ayarların nasıl okunduğundan veya doğrulandığından tamamen habersiz. O sadece IOptions<SmtpSettings> arayüzü üzerinden ihtiyacı olan geçerli ayarlara ulaşıyor.

Peki Ayarlar Hatalıysa Ne Olur? ValidateOnStart'ın Gücü

Diyelim ki bir geliştirici appsettings.json dosyasından Port satırını sildi. Eğer .ValidateOnStart() kullanmasaydık, uygulamanız başarıyla başlar, ancak SendEmail metodu çağrıldığında _smtpSettings.Port değeri 0 olacağı için çalışma anında (runtime) bir hata alırdınız.

Ancak bizim modern yapılandırmamız sayesinde, uygulamayı başlattığınız anda konsolda şöyle bir hata görürsünüz:

Microsoft.Extensions.Options.OptionsValidationException: DataAnnotation validation failed for 'SmtpSettings' members: 'Port' with the error: 'Port numarası 1 ile 65535 arasında olmalıdır.'.

Bu "fail-fast" (hata anında dur) yaklaşımı, yapılandırma hatalarını anında yakalamanızı sağlayarak sizi production'da yaşanacak büyük sorunlardan kurtarır.

IOptions, IOptionsSnapshot ve IOptionsMonitor

• IOptions<T> (Singleton): Ayarları uygulama başlarken bir kez okur.

• IOptionsSnapshot<T> (Scoped): Her HTTP isteği için ayarları yeniden okur. Web uygulamaları için harikadır.

• IOptionsMonitor<T> (Singleton): appsettings.json dosyasındaki değişiklikleri uygulama çalışırken bile anlık olarak algılar.

Kullanım senaryonuza göre constructor'ınıza bu arayüzlerden uygun olanı enjekte edebilirsiniz.

Özet

.NET ile uygulama geliştirirken, ayarlarınızı yapılandırmak için AddOptions() ile başlayan bu akıcı ve güvenli yöntemi kullanmak en iyi pratiktir. Bu yöntem size şunları sağlar:

• Okunabilirlik: Zincirleme yapı, ayarların nasıl yüklendiğini ve doğrulandığını net bir şekilde anlatır.

• Güvenlik: ValidateOnStart ile hatalı yapılandırmaların uygulamanızı başlatmasını engellersiniz.

• Bakım Kolaylığı: nameof() kullanımı, "sihirli string" kaynaklı hataların önüne geçer.

Artık ayarlarınızı yönetirken endişelenmenize gerek yok. Bu modern yaklaşımı benimseyin ve daha sağlam, güvenilir ve bakımı kolay uygulamalar geliştirin.

🔧 Neyi Çözüyoruz?

• Sunucu-taraflı render: SEO dostu, hızlı ilk yükleme, sade mimari.

• XSS koruması: html/template otomatik escape ile “yanlışlıkla XSS” şovunu bitiriyor.

• Parça/kalıp: Layout + partial düzeniyle kopyala-yapıştır çilesi yok.

• Tailwind ile hız: Component kütüphanesine boğulmadan temiz UI.

🧠 Temel Kavramlar

• text/template vs html/template

  Go'da iki farklı template paketi var. text/template metin çıktıları için, html/template ise HTML çıktıları için kullanılır. HTML'de XSS koruması sağladığı için web projelerinde her zaman html/template tercih edilir.

• define / block

  Template miras yapısını kurmak için kullanılır. define ile bir şablon bloğu tanımlanır, block ile bu blok başka bir dosyada override edilebilir. Örneğin base.html içinde {{block "content" .}}...{{end}} varsa, home.html bu bloğu doldurur. Böylece base → sayfa ilişkisi kurulur.

• template

  Başka bir template dosyasını çağırmak için kullanılır. Genellikle partial (parça) dosyaları çağırmak için kullanılır: {{template "partials/nav" .}}. Bu sayede tekrar eden yapılar (örn. navigasyon) tek bir yerde tanımlanır.

• FuncMap

  Template içinde özel fonksiyonlar tanımlamak için kullanılır. Örneğin upper, truncate, fmtDate gibi fonksiyonlarla veriyi biçimlendirebilirsin. Go tarafında template.FuncMap ile tanımlanır ve Parse* öncesinde şablona eklenir.

• Otomatik Escape (auto-escape)

  html/template kullanıcıdan gelen verileri otomatik olarak encode eder. Örneğin <script> gibi zararlı içerikler HTML olarak değil, düz metin olarak basılır. Bu sayede XSS saldırılarına karşı koruma sağlanır. Ancak template.HTML ile escape’i devre dışı bırakmak mümkündür — dikkatli kullanılmalıdır.

Basit örnek:

type PageData struct{ Title, User string }

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
  tpl := template.Must(template.ParseFiles("views/home.html"))
  _ = tpl.Execute(w, PageData{Title: "Anasayfa", User: "Uygar"})
})

views/home.html:

<!doctype html>
<html>
<head><title>{{.Title}}</title></head>
<body><h1>Merhaba {{.User}}</h1></body>
</html>

🗂 Proje Yapısı ve Başlangıç

Hızlı bir iskelet:

/cmd/server/main.go
/internal/http/router.go
/views
  /layouts/base.html
  /partials/nav.html
  /pages/home.html
/assets/tailwind.css
/public/app.css (build çıkışı)

🏗 Layout & Partial Sistemi

views/layouts/base.html

{{define "base"}}
<!DOCTYPE html>
<html lang="tr">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>{{block "title" .}}Varsayılan Başlık{{end}}</title>
    <link rel="stylesheet" href="/app.css" />
  </head>
  <body class="bg-neutral-50 text-neutral-900">
    {{template "partials/nav" .}}
    <main class="container mx-auto max-w-4xl px-4 py-8">
      {{block "content" .}}{{end}}
    </main>
    <footer class="py-8 text-center text-sm text-neutral-500">
      © {{.Year}} MyBlog
    </footer>
  </body>
</html>
{{end}}

views/partials/nav.html

{{define "partials/nav"}}
<header class="border-b bg-white/80 backdrop-blur">
  <div
    class="container mx-auto max-w-4xl px-4 h-14 flex items-center justify-between"
  >
    <a href="/" class="font-semibold">uygarceylan.net</a>
    <nav class="flex gap-4 text-sm">
      <a class="hover:underline" href="/">Ana Sayfa</a>
      <a class="hover:underline" href="/posts">Bloglar</a>
    </nav>
  </div>
</header>
{{end}}

views/pages/home.html

{{define "content"}}
<section class="space-y-6">
  <h1 class="text-3xl font-bold">Merhaba {{.User}}</h1>
  <p class="text-neutral-600">
    Bu blog Go <code>html/template</code> ile render ediliyor.
  </p>
  <div class="rounded-lg border border-amber-200 bg-amber-50 p-4">
    <strong class="block mb-1">İpucu:</strong>
    Layout + partial ile tekrar eden HTML’i çöpe at.
  </div>
</section>
{{end}}

Küçük ama kritik: Sayfa dosyası sadece content block’larını tanımlar; base her şeyi çerçeveler.

🧰 FuncMap ile Helper’lar

Go tarafında:

import (
  "html/template"
  "strings"
  "time"
)

func newTemplates() *template.Template {
  return template.Must(template.New("").Funcs(template.FuncMap{
    "upper": strings.ToUpper,
    "truncate": func(s string, n int) string {
      if len(s) <= n { return s }
      return s[:n] + "…"
    },
    "fmtDate": func(t time.Time) string {
      return t.Format("02 Jan 2006")
    },
  }).ParseGlob("views/**/*.html"))
}

Kullanımı (örnek):

<h2 class="text-xl">{{upper .Title}}</h2>
<p class="text-sm text-neutral-500">{{fmtDate .PublishedAt}}</p>
<p>{{truncate .Excerpt 120}}</p>

Diğer bölümlerde burayı kodumuza entegre edeceğiz

🎨 TailwindCSS Entegrasyonu

Kurulum (Node gerektirir):

yarn add -D tailwindcss@3 postcss autoprefixer
npx tailwindcss init -p

tailwind.config.js

module.exports = {
  content: ["./views/**/*.html", "./assets/**/*.js"],
  theme: { extend: {} },
  plugins: []
}

/assets/tailwind.css

@tailwind base;
@tailwind components;
@tailwind utilities;

.container { @apply mx-auto px-4; }
.btn { @apply inline-flex items-center gap-2 rounded-md px-3 py-2 text-sm font-medium border bg-white hover:bg-neutral-50; }
.input { @apply w-full rounded-md border px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-neutral-900/10; }
.card { @apply rounded-lg border bg-white p-4 shadow-sm; }

Geliştirme build:

npx tailwindcss -i ./assets/tailwind.css -o ./public/app.css --watch

Prod build (minify):

npx tailwindcss -i ./assets/tailwind.css -o ./public/app.css --minify

🧪 Örnek Sayfa: “Blog Listesi”

Go (veri + render)

internal/http/router.go

type Post struct {
    ID             int
    Title          string
    Excerpt        string
    ExcerptShort   string
    PublishedAt    time.Time
    PublishedAtStr string
}

type Router struct {
    // render, HTTP yanıtını yöneten ve HTML şablonunu işleyen fonksiyondur.
    // Bu fonksiyon, bir HTTP yanıt yazıcısı (ResponseWriter), bir şablon adı ve veriyi bekler.
    render func(http.ResponseWriter, string, any)
}

func New(render func(http.ResponseWriter, string, any)) http.Handler {
    r := &Router{render: render}
    mux := chi.NewRouter()

    // Ana sayfa ve blog listesi için GET isteklerini dinler.
    mux.Get("/home", r.Home)
    mux.Get("/posts", r.PostList)

    return mux
}

// Home fonksiyonu, ana sayfa için gerekli veriyi hazırlar ve render fonksiyonuna gönderir.
func (r *Router) Home(w http.ResponseWriter, _ *http.Request) {
    // Şablona gönderilecek veriyi bir map içinde topluyoruz.
    data := map[string]any{
        "Title": "Anasayfa",
        "User":  "Onur",
        "Year":  time.Now().Year(),
    }
    // "home" adlı şablonu (views/pages/home.html) bu veriyle işliyor ve yanıt olarak gönderiyoruz.
    r.render(w, "home", data)
}

// PostList fonksiyonu, blog yazıları listesi için veriyi hazırlar.
func (r *Router) PostList(w http.ResponseWriter, _ *http.Request) {
    // Örnek blog yazıları oluşturup bir slice içine ekliyoruz.
    posts := []Post{
        {
            ID:             1,
            Title:          "Go Templates ile Başlarken",
            Excerpt:        "Template mimarisi, base ve partial pratikleri…",
            ExcerptShort:   "Template mimarisi, base ve partial pratikleri…",
            PublishedAt:    time.Now().AddDate(0, 0, -2),
            PublishedAtStr: time.Now().AddDate(0, 0, -2).Format("02 Jan 2006"),
        },
        {
            ID:             2,
            Title:          "HTMX’a Giriş",
            Excerpt:        "Partial render ve progressive enhancement…",
            ExcerptShort:   "Partial render ve progressive enhancement…",
            PublishedAt:    time.Now().AddDate(0, 0, -1),
            PublishedAtStr: time.Now().AddDate(0, 0, -1).Format("02 Jan 2006"),
        },
    }

    // Şablona gönderilecek veriyi hazırlıyoruz.
    data := map[string]any{
        "Title": "Yazılar",
        "Year":  time.Now().Year(),
        "Posts": posts,
    }

    // "posts" adlı şablonu (views/pages/posts.html) bu veriyle işliyoruz.
    r.render(w, "posts", data)
}

views/pages/posts.html

{{define "content"}}
<section class="space-y-6">
  <header class="flex items-end justify-between">
    <h1 class="text-3xl font-bold">{{.Title}}</h1>
    <div class="w-64">
      <input class="input" placeholder="Ara (dummy — HTMX sonraki yazıda)" />
    </div>
  </header>

  <ul class="grid gap-4 md:grid-cols-2">
    {{range .Posts}}
    <li class="card">
      <a class="block group" href="/posts/{{.ID}}">
        <div class="flex items-center justify-between">
          <h2 class="text-lg font-semibold group-hover:underline">
            {{.Title}}
          </h2>
          <span class="text-xs text-neutral-500">{{.PublishedAtStr}}</span>
        </div>
        <p class="mt-2 text-sm text-neutral-600">{{.ExcerptShort}}</p>
        <div class="mt-4">
          <span class="btn text-neutral-700">Oku</span>
        </div>
      </a>
    </li>
    {{else}}
    <li class="card">
      <p class="italic text-neutral-600">Henüz yazı yok.</p>
    </li>
    {{end}}
  </ul>

  <div class="rounded-lg border border-blue-200 bg-blue-50 p-4">
    <strong class="block mb-1">Sonraki adım:</strong>
    Bu listeyi HTMX ile <em>partial</em> olarak yeniler hale getireceğiz.
  </div>
</section>
{{end}}

cmd/server/main.go

func render(w http.ResponseWriter, name string, data any) {

    // template.ParseFiles fonksiyonu, tüm şablon dosyalarını tek tek okuyup ayrıştırır.
    // Bu örnekte, her istekte şablonlar yeniden okunup ayrıştırılıyor.
    // Production ortamında bu işlemi sadece uygulama başlangıcında yapmak daha performanslıdır.
    tpl := template.Must(template.ParseFiles(
        "views/layouts/base.html",
        "views/partials/nav.html",
        "views/pages/"+name+".html",
    ))

    // ExecuteTemplate, ana (base) şablonu çağırır ve diğer şablonları (partial, content) onun içine yerleştirir.
    if err := tpl.ExecuteTemplate(w, "base", data); err != nil {
        // Herhangi bir hata oluşursa, sunucu hatası (500) döndürürüz.
        http.Error(w, err.Error(), 500)
    }
}

func main() {

    mux := http.NewServeMux()
    // /app.css isteğini, public klasöründeki dosyayı sunacak şekilde yönlendiriyoruz.
    mux.Handle("/app.css", http.FileServer(http.Dir("public")))

    // Router'ı oluştururken, yukarıdaki render fonksiyonunu parametre olarak veriyoruz.
    app := routerpkg.New(render)

    // Gelen tüm HTTP isteklerini (varsayılan "/" yolu üzerinden) oluşturduğumuz router'a yönlendiriyoruz.
    mux.Handle("/", app)
    log.Println("http://localhost:8081")
    _ = http.ListenAndServe("localhost:8081", mux)
}

🔒 Güvenlik & Anti-Pattern’ler

• html/template otomatik escape yapar; kullanıcı verisini güvenle basarsın.

• Asla doğrulanmamış HTML’i template.HTML ile “güvenli” yapma.

• Unutma: escape, {{...}} çıktısında çalışır; JS eventlerinde inline string kaçışını da düzgün yap.

“HTML basmam lazım” diyorsan:

• İçeriği back-office’te sanitize et (ör. allowlist).

• Sonra template.HTML ver — ama gerçekten güvenli olduğundan emin ol.

🥊 Zorluklar vs Kolaylıklar

✅ Kolaylıklar

• Basit yığın: Go + Template + (ileride) HTMX/Alpine. Build karmaşası yok.

• SEO ve hız: SSR ile hızlı FCP, botlar mutlu.

• Güvenlik: Oto-escape default güvenli.

⚠️ Zorluklar

• Büyük front-end interaktivite: SPA konforunu birebir bekleme. (Çözüm: HTMX/Alpine parça parça.)

• Template mirası: define/block isim çakışmaları, hangi dosyada hangi block override ediliyor — dikkat ister.

• Önbellekleme & hot-reload: Dev’de her istekte parse rahat; prod’da parse-cache veya build-time embed istersin.

🚀 Bonus: Geliştirme Deneyimini İyileştirme (Vite + Air)

Hot-reload eksikliğini tek komutla çözmek mümkün.
İşin püf noktası:

• Vite → TailwindCSS derlemesi + views klasöründeki .html dosyalarını izler

• Air → Go kod değişikliklerini izler, otomatik yeniden başlatır

1️⃣ Air Kurulumu

go install github.com/cosmtrek/air@latest

.air.toml (örnek):

root = "."
tmp_dir = "tmp"

[build]
cmd = "go build -o ./tmp/main ./cmd/server"
bin = "tmp/main"
include_ext = ["go", "html"]
exclude_dir = ["node_modules", "public"]

[log]
time = true

2️⃣ Vite Konfigürasyonu

vite.config.js

import { defineConfig } from 'vite'
import tailwindcss from 'tailwindcss'
import autoprefixer from 'autoprefixer'

export default defineConfig({
  server: {
    watch: {
      // .html dosyalarını izleyelim
      paths: ['views/**/*.html']
    }
  },
  css: {
    postcss: {
      plugins: [tailwindcss, autoprefixer]
    }
  }
})

3️⃣ Makefile ile Tek Komut

dev:
\t# Vite + Air aynı anda çalışsın
\tconcurrently "yarn dev" "air"

package.json

{
  "scripts": {
    "dev": "vite",
    "dev:css": "tailwindcss -i ./assets/tailwind.css -o ./public/app.css --watch"
  },
  "devDependencies": {
    "vite": "^5.0.0",
    "tailwindcss": "^3.4.0",
    "autoprefixer": "^10.4.0",
    "concurrently": "^8.0.0"
  }
}

🧭 html/template'i Tercih Etmek İçin Uygun Senaryolar

✅ Statik ağırlıklı içerikler

• Blog, haber, dokümantasyon gibi sayfa odaklı projelerde mükemmel çalışır.

• Hızlı ilk yükleme, SEO dostu yapı.

✅ Yönetim panelleri ve dashboard’lar

• SSR ile hızlı tepki veren sayfalar üretilebilir.

• Görsel tutarlılığı layout/partial yapısı sağlar. ✅ Basit formlar, CRUD işlemleri

• Backend’de üretilen form yapıları için uygundur.

• Validasyon sonrası sayfanın tamamını ya da bir kısmını kolayca güncelleyebilirsiniz.

⚠️ Ne Zaman Alternatif Düşünmeli?

❌ Ağır client-side etkileşimler

• Offline modlar

• Karmaşık form sihirbazları

• Çok adımlı state’li UI’ler

Bu tür senaryolarda SSR tabanlı başla, gerektiğinde HTMX veya Alpine.js gibi çözümlerle client tarafını güçlendir.

🚨 Sık Yapılan Hatalar

• text/template ile HTML basmak → XSS riski.

• Execute yerine ExecuteTemplate("base", ...) çağırmamak → layout çalışmaz.

• Funcs()’ı Parse*’dan sonra çağırmak → helper’lar tanınmaz.

• Aynı define adını iki farklı dosyada hatalı kullanmak → override karmaşası.

• Template’te .Title beklerken Go tarafında Title vermemek → zero string ve sessiz hatalar.

❓ SSS

🏁 Kapanış

Bu bölümde:

• html/template ile base/partial mimarisini kurduk,

• FuncMap ile helper yazdık,

• “Blog Listesi” sayfası yaptık,

• Güvenlik ve pratik tuzakları konuştuk.

🔜 Bir Sonraki Bölümde Ne Var?

Bölüm 2: HTMX ile Dinamik Parçalar

Sıradaki yazımızda, html/template sistemimizi HTMX ile zenginleştireceğiz.
Arama kutusu gibi bir input ile, sadece sayfanın bir bölümünü (örneğin liste alanını) güncelleyen interaktif yapılar kuracağız:

• Sayfa yenilemeden içerik güncelleme

• hx-get, hx-target, hx-swap gibi temel HTMX kavramları

• Liste filtreleme örneği

• Kodla açıklanan canlı demo parçaları

👉 Hiçbir framework ya da build sistemi kullanmadan, sadece HTML ve Go ile SPA benzeri deneyimler oluşturmanın yolunu göreceğiz.

📬 Kaynak Kodu

• GitHub repo: https://github.com/uodev/go-htmx-blog