swift-ddd-kit

Install安裝

Add the package to your Package.swift. DDDKit is the umbrella product; it re-exports the core protocols, the event sourcing layer, the KurrentDB adapter, the in-memory event bus and read model persistence.

在 Package.swift 加入套件。DDDKit 是 umbrella product，會一併重新導出核心協定、event sourcing 層、KurrentDB 轉接層、記憶體內 event bus 與 read model 持久化。

dependencies: [
    .package(url: "https://github.com/gradyzhuo/swift-ddd-kit.git", from: "1.3.0")
],
targets: [
    .target(
        name: "MyContext",
        dependencies: [
            .product(name: "DDDKit", package: "swift-ddd-kit"),
        ]
    )
]

🧪 Trying 1.4? The template variables framework ships as a pre-release. Pin from: "1.4.0-beta.9" to pick it up; the API may still move before 1.4.0 is final.

🧪 想試 1.4？ Template variables 框架目前以 pre-release 發佈。將版本設為 from: "1.4.0-beta.9" 即可取得；在 1.4.0 正式版之前 API 仍可能調整。

Why swift-ddd-kit為什麼選擇 swift-ddd-kit

The Swift server ecosystem has matured, but the building blocks of a production DDD architecture, aggregate roots, event-sourced repositories, CQRS projectors and event migration, have been missing. swift-ddd-kit fills that gap.

Swift 後端生態已經成熟，但 production 等級 DDD 架構的建構元件，aggregate root、event-sourced repository、CQRS projector、事件 migration，一直缺席。swift-ddd-kit 補上這一塊。

How it works運作方式

The write side and the read side share no code path. Both talk to KurrentDB on their own: commands append events, queries read those same events to build query-optimised models.

寫入端與讀取端沒有共用的程式路徑，各自對 KurrentDB 存取：command 附加事件，query 讀取同一批事件建立查詢最佳化的模型。

1. Define events定義事件

   Conform to DomainEvent, or generate them from event.yaml.

   讓事件 conform DomainEvent，或從 event.yaml 生成。

2. Model the aggregate建立 aggregate

   Implement AggregateRoot; when(happened:) turns each event into state.

   實作 AggregateRoot；when(happened:) 把每個事件轉成狀態。

3. Map stored records back把儲存的記錄映射回來

   An EventTypeMapper decodes KurrentDB records into typed events.

   EventTypeMapper 把 KurrentDB 的記錄解碼回型別化的事件。

4. Save儲存

   repository.save(aggregateRoot:) appends the uncommitted events with optimistic concurrency.

   repository.save(aggregateRoot:) 以 optimistic concurrency 附加未提交的事件。

5. Find讀取

   repository.find(byId:) replays the stream and rebuilds the aggregate.

   repository.find(byId:) 重播 stream、重建 aggregate。

6. Project投影

   An EventSourcingProjector folds events into a ReadModel, on demand or through a persistent subscription.

   EventSourcingProjector 把事件折疊成 ReadModel，可即時計算，也可透過 persistent subscription 持續更新。

Quick Start快速上手

1. Events1. 事件

import DDDKit

struct OrderCreated: DomainEvent {
    var id: UUID = .init()
    var occurred: Date = .now
    var aggregateRootId: String
    let customerId: String
}

struct OrderCancelled: DeletedEvent {
    var id: UUID = .init()
    var occurred: Date = .now
    let aggregateRootId: String
}

2. Aggregate root2. Aggregate root

final class Order: AggregateRoot {
    typealias DeletedEventType = OrderCancelled

    let id: String
    private(set) var customerId: String = ""
    var metadata: AggregateRootMetadata = .init()

    init(id: String, customerId: String) throws {
        self.id = id
        try apply(event: OrderCreated(aggregateRootId: id, customerId: customerId))
    }

    required init?(events: [any DomainEvent]) throws {
        guard let first = events.first as? OrderCreated else { return nil }
        self.id = first.aggregateRootId
        try apply(events: events)
    }

    func when(happened event: some DomainEvent) throws {
        switch event {
        case let e as OrderCreated: customerId = e.customerId
        default: break
        }
    }
}

3. Mapper and repository3. Mapper 與 repository

struct OrderEventMapper: EventTypeMapper {
    func mapping(eventData: any RecordedEventLike) throws -> (any DomainEvent)? {
        switch eventData.eventType {
        case "OrderCreated":   return try eventData.decode(to: OrderCreated.self)
        case "OrderCancelled": return try eventData.decode(to: OrderCancelled.self)
        default:               return nil
        }
    }
}

final class OrderRepository: EventSourcingRepository {
    typealias AggregateRootType = Order
    typealias Store = KurrentStorageCoordinator<Order, CustomMetadata>

    let store: Store
    init(client: KurrentDBClient) {
        store = .init(client: client, eventMapper: OrderEventMapper())
    }
}

4. Save and find4. 儲存與讀取

let client = KurrentDBClient(settings: .localhost())
let repository = OrderRepository(client: client)

let order = try Order(id: "order-001", customerId: "customer-42")
try await repository.save(aggregateRoot: order)

let found = try await repository.find(byId: "order-001")   // replayed from the stream

try await repository.delete(byId: "order-001")   // soft delete: appends OrderCancelled
try await repository.purge(byId: "order-001")    // hard delete: removes the stream

5. Metadata without touching the domain5. 不碰 domain 的 metadata

struct AuditMetadata: EventMetadata {
    let operatorId: String
    let tenantId: String
}

// Bind the schema on the store …
typealias Store = KurrentStorageCoordinator<Order, AuditMetadata>

// … and set it once at the use case entry. save() picks it up automatically.
try await EventMetadataContext<AuditMetadata>.withValue(meta) {
    try await repository.save(aggregateRoot: order)
}

A ready-to-run starter project with all of this wired up is one command away with swift-pangu-cli: pangu project create.

想要一個已經接好線、可直接執行的起始專案，用 swift-pangu-cli 一行搞定：pangu project create。

Modules模組

Pick only what a context needs. DDDKit covers the write and read side against KurrentDB; everything else is an optional product.

只挑 context 需要的部分。DDDKit 涵蓋對 KurrentDB 的寫入與讀取端；其餘都是選用的 product。

Code generation程式碼生成

Three SPM build-tool plugins read YAML next to your sources and emit Swift at build time; one command plugin emits KurrentDB projection definitions on demand. The same logic is reachable by hand through swift run generate.

三個 SPM build-tool plugin 讀取原始碼旁的 YAML，在建置時輸出 Swift；另有一個 command plugin 可隨時輸出 KurrentDB projection 定義。同樣的邏輯也可以透過 swift run generate 手動執行。

OrderCreated:
  kind: createdEvent
  aggregateRootId:
    alias: orderId
  properties:
    customerId: String
    totalAmount: Double

OrderCancelled:
  kind: deletedEvent

OrderSummary:
  model: readModel
  events:
    - OrderCreated
    - OrderAmountUpdated

CustomerName:
  placeholder: CustomerName
  inputs:
    - customerId: String

swift run generate event        Sources/MyContext/event.yaml \
    --configuration Sources/MyContext/event-generator-config.yaml -o Generated/Events.swift
swift run generate projector    Sources/MyContext/projection-model.yaml \
    --events Sources/MyContext/event.yaml -o Generated/Projectors.swift
swift run generate variables    Sources/MyContext/variables.yaml    -o Generated/Variables.swift

Guides文件