Kapitola 18 · Praxe · Migrace z CRUD architektury na DDD

Migrace z CRUD architektury na DDD

Podrobný průvodce migrací z CRUD architektury na Domain-Driven Design v Symfony. Strangler Fig Pattern, extrakce doménové vrstvy, zavedení repozitářů a postupné zavedení CQRS s praktickými PHP příklady.

Autor M. Katuščák

Doba čtení ≈ 25 min

Náročnost pokročilá

Publikováno · Aktualizováno 24. 4. 2025 · 3. 5. 2026

Obsah kapitoly

18.01 Kdy a proč migrovat z CRUD na DDD

CRUD architektura (Create, Read, Update, Delete) je výchozí volba pro většinu aplikací a dlouho stačí. Pro správu dat bez komplexní logiky – záznamy kontaktů, katalogy produktů, administrační rozhraní – CRUD odvede práci a vrstvy DDD by byly zbytečnou zátěží. Problém přijde, když aplikace přeroste do větší komplexity a doménová logika proniká na nevhodná místa.

§ Poznámka

Příznaky, že CRUD architektura nestačí

God Services (Boží služby) – Třídy jako UserService nebo OrderService mají stovky řádků a soustřeďují celou doménovou logiku. Každá nová funkce vede do stejné třídy a riziko regresí roste.
Fat Controllers (Tlusté kontrolery) – Symfony kontrolery přestaly být tenkou vrstvou pro HTTP adaptaci. Místo toho přímo implementují doménová pravidla: validaci, výpočty, přechody stavů. Kontroler má delegovat na doménový model, nikoli ho suplovat.
Doménová logika v repozitářích – Doctrine repozitáře obsahují komplexní podmínky, které vyjadřují doménová pravidla (např. „objednávky, které je možné zrušit“). Tato logika patří do doménového modelu, nikoli do databázové vrstvy.
Překrývání zodpovědností – Není jasné, zda konkrétní pravidlo patří do kontroleru, service nebo repozitáře. Tým nemá sdílené chápání, kde co hledat.
Nízká testovatelnost – Doménová logika je neoddělitelně svázána s HTTP vrstvou nebo databází. Napsání unit testu pro doménové pravidlo vyžaduje rozsáhlé mockování.
Komunikační propast – Vývojáři a doménoví experti používají jiný slovník. Kód neodráží doménový jazyk; pojmy jako „aktivace účtu“ nebo „storno objednávky“ nejsou viditelné v názvech tříd a metod.

Kdy DDD přináší hodnotu a kdy je CRUD dostačující

Rozhodnutí o migraci stojí na analýze komplexity domény, ne na trendech. Martin Fowler ve své práci o architektonických vzorech ukazuje, že Transaction Script a CRUD jsou legitimní volbou pro aplikace s jednoduchými doménovými pravidly [1].

Realistické zhodnocení nákladů migrace

Migrace z CRUD na DDD trvá měsíce až roky podle velikosti kódové základny — jde o dlouhý proces, ne jednorázovou akci. Sama o sobě nepřináší zákazníkovi okamžitou hodnotu – hodnota přijde s tím, jak tým začne přidávat funkce rychleji a s menším rizikem regresí. Management přijme migraci snáz, když probíhá inkrementálně souběžně s vývojem nových funkcí, ne jako izolovaný refaktoringový projekt.

18.02 Strangler Fig Pattern – vzor postupné náhrady

Strangler Fig Pattern (vzor fíkovníku škrtiče) pojmenoval Martin Fowler [2]. Vzor nahrazuje starý systém po částech, bez „big bang“ přepisu. Název pochází od tropického fíkovníku, který roste kolem hostitelského stromu a postupně ho zardousí.

Strangler Fig: čtyři fáze migrace CRUD → DDD

◢ Vzor

Příklad: Koexistence CRUD a DDD ve struktuře projektu

bash snippet.sh

src/
├── Controller/                    # Stará CRUD vrstva (postupně se zmenšuje)
│   ├── UserController.php         # Původní CRUD kontroler
│   └── OrderController.php        # Původní CRUD kontroler
│
├── Service/                       # Stará service vrstva (God Services)
│   ├── UserService.php            # Bude nahrazena DDD vrstvou
│   └── OrderService.php           # Bude nahrazena DDD vrstvou
│
├── Entity/                        # Doctrine entity (sdílené nebo duplikované)
│   ├── User.php
│   └── Order.php
│
└── UserManagement/                # Nová DDD vrstva (postupně roste)
    ├── Domain/
    │   ├── Model/
    │   │   ├── User.php           # Doménová entita (ne Doctrine entita)
    │   │   └── Email.php          # Value Object
    │   ├── Repository/
    │   │   └── UserRepository.php # Doménové rozhraní
    │   └── Event/
    │       └── UserRegistered.php # Domain Event
    ├── Application/
    │   ├── Command/
    │   │   ├── RegisterUser.php
    │   │   └── RegisterUserHandler.php
    │   └── Query/
    │       ├── GetUserProfile.php
    │       └── GetUserProfileHandler.php
    └── Infrastructure/
        └── Repository/
            └── DoctrineUserRepository.php  # Implementace repozitáře

