ddd-architecture（ddd 架构）

Domain-Driven Design (DDD) Architecture

Rules

Layered Architecture

• Use four-layer architecture: Presentation → Application → Domain ← Infrastructure
• Domain layer MUST be pure TypeScript with NO framework dependencies
• ALL dependencies point inward toward the Domain layer
• Do NOT allow Domain layer to depend on Application, Infrastructure, or Presentation

Dependency Direction

• Presentation MAY depend on Application and Shared layers
• Application MAY depend on Domain and Shared layers
• Infrastructure MUST depend ONLY on Domain layer interfaces
• Domain MUST NOT depend on any other layer

Domain Layer - Entities

• Use entities for objects with identity and lifecycle
• Encapsulate business logic in entity methods
• Use private fields with getters (NO public setters)
• Implement factory methods (e.g., static create()) for entity creation
• Raise domain events when state changes occur
• Do NOT expose internal state through public setters

Domain Layer - Value Objects

• Use value objects for concepts without identity
• Make value objects IMMUTABLE (readonly fields, private constructor)
• Implement validation in static factory method (e.g., static create())
• Implement equals() method for value-based equality comparison
• Do NOT create value objects without validation

Domain Layer - Aggregates

• Use aggregates as consistency boundaries for related entities
• Enforce business invariants across all entities in the aggregate
• Access entities ONLY through the aggregate root
• Do NOT allow direct access to entities within an aggregate

Domain Layer - Domain Events

• Raise domain events for business-significant occurrences
• Store events in entity's internal _domainEvents array
• Include eventId, occurredOn, and eventType in all events
• Clear events after publishing via clearDomainEvents()

Domain Layer - Repository Interfaces

• Define repository interfaces in the Domain layer
• Use Observable return types for async operations
• Use domain entities and value objects in method signatures
• Do NOT implement repositories in the Domain layer

Application Layer

• Orchestrate domain objects and infrastructure in application services
• Use command/query pattern for use case operations
• Publish domain events after persisting entities
• Do NOT put business logic in application services (belongs in Domain)

Infrastructure Layer - Repository Implementation

• Implement domain repository interfaces in Infrastructure layer
• Convert between domain entities and persistence models
• Use toDomain() method to map persistence data to domain entities
• Use toFirestore() (or similar) method to map domain entities to persistence
• Do NOT expose persistence details to Domain or Application layers

Testing

• Test domain entities and value objects independently (unit tests)
• Test invariants and business rules in domain layer
• Mock repository interfaces when testing application services
• Test domain event generation and clearing

Context

When to Use This Skill

Activate this skill when you need to:

• Design domain models with aggregates and entities
• Implement value objects and domain events
• Define repository interfaces and domain services
• Establish bounded contexts and ubiquitous language
• Enforce layer dependencies (Domain ← Application ← Infrastructure ← Presentation)
• Apply tactical DDD patterns (specifications, factories, domain events)
• Implement strategic DDD patterns (context mapping, anti-corruption layers)
• Migrate from anemic domain models to rich domain models

Core DDD Concepts

Layered Architecture

┌─────────────────────────────────────────┐
│      Presentation Layer (UI)            │  Angular Components
│      src/app/presentation/              │
└──────────────┬──────────────────────────┘
               │ depends on
┌──────────────▼──────────────────────────┐
│      Application Layer                  │  Use Cases, Stores
│      src/app/application/               │
└──────────────┬──────────────────────────┘
               │ depends on
┌──────────────▼──────────────────────────┐
│      Domain Layer (Business Logic)      │  Pure TypeScript
│      src/app/domain/                    │
└──────────────▲──────────────────────────┘
               │ implements
┌──────────────┴──────────────────────────┐
│      Infrastructure Layer               │  Firebase, External APIs
│      src/app/infrastructure/            │
└─────────────────────────────────────────┘

Dependency Rules

Golden Rule: Dependencies point inward, never outward.

