密封类与密封接口

是什么，为什么存在

密封类型表示一个受控的继承层级。编译器知道哪些具名类型可以直接继承它，因此能判断针对该层级的 when 是否覆盖全部可能情况。新增一个需要单独处理的分支后，旧的穷尽判断会停止编译，把遗漏暴露在发布之前。

这种约束适合“取值形式有限、每种形式携带的数据不同”的领域。例如，一次加载可能正在进行、已经得到数据，或者携带失败原因。枚举可以列出固定实例，却不能让每个枚举项拥有不同的属性结构；普通接口又允许未知实现随时加入。

密封类型常用来表达结果类型、界面状态、协议消息、命令和抽象语法树。它不是一种错误处理框架，也不会自动验证状态转换。它提供的是类型集合的边界，具体业务规则仍要由构造逻辑和处理函数表达。

密封类本身是抽象类，可以有构造函数、保存实例状态，并提供受保护成员。一个类只能继承一个类，因此选择密封类会占用类继承位置。它适合所有变体需要共享状态或实现的层级。

密封接口 没有构造函数状态，一个类却可以同时实现多个接口。需要让同一变体属于两个受控分类，或者只想规定行为契约时，密封接口通常更合适。两者都支持 when 的穷尽性检查，区别主要在状态所有权和组合方式。

密封层级表达的是刻意关闭的扩展点。若第三方模块、本地插件或应用功能需要自由增加实现，应使用普通接口并在处理位置保留明确的未知分支。把开放生态建模成密封层级，只会把合法扩展变成编译错误。

工作原理

直接子类型的边界

密封类或密封接口的直接子类型必须与它位于同一个包和同一个模块。它们可以是顶层声明，也可以嵌套在具名的类、接口或对象中，但必须有可限定名称；局部类和匿名对象不能直接继承密封类型。

“直接”是关键。若 NetworkFailure 直接实现 Failure，它受包和模块限制；若 NetworkFailure 本身是 open，其他包仍可继承 NetworkFailure。密封父类型只控制第一道边界，后续扩展由每个直接子类型自己的修饰符决定。

普通 Kotlin 类默认是 final，数据类和对象也不能继续继承。需要分层组织变体时，可以把直接子类型继续声明为 sealed；编译器会穿过这些密封节点，找到最终需要覆盖的非密封叶节点。

下面的层级中，Failure 的直接子类型是密封的 IoFailure 和最终的 Rejected。判断 Failure 时，可以用一个 is IoFailure 分支覆盖整个 I/O 子树，也可以继续区分 Offline 与 Timeout。

when 如何判断穷尽

穷尽 when（exhaustive when） 保证其主题的每个可能值都会命中一个分支。when 用作表达式并返回值时必须穷尽；主题是密封类型时，逐项覆盖相关子类型便可以省略 else。

编译器围绕“直接非密封子类型”的集合判断覆盖情况。中间节点仍是密封类型时，它会沿层级继续寻找；某个直接节点已经是非密封类型时，一个针对该节点的类型检查就覆盖了它的所有可能后代。穷尽性因此证明的是类型边界覆盖，不是每个运行时具体类都在源码中单独出现。

分支中的 is 检查还会触发 智能转换（smart cast） 。编译器证明值属于某个子类型后，该分支可以直接访问该类型的属性。这里没有运行时反射注册表，新增子类型后的反馈来自重新编译相关源码。

在封闭领域上写 else 虽然合法，却会削弱这种反馈。后来增加 Expired 时，已有 else -> "unknown" 仍能通过编译，新的业务状态便悄悄落入旧回退。只有未知值确实属于契约的一部分时，才应保留回退分支。

类、接口与枚举

这三种声明都能支持穷尽 when，但表达的集合不同。选择时先问每个变体是否需要不同载荷，再问实现是否需要共享类状态或多接口组合。

无载荷的固定常量通常优先使用枚举。需要 Success(value) 与 Failure(message) 这种不同载荷时，密封层级更贴切。不要仅为了获得 when 补全，就把本来是常量集合的类型展开成多个对象声明。

声明位置与可见性

直接子类型可以和密封父类型放在同一文件，也可以放在同包同模块的其他文件。旧草稿和旧教程常把“同一文件”说成永久限制；那是早期 Kotlin 的规则，不适用于当前目标版本。

子类型的可见性仍要满足普通继承规则。密封类的构造函数只能是 protected 或 private，默认是 protected；不能把它声明为 public 或 internal。私有构造函数适合强制所有直接子类都嵌套在父类能够访问的位置。

密封接口没有构造函数，也不能保存后备字段。接口属性可以要求实现提供值，或者用访问器计算值，但不能承担每个实例的构造状态。若所有变体都需要同一个已验证字段，密封类往往能把不变量放在一个位置。

示例

下面三个示例依次展示带载荷的状态、显式状态转换和多接口分类。每个输出都由本地 Kotlin 2.4.10 编译器编译并在 Java 21 上运行对应文件得到。

带载荷的加载状态

LoadState 的三个变体拥有不同结构。Loading 没有每次事件独有的数据，所以使用 data object；另外两个变体用数据类携带值。

when 没有 else，三种状态都必须明确产生字符串。Ready 分支内的 state 已被智能转换，所以可以直接读取 value。若加入第四个非密封变体，render() 会在重新编译时指出遗漏。

类型参数上的 out 让 LoadState 具有 协变（covariance） 。Loading 与 Failed 使用 底类型（bottom type） Nothing，因此它们可以出现在 LoadState<String> 列表中，而不必伪造一个字符串值。