Výhody oproti přímé refaktorizaci (Big Bang Rewrite)

Přepsat celý systém najednou (tzv. „big bang rewrite“) je jedno z největších rizik v softwarovém vývoji. Joel Spolsky ve svém článku „Things You Should Never Do“ [3] popisuje, proč firmy ztratily konkurenční výhodu tím, že kompletně přepsaly fungující systémy. Strangler Fig Pattern oproti tomu:

Umožňuje kontinuální dodávku nové hodnoty zákazníkovi i během migrace.
Snižuje riziko – systém nikdy není kompletně „rozbitý“.
Poskytuje možnost rollbacku: pokud nová implementace selhává, stará stále funguje.
Umožňuje týmu učit se DDD postupně, na reálném produkčním kódu.
Refaktoring lze zastavit kdykoli – systém zůstává v konzistentním, funkčním stavu.

18.03 Krok 1: Analýza existující domény

Než začneme přesouvat kód, musíme pochopit doménu. Nejčastější chybou je přímý skok do refaktoringu bez předchozí analýzy – výsledkem je pak DDD architektura, která přesně kopíruje strukturu starých databázových tabulek, aniž by odrážela skutečný doménový model.

Identifikace Bounded Contexts z existujícího CRUD kódu

Bounded Contexts lze v existující CRUD aplikaci identifikovat sledováním přirozených hranic:

Skupiny entit a tabulek, které jsou silně provázané navzájem, ale slabě propojené s ostatními skupinami – to jsou kandidáti na jeden Bounded Context.
God Services – velké service třídy jsou paradoxně dobrým vodítkem. Pokud OrderService obsahuje logiku objednávky, platby i doručení, jsou to tři různé Bounded Contexts skryté v jedné třídě.
Opakující se slovo s různým významem – pokud „zákazník“ v kontextu prodeje znamená něco jiného než „zákazník“ v kontextu zákaznické podpory, jde o přirozené rozhraní dvou Bounded Contexts.

Event Storming jako nástroj pro analýzu

Event Storming vymyslel Alberto Brandolini [4]. Workshopová technika modeluje doménu přes doménové události a zapojí do návrhu i lidi mimo tým vývoje. Při migraci z CRUD pomáhá:

Odkrytí implicitní doménové logiky skryté v kontrolerech a service třídách.
Identifikaci přechodů stavů entit (z pohledu domény, nikoli databáze).
Nalezení přirozených hranic Bounded Contexts.
Zapojení doménových expertů do návrhu nové architektury.

◢ Vzor

Příklad: Identifikace doménové logiky v CRUD kontroleru

Následující příklad ilustruje typický CRUD kontroler, ve kterém se skrývá netriviální doménová logika. Tuto logiku v dalších krocích extrahujeme do doménového modelu.

php src/Controller/UserController.php

<?php

// PŘED migrací: Typický CRUD kontroler s ukrytou doménovou logikou
namespace App\Controller;

use App\Entity\User;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Doctrine\ORM\EntityManagerInterface;

class UserController extends AbstractController
{
    public function __construct(
        private EntityManagerInterface $em
    ) {}

    #[Route('/users/register', methods: ['POST'])]
    public function register(Request $request): Response
    {
        $email = $request->request->get('email');
        $password = $request->request->get('password');

        // Doménová logika č. 1: validace emailu (patří do Value Object)
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            return $this->json(['error' => 'Neplatný e-mail'], 422);
        }

        // Doménová logika č. 2: kontrola unikátnosti (patří do doménové služby)
        $existing = $this->em->getRepository(User::class)
            ->findOneBy(['email' => $email]);
        if ($existing) {
            return $this->json(['error' => 'E-mail již existuje'], 409);
        }

        // Doménová logika č. 3: hashování hesla a bezpečnostní pravidla
        if (strlen($password) < 8) {
            return $this->json(['error' => 'Heslo musí mít alespoň 8 znaků'], 422);
        }
        $hashedPassword = password_hash($password, PASSWORD_BCRYPT);

        $user = new User();
        $user->setEmail($email);
        $user->setPassword($hashedPassword);
        $user->setCreatedAt(new \DateTimeImmutable());
        // Doménová logika č. 4: výchozí stav uživatele
        $user->setStatus('pending_verification');

        $this->em->persist($user);
        $this->em->flush();

        // Doménová logika č. 5: odeslání uvítacího e-mailu
        // ... (inline kód pro odeslání e-mailu)

        return $this->json(['id' => $user->getId()], 201);
    }
}

V tomto kontroleru lze identifikovat nejméně pět oblastí doménové logiky, které patří do doménového modelu: validace formátu e-mailu, unikátnost e-mailu, bezpečnostní pravidla hesla, výchozí stav uživatele a vedlejší efekt registrace (uvítací e-mail jako Domain Event).

18.04 Krok 2: Extrakce doménové vrstvy

Extrakce doménové vrstvy přesouvá doménová pravidla z kontrolerů a service tříd do doménových objektů. Cíl: doménové objekty si své invarianty hlídají samy. Nikdo zvenčí je nemůže obejít.

