密封类建模支付结果：穷尽分支与扩展边界

支付结果是典型的封闭领域：一次支付要么成功、被拒绝，或仍在处理中，类型集合应由支付团队统一维护。用普通开放接口建模时，任何模块都能添加实现；旧消费者如果依赖宽泛 default，新增类型就可能被静默归入错误分支。Java 的 sealed interface 配合 record 和模式匹配 switch，可以把这种遗漏变成编译期问题。

本文用一次“处理中被误判为失败”的故障复盘说明完整做法。示例适用于 Java 21 及更高版本；密封类在 Java 17 已正式交付，switch 模式匹配在 Java 21 正式交付。

Java 语言更新官方地址：https://docs.oracle.com/en/java/javase/25/language/

影响面：处理中结果被当成失败

原系统只有“成功”和“失败”两种支付结果。接入异步渠道后，网关适配器新增了“处理中”实现，希望上层启动轮询。消息转换器没有改动，因为它的 switch-like 判断最后有一个兜底分支。结果是处理中订单收到“支付失败”通知，轮询任务也没有被创建。

触发条件：开放接口遇到宽泛兜底

问题代码的危险之处不在语法，而在两个设计选择叠加：PaymentResult 是开放接口，任何包都能实现；消费者又用 else 或 default 处理未知类型。新增类型可以顺利编译，但它的业务语义并没有被所有消费者理解。

public interface PaymentResult {
    // 开放接口没有声明允许的实现集合。
}

String toMessage(PaymentResult result) {
    if (result instanceof Succeeded succeeded) {
        return "支付成功：" + succeeded.orderId();
    }
    // 任何新增实现都会被静默压进失败文案。
    return "支付失败";
}

如果结果模型确实允许第三方自由扩展，开放接口是正确选择，消费者就必须设计插件注册、访问者或能力查询机制。但支付结果由单一服务定义，外部实现并没有业务价值，开放性反而掩盖了维护边界。

根因：类型层次没有表达领域封闭性

根因不是“开发者忘记写一个 if”，而是类型系统没有表达“结果只可能来自这个固定集合”。当领域模型与类型声明不一致时，编译器只能把遗漏留到运行期。

密封类或密封接口正用于限制哪些类型可以直接扩展或实现它。官方规则要求 permitted 直接子类型在命名模块中属于同一模块；在未命名模块中，它们必须位于同一包。每个直接子类型还要声明为 final、sealed 或 non-sealed，明确层次结构是否继续开放。

这意味着 sealed hierarchy 不只是少写几个判断，它把扩展权收回到同一维护域。对于由多个独立团队和插件共同扩展的 SPI，反而不应轻易密封。

修复动作：把支付结果改为密封层次

修复后的根类型只允许三个 record 实现。record 隐式 final，无法再被继续继承，正好适合不可变结果值。

import java.time.Instant;

// permits 明确列出当前支付领域允许出现的直接结果类型。
public sealed interface PaymentResult
        permits Succeeded, Declined, Pending {
}

// 成功结果保留订单号和支付完成时间。
record Succeeded(String orderId, Instant paidAt)
        implements PaymentResult {
}

// 拒绝结果保留稳定错误码和可展示原因。
record Declined(String code, String reason)
        implements PaymentResult {
}

// 处理中结果保留后续查询所需的追踪号。
record Pending(String traceId)
        implements PaymentResult {
}

如果所有 permitted 类型都与 sealed 类型写在同一个源文件，编译器可以推断允许列表，此时可省略显式 permits。工程项目通常把类型分文件保存，明确列出 permits 更容易审查扩展边界。

穷尽分支：让新增类型在编译期暴露遗漏

模式匹配 switch 能直接解构 record。因为 PaymentResult 的所有 permitted 类型都已覆盖，所以不需要 default。这不是为了代码更短，而是为了保留编译器的穷尽检查。

import java.util.Objects;

static String toMessage(PaymentResult result) {
    // 先明确拒绝 null，避免 null 绕开支付结果类型契约。
    Objects.requireNonNull(result, "result");

    return switch (result) {
        case Succeeded(String orderId, var paidAt) ->
                "支付成功：" + orderId + "，时间：" + paidAt;
        case Declined(String code, String reason) ->
                "支付被拒绝：" + code + "，" + reason;
        case Pending(String traceId) ->
                "支付处理中，请稍后查询：" + traceId;
    };
}

