Domain-Driven Design

// ❌ BAD — anemic model, no invariant enforcement, no typed IDs, no events

@Entity
@Data                                        // generates public setters — anyone can mutate state
@NoArgsConstructor                           // public no-arg constructor allows invalid objects
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;                         // Long ID — not a typed value object

    private Long customerId;                 // Long — should be CustomerId value object

    private String customerEmail;            // raw String — should be EmailAddress value object

    @Enumerated(EnumType.ORDINAL)            // ORDINAL breaks if enum is reordered
    private OrderStatus status;

    private BigDecimal total;                // raw BigDecimal — should be Money value object

    @OneToMany(mappedBy = "order")           // missing cascade, orphanRemoval
    private List<OrderItem> items;           // not initialized — NPE risk

    // No behavior methods — all logic will live in service:
    // - No addItem() method
    // - No place() method
    // - No state transition validation
    // - No domain events
    // - Total is set manually from outside, not calculated

    // External code does:
    // order.getItems().add(new OrderItem(...));  // bypasses aggregate boundary
    // order.setStatus(OrderStatus.PLACED);       // no invariant check
    // order.setTotal(calculateTotal(items));      // logic outside domain
}

// ✅ GOOD — rich domain model, typed IDs, behavior methods, domain events, no public setters

public class Order {

    private final OrderId id;
    private final CustomerId customerId;
    private final EmailAddress customerEmail;
    private final Currency currency;
    private OrderStatus status;
    private Money total;
    private final List<OrderItem> items = new ArrayList<>();
    @Transient
    private final List<Object> domainEvents = new ArrayList<>();

    private Order(OrderId id, CustomerId customerId, EmailAddress customerEmail, Currency currency) {
        this.id = Objects.requireNonNull(id);
        this.customerId = Objects.requireNonNull(customerId);
        this.customerEmail = Objects.requireNonNull(customerEmail);
        this.currency = Objects.requireNonNull(currency);
        this.status = OrderStatus.DRAFT;
        this.total = Money.zero(currency);
    }

    // Static factory — enforces valid initial state
    public static Order create(CustomerId customerId, EmailAddress email, Currency currency) {
        return new Order(OrderId.generate(), customerId, email, currency);
    }

    // Behavior methods enforce invariants
    public void addItem(ProductId productId, String name, int quantity, Money unitPrice) {
        if (status != OrderStatus.DRAFT)
            throw new OrderNotModifiableException(id);
        if (quantity <= 0)
            throw new InvalidQuantityException(quantity);
        if (!unitPrice.currency().equals(currency))
            throw new CurrencyMismatchException(currency, unitPrice.currency());
        items.add(new OrderItem(productId, name, quantity, unitPrice));
        recalculateTotal();
    }

    public void place() {
        if (items.isEmpty())
            throw new EmptyOrderException(id);
        if (status != OrderStatus.DRAFT)
            throw new IllegalOrderStateTransitionException(status, OrderStatus.PLACED);
        this.status = OrderStatus.PLACED;
        domainEvents.add(OrderPlaced.of(this));
    }

    public void cancel(String reason) {
        if (status == OrderStatus.SHIPPED || status == OrderStatus.DELIVERED)
            throw new IllegalOrderStateTransitionException(status, OrderStatus.CANCELLED);
        this.status = OrderStatus.CANCELLED;
        domainEvents.add(new OrderCancelled(id, customerId, reason, Instant.now()));
    }

    public List<Object> pullDomainEvents() {
        var events = List.copyOf(domainEvents);
        domainEvents.clear();
        return events;
    }

    private void recalculateTotal() {
        this.total = items.stream()
            .map(OrderItem::lineTotal)
            .reduce(Money.zero(currency), Money::add);
    }

    // No public setters — state changes only through behavior methods
    public OrderId getId() { return id; }
    public CustomerId getCustomerId() { return customerId; }
    public OrderStatus getStatus() { return status; }
    public Money getTotal() { return total; }
    public List<OrderItem> getItems() { return Collections.unmodifiableList(items); }
}