Přesunutí doménových pravidel do doménových objektů

Refaktoring má dva kroky. Nejdřív vzniknou Value Objects pro primitivy s doménovými pravidly. Pak se logika přesune do entit a doménových služeb.

◢ Vzor

Příklad: Refaktorizace UserService – before/after

php src/Service/UserService.php

<?php

// PŘED: God Service s přímou závislostí na Doctrine
namespace App\Service;

class UserService
{
    public function __construct(
        private EntityManagerInterface $em,
        private MailerInterface $mailer
    ) {}

    public function register(string $email, string $password): User
    {
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException('Neplatný e-mail');
        }
        if (strlen($password) < 8) {
            throw new \InvalidArgumentException('Heslo příliš krátké');
        }
        $existing = $this->em->getRepository(User::class)
            ->findOneBy(['email' => $email]);
        if ($existing) {
            throw new \RuntimeException('E-mail již existuje');
        }

        $user = new User();
        $user->setEmail($email);
        $user->setPassword(password_hash($password, PASSWORD_BCRYPT));
        $user->setStatus('pending_verification');
        $this->em->persist($user);
        $this->em->flush();

        $this->mailer->send(/* uvítací e-mail */);

        return $user;
    }
}

php src/UserManagement/Domain/Model/User.php

<?php

declare(strict_types=1);

// PO: Doménová entita s vlastními invarianty
namespace App\UserManagement\Domain\Model;

use App\Shared\Domain\AggregateRoot;
use App\UserManagement\Domain\Event\UserActivated;
use App\UserManagement\Domain\Event\UserRegistered;
use App\UserManagement\Domain\ValueObject\Email;
use App\UserManagement\Domain\ValueObject\HashedPassword;
use App\UserManagement\Domain\ValueObject\UserId;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Table(name: 'users')]
final class User extends AggregateRoot
{
    #[ORM\Id]
    #[ORM\Column(type: 'user_id')]
    public readonly UserId $id;

    #[ORM\Column(type: 'email_vo', unique: true)]
    private Email $email;

    #[ORM\Embedded(class: HashedPassword::class)]
    private HashedPassword $password;

    #[ORM\Column(enumType: UserStatus::class)]
    private UserStatus $status;

    #[ORM\Column(type: 'datetime_immutable')]
    public readonly \DateTimeImmutable $registeredAt;

    #[ORM\Version]
    #[ORM\Column(type: 'integer')]
    private int $version = 1;

    private function __construct(UserId $id, Email $email, HashedPassword $password)
    {
        $this->id = $id;
        $this->email = $email;
        $this->password = $password;
        $this->status = UserStatus::PENDING_VERIFICATION;
        $this->registeredAt = new \DateTimeImmutable();

        // Doménová událost – vedlejší efekt registrace je nyní explicitní
        $this->record(new UserRegistered($id, $email));
    }

    // Named constructor vyjadřuje záměr lépe než new User()
    public static function register(UserId $id, Email $email, HashedPassword $password): self
    {
        return new self($id, $email, $password);
    }

    public function activate(VerificationToken $token): void
    {
        if ($this->status !== UserStatus::PENDING_VERIFICATION) {
            throw new \DomainException('Uživatel již byl aktivován nebo je zablokován.');
        }
        $token->validate(); // Token si validuje sám sebe
        $this->status = UserStatus::ACTIVE;
        $this->record(new UserActivated($this->id));
    }

    public function email(): Email { return $this->email; }
    public function status(): UserStatus { return $this->status; }
}

Doménová entita User nyní sama vynucuje svá pravidla: výchozí stav, přechod stavu při aktivaci, emituje Domain Event při registraci. Kontroler ani service nemůže tyto invarianty obejít.

Zavedení Value Objects místo primitive types

Doménový koncept skrytý v string nebo int se nazývá Primitive Obsession. Value Object nahradí primitiv objektem, který drží validaci i chování pohromadě.

◢ Vzor

Příklad: Refaktorizace string emailu na Email Value Object

php src/UserManagement/Domain/ValueObject/Email.php

<?php

// PŘED: Email jako string – validace je rozptýlena v celé aplikaci
class UserController {
    public function register(Request $request): Response {
        $email = $request->request->get('email'); // string, nic negarantuje
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) { /* ... */ }
        // ... validace se opakuje na každém místě použití
    }
}

// --- Soubor: Email.php ---
declare(strict_types=1);

// PO: Email jako Value Object – validace je na jednom místě
namespace App\UserManagement\Domain\ValueObject;

final class Email
{
    private readonly string $value;