把无效转换留在模型中

密封状态只说明状态集合有限，不代表任意命令都能作用于任意状态。这个规约器让每一组组合都返回 Applied 或 Rejected，避免用异常掩盖预期内的无效操作。

sealed interface OrderState {
    data class Created(val id: String) : OrderState
    data class Paid(val id: String, val receipt: String) : OrderState
    data class Cancelled(val id: String) : OrderState
}

sealed interface OrderCommand {
    data class Pay(val receipt: String) : OrderCommand
    data object Cancel : OrderCommand
}

sealed interface Transition {
    data class Applied(val state: OrderState) : Transition
    data class Rejected(val reason: String) : Transition
}

fun reduce(state: OrderState, command: OrderCommand): Transition = when (state) {
    is OrderState.Created -> when (command) {
        is OrderCommand.Pay -> Transition.Applied(
            OrderState.Paid(state.id, command.receipt),
        )
        OrderCommand.Cancel -> Transition.Applied(OrderState.Cancelled(state.id))
    }
    is OrderState.Paid -> Transition.Rejected("paid order is final")
    is OrderState.Cancelled -> Transition.Rejected("cancelled order is final")
}

fun main() {
    val created = OrderState.Created("O-17")
    val paid = reduce(created, OrderCommand.Pay("R-8"))
    val cancelled = reduce(created, OrderCommand.Cancel)

    println(paid)
    println(cancelled)
    println(reduce(OrderState.Cancelled("O-17"), OrderCommand.Cancel))
}

Applied(state=Paid(id=O-17, receipt=R-8))
Applied(state=Cancelled(id=O-17))
Rejected(reason=cancelled order is final)

外层 when 覆盖所有订单状态；只有 Created 需要查看命令，因此内层 when 再覆盖两种命令。这个结构让新增状态和新增命令在真正相关的位置产生编译错误，却仍允许终态共享同一条拒绝规则。

Transition 把预期内的拒绝保留为数据，调用方可以继续用穷尽 when 决定显示、记录或重试。它并不会自动防止同一订单被两个并发请求同时转换；状态存储仍需要自己的并发控制和版本检查。

用密封接口交叉分类

NetworkFailure 同时属于失败集合和可重试集合，ValidationFailure 只属于失败集合。密封接口允许这种交叉分类，而单个密封类层级无法占据两个类父类型位置。

sealed interface Failure {
    val message: String
}

sealed interface Retryable {
    val delaySeconds: Int
}

data class NetworkFailure(
    override val message: String,
    override val delaySeconds: Int,
) : Failure, Retryable

data class ValidationFailure(
    val field: String,
    override val message: String,
) : Failure

data object Cancelled : Failure {
    override val message: String = "cancelled"
}

fun describe(failure: Failure): String = when (failure) {
    is NetworkFailure -> "network: ${failure.message}"
    is ValidationFailure -> "${failure.field}: ${failure.message}"
    Cancelled -> failure.message
}

fun retryPlan(value: Retryable): String =
    "retry in ${value.delaySeconds}s"

fun main() {
    val network = NetworkFailure("unreachable", 5)
    println(describe(network))
    println(retryPlan(network))
    println(describe(ValidationFailure("email", "invalid")))
    println(describe(Cancelled))
}

network: unreachable
retry in 5s
email: invalid
cancelled

describe() 按完整失败集合进行判断，retryPlan() 则只接受可重试值。类型关系本身排除了把验证错误传给重试计划的调用，不需要再用布尔属性让调用方猜测哪些组合有效。

两个接口是否都该密封取决于扩展策略。如果外部模块需要定义新的重试对象，Retryable 应是普通接口；不能为了保持图形对称，就关闭一个本应开放的角色。

陷阱

用 else 吞掉新增状态

修复方法： 对确实封闭的层级逐项列出分支并删除 else。添加新变体时先让编译失败，再逐个决定每个判断点应该支持、拒绝还是转换它；不要批量加入同一个占位回退。

把所有后代都当成固定集合

修复方法： 审查每个直接子类型的修饰符。叶变体保持默认 final；需要分组的中间节点继续使用 sealed；只有领域确实需要第二层开放扩展时才使用 open，并把该分支当作扩展边界处理。

跨包或跨模块放置直接子类型

修复方法： 把直接变体留在同包同模块，并让功能层组合或包装这些领域值。若部署边界要求第三方实现，就改用普通接口；不要靠移动包声明或复制同名密封接口掩盖设计冲突。

用单例表示带事件数据的变体

修复方法： 真正无载荷的状态使用 data object，每次发生都携带数据的变体使用含 val 属性的数据类。先写出调用方需要读取的载荷，再选择声明形式；不要为减少分配而引入共享可变事件。

把密封层级当成状态机

修复方法： 用显式转换函数同时匹配当前状态和命令，并让非法转换返回有类型的拒绝结果。测试状态与命令的组合边界；涉及持久化或并发写入时，再增加版本、事务或单一所有者约束。

在开放协议上强行密封

修复方法： 让开放协议保持普通接口，并在消费端设计明确的默认或能力查询。只有拥有方能控制全部直接实现、而且新增实现应触发所有处理点复审时，才选择密封接口。

延伸阅读

• Kotlin 文档：密封类与密封接口
• Kotlin 文档：when 表达式与语句
• Kotlin 文档：泛型型变
• Kotlin 语言规范：密封类与密封接口
• Kotlin 语言规范：穷尽 when 表达式