Büyük çaplı projelerde (kurumsal çözümlerde diyebiliriz) bazı şeylerin garanti altına alınması gerekir. Örneğin uygulamanın mimarisinde geliştirici kaynaklı yapılabilecek bir takım hatalar derleme aşamalarında fark edilmez. Kod bir anda üretim ortamına kadar çıkabilir. Bu tip istenmeyen durumların önüne geçmek için kullanılabilecek farklı yollar var. Kodun kontrollü şekilde çıkartılması için bir review sürecinden geçmesi ve pull request kullanımı bu yöntemlerden birisidir. Ancak birde genel mimariyi etkileyebilecek, statik kod tarama araçları tarafından değerlendirilmeyen hususlar da vardır. Bir katmanın erişmemesi gereken bir katmandan nesne kullanmaya çalışması, geliştirilen bir adaptörün olması gereken katmanda durmaması vb
İşte bu gibi senaryolarda ADR (Architecture Decision Record) belgelerince kayıt altına alınan bir takım garantilerin kodun derlenmesi sırasında en azından birim testler yoluyla denetlenmesi çok işe yarar. Özellikle Java dünyasında bu amaçla kullanılan ArchUnit paketleri .Net tarafında da ele alınabilir. Bu repodaki çalışmanın amacı ArcUnitNet kütüphanesinin nasıl kullanıldığına dair bir demo sunmaktır.
Çözümde çok iddialı bir mimari tasarımı ele almıyoruz. Sadece üzerinde ADR kuralları işleteceğimiz bir solution olması yeterli. Kabaca aşağıdaki bağımlıkların söz konusu olduğunu söyleyebiliriz.
Api çalıştırılabilir giriş noktası ve composition root rolündedir. Application, use case ile repository portlarını içerir. Infrastructure, portların adaptörlerini sağlar. Domain katmanı malum business içerisindeki taban nesneleri taşır ve en önemlisi dış katmanları bilmez (Business'ı koruma ilkesi)
Proje referansların yönü aşağıdaki tabloda olduğu gibidir;
| Proje | Referans verdiği uygulama projeleri |
|---|---|
OrderManagement.Domain |
Yok |
OrderManagement.Application |
Domain |
OrderManagement.Infrastructure |
Application |
OrderManagement.Api |
Application, Infrastructure |
OrderManagement.ArchitectureTests |
Dört uygulama projesine de |
Infrastructure, Application üzerinden kullanılan Domain türlerini geçişli referanslarla görebilir. Application katmanının Infrastructure'a referans vermemesi bizim için kritik sınırdır.
Aşağıdaki adımları izleyerek .NET 10 tabanlı solution ve içeriğini oluşturabiliriz.
# Solution ve projelerin oluşturulması
dotnet new sln -n OrderManagement
dotnet new classlib -n OrderManagement.Domain -o src/OrderManagement.Domain -f net10.0
dotnet new classlib -n OrderManagement.Application -o src/OrderManagement.Application -f net10.0
dotnet new classlib -n OrderManagement.Infrastructure -o src/OrderManagement.Infrastructure -f net10.0
dotnet new web -n OrderManagement.Api -o src/OrderManagement.Api -f net10.0
dotnet new xunit -n OrderManagement.ArchitectureTests -o tests/OrderManagement.ArchitectureTests -f net10.0
# Projelerin solution'a eklenmesi
dotnet sln add src/OrderManagement.Domain/OrderManagement.Domain.csproj
dotnet sln add src/OrderManagement.Application/OrderManagement.Application.csproj
dotnet sln add src/OrderManagement.Infrastructure/OrderManagement.Infrastructure.csproj
dotnet sln add src/OrderManagement.Api/OrderManagement.Api.csproj
dotnet sln add tests/OrderManagement.ArchitectureTests/OrderManagement.ArchitectureTests.csproj
# Projelerin ihtiyaçı olan referans projelerin eklenmesi
dotnet add src/OrderManagement.Application reference src/OrderManagement.Domain
dotnet add src/OrderManagement.Infrastructure reference src/OrderManagement.Application
dotnet add src/OrderManagement.Api reference src/OrderManagement.Application src/OrderManagement.Infrastructure
dotnet add tests/OrderManagement.ArchitectureTests reference src/OrderManagement.Domain src/OrderManagement.Application src/OrderManagement.Infrastructure src/OrderManagement.Api
# Gereksiz Class1'lerin silinmesi
rm src/OrderManagement.Domain/Class1.cs
rm src/OrderManagement.Application/Class1.cs
rm src/OrderManagement.Infrastructure/Class1.cs
# ve mimari test paketinin eklenmesi
dotnet add tests/OrderManagement.ArchitectureTests package TngTech.ArchUnitNET.xUnit
# Infrastructure projesine aşağıdaki Nuget bağımlılığı eklenmeli
# Microsoft.Extensions.DependencyInjection.AbstractionsBundan sonraki kısımları kodlardan takip edebiliriz. Odaklanmamız gereken yer test projesi içeriği ve ADR dokümanları olacak.
Projede ele alacağımız ADR dökümanları docs klasörü altında yer alacaktır.
- ADR 001 Layered Dependency Direction
- ADR 002 Ports and Adapters
- ADR 003 Api as Composition Root
- ADR 004 Naming and Placement
- ADR 005 Framework Independence
ArchUnitNET kaynak kodu değil de derlenmiş assembly'leri analiz eder. Bu yüzden de statik kod tarama araçlarından farklı bir amaca hizmet eder. Solution içerisindeki projelerde herhangi bir üye içermeyen boş arayüz (interface) türleri yer almaktadır. I{LayerAdı}AssemblyMarker şeklinde isimlendirilmişlerdir. Test projesinde yer alan ArchitectureTestBase sınıfı bu açıdan incelemeye değerdir. Örneğin Architecture isimli alan mimariye dahil olan tüm assembly'ları bir seferliğine test çalışma zamanına yükler.
protected static readonly Architecture Architecture = new ArchLoader()
.LoadAssemblies(
typeof(Domain.IDomainAssemblyMarker).Assembly,
typeof(Application.IApplicationAssemblyMarker).Assembly,
typeof(Infrastructure.IInfrastructureAssemblyMarker).Assembly,
typeof(Api.IApiAssemblyMarker).Assembly)
.Build();Birim testlerde Architecture alanının nasıl kullanıldığına dikkat edelim. Diğer yandan katmanlar assembly sağlayıcılarıyla bir kez tanımlanır. Böylece root namespace'in altındaki bütün tipler katmana dahil edilebilir.
protected static readonly IObjectProvider<IType> InfrastructureLayer = Types()
.That()
.ResideInAssembly(typeof(Infrastructure.IInfrastructureAssemblyMarker).Assembly)
.As("Infrastructure Layer");Buna göre aşağıdaki kod parçasının nasıl bir kural işlettiğine bakalım.
IArchRule rule = Types().That().Are(DomainLayer).Should()
.NotDependOnAny(ApplicationLayer)
.AndShould().NotDependOnAny(InfrastructureLayer)
.AndShould().NotDependOnAny(ApiLayer)
.Because("ADR-001 keeps the domain independent of outer layers");
rule.Check(Architecture);Metot zincirini şöyle okuyabiliriz;
DomainLayershould not depend on anyApplicationLayer- And should not depend on any
InfrastructureLayer - And should not depend on any
ApiLayer - Because of "ADR-001"
diğer birim test metotlarını da bu şekilde yorumlayarak anlamaya çalışın.
Tüm mimari testler tamamlandığında projeyi normal şekilde test edebiliriz. İster komut satırından ister Visual Studio gibi IDE ortamlarından.
dotnet testBazı ihlallerde kodun derlenmesinde hiçbir sıkıntı görünmez. Örneğin API katmanı referans ettiği için Infrastructure katmanından bir bileşene (örneğin concrete repository) doğrudan erişebilir. Lakin dokümante edilen ADR ve test implementasyonu bunu test koşusunda fark edecektir. Bu çalışmada gösterilmek istenen şey de budur. Yazabildiğimiz kod ama ADR talimatnamesine göre yazılmamalı.
Api katmanındaki Endpoints/OrdersEndpoint.cs dosyasına aşağıdaki namespace'i ekleyelim ve örnek bir nesnesini kullanalım.
using OrderManagement.Infrastructure.Persistence;
// Field ekleyelim
private static Type ForbiddenPersistenceType => typeof(InMemoryOrderRepository);
usingdirektifi tek başına derlenmiş assembly içinde bir tip bağımlılığı oluşturmaz. Bu nedenleApi_Should_Not_Depend_On_Persistence_Adapterstesti namespace bildirimi olsa dahi başarılı kalır. ArchUnitNET assembly'leri incelediği için gerçek bir ihlal oluşturmak üzere namespace içindeki bir tipi de referanslamak gerekir.
Yine Api layer'da Endpoint lambda parametrelerine geçici olarak bir somut adapter tipini (InMemoryOrderRepository) ekleyelim.
async (CreateOrderRequest request,
CreateOrderHandler handler,
InMemoryOrderRepository forbiddenAdapter,
CancellationToken cancellationToken) =>ADR-001'in üç kuralı (Domain/Application katmanlarının dış katmanlara bağımlı olamaması) için ayrı bir ihlal örneğimiz yok. Çünkü proje referans grafiği zaten
Application -> InfrastructureveyaInfrastructure -> Apiyönünde bir referans eklenmesine izin vermez. Böyle bir referans eklemeye çalışmak dairesel bağımlılık (circular dependency) oluşur ve otomatik olarak derleme zamanı hatası alırız. Yani bu kurallar için derleyici zaten ilk savunma hattımızdır. ArchUnitNET testleri ise ikinci bir güvence katmanıdır. Aşağıdaki ihlaller derleyicinin izin verdiği ama ADR'lerin yasakladığı, dolayısıyla yalnızca mimari testlerin yakalayabildiği bazı senaryolara odaklanır.
OrdersEndpoint.cs dosyasına, Contracts namespace'i dışında yeni bir Request tipi ekleyelim.
namespace OrderManagement.Api.Endpoints;
public sealed record UpdateOrderRequest(Guid OrderId, decimal TotalAmount);Tip derlenir ve endpoint'te hiç kullanılmasa da adında Request geçtiği için Api_Requests_Should_Reside_In_Contracts_Namespace testi bunu yakalar:
Application.Ports namespace'ine, adında Repository geçmeyen yeni bir arayüz (interface) tipi ekleyelim.
namespace OrderManagement.Application.Ports;
public interface IOrderNotifier
{
Task NotifyAsync(Guid orderId, CancellationToken cancellationToken);
}Infrastructure.Persistence namespace'ine, adında Repository geçmeyen bir sınıf ekleyelim.
namespace OrderManagement.Infrastructure.Persistence;
public sealed class OrderCache
{
private readonly ConcurrentDictionary<Guid, Order> _cache = new();
}Sınıf hiçbir portu implemente etmese, hatta hiç kullanılmasa dahi yalnızca bu namespace'te bulunması Persistence_Adapters_Should_Have_Repository_In_Their_Name testini kırar:
Application.Orders.Handlers namespace'ine, adında Handler geçmeyen bir sınıf ekleyelim.
namespace OrderManagement.Application.Orders.Handlers;
public sealed class OrderCreationProcessor(IOrderRepository repository)
{
public Task<Order> BuildAsync(CreateOrderCommand command) =>
Task.FromResult(Order.Create(command.CustomerEmail, command.TotalAmount));
}Application_Handlers_Should_Have_Handler_In_Their_Name testi bu kez namespace'e uygun ama isimlendirmesi yanlış olan tipi yakalar:
Domain katmanına, framework bağımlılığı getiren bir attribute ekleyelim. Örneğin Orders entity'sinde System.Text.Json.Serialization namespace'inden gelen JsonPropertyName attribute'u ile bir alanı işaretleyebiliriz.
using System.Text.Json.Serialization;
[JsonPropertyName("customer_email")]
public string CustomerEmail { get; }Domain_Should_Not_Depend_On_Frameworks testi bu ihlali yakalar:
ADR-005 uyarında Application katmanı da framework bağımlılıklarından arındırılmalıdır. Örneğin, HttpClient veya DbContext gibi framework sınıflarına doğrudan bağımlılık verilmemelidir. Bu tür bağımlılıklar, portlar ve adaptörler aracılığıyla Infrastructure katmanına taşınmalıdır. Ancak burada ilginç bir durum da var. Bu kurala göre Application katmanında Microsoft.EntityFrameworkCore paketinin kullanılmaması da gerekiyor. ArchUnitTest bunu yakalayamayacaktır ve test yeşil geçer. Zira sadecce paket eklenmesi ve bir üyenin kullanılmaması derlenmiş çıktıda iz bırakmayacağından bir ihlal olarak görülmez. Bu gibi durumlar için ArchUnitNet yerine daha geleneksel yollarla da ilerlenebilir. PackageReferenceTests isimli birim test sınıfını bir incelemek lazım.
Burada aldığımız tedbir tam garanti sağlamayabilir. Örneğin Application katmanı EF Core'u referans etmese de, kullandığı başka bir paket EF Core bağımlılığı ile gelebilir ve test yeşil bayral kaldırır. Tam garanti için obj/project.assets.json dosyasındaki bağımlılık grafiğini okuyup analiz etmek gerekir ki bu yöntem de obj klasörüne bağımlı olduğu için kırılgandır. Böyle durumlarda tam garanti sağlamak zordur. O nedenle bu gibi durumları ADR belgesindeki sonuçlar kısmında bilinen bir sınır olarak belirtmek çok daha anlamlıdır. Yani, ADR belgesinin neyi garanti etmediğini söylemesi de değerlidir!
Bir ADR maddesi derleme zamanında veya test zamanında olmak üzere iki kapıyla korunabilir. Derleme zamanından koruma hızlı geri bildirim almayı sağlar. Test koşusu ise belgelenmiş bir kanıt üretir.
Github tarafı için eklenmiş bir workflow dosyamız var. .github/workflow/ci.yml dosyası. Aslında içerisinde test koşusunun yapıldığı bir adım da bulunuyor. Bu sayede her push veya pull request işleminde testler otomatik olarak çalıştırılıyor ve sonuçlar GitHub Actions üzerinden takip edilebiliyor. Örneğin bir ADR ihlali söz konusu ise Pull Request açıldığında test koşusunda hata alınacaktır. Aşağıdaki ekran görüntüsünde olduğu gibi.