    public function __construct(string $value)
    {
        $normalized = mb_strtolower(trim($value));

        if (!filter_var($normalized, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException(
                sprintf('"%s" není platná e-mailová adresa.', $value)
            );
        }

        // Zakázané domény (doménové pravidlo)
        $domain = substr($normalized, strpos($normalized, '@') + 1);
        if (in_array($domain, ['example.com', 'test.com'], true)) {
            throw new \DomainException(
                'Registrace z testovacích domén není povolena.'
            );
        }

        $this->value = $normalized;
    }

    public function value(): string
    {
        return $this->value;
    }

    public function domain(): string
    {
        return substr($this->value, strpos($this->value, '@') + 1);
    }

    public function equals(self $other): bool
    {
        return $this->value === $other->value;
    }

    public function __toString(): string
    {
        return $this->value;
    }
}

Value Object Email zapouzdřuje validaci na jednom místě. Kdykoli vznikne instance Email, máme garantovanou platnost hodnoty – bez ohledu na to, kde v aplikaci k vytvoření dochází. Toto je základní princip „Make Illegal States Unrepresentable“.

18.05 Krok 3: Zavedení repozitářů

CRUD aplikace typicky volá EntityManagerInterface nebo Doctrine repozitáře přímo z kontrolerů a service tříd. DDD postaví mezi doménu a persistenci doménové rozhraní repozitáře. Doménový kód o Doctrine ani SQL nic neví a implementace se dá vyměnit bez jeho úprav.

Vytvoření doménového rozhraní repozitáře

Doménové rozhraní repozitáře žije v doménové vrstvě. Popisuje operace tak, jak je potřebuje doména. O Doctrine, SQL ani jiné infrastruktuře nepadne ani zmínka.

◢ Vzor

Příklad: Doménové rozhraní vs. Doctrine implementace

php src/UserManagement/Domain/Repository/UserRepository.php

<?php

declare(strict_types=1);

// Doménové rozhraní – součást domény, žádná infrastrukturní závislost
namespace App\UserManagement\Domain\Repository;

use App\UserManagement\Domain\Model\User;
use App\UserManagement\Domain\ValueObject\Email;
use App\UserManagement\Domain\ValueObject\UserId;

interface UserRepository
{
    public function save(User $user): void;

    public function findById(UserId $id): ?User;

    public function findByEmail(Email $email): ?User;

    /** @return User[] */
    public function findActiveUsers(): array;

    public function nextIdentity(): UserId;
}

php src/UserManagement/Infrastructure/Repository/DoctrineUserRepository.php

<?php

declare(strict_types=1);

// Infrastrukturní implementace – obaluje Doctrine EntityManager
namespace App\UserManagement\Infrastructure\Repository;

use App\UserManagement\Domain\Model\User;
use App\UserManagement\Domain\Repository\UserRepository;
use App\UserManagement\Domain\ValueObject\Email;
use App\UserManagement\Domain\ValueObject\UserId;
use Doctrine\ORM\EntityManagerInterface;

final class DoctrineUserRepository implements UserRepository
{
    public function __construct(
        private EntityManagerInterface $em
    ) {}

    public function save(User $user): void
    {
        $this->em->persist($user);
        // Flush je záměrně ponechán na aplikační vrstvě (Command Handler)
        // aby byla možná transakční konzistence přes více agregátů
    }

    public function findById(UserId $id): ?User
    {
        return $this->em->find(User::class, $id->value());
    }

    public function findByEmail(Email $email): ?User
    {
        return $this->em->getRepository(User::class)
            ->findOneBy(['email.value' => $email->value()]);
    }

    public function findActiveUsers(): array
    {
        return $this->em->createQueryBuilder()
            ->select('u')
            ->from(User::class, 'u')
            ->where('u.status = :status')
            ->setParameter('status', 'active')
            ->getQuery()
            ->getResult();
    }

    public function nextIdentity(): UserId
    {
        return UserId::generate();
    }
}

Doménová vrstva závisí pouze na rozhraní UserRepository. Symfony DI container injektuje do doménových služeb DoctrineUserRepository. Díky tomu lze implementaci repozitáře vyměnit v konfiguračním souboru bez změny doménového kódu.

§ Poznámka

Konfigurace Dependency Injection v Symfony

yaml config/packages/doctrine.yaml

# config/services.yaml
services:
    App\UserManagement\Domain\Repository\UserRepository:
        alias: App\UserManagement\Infrastructure\Repository\DoctrineUserRepository

Tato konfigurace zajistí, že Symfony automaticky injektuje Doctrine implementaci všude tam, kde je typovaná závislost na doménovém rozhraní UserRepository.

18.06 Krok 4: Postupné zavedení CQRS

Command Query Responsibility Segregation (CQRS) na DDD navazuje, ale má se zavést až po tom, co se doménový model usadí. Když přijde dřív, přesune komplexitu z domény do handleru, kde je neviditelná a hůř se testuje.

Začít s Command stranou (write side)

Nejpřirozenějším místem pro zavedení CQRS je write side – operace, které mění stav systému. Query side (čtení) lze zpočátku ponechat s přímými Doctrine dotazy a refaktorovat ji samostatně, nebo ji ponechat jako optimalizované SQL dotazy i v DDD systému (read modely).

◢ Vzor

Příklad: Extrakce RegisterUserCommand z UserController

php src/Controller/UserController.php

<?php

// PŘED: Logika přímo v kontroleru nebo service
namespace App\Controller;

class UserController extends AbstractController
{
    public function __construct(
        private UserService $userService
    ) {}

