SuperAPI AI 工具集

ddd-kotlin-idioms

编程与开发

查看项目

更新于 10-16 16:27

技能介绍

一句话概述

把 DDD 模式决策翻译成仅使用 Kotlin 标准库的惯用写法 —— 不含框架倾向。

何时使用

  • 已经选定某个 DDD 模式(通常经由 ddd-implement),且目标语言是 Kotlin。
  • 用户想要惯用代码,而非伪代码。
  • 对 Kotlin DDD 代码做代码评审时,被问到“这个模式对应的正确 Kotlin 构造是什么?”。

何时不使用

  • 目标语言不是 Kotlin。
  • 用户仍在决定模式 —— 应先转到 ddd-core 模式技能。
  • 用户想要框架特定的脚手架(Spring 注解、Arrow Either)—— 这些不在本技能范围内,将存在于未来的适配插件中(ddd-kotlin-spring、ddd-kotlin-arrow)。

核心内容

映射关系:对每个 DDD 模式,给出惯用的 Kotlin 构造,以及促成该选择的权衡。

值对象 —— 单个原始类型的包装

@JvmInline
value class CustomerId(val raw: UUID)

对零分配的带类型 ID 以及其他单字段包装,使用 Kotlin 的 @JvmInline value class。注意:在 Kotlin 1.9 之前,value class 不能有 init {} 块;对于需要校验的单字段包装,应使用 data class,或使用带校验 companion 工厂的私有构造函数。

值对象 —— 组合式、多字段

data class Money(val amount: BigDecimal, val currency: Currency) {
    init {
        require(amount.scale() <= currency.defaultFractionDigits) {
            "amount scale exceeds ${currency.defaultFractionDigits} for ${currency.currencyCode}"
        }
    }
    fun add(other: Money): Money {
        require(currency == other.currency) { "cannot add $currency and ${other.currency}" }
        return Money(amount + other.amount, currency)
    }
}

data class 是正确选择 —— 按属性相等、默认不可变(使用 val)、通过 copy() 修改时复制。把不变量放在 init 块中。

实体

class Customer(val id: CustomerId, name: String) {
    var name: String = name
        private set

    fun rename(to: String) {
        require(to.isNotBlank())
        this.name = to
    }

    override fun equals(other: Any?) = other is Customer && other.id == id
    override fun hashCode() = id.hashCode()
}

使用普通 class,而非 data class。重写 equals/hashCode 以仅按身份(id)比较。data class 会比较所有字段,这会导致两个同名但不同 ID 的 Customer 实例相等 —— 这是错误的。

聚合根

只暴露命令的实体。内部保持私有;查询返回不可变视图。

class Order(val id: OrderId, val customerId: CustomerId) {
    private val _items = mutableListOf<LineItem>()
    val items: List<LineItem> get() = _items.toList()

    fun addItem(productId: ProductId, quantity: Int) {
        check(items.none { it.productId == productId }) { "product already in order" }
        _items.add(LineItem(productId, quantity))
    }
}

注意 customerId: CustomerId —— 对 Customer 聚合是按 ID 引用,而不是持有 Customer 对象引用。

领域事件

sealed interface OrderEvent {
    data class Placed(val orderId: OrderId, val at: Instant) : OrderEvent
    data class Cancelled(val orderId: OrderId, val reason: String, val at: Instant) : OrderEvent
}

使用过去时名称。标记性层级优先使用 sealed interface 而非 sealed class;各变体是 data class,因为它们是值对象。

状态 / 状态机

sealed class OrderStatus {
    data object Draft : OrderStatus()
    data class Placed(val at: Instant) : OrderStatus()
    data object Cancelled : OrderStatus()
}

sealed 支持穷尽的 when。无状态变体使用 data object(Kotlin 1.9+),这样 toString 和 equals 才合理。

结果 / 可失败操作

fun place(order: Order): Result<Order> = runCatching { /* domain logic */ }

目前使用 kotlin.Result。(未来的 ddd-kotlin-arrow 插件会用带命名错误类型的 Arrow Either<DomainError, Order> 替代。)

不变量

  • 构造函数前置条件用 require(...) —— 抛出 IllegalArgumentException。
  • 操作期间的状态不变量检查用 check(...) —— 抛出 IllegalStateException。
  • 领域特定异常需自行定义:class OrderAlreadyPlacedException(...) : IllegalStateException(...)。

仓储接口

interface OrderRepository {
    fun save(order: Order)
    fun findById(id: OrderId): Order?
}

接口位于领域模块。实现位于基础设施模块,并由应用启动装配。

工厂 —— 推荐形式

class Order private constructor(/* ... */) {
    companion object {
        fun place(customerId: CustomerId, items: List<LineItem>): Order { /* invariant checks, then return Order */ }
    }
}

私有构造函数 + 具名 companion 工厂表达领域动词(place),并防止任意调用者构造无效的 Order 实例。

决策启发式

  • 仅当所有属性都参与身份时才用 data class(值对象)。实体用重写了 equals 的普通 class,使身份仅由 ID 决定。
  • 除非层级需要共享状态,否则优先 sealed interface 而非 sealed class。
  • 对于带类型 ID 以及无需校验的单原始类型包装,优先 @JvmInline value class。否则优先 data class。
  • 处处优先不可变性,除了拥有可变状态的实体内部 —— 即便如此,也只能通过维护不变量的方法来修改。

反模式

  • 对实体使用 data class —— 相等性包含可变字段,破坏身份语义。
  • 在纯领域模块的领域实体上放 JPA 注解(@Entity、@Column)—— 让领域耦合到持久化框架。
  • 到处抛裸 IllegalArgumentException,而不定义有领域含义的异常。
  • 滥用 lateinit var 伪造不可变性 —— lateinit 是应对 DI 生命周期的变通手段,不是领域建模工具。
  • 把 JpaRepository<Order, UUID> 当作领域仓储 —— 暴露全部 CRUD 方法并把领域绑到 JPA。

另见

ddd-entity、ddd-value-object、ddd-aggregate、ddd-domain-event、ddd-repository、ddd-factory —— 本技能所实现的模式。

ddd-implement —— 为 Kotlin 代码生成路由到这里的入口点。

参考资料

  • Kotlin 语言文档:data class、value class(@JvmInline)、sealed class / sealed interface、Result。
  • Evans, Domain-Driven Design (2003), 第 5–6 章,了解底层模式。

限制

仅面向 Kotlin 语言与 Kotlin 标准库;不涵盖框架特定内容(Spring 注解、Arrow Either 等),这些被明确列为范围外,留待未来的适配插件。适用前需已确定 DDD 模式;模式未定时不适用。