SuperAPI AI Directory

domain-modeling

Coding & development

View repository

Updated 10-16 09:56

About this skill

Domain Modeling

References: Eric Evans "Domain-Driven Design", Vaughn Vernon "Implementing DDD", Martin Fowler rich model / anemic model, Robert Martin Clean Architecture.

Applicable Scenarios

  • Complex business rules need clear modeling
  • State transitions / workflows (orders / approvals / payments)
  • Multiple business methods involve the same object
  • Prevent business logic from scattering into Service / Controller
  • Refactor an anemic model into a rich model

Core Principles

1. 业务规则放进 Domain Model
   不放 Controller,不放 Service,不放 Repository
  1. Entity vs Value Object Entity: has a unique identity (ID), mutable Value Object: no identity, immutable, compared by attributes

  2. Aggregate Root External access to entities within an aggregate is only allowed through the aggregate root One transaction modifies only one aggregate

  3. Business Invariants Ensure the object satisfies business rules at all times Constructors / factory methods enforce validation

  4. Imperative → Business naming ❌ user.setStatus("active") ✅ user.activate()

  5. Use a state machine for state transitions Express state transitions with methods Throw an exception for illegal transitions

  6. Do not depend on frameworks The Domain layer should be able to compile and run independently


## 充血模型 vs 贫血模型

### 贫血模型(反模式,常见)