• ✅ Presentation → Application → Domain
• ✅ Infrastructure → Domain (implements interfaces)
• ❌ Domain → Application
• ❌ Domain → Infrastructure
• ❌ Domain → Presentation

Domain Layer

Entities

Entities have identity and lifecycle. Use for objects that need to be tracked over time.

// src/app/domain/workspace/entities/workspace.entity.ts
import { WorkspaceId } from '../value-objects/workspace-id.value-object';
import { WorkspaceName } from '../value-objects/workspace-name.value-object';
import { WorkspaceCreatedEvent } from '../events/workspace-created.event';
import { DomainEvent } from '@domain/shared/domain-event';

export class Workspace {
  private readonly _id: WorkspaceId;
  private _name: WorkspaceName;
  private _ownerId: string;
  private _createdAt: Date;
  private _updatedAt: Date;
  private _domainEvents: DomainEvent[] = [];

  constructor(props: {
    id: WorkspaceId;
    name: WorkspaceName;
    ownerId: string;
    createdAt?: Date;
    updatedAt?: Date;
  }) {
    this._id = props.id;
    this._name = props.name;
    this._ownerId = props.ownerId;
    this._createdAt = props.createdAt ?? new Date();
    this._updatedAt = props.updatedAt ?? new Date();
  }

  // Factory method
  static create(props: { name: string; ownerId: string }): Workspace {
    const workspace = new Workspace({
      id: WorkspaceId.create(),
      name: WorkspaceName.create(props.name),
      ownerId: props.ownerId
    });

    // Raise domain event
    workspace.addDomainEvent(new WorkspaceCreatedEvent(workspace.id.value, workspace.name.value));

    return workspace;
  }

  // Getters (no setters - mutations via methods only)
  get id(): WorkspaceId { return this._id; }
  get name(): WorkspaceName { return this._name; }
  get ownerId(): string { return this._ownerId; }
  get createdAt(): Date { return this._createdAt; }
  get domainEvents(): DomainEvent[] { return this._domainEvents; }

  // Business methods encapsulate domain logic
  rename(newName: string): void {
    const oldName = this._name.value;
    this._name = WorkspaceName.create(newName);
    this._updatedAt = new Date();

    this.addDomainEvent(new WorkspaceRenamedEvent(this.id.value, oldName, newName));
  }

  // Invariant: Only owner can perform certain actions
  validateOwnership(userId: string): void {
    if (this._ownerId !== userId) {
      throw new Error('Only the owner can perform this action');
    }
  }

  private addDomainEvent(event: DomainEvent): void {
    this._domainEvents.push(event);
  }

  clearDomainEvents(): void {
    this._domainEvents = [];
  }
}

Value Objects

Value objects have no identity, only value. They are immutable and equality is based on value.

// src/app/domain/workspace/value-objects/workspace-name.value-object.ts
export class WorkspaceName {
  private readonly _value: string;

  private constructor(value: string) {
    this._value = value;
  }

  static create(value: string): WorkspaceName {
    // Validation rules
    if (!value || value.trim().length === 0) {
      throw new Error('Workspace name cannot be empty');
    }
    if (value.length > 100) {
      throw new Error('Workspace name cannot exceed 100 characters');
    }
    if (!/^[\w\s-]+$/.test(value)) {
      throw new Error('Workspace name contains invalid characters');
    }

    return new WorkspaceName(value.trim());
  }

  get value(): string {
    return this._value;
  }

  // Value objects are compared by value, not reference
  equals(other: WorkspaceName): boolean {
    return this._value === other._value;
  }

  toString(): string {
    return this._value;
  }
}

// src/app/domain/workspace/value-objects/workspace-id.value-object.ts
import { v4 as uuidv4 } from 'uuid';

export class WorkspaceId {
  private readonly _value: string;

  private constructor(value: string) {
    this._value = value;
  }

  static create(): WorkspaceId {
    return new WorkspaceId(uuidv4());
  }