不要为了“保险”再加一个 default。default 会重新允许未知子类型绕过显式分支，削弱 sealed hierarchy 的主要收益。若业务确实需要处理 null，可添加单独的 case null，而不是把 null 混入某个结果类型。

扩展演示：新增取消结果会发生什么

假设需求新增“用户主动取消”。先把 Canceled 加入 permits，并新增 record：

public sealed interface PaymentResult
        permits Succeeded, Declined, Pending, Canceled {
}

// 新结果带有取消发起方，供通知和审计使用。
record Canceled(String actor) implements PaymentResult {
}

这时原来的 toMessage 不再穷尽，编译器会要求处理 Canceled。所有依赖此层次且使用穷尽 switch 的位置都会暴露出来，团队可以逐一确认通知、退款、审计和监控语义，而不是让未知结果静默滑入 default。

编译错误在这里是保护机制。它把“新增一种支付结果要检查哪些消费者”从人工清单变成了类型系统提供的变更影响列表。

扩展边界：final、sealed 与 non-sealed 怎么选

如果把某个 permitted 子接口声明为 non-sealed，其下可以出现未知实现。此时消费者无法仅列举已知叶子类型来证明完全覆盖，通常要处理这个开放分支本身。对支付结果这种要求审计完整性的模型，优先让叶子类型保持 final。

另一个兼容性边界是：不要把已经向外部自由开放的接口直接改成 sealed。已有第三方实现可能在加载时触发不兼容错误。更安全的做法是引入新的密封结果类型，通过适配器迁移内部消费者，再评估旧接口的弃用周期。

防复发：把封闭集合写进测试和评审

sealed 与穷尽 switch 已经提供编译期主防线，测试仍要验证每种结果的业务内容：

import static org.junit.jupiter.api.Assertions.assertTrue;

import java.time.Instant;
import org.junit.jupiter.api.Test;

class PaymentMessageTest {
    @Test
    void keepsPendingTraceIdInMessage() {
        // 处理中消息必须保留追踪号，后续查询才能关联同一支付。
        var result = new Pending("trace-42");

        var message = PaymentMessages.toMessage(result);

        assertTrue(message.contains("trace-42"));
    }

    @Test
    void keepsSuccessOrderIdInMessage() {
        // 成功消息必须携带订单号，避免通知与订单失去关联。
        var result = new Succeeded("order-7", Instant.EPOCH);

        var message = PaymentMessages.toMessage(result);

        assertTrue(message.contains("order-7"));
    }
}

评审清单可以保持很短：新增 permitted 类型时是否有新的业务语义；所有穷尽 switch 是否已补分支；序列化协议是否识别新类型；数据库、消息和 API 是否需要版本兼容；是否误用了 default 掩盖未来遗漏。

常见问题

sealed interface 和 enum 有什么区别？

enum 适合每个常量结构相同或行为集中在枚举本身的固定集合。密封层次允许每个分支拥有不同字段和实现，例如成功携带支付时间、拒绝携带错误码、处理中携带追踪号。

为什么 permitted 类型要在同一模块？

密封层次需要根类型与直接子类型互相引用，并且应由同一维护域管理。命名模块中的 permitted 类型必须与根类型属于同一模块；未命名模块中则必须在同一包。

switch 中可以保留 default 吗？

语法上可以，但对封闭领域通常不建议。default 会吞掉未来新增类型，使编译器无法指出需要补充业务处理的位置。

所有领域接口都应该 sealed 吗？

不是。插件 SPI、驱动接口和第三方扩展点本来就需要开放。只有类型集合已知、固定且由同一维护方控制时，sealed 才与领域语义一致。

这次故障的真正修复不是多加一个 Pending 判断，而是让类型系统准确表达支付结果的封闭集合。sealed interface 控制谁能进入层次，record 固化每个结果的数据，穷尽 switch 则把遗漏转成编译错误。三者组合后，扩展边界清晰，新增结果也会主动暴露影响面。