    #[Route('/users/register', methods: ['POST'])]
    public function register(Request $request): Response
    {
        // Kontroler musí vědět, jaké parametry service očekává
        $this->userService->register(
            $request->request->get('email'),
            $request->request->get('password'),
            $request->request->get('name')
        );
        return $this->json(['status' => 'ok'], 201);
    }
}

php src/UserManagement/Application/Command/RegisterUser.php

<?php

// --- Soubor: RegisterUser.php ---
// PO: Command objekt jako explicitní kontrakt
namespace App\UserManagement\Application\Command;

final readonly class RegisterUser
{
    public function __construct(
        public string $email,
        public string $password,
        public string $name,
    ) {}
}

// --- Soubor: RegisterUserHandler.php ---
// Handler zapouzdřuje aplikační logiku jednoho use case
namespace App\UserManagement\Application\Command;

use App\UserManagement\Domain\Model\User;
use App\UserManagement\Domain\ValueObject\UserId;
use App\UserManagement\Domain\Repository\UserRepository;
use App\UserManagement\Domain\ValueObject\Email;
use App\UserManagement\Domain\ValueObject\HashedPassword;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class RegisterUserHandler
{
    public function __construct(
        private UserRepository $users,
        private UserRegistrationPolicy $policy,
    ) {}

    public function __invoke(RegisterUser $command): void
    {
        $email = new Email($command->email);
        $password = HashedPassword::fromPlaintext($command->password);

        // Doménová politika ověřuje pravidla přes repozitář
        $this->policy->assertEmailIsUnique($email);

        $user = User::register(
            $this->users->nextIdentity(),
            $email,
            $password
        );

        $this->users->save($user);

        // Domain Events jsou zpracovány Symfony Messengerem
        foreach ($user->releaseDomainEvents() as $event) {
            // event dispatch je řešen infrastrukturní vrstvou
        }
    }
}

// --- Soubor: UserController.php ---
// Kontroler je nyní tenký – pouze HTTP adaptér
namespace App\Controller;

use App\UserManagement\Application\Command\RegisterUser;
use Symfony\Component\Messenger\MessageBusInterface;

class UserController extends AbstractController
{
    public function __construct(
        private MessageBusInterface $commandBus
    ) {}

    #[Route('/users/register', methods: ['POST'])]
    public function register(Request $request): Response
    {
        $this->commandBus->dispatch(new RegisterUser(
            email: $request->request->getString('email'),
            password: $request->request->getString('password'),
            name: $request->request->getString('name'),
        ));
        return $this->json(['status' => 'ok'], 201);
    }
}

Command RegisterUser je prosté DTO (Data Transfer Object) bez závislostí. Handler RegisterUserHandler orchestruje doménový model. Kontroler se zužuje na HTTP vrstvu, která pouze přeloží HTTP požadavek na Command. Vrstvy oddělené takto se dají testovat každá zvlášť.

18.07 Testování při migraci

O úspěchu migrace rozhodují testy. Bez nich refaktoring zavede regrese, které se projeví v produkci. Migrace z CRUD na DDD potřebuje dvě techniky: charakterizační testy pro zachycení stávajícího chování a unit testy pro nově vznikající doménovou vrstvu.

Charakterizační testy (Characterization Tests)

Pojem „charakterizační testy“ pochází z knihy Michaela Featherse „Working Effectively with Legacy Code“ [5]. Charakterizační test nepopisuje, jaké by mělo být správné chování systému, ale zachycuje jaké chování systém aktuálně má. Slouží jako síť, která zachytí nechtěné změny chování při refaktoringu.

◢ Vzor

Příklad: Charakterizační test pro CRUD kontroler

php Tests/Characterization/UserRegistrationCharacterizationTest.php

<?php

declare(strict_types=1);

namespace Tests\Characterization;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

/**
 * Charakterizační testy zachycují AKTUÁLNÍ chování systému.
 * Jsou záměrně popsány jako "chová se tak, jak se chová",
 * ne "mělo by se chovat tak a tak".
 * Pokud refaktoring změní toto chování, test selže a upozorní tým.
 */
class UserRegistrationCharacterizationTest extends WebTestCase
{
    public function test_registration_returns_201_with_valid_data(): void
    {
        $client = static::createClient();
        $client->request('POST', '/users/register', [
            'email' => '[email protected]',
            'password' => 'SecurePassword123',
            'name' => 'Jan Novák',
        ]);

        // Zachycujeme aktuální HTTP status kód
        self::assertResponseStatusCodeSame(201);
    }

    public function test_registration_returns_422_for_invalid_email(): void
    {
        $client = static::createClient();
        $client->request('POST', '/users/register', [
            'email' => 'not-an-email',
            'password' => 'SecurePassword123',
            'name' => 'Jan Novák',
        ]);

        // Zachycujeme aktuální chybový kód a strukturu odpovědi
        self::assertResponseStatusCodeSame(422);
        $data = json_decode($client->getResponse()->getContent(), true);
        self::assertArrayHasKey('error', $data);
    }