  static fromString(value: string): WorkspaceId {
    if (!this.isValid(value)) {
      throw new Error('Invalid workspace ID format');
    }
    return new WorkspaceId(value);
  }

  private static isValid(value: string): boolean {
    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
    return uuidRegex.test(value);
  }

  get value(): string {
    return this._value;
  }

  equals(other: WorkspaceId): boolean {
    return this._value === other._value;
  }
}

Aggregates

Aggregates are consistency boundaries. They group entities and value objects that must be consistent together.

// src/app/domain/workspace/aggregates/workspace.aggregate.ts
import { Workspace } from '../entities/workspace.entity';
import { WorkspaceMember } from '../entities/workspace-member.entity';
import { MemberRole } from '../enums/member-role.enum';

export class WorkspaceAggregate {
  private readonly _workspace: Workspace;
  private readonly _members: WorkspaceMember[] = [];

  constructor(workspace: Workspace, members: WorkspaceMember[] = []) {
    this._workspace = workspace;
    this._members = members;
  }

  get workspace(): Workspace {
    return this._workspace;
  }

  get members(): ReadonlyArray<WorkspaceMember> {
    return this._members;
  }

  // Aggregate root enforces invariants across all entities
  addMember(userId: string, role: MemberRole, addedBy: string): void {
    // Invariant: Only admins or owner can add members
    const adder = this.findMember(addedBy);
    if (!adder || (!adder.isAdmin() && !this.isOwner(addedBy))) {
      throw new Error('Only admins or owner can add members');
    }

    // Invariant: Cannot add duplicate members
    if (this.findMember(userId)) {
      throw new Error('User is already a member');
    }

    // Invariant: Maximum members limit
    if (this._members.length >= 50) {
      throw new Error('Workspace has reached maximum member limit');
    }

    const member = WorkspaceMember.create({
      workspaceId: this._workspace.id.value,
      userId,
      role
    });

    this._members.push(member);
  }

  removeMember(userId: string, removedBy: string): void {
    // Invariant: Cannot remove the owner
    if (this.isOwner(userId)) {
      throw new Error('Cannot remove workspace owner');
    }

    // Invariant: Only admins or owner can remove members
    const remover = this.findMember(removedBy);
    if (!remover || (!remover.isAdmin() && !this.isOwner(removedBy))) {
      throw new Error('Only admins or owner can remove members');
    }

    const index = this._members.findIndex(m => m.userId === userId);
    if (index === -1) {
      throw new Error('Member not found');
    }

    this._members.splice(index, 1);
  }

  private findMember(userId: string): WorkspaceMember | undefined {
    return this._members.find(m => m.userId === userId);
  }

  private isOwner(userId: string): boolean {
    return this._workspace.ownerId === userId;
  }
}

Domain Events

Domain events capture business-significant occurrences.

// src/app/domain/shared/domain-event.ts
export interface DomainEvent {
  readonly eventId: string;
  readonly occurredOn: Date;
  readonly eventType: string;
}

export abstract class BaseDomainEvent implements DomainEvent {
  readonly eventId: string;
  readonly occurredOn: Date;
  readonly eventType: string;

  protected constructor(eventType: string) {
    this.eventId = uuidv4();
    this.occurredOn = new Date();
    this.eventType = eventType;
  }
}

// src/app/domain/workspace/events/workspace-created.event.ts
import { BaseDomainEvent } from '@domain/shared/domain-event';

export class WorkspaceCreatedEvent extends BaseDomainEvent {
  constructor(
    public readonly workspaceId: string,
    public readonly name: string
  ) {
    super('WorkspaceCreated');
  }
}

Repository Interfaces

Repositories are defined as interfaces in the domain layer and implemented in infrastructure.

// src/app/domain/repositories/workspace.repository.ts
import { Observable } from 'rxjs';
import { Workspace } from '../workspace/entities/workspace.entity';
import { WorkspaceId } from '../workspace/value-objects/workspace-id.value-object';

