Pr.BuildingBlocks.Cms.Core 5.0.1

Pr.BuildingBlocks.Cms.Core

Biblioteka building blocków warstwy domeny dla mikroserwisów CMS Polskiego Radia. Zawiera podstawowe abstrakcje, kontrakty i klasy bazowe — bez zależności od ASP.NET Core, EF Core, Wolverine ani konkretnej infrastruktury. Pakiet startowy każdego mikroserwisu CMS.

• Target framework: net8.0
• PackageId: Pr.BuildingBlocks.Cms.Core
• Wersja: 5.0.1

Spis treści

• Instalacja
• Typy domenowe
• Zdarzenia domenowe
• Komendy
• Wyjątki domenowe
• Guard clauses
• Czas
• Slugi
• DTO
• Konwertery JSON

Instalacja

<PackageReference Include="Pr.BuildingBlocks.Cms.Core" Version="5.0.1" />

Typy domenowe

Bazowe abstrakcje budowy modelu domenowego (DDD).

Entity<TId>

Bazowa encja z typowanym identyfikatorem. Implementuje równość na podstawie typu i wartości Id (operatory == i != plus Equals/GetHashCode). Po zmianie Id zmienia się też hash, więc encje należy traktować jako niezmienne pod tym względem.

public sealed class Episode : Entity<EpisodeId>
{
    public string Title { get; private set; }

    private Episode(EpisodeId id, string title) : base(id) { Title = title; }
}

AggregateRoot<TId>

Bazowy agregat (dziedziczy Entity<TId>, implementuje IAggregateRoot). Udostępnia:

• IReadOnlyCollection<IDomainEvent> DomainEvents — zdarzenia zarejestrowane podczas operacji.
• int Version — token wersjonowania dla optimistic concurrency.
• protected void AddDomainEvent(IDomainEvent @event) — dodaje zdarzenie do kolekcji.
• protected void IncrementVersion() — inkrementuje Version.
• void ClearDomainEvents() — czyści listę po publikacji (wołane przez DomainEventsMiddleware).

IAggregateRoot

Interfejs marker eksponujący DomainEvents i ClearDomainEvents(). Wykorzystywany przez DomainEventsMiddleware w warstwie Infrastructure do automatycznego wykrywania agregatów w ChangeTracker EF Core i publikacji ich zdarzeń.

TypedId

Bazowy rekord dla strongly-typed ID. Opakowuje Guid Value. W trybie isRequired = true (domyślnym) walida, że wartość nie jest Guid.Empty (rzuca ArgumentException z komunikatem „Wartość ID nie może być wartością domyślną.").

public sealed record EpisodeId(Guid Value) : TypedId(Value);

Zapewnia bezpieczeństwo typów — nie pomylisz EpisodeId z ArticleId, choć oba opakowują Guid.

IValueObject<T>

Kontrakt obiektu wartości. Wymusza pojedynczą właściwość T Value. Współpracuje z ValueObjectConverterFactory — typy implementujące IValueObject<T> są automatycznie serializowane jako prymityw w JSON.

public sealed record Slug(string Value) : IValueObject<string>;

Zdarzenia domenowe

IDomainEvent

Kontrakt zdarzenia: Guid Id, DateTimeOffset OccurredOn, void SetTime(DateTimeOffset). OccurredOn jest ustawiane na końcu pipeline'u przez DomainEventsMiddleware (Infrastructure) za pomocą IClock.UtcNow, dzięki czemu w testach jednostkowych domena nie zna czasu.

DomainEvent

Bazowa klasa zdarzenia. W konstruktorze generuje Guid.NewGuid() jako Id. Pochodne klasy zwykle są rekordami niosącymi tylko dane:

public sealed record EpisodePublished(EpisodeId EpisodeId, string Title) : DomainEvent;

Komendy

Markery dla komend obsługiwanych przez Wolverine.

• IInternalCommand — komenda lokalna (in-process). Routing/konwencje Wolverine traktują ten interfejs jako sygnał, że wiadomość ma być obsługiwana przez handler w tym samym procesie.
• IExternalCommand — komenda przekraczająca granicę procesu (message bus, RabbitMQ, inny mikroserwis). Routing kieruje ją na zewnętrzny transport.

Oba interfejsy są puste (markerami) — używaj ich jako : IInternalCommand / : IExternalCommand na rekordzie komendy.

Wyjątki domenowe

Wszystkie wyjątki domenowe dziedziczą po BaseException, co pozwala middleware ExceptionHandlerMiddleware (Infrastructure) automatycznie mapować je na odpowiedzi HTTP z polskimi komunikatami.

Konstruktory większości wyjątków przyjmują albo dwie wartości (np. resourceName + resourceId), albo gotowy komunikat — wybierz to, co lepiej pasuje do kontekstu.

if (episode is null)
    throw new NotFoundException(nameof(Episode), episodeId);

if (versionMismatch)
    throw new OptimisticConcurrencyException(nameof(Episode), episodeId);

Guard clauses

Walidacja wejściowa w stylu Ardalis.GuardClauses. Punkt wejścia: Guard.Against.

public sealed record CreateEpisodeRequest(string Title, int DurationSeconds, string Status)
{
    public void Validate()
    {
        Guard.Against.NullOrWhiteSpace(Title);
        Guard.Against.LengthOutOfRange(Title, 1, 200);
        Guard.Against.NegativeOrZero(DurationSeconds);
        Guard.Against.InvalidEnum<EpisodeStatus>(Status);
    }
}

Wszystkie metody używają atrybutu [CallerArgumentExpression], dzięki czemu nazwa parametru w komunikacie jest wykrywana automatycznie.

Czas

IClock

Abstrakcja dostawcy czasu — wstrzykuj zamiast DateTime.UtcNow/DateTimeOffset.UtcNow, żeby testy mogły kontrolować czas.

public interface IClock
{
    DateTimeOffset UtcNow { get; }
    DateOnly Today { get; }
}

Domyślna implementacja SystemDateTimeProvider znajduje się w Pr.BuildingBlocks.Cms.Infrastructure i zwraca czas w strefie Europe/Warsaw.

Slugi

ISlugifier

Kontrakt komponentu generującego slug z dowolnego tekstu (string GenerateSlug(string text)). Implementacja Slugifier znajduje się w Pr.BuildingBlocks.Cms.Infrastructure i jest konfigurowalna od v5.0.0 przez services.AddSlugifier(opt => ...) (lower case, collapse dashes, trim, custom replacements). Domyślnie obsługuje polskie znaki diakrytyczne i transliteruje cyrylicę. Szczegóły: README pakietu Infrastructure.

DTO

PagedResultDto<T>

Generyczny DTO wyniku stronicowanego:

Filtr ApiResponseWrapperFilter (Infrastructure) rozpoznaje ten typ i nie opakowuje go w { data: ... } — paginacja ma już własną strukturę.

return new PagedResultDto<EpisodeDto>(items, totalCount, pageNumber, pageSize);

Konwertery JSON

ValueObjectConverterFactory

Fabryka konwerterów System.Text.Json automatycznie obsługująca każdy typ implementujący IValueObject<T>. Przy odczycie woła statyczną metodę Create(TPrimitive) lub publiczny konstruktor; przy zapisie serializuje samą wartość prymitywną.

services.Configure<JsonOptions>(options =>
{
    options.SerializerOptions.Converters.Add(new ValueObjectConverterFactory());
});

Po rejestracji Slug (z przykładu wyżej) jest serializowany jako goły string, nie obiekt: "abc" zamiast { "value": "abc" }.