    public function test_duplicate_email_returns_409(): void
    {
        $client = static::createClient();
        // První registrace
        $client->request('POST', '/users/register', [
            'email' => '[email protected]',
            'password' => 'SecurePassword123',
            'name' => 'Jan Novák',
        ]);
        // Druhá registrace se stejným e-mailem
        $client->request('POST', '/users/register', [
            'email' => '[email protected]',
            'password' => 'AnotherPassword456',
            'name' => 'Jiný Uživatel',
        ]);

        self::assertResponseStatusCodeSame(409);
    }
}

Charakterizační testy vznikají před refaktoringem. Mají procházet po celou dobu migrace. Když nějaký selže, refaktoring změnil pozorovatelné chování systému – buď záměrně, nebo omylem.

Unit testy doménové vrstvy

Jednou z výhod DDD je testovatelnost doménových objektů v izolaci bez databáze, HTTP klienta nebo jiné infrastruktury. Unit testy doménové vrstvy jsou rychlé, deterministické a přesně dokumentují doménová pravidla.

◢ Vzor

Příklad: Unit test doménové entity

php Tests/UserManagement/Domain/Model/UserTest.php

<?php

declare(strict_types=1);

namespace Tests\UserManagement\Domain\Model;

use App\UserManagement\Domain\Model\User;
use App\UserManagement\Domain\ValueObject\UserId;
use App\UserManagement\Domain\ValueObject\Email;
use App\UserManagement\Domain\ValueObject\HashedPassword;
use App\UserManagement\Domain\Event\UserRegistered;
use PHPUnit\Framework\TestCase;

final class UserTest extends TestCase
{
    public function test_newly_registered_user_is_pending_verification(): void
    {
        $user = User::register(
            UserId::generate(),
            new Email('[email protected]'),
            HashedPassword::fromPlaintext('SecurePass123')
        );

        self::assertTrue($user->status()->isPendingVerification());
    }

    public function test_registration_emits_user_registered_event(): void
    {
        $user = User::register(
            UserId::generate(),
            new Email('[email protected]'),
            HashedPassword::fromPlaintext('SecurePass123')
        );

        $events = $user->releaseDomainEvents();
        self::assertCount(1, $events);
        self::assertInstanceOf(UserRegistered::class, $events[0]);
    }