export interface IWorkspaceRepository {
  findById(id: WorkspaceId): Observable<Workspace | null>;
  findByOwnerId(ownerId: string): Observable<Workspace[]>;
  save(workspace: Workspace): Observable<Workspace>;
  delete(id: WorkspaceId): Observable<void>;
}

Domain Services

Domain services contain business logic that doesn't naturally fit in an entity or value object.

// src/app/domain/services/workspace-guard.service.ts
export interface IWorkspaceGuardService {
  canUserAccessWorkspace(userId: string, workspaceId: string): Observable<boolean>;
  getUserPermissions(userId: string, workspaceId: string): Observable<string[]>;
}

Application Layer

Application Services

Application services orchestrate domain objects and infrastructure.

// src/app/application/services/workspace.service.ts
import { Injectable, inject } from '@angular/core';
import { Observable } from 'rxjs';
import { map, tap } from 'rxjs/operators';
import { IWorkspaceRepository } from '@domain/repositories/workspace.repository';
import { Workspace } from '@domain/workspace/entities/workspace.entity';
import { WorkspaceId } from '@domain/workspace/value-objects/workspace-id.value-object';
import { DomainEventPublisher } from '@infrastructure/events/domain-event-publisher';

@Injectable({ providedIn: 'root' })
export class WorkspaceService {
  private readonly repository = inject(IWorkspaceRepository);
  private readonly eventPublisher = inject(DomainEventPublisher);

  createWorkspace(name: string, ownerId: string): Observable<Workspace> {
    // Create domain entity
    const workspace = Workspace.create({ name, ownerId });

    // Persist via repository
    return this.repository.save(workspace).pipe(
      tap(savedWorkspace => {
        // Publish domain events
        savedWorkspace.domainEvents.forEach(event => {
          this.eventPublisher.publish(event);
        });
        savedWorkspace.clearDomainEvents();
      })
    );
  }

  renameWorkspace(workspaceId: string, newName: string, userId: string): Observable<Workspace> {
    const id = WorkspaceId.fromString(workspaceId);

    return this.repository.findById(id).pipe(
      map(workspace => {
        if (!workspace) {
          throw new Error('Workspace not found');
        }

        // Domain logic enforces business rules
        workspace.validateOwnership(userId);
        workspace.rename(newName);

        return workspace;
      }),
      tap(workspace => this.repository.save(workspace)),
      tap(workspace => {
        workspace.domainEvents.forEach(event => {
          this.eventPublisher.publish(event);
        });
        workspace.clearDomainEvents();
      })
    );
  }
}

Command Pattern

// src/app/application/commands/create-workspace.command.ts
export class CreateWorkspaceCommand {
  constructor(
    public readonly name: string,
    public readonly ownerId: string
  ) {}
}

// src/app/application/commands/handlers/create-workspace.handler.ts
import { Injectable } from '@angular/core';
import { Observable } from 'rxjs';
import { CreateWorkspaceCommand } from '../create-workspace.command';
import { WorkspaceService } from '@application/services/workspace.service';
import { Workspace } from '@domain/workspace/entities/workspace.entity';

@Injectable({ providedIn: 'root' })
export class CreateWorkspaceHandler {
  constructor(private workspaceService: WorkspaceService) {}

  execute(command: CreateWorkspaceCommand): Observable<Workspace> {
    return this.workspaceService.createWorkspace(command.name, command.ownerId);
  }
}

Infrastructure Layer

Repository Implementation

// src/app/infrastructure/persistence/workspace-firestore.repository.ts
import { Injectable, inject } from '@angular/core';
import { Observable, from } from 'rxjs';
import { map } from 'rxjs/operators';
import {
  Firestore,
  collection,
  doc,
  getDoc,
  setDoc,
  query,
  where,
  getDocs
} from '@angular/fire/firestore';
import { IWorkspaceRepository } from '@domain/repositories/workspace.repository';
import { Workspace } from '@domain/workspace/entities/workspace.entity';
import { WorkspaceId } from '@domain/workspace/value-objects/workspace-id.value-object';
import { WorkspaceName } from '@domain/workspace/value-objects/workspace-name.value-object';