// Typed ID — value object
public record OrderId(UUID value) {
    public static OrderId generate() { return new OrderId(UUID.randomUUID()); }
    public static OrderId of(UUID value) { return new OrderId(Objects.requireNonNull(value)); }
}

package com.example.common.domain;

import java.time.Instant;
import java.util.UUID;

/**
 * Base interface for all domain events.
 * Events are immutable facts about something that happened in the domain.
 */
public interface DomainEvent {
    UUID eventId();
    Instant occurredAt();
}

// --- Concrete domain events as records ---

package com.example.order.domain.event;

import com.example.common.domain.DomainEvent;
import com.example.order.domain.model.CustomerId;
import com.example.order.domain.model.Money;
import com.example.order.domain.model.OrderId;

import java.time.Instant;
import java.util.UUID;

public record OrderPlaced(
    UUID eventId,
    Instant occurredAt,
    OrderId orderId,
    CustomerId customerId,
    Money total
) implements DomainEvent {

    public static OrderPlaced of(Order order) {
        return new OrderPlaced(
            UUID.randomUUID(),
            Instant.now(),
            order.getId(),
            order.getCustomerId(),
            order.getTotal()
        );
    }
}

public record OrderCancelled(
    UUID eventId,
    Instant occurredAt,
    OrderId orderId,
    CustomerId customerId,
    String reason
) implements DomainEvent {

    public OrderCancelled(OrderId orderId, CustomerId customerId, String reason, Instant occurredAt) {
        this(UUID.randomUUID(), occurredAt, orderId, customerId, reason);
    }
}

package com.example.common.domain;

import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.Currency;
import java.util.Objects;

/**
 * Value object representing monetary amount with currency.
 * Immutable — all operations return new instances.
 */
public record Money(BigDecimal amount, Currency currency) {

    // No shared ZERO constant: a USD zero silently breaks every non-USD aggregate
    // the first time it is used as a starting total or a reduce() identity.
    public static Money zero(Currency currency) {
        return new Money(BigDecimal.ZERO, currency);
    }

    public Money {
        Objects.requireNonNull(amount, "Amount must not be null");
        Objects.requireNonNull(currency, "Currency must not be null");
        if (amount.compareTo(BigDecimal.ZERO) < 0)
            throw new IllegalArgumentException("Amount cannot be negative: " + amount);
        // Scale to the currency (JPY 0, EUR 2, BHD 3) and refuse to round: losing
        // precision in a money value must fail loudly, never happen silently.
        amount = amount.setScale(currency.getDefaultFractionDigits(), RoundingMode.UNNECESSARY);
    }

    public static Money of(BigDecimal amount, Currency currency) {
        return new Money(amount, currency);
    }

    public static Money of(String amount, String currencyCode) {
        return new Money(new BigDecimal(amount), Currency.getInstance(currencyCode));
    }

    public static Money usd(String amount) {
        return of(amount, "USD");
    }

    public Money add(Money other) {
        assertSameCurrency(other);
        return new Money(amount.add(other.amount), currency);
    }

    public Money subtract(Money other) {
        assertSameCurrency(other);
        BigDecimal result = amount.subtract(other.amount);
        if (result.compareTo(BigDecimal.ZERO) < 0)
            throw new IllegalArgumentException("Result would be negative");
        return new Money(result, currency);
    }

    public Money multiply(int quantity) {
        return new Money(amount.multiply(BigDecimal.valueOf(quantity)), currency);
    }

    public boolean isGreaterThan(Money other) {
        assertSameCurrency(other);
        return amount.compareTo(other.amount) > 0;
    }

    private void assertSameCurrency(Money other) {
        if (!currency.equals(other.currency))
            throw new IllegalArgumentException(
                "Currency mismatch: %s vs %s".formatted(currency, other.currency));
    }

    @Override
    public String toString() {
        return "%s %s".formatted(currency.getCurrencyCode(), amount);
    }
}