    public function test_cannot_activate_already_active_user(): void
    {
        $user = User::register(/* ... */);
        $token = VerificationToken::valid('abc123');
        $user->activate($token);

        $this->expectException(\DomainException::class);
        $user->activate($token); // druhá aktivace musí selhat
    }
}

18.08 Rizika a doporučení

Nejčastější chyby při migraci

Anémický doménový model – Nejčastější past. Vývojáři vytvoří třídy s názvem jako v DDD (User, Order), ale tyto třídy obsahují pouze gettery a settery bez doménové logiky. Logika zůstane v service třídách. Výsledek je DDD terminologie s CRUD implementací.
Přílišná granularita Bounded Contexts – Rozdělení domény na příliš mnoho malých kontextů vede k distribuované komplexitě. Každá integrace mezi kontexty přidává overhead. Začněte s většími kontexty a rozdělujte je až tehdy, když je důvod k tomu jasný.
Doctrine entity jako doménové entity – Přímé přidávání DDD logiky do Doctrine entit je anti-vzor. Doctrine mapování (anotace, atributy) svazuje doménový objekt s infrastrukturní technologií. Oddělte doménové entity od persistence mapování.
CQRS bez doménového modelu – Zavedení CommandBusu a QueryBusu bez refaktorovaného doménového modelu přidá vrstvy komplexity bez přínosu. CQRS je amplifikátor – zesílí jak výhody, tak problémy stávající architektury.
Ignorování Anti-Corruption Layer – Při integraci nové DDD vrstvy se starým CRUD kódem je nutné vytvořit překladovou vrstvu. Bez ní pronikají koncepty starého modelu do nového a kontaminují ho.

Tipy pro týmovou komunikaci

Vytvořte glosář pojmů (Ubiquitous Language) a udržujte ho aktuální. Vyvěste ho na wiki nebo přímo v repozitáři jako součást dokumentace.
Pravidelně pořádejte krátká Event Storming sezení (30–60 minut) pro nové funkcionality před jejich implementací.
Nastavte code review pravidla: doménová logika nesmí být v kontrolerech, doménové objekty nesmějí záviset na infrastruktuře.
Komunikujte s managementem v pojmech obchodní hodnoty, nikoli technické architektury. Migrace na DDD = schopnost rychleji a bezpečněji přidávat nové funkce.

Realistické odhady náročnosti

Inkrementální migrace středně velké CRUD aplikace (50–100 tabulek, 3–5 let vývoje) na DDD trvá v praxi 12 až 24 měsíců. Číslo počítá s tím, že migrace běží souběžně s vývojem nových funkcí a nemá dedikovaný tým na plný úvazek. Co dobu prodlužuje: špatná testovatelnost stávajícího kódu (nutnost psát charakterizační testy), slabá znalost domény v týmu, chybějící doménoví experti.

! Pozor

Varování před Big Bang Rewrites

Nikdy nezačínejte migraci na DDD kompletním přepisem systému. Big Bang Rewrite je architektonicky nejrizikovější rozhodnutí, které tým může učinit. Typický scénář: tým začne „přepis na zelenou louku“. Po 6 měsících zjistí, že nový systém nesplňuje všechny okrajové případy původního systému (které nikdo nezdokumentoval). Původní systém mezitím dostává nové funkcionality a nový systém za ním nestíhá. Výsledkem je buď zrušení projektu přepisu, nebo spuštění nedokončeného systému s fatálními chybami.

Vždy preferujte inkrementální migraci pomocí Strangler Fig Patternu: zachovejte funkční systém v produkci, přidávejte DDD vrstvami a nahrazujte CRUD kód postupně při každém sprintu.

DDD koncepty a jejich implementaci v Symfony rozebírají navazující kapitoly Implementace DDD v Symfony a CQRS v Symfony.

18.09 Refaktoring kuchařka – krátké recepty

Strangler Fig je strategický pohled na celou migraci. V denní praxi narazíte na opakující se mikrosituace. Tato kuchařka obsahuje 8 nejčastějších, každá ve formátu „symptomy → krok 1, 2, 3“. Recepty jsou záměrně krátké – když potřebujete kontext nebo důkladnější rozbor, projděte odkazované kapitoly.

Recept 1: Anémická Doctrine entita

Symptomy: entita má jen gettery/settery, veškerá logika je v Service třídě.

Identifikujte invarianty entity (co nesmí být porušeno).
Pro každý invariant najděte metodu v *Service, která ho dnes drží.
Přesuňte metodu do entity, getter/setter zúžte na private nebo zrušte.
Service se stane tenkým koordinátorem (Application Service) – jen volá entitu, transakce, eventy.
Souvisí: Anti-vzor: Anemic Domain Model · Domain Services vs. Application Services.

Recept 2: Doctrine atributy v doménové třídě – kdy je to problém

Symptomy: App\Domain\Order má #[ORM\Entity], doména závisí na Doctrine.

Pragmatická výchozí volba v tomto průvodci atributy přijímá – jsou to metadata, ne chování, a Symfony ekosystém s nimi pracuje idiomaticky (viz rozhodnutí o mappingu). Pokud váš projekt skutečně potřebuje striktní oddělení (Hexagonal, dlouhodobá výměna ORM, core doména s vysokou hodnotou), postup je:

Zaveďte Persisted Object Pattern – doménová třída zůstane POPO, persistence model + mapper jdou do App\<BC>\Infrastructure\Persistence\Doctrine\.
Mapper hydratujte z perzistence přes User::reconstitute(...) factory metodu, která neemituje doménové události.
Hlídejte hranici staticky: composer require --dev phpat/phpat + rule App\<BC>\Domain\* nesmí závisět na Doctrine\*.

Recept 3: Primitivní ID jako `string` / `int`

Symptomy: Order::$id: string, kdekoli se předává jen string.

Zaveďte VO OrderId (final readonly class OrderId { public function __construct(public Ulid $value) {} }).
Doctrine custom type pro OrderId (mapping z DB string ↔ VO).
Postupně refaktorujte signature napříč handlery. PHPStan na úrovni 8 odhalí každý zapomenutý string.

Recept 4: Doctrine tabulka sdílená napříč BC

Symptomy: tabulka users se používá v Ordering BC i Billing BC; oba do ní zapisují.

Identifikujte vlastnícího BC (typicky Identity).
Ostatní BC do ní nesmí zapisovat – jen číst. Čtení přesuňte do read-modelů (každý BC má vlastní projekci).
Zápisy nahraďte voláním Identity API (sync HTTP nebo async event publishing s outboxem).
Souvisí: Outbox Pattern.

Recept 5: Doménová logika v controlleru

Symptomy: 200řádkový controller s if-else stromem doménových rozhodnutí.

Vytvořte Command DTO + CommandHandler v Application vrstvě.
Controller se zúží na: validate input → dispatch command → vrátit response.
Autorizaci přesuňte do Voteru (souvisí Autorizace).

Recept 6: Aggregate bobtná (1000+ řádků)

Symptomy: Order má 30 metod a 15 polí.

Najděte pole, která se mění nezávisle (různé invarianty, různé use cases).
Zvažte rozdělení na 2 agregáty (např. Order + OrderShipment). Spojí je sdílené OrderId, žádná silná reference.
Specifikační logiku vyextrahujte do Specification tříd (souvisí Specifications).

Recept 7: `eventDispatcher->dispatch()` uvnitř doménové metody

Symptomy: Aggregate volá Symfony EventDispatcher přímo.

Aggregate uchová eventy v private array $releasedEvents.
Aplikační handler po repository->save() volá $order->releaseEvents() a publikuje (přes outbox).
Doména ztratí závislost na Symfony EventDispatcheru. Test je čistý.
Souvisí: Outbox – Aggregate publikuje.

Recept 8: Stav je sloupec `string $status`

Symptomy: Order::$status: string, podmínky všude if ($order->status === 'PLACED').

Zaveďte enum (PHP 8.1+): enum OrderStatus: string { case PLACED = 'placed'; case CANCELLED = 'cancelled'; }.
Aggregate metody dělají transitions: $this->status = OrderStatus::CANCELLED.
Pro komplexní transition rules zvažte State Machine (Symfony Workflow component nebo doménová reprezentace).

Časté otázky

Jaké příznaky ukazují, že CRUD aplikace je zralá na migraci?

Typickými signály jsou God Services o stovkách řádků a kontrolery obsahující doménová pravidla. Dále doménová logika zamíchaná v Doctrine repozitářích, opakované regresní chyby při drobných změnách a rostoucí čas potřebný pro onboarding nových vývojářů. Pokud aplikace tyto příznaky nevykazuje a zůstává prostým mapováním formulářů na tabulky, migrace odpovídající hodnotu nepřinese. Obecnější otázku, pro jaké projekty je DDD vhodné, řeší samostatná kapitola Kdy DDD nepoužívat. Viz také sekci Kdy a proč migrovat.

Co je Strangler Fig Pattern?

Strangler Fig (fíkovník škrtič) je migrační vzor popsaný Martinem Fowlerem, při kterém nová architektura postupně „obroste“ starý systém a nahradí ho po částech. Nová funkcionalita vzniká od začátku v DDD stylu, zatímco stará CRUD část zůstává v provozu a s každou iterací ubývá. Obě části existují paralelně a propojují se přes Anti-Corruption Layer. Podrobný rozbor v sekci Strangler Fig Pattern.

Jak začít s analýzou existující domény?

Začíná se Event Stormingem nebo obdobnou kolaborativní technikou s doménovými experty – zmapují se hlavní události, commands a aktéři. Z této mapy vyplývá návrh Bounded Contexts a Ubiquitous Language. Paralelně se v existujícím kódu hledají implicitní hranice modelu: moduly, tabulky nebo funkční celky, které jsou málo propojené. Cílem první iterace je hrubá mapa, ne úplný model. Praktický postup v sekci Analýza existující domény.

Jak extrahovat doménovou vrstvu z existujícího CRUD kódu?

Migrace začíná u jednoho vybraného Bounded Contextu, pro který vzniká nová doménová vrstva oddělená od Doctrine entit. Doménová logika ze service tříd a kontrolerů se přesouvá do metod agregátu, zatímco původní CRUD kód zůstává jako adaptér pro API a persistenci. Nejprve se zavede Anti-Corruption Layer, pak se refaktorují jednotlivé use casy. Charakterizační testy proti původnímu chování minimalizují regrese. Detailní rozbor v sekci Extrakce doménové vrstvy.

Jaká jsou hlavní rizika migrace z CRUD na DDD a jak je zmírnit?

Nejčastější pastí je anémický model: nové třídy mají DDD názvy, ale logika zůstává v servisech. Dále hrozí nadměrná granularita Bounded Contexts, přímé ukládání doménové logiky do Doctrine entit a zavádění CQRS bez přepracovaného modelu. Největším rizikem je Big Bang Rewrite, který se zřídka dotáhne do konce. Migrace má probíhat inkrementálně přes Strangler Fig, u středně velké aplikace s realistickým odhadem 12–24 měsíců. Rozbor rizik a zmírňujících opatření v sekci Rizika a doporučení.

18.01 Kdy a proč migrovat z CRUD na DDD

Kdy DDD přináší hodnotu a kdy je CRUD dostačující

Realistické zhodnocení nákladů migrace

18.02 Strangler Fig Pattern – vzor postupné náhrady

Výhody oproti přímé refaktorizaci (Big Bang Rewrite)

18.03 Krok 1: Analýza existující domény

Identifikace Bounded Contexts z existujícího CRUD kódu

Event Storming jako nástroj pro analýzu

18.04 Krok 2: Extrakce doménové vrstvy

Přesunutí doménových pravidel do doménových objektů

Zavedení Value Objects místo primitive types

18.05 Krok 3: Zavedení repozitářů

Vytvoření doménového rozhraní repozitáře

18.06 Krok 4: Postupné zavedení CQRS

Začít s Command stranou (write side)

18.07 Testování při migraci

Charakterizační testy (Characterization Tests)

Unit testy doménové vrstvy

18.08 Rizika a doporučení

Nejčastější chyby při migraci

Tipy pro týmovou komunikaci

Realistické odhady náročnosti

18.09 Refaktoring kuchařka – krátké recepty

Recept 1: Anémická Doctrine entita

Recept 2: Doctrine atributy v doménové třídě – kdy je to problém

Recept 3: Primitivní ID jako string / int

Recept 4: Doctrine tabulka sdílená napříč BC

Recept 5: Doménová logika v controlleru

Recept 6: Aggregate bobtná (1000+ řádků)

Recept 7: eventDispatcher->dispatch() uvnitř doménové metody

Recept 8: Stav je sloupec string $status

Časté otázky

Recept 3: Primitivní ID jako `string` / `int`

Recept 7: `eventDispatcher->dispatch()` uvnitř doménové metody

Recept 8: Stav je sloupec `string $status`