@Injectable({ providedIn: 'root' })
export class WorkspaceFirestoreRepository implements IWorkspaceRepository {
  private firestore = inject(Firestore);
  private collectionRef = collection(this.firestore, 'workspaces');

  findById(id: WorkspaceId): Observable<Workspace | null> {
    const docRef = doc(this.collectionRef, id.value);
    return from(getDoc(docRef)).pipe(
      map(snapshot => {
        if (!snapshot.exists()) return null;
        return this.toDomain(snapshot.id, snapshot.data());
      })
    );
  }

  findByOwnerId(ownerId: string): Observable<Workspace[]> {
    const q = query(this.collectionRef, where('ownerId', '==', ownerId));
    return from(getDocs(q)).pipe(
      map(snapshot => snapshot.docs.map(doc =>
        this.toDomain(doc.id, doc.data())
      ))
    );
  }

  save(workspace: Workspace): Observable<Workspace> {
    const docRef = doc(this.collectionRef, workspace.id.value);
    const data = this.toFirestore(workspace);

    return from(setDoc(docRef, data)).pipe(
      map(() => workspace)
    );
  }

  delete(id: WorkspaceId): Observable<void> {
    const docRef = doc(this.collectionRef, id.value);
    return from(deleteDoc(docRef));
  }

  private toDomain(id: string, data: any): Workspace {
    return new Workspace({
      id: WorkspaceId.fromString(id),
      name: WorkspaceName.create(data.name),
      ownerId: data.ownerId,
      createdAt: data.createdAt?.toDate(),
      updatedAt: data.updatedAt?.toDate()
    });
  }

  private toFirestore(workspace: Workspace): any {
    return {
      name: workspace.name.value,
      ownerId: workspace.ownerId,
      createdAt: workspace.createdAt,
      updatedAt: new Date()
    };
  }
}

Best Practices

✅ DO

• Keep domain layer pure (no framework dependencies)
• Use value objects for business concepts
• Encapsulate business rules in entities
• Raise domain events for state changes
• Define repository interfaces in domain
• Use aggregates for consistency boundaries
• Implement factories for complex object creation
• Use ubiquitous language consistently

❌ DON'T

• Put business logic in application or infrastructure
• Use anemic domain models (getters/setters only)
• Directly access database from domain
• Skip validation in value objects
• Expose entity internals via public setters
• Create circular dependencies between aggregates
• Mix infrastructure code with domain code

Testing

Domain Testing

// workspace.entity.spec.ts
describe('Workspace Entity', () => {
  describe('create', () => {
    it('should create workspace with valid data', () => {
      const workspace = Workspace.create({
        name: 'Test Workspace',
        ownerId: 'user-123'
      });

      expect(workspace.name.value).toBe('Test Workspace');
      expect(workspace.ownerId).toBe('user-123');
      expect(workspace.domainEvents).toHaveLength(1);
      expect(workspace.domainEvents[0].eventType).toBe('WorkspaceCreated');
    });

    it('should throw error for invalid name', () => {
      expect(() => {
        Workspace.create({ name: '', ownerId: 'user-123' });
      }).toThrow('Workspace name cannot be empty');
    });
  });

  describe('rename', () => {
    it('should rename workspace and raise event', () => {
      const workspace = Workspace.create({
        name: 'Old Name',
        ownerId: 'user-123'
      });
      workspace.clearDomainEvents();

      workspace.rename('New Name');

      expect(workspace.name.value).toBe('New Name');
      expect(workspace.domainEvents).toHaveLength(1);
      expect(workspace.domainEvents[0].eventType).toBe('WorkspaceRenamed');
    });
  });
});

Troubleshooting

References

• Domain-Driven Design by Eric Evans
• Implementing Domain-Driven Design by Vaughn Vernon
• DDD Patterns
• Clean Architecture