```java
// Order 只是数据容器
public class Order {
  private Long id;
  private String status;
  private BigDecimal totalAmount;
  // 全是 getter / setter
}

// 业务逻辑全在 Service
public class OrderService {
  public void cancelOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    if (!order.getStatus().equals("paid")) {
      throw new IllegalStateException("...");
    }
    if (order.getCreatedAt().isBefore(now().minusDays(7))) {
      throw new IllegalStateException("...");
    }
    order.setStatus("cancelled");
    order.setCancelledAt(now());
    orderRepository.save(order);
  }
}

Problem:

  • Business rules are scattered
  • The same rule is implemented in multiple places
  • Easy to bypass (order.setStatus("cancelled") called directly)

Rich Model (Recommended)

public class Order {
  private Long id;
  private OrderStatus status;
  private BigDecimal totalAmount;
  private LocalDateTime createdAt;
  private LocalDateTime cancelledAt;
  
  // 私有构造,强制使用工厂方法
  private Order() {}
  
  public static Order create(User user, List<OrderItem> items) {
    if (items.isEmpty()) {
      throw new IllegalArgumentException("Order must have at least one item");
    }
    Order order = new Order();
    order.status = OrderStatus.DRAFT;
    order.totalAmount = items.stream()
        .map(OrderItem::getSubtotal)
        .reduce(BigDecimal.ZERO, BigDecimal::add);
    order.createdAt = LocalDateTime.now();
    return order;
  }
  
  // 业务方法(不是 setStatus)
  public void cancel() {
    if (this.status != OrderStatus.PAID) {
      throw new IllegalStateException("Only paid orders can be cancelled");
    }
    if (this.createdAt.isBefore(LocalDateTime.now().minusDays(7))) {
      throw new IllegalStateException("Cancellation window has expired");
    }
    this.status = OrderStatus.CANCELLED;
    this.cancelledAt = LocalDateTime.now();
  }
  
  public void pay() {
    if (this.status != OrderStatus.SUBMITTED) {
      throw new IllegalStateException("Only submitted orders can be paid");
    }
    this.status = OrderStatus.PAID;
  }
  
  // 没有 setStatus(),无法绕过业务规则
}
// Service 变薄,编排为主
public class OrderService {
  public void cancelOrder(Long orderId) {
    Order order = orderRepository.findById(orderId).orElseThrow();
    order.cancel();  // 业务规则由 Order 自己保证
    orderRepository.save(order);
  }
}

Entity vs Value Object

Entity

public class User {
  private Long id;          // 唯一身份
  private String email;
  private String name;
  // ...
  
  // 相等性靠 ID
  @Override
  public boolean equals(Object o) {
    if (!(o instanceof User other)) return false;
    return id != null && id.equals(other.id);
  }
}

Value Object

// 不可变 + 靠属性比较
public record Money(BigDecimal amount, String currency) {
  public Money {
    if (amount.signum() < 0) {
      throw new IllegalArgumentException("Amount cannot be negative");
    }
    if (currency == null || currency.length() != 3) {
      throw new IllegalArgumentException("Currency must be ISO 4217");
    }
  }
  
  public Money add(Money other) {
    if (!this.currency.equals(other.currency)) {
      throw new IllegalStateException("Currency mismatch");
    }
    return new Money(this.amount.add(other.amount), this.currency);
  }
}

// 用法
Money price = new Money(new BigDecimal("99.99"), "USD");
Money total = price.add(shipping);  // 返回新对象,原对象不变

When to Use Which

有唯一身份(用户、订单、产品) → 实体
描述属性(金额、地址、日期范围、坐标) → 值对象
身份不可变(一旦创建就不变) → 值对象
状态会变化(订单状态、用户状态) → 实体

Aggregate

// 订单聚合:Order 是聚合根,OrderItem 在聚合内
public class Order {
  private Long id;
  private List<OrderItem> items = new ArrayList<>();
  
  public void addItem(Product product, int quantity) {
    if (this.status != OrderStatus.DRAFT) {
      throw new IllegalStateException("Cannot modify non-draft order");
    }
    this.items.add(new OrderItem(product, quantity));
    recalculateTotal();
  }
  
  public void removeItem(Long itemId) {
    if (this.status != OrderStatus.DRAFT) {
      throw new IllegalStateException("Cannot modify non-draft order");
    }
    this.items.removeIf(i -> i.getId().equals(itemId));
    recalculateTotal();
  }
  
  // OrderItem 不能被外部直接 new 或修改
  // 必须通过 Order 的方法
}

Aggregate Rules:

  • External code holds a reference to the aggregate root, not directly to internal entities
  • One transaction modifies only one aggregate
  • Aggregates are associated by ID, not by directly holding references

State Machine Pattern

public enum OrderStatus {
  DRAFT,
  SUBMITTED,
  PAID,
  SHIPPED,
  DELIVERED,
  CANCELLED,
  REFUNDED;
}

public class Order {
  // 状态转换规则集中在一处
  private static final Map<OrderStatus, Set<OrderStatus>> ALLOWED_TRANSITIONS = Map.of(
    OrderStatus.DRAFT, Set.of(OrderStatus.SUBMITTED, OrderStatus.CANCELLED),
    OrderStatus.SUBMITTED, Set.of(OrderStatus.PAID, OrderStatus.CANCELLED),
    OrderStatus.PAID, Set.of(OrderStatus.SHIPPED, OrderStatus.REFUNDED),
    OrderStatus.SHIPPED, Set.of(OrderStatus.DELIVERED),
    OrderStatus.DELIVERED, Set.of(OrderStatus.REFUNDED)
    // CANCELLED / REFUNDED 是终态
  );
  
  private void transitionTo(OrderStatus newStatus) {
    Set<OrderStatus> allowed = ALLOWED_TRANSITIONS.getOrDefault(this.status, Set.of());
    if (!allowed.contains(newStatus)) {
      throw new IllegalStateException(
        String.format("Cannot transition from %s to %s", this.status, newStatus)
      );
    }
    this.status = newStatus;
  }
  
  public void submit() { transitionTo(OrderStatus.SUBMITTED); }
  public void pay() { transitionTo(OrderStatus.PAID); }
  public void ship() { transitionTo(OrderStatus.SHIPPED); }
  public void deliver() { transitionTo(OrderStatus.DELIVERED); }
}

TypeScript Paradigm

// Value Object
export class Money {
  constructor(
    public readonly amount: number,
    public readonly currency: string,
  ) {
    if (amount < 0) throw new Error('Amount cannot be negative');
    if (currency.length !== 3) throw new Error('Currency must be ISO 4217');
  }
  
  add(other: Money): Money {
    if (this.currency !== other.currency) throw new Error('Currency mismatch');
    return new Money(this.amount + other.amount, this.currency);
  }
  
  equals(other: Money): boolean {
    return this.amount === other.amount && this.currency === other.currency;
  }
}

// Entity
export class Order {
  private constructor(
    public readonly id: number,
    private _status: OrderStatus,
    private _items: OrderItem[],
    private _total: Money,
  ) {}
  
  static create(items: OrderItem[]): Order {
    if (items.length === 0) throw new Error('Order must have items');
    const total = items.reduce(
      (sum, item) => sum.add(item.subtotal),
      new Money(0, items[0].currency),
    );
    return new Order(0, OrderStatus.DRAFT, items, total);
  }
  
  get status(): OrderStatus { return this._status; }
  
  cancel(): void {
    if (this._status !== OrderStatus.PAID) {
      throw new Error('Only paid orders can be cancelled');
    }
    this._status = OrderStatus.CANCELLED;
  }
}

Python Paradigm

from dataclasses import dataclass, field
from datetime import datetime
from enum import Enum

class OrderStatus(Enum):
    DRAFT = 'DRAFT'
    SUBMITTED = 'SUBMITTED'
    PAID = 'PAID'
    CANCELLED = 'CANCELLED'

# Value Object
@dataclass(frozen=True)
class Money:
    amount: Decimal
    currency: str
    
    def __post_init__(self):
        if self.amount < 0:
            raise ValueError('Amount cannot be negative')
        if len(self.currency) != 3:
            raise ValueError('Currency must be ISO 4217')
    
    def add(self, other: 'Money') -> 'Money':
        if self.currency != other.currency:
            raise ValueError('Currency mismatch')
        return Money(self.amount + other.amount, self.currency)

# Entity
@dataclass
class Order:
    id: int
    status: OrderStatus = OrderStatus.DRAFT
    items: list = field(default_factory=list)
    total: Money = None
    created_at: datetime = field(default_factory=datetime.utcnow)
    
    @classmethod
    def create(cls, items):
        if not items:
            raise ValueError('Order must have items')
        return cls(id=0, items=items, total=sum_items(items))
    
    def cancel(self):
        if self.status != OrderStatus.PAID:
            raise ValueError('Only paid orders can be cancelled')
        self.status = OrderStatus.CANCELLED

Go Paradigm

package model

type OrderStatus string

const (
    OrderStatusDraft     OrderStatus = "DRAFT"
    OrderStatusSubmitted OrderStatus = "SUBMITTED"
    OrderStatusPaid      OrderStatus = "PAID"
    OrderStatusCancelled OrderStatus = "CANCELLED"
)

// Value Object
type Money struct {
    Amount   int64  // 分
    Currency string
}

func NewMoney(amount int64, currency string) (Money, error) {
    if amount < 0 {
        return Money{}, errors.New("amount cannot be negative")
    }
    if len(currency) != 3 {
        return Money{}, errors.New("currency must be ISO 4217")
    }
    return Money{Amount: amount, Currency: currency}, nil
}

func (m Money) Add(other Money) (Money, error) {
    if m.Currency != other.Currency {
        return Money{}, errors.New("currency mismatch")
    }
    return Money{Amount: m.Amount + other.Amount, Currency: m.Currency}, nil
}

// Entity
type Order struct {
    id     int64
    status OrderStatus
    items  []OrderItem
    total  Money
}

func NewOrder(items []OrderItem) (*Order, error) {
    if len(items) == 0 {
        return nil, errors.New("order must have items")
    }
    return &Order{
        status: OrderStatusDraft,
        items:  items,
    }, nil
}

func (o *Order) Cancel() error {
    if o.status != OrderStatusPaid {
        return errors.New("only paid orders can be cancelled")
    }
    o.status = OrderStatusCancelled
    return nil
}

Workflow

1. 识别业务实体(与 PM 沟通)
   ↓
2. 区分实体 vs 值对象
   ↓
3. 识别聚合(事务边界)
   ↓
4. 列业务不变量
   - 哪些规则任何时候都成立
   ↓
5. 列状态机(状态 + 转换)
   ↓
6. 用充血模型实现
   - 私有构造 + 工厂方法
   - 业务方法替代 setter
   - 不变量在构造时校验
   ↓
7. 写单元测试(核心)
   - 业务规则测试
   - 状态转换测试
   - 不变量违反测试
   ↓
8. Service 层只做编排

Supporting Templates

  • templates/domain-model-template.md — Entity + Value Object + Aggregate + State Machine + Invariants + Business Methods + Tests

Quality Self-Check

□ 实体 vs 值对象 区分清楚
□ 聚合根明确
□ 业务规则在 Domain,不在 Service
□ 用业务方法名(cancel/pay)替代 setter
□ 私有构造 + 工厂方法
□ 不变量在构造时校验
□ 状态机定义所有合法转换
□ 非法状态转换抛异常
□ 值对象不可变
□ 聚合事务边界 = 一个聚合
□ Domain 层不依赖框架
□ 单元测试覆盖业务规则

Common Pitfalls

  1. Anemic model——business logic is all in Service, Domain degenerates into a data container
  2. Exposing setters——bypasses business rules
  3. Using float for money——precision issues
  4. Using String for state——not compile-time safe
  5. State transitions are scattered——the same rule is implemented in multiple places
  6. Aggregate transaction spans multiple aggregates——consistency is hard to guarantee
  7. Mutable value objects——corrupted when shared
  8. Business rules in Controller——duplication / hard to test
  9. Constructor does not validate invariants——illegal objects can be created
  10. Domain depends on Spring/NestJS——loses independence

Collaboration with Other Skills

上游:
  product-manager 工作流 → 业务实体 / 状态 / 规则
  database 工作流 → 数据模型映射

下游:
  api-implementation → Service 编排 Domain
  data-access → Domain ↔ ORM 映射
  testing-implementation → 单元测试 Domain

Related References

  • Project root references/backend-frameworks-2026.md — The relationship between frameworks and modeling styles