[Java] Java 关键字 `sealed`(密封):给"【谁能继承我】"这件事加一个编译器强制执行的边界 [JDK17-]

0 序

  • 公司项目工程(JDK17)中在使用 sealed interface 定义接口,需了解一二。

1 Java 关键字 sealed

  • sealed 是 Java 17(JEP 409)正式引入的类/接口修饰符,作用是给"【谁能继承我】"这件事加一个编译器强制执行的边界。

sealed 英译: 密封的、封闭的。

核心定位

  • 普通继承的家族是"开放的、不可知的";sealed 把它变成"封闭的、可穷举的":父类型显式声明一个允许继承的名单,名单之外的类一律编译报错。
public sealed interface Shape permits Circle, Square, Rectangle {}

final class Circle       implements Shape { ... }   // 终结,不再被继承
final class Square       implements Shape { ... }
sealed interface Rectangle extends Shape permits RoundedRect { ... }
final class RoundedRect implements Rectangle { ... }

三条硬规则

  1. permits 里只能是【直接子类】,【间接子类】要由中间的 sealed 子类继续声明。
  2. 每个【被允许的子类】必须显式三选一:final / sealed / non-sealed,否则【编译报错】(这是新手最常踩的坑)。
  3. 可见性约束:【允许的子类】必须在同一包(具名模块下可放宽到同一模块)内,不能"跨包偷偷继承"。

permits 可省略:当所有子类与父类写在同一个 .java 文件里时,编译器【自动推断名单】(常用于把 ADT 定义成一个文件)。

flowchart TD A["sealed 类/接口"] --> B["final 子类:终结,不能再被继承"] A --> C["sealed 子类:继续受限继承"] A --> D["non-sealed 子类:解除封闭,回到普通开放继承"]
修饰符 含义 还能被继承吗
sealed 仅 permits 名单可继承 仅名单内
non-sealed 显式放弃封闭(类、接口都可加) 任意类
final 完全禁止继承 否

注意 sealed 与 final、sealed 与 non-sealed 互斥,同时写是【编译错误】;abstract sealed 是【合法组合】,也是【最常见的用法】。

它真正解决的是什么

  • sealed 本身不是"性能特性",也不是【访问控制】——被允许的子类照样可以 new 出来。它的价值在【类型设计】上:

1. 穷尽性检查(最大收益)

配合 Java 21 的模式匹配 switch,编译器能证明你覆盖了所有子类型,不用写 default,而且以后新增一个【子类型】,所有漏改的地方会【直接编译失败】:

double area(Shape s) {
    return switch (s) {                 // 无 default 也是【合法】且【穷尽】的
        case Circle c          -> Math.PI * c.r() * c.r();
        case Square q          -> q.side() * q.side();
        case RoundedRect r     -> ...;
    };
}

这就是 Java 版的代数数据类型(ADT)/ 可辨识联合,把"枚举的穷举性"从常量扩展到"带数据的类型"。

2. API 演进可控

公开库用 sealed 声明:外部只能消费、不能派生 → 你不用为未知的第三方子类保守设计,也不用担心有人实现你的接口塞进奇怪行为。要放开某个分支,加 non-sealed 即可。

3. 与 record / enum 天然契合

  • record 隐式 final、enum 隐式封闭,天生适合做 【sealed】 家族里的【叶子节点】:"密封父类型 + 若干 record 子类"已是 Java 里表达【领域模型】的【推荐写法】。

参见案例: CASE sealed 父类型(PaymentOutcome/支付受理结果) + record 叶子(Paid, Pending, Declined)

4. 可反射、可工具化

Class#isSealed()、Class#getPermittedSubclasses() 让框架能识别封闭层级,IDE 和静态检查也能据此做更严格的穷举提醒。

实践注意点

  • 不是【运行时多态】的替代品:虚方法调用、JIT 的 devirtualization 靠【类型谱分析】,跟 sealed 无关。

  • 一个类可以被多个 sealed 接口共同允许(只要它在每个 permits 名单里),但只能直接继承一个类。

  • 版本门槛:Java 15/16 是预览(需 --enable-preview),17 起正式可用,21 配合 switch 模式匹配才完全释放价值。

  • 【框架序列化】:用 Jackson 反序列化多态类型时, jackson 的 @JsonSubTypes 与 permits 是两套独立声明,必须手动保持一致——否则会出现"【编译期穷举通过】、【反序列化】却报 unknown subtype"的错位。这类一致性建议写个单测覆盖,而不是靠肉眼对齐。

import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;

/**
 * 对象集表达式
 * <p>
 * JSON 里的 type 字段决定子类型:base 取某个类型的全部对象,filter 追加过滤条件,
 * static 使用给定的主键,union 求并,intersect 求交,subtract 求差,
 * searchAround 沿链接跳到关联类型,distinct 去重。
 */
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type", visible = true)
@JsonSubTypes({
        @JsonSubTypes.Type(value = ObjectSetBase.class, name = "base"),
        @JsonSubTypes.Type(value = ObjectSetFilter.class, name = "filter"),
        @JsonSubTypes.Type(value = ObjectSetStatic.class, name = "static"),
        @JsonSubTypes.Type(value = ObjectSetUnion.class, name = "union"),
        @JsonSubTypes.Type(value = ObjectSetIntersect.class, name = "intersect"),
        @JsonSubTypes.Type(value = ObjectSetSubtract.class, name = "subtract"),
        @JsonSubTypes.Type(value = ObjectSetSearchAround.class, name = "searchAround"),
        @JsonSubTypes.Type(value = ObjectSetDistinct.class, name = "distinct")
})
public sealed interface ObjectSet permits
        ObjectSetBase,
        ObjectSetFilter,
        ObjectSetStatic,
        ObjectSetUnion,
        ObjectSetIntersect,
        ObjectSetSubtract,
        ObjectSetSearchAround,
        ObjectSetDistinct {

    /**
     * 表达式类型,即 JSON 中的 type
     */
    String type();
}

2 案例实践

CASE sealed 父类型(PaymentOutcome/支付受理结果) + record 叶子(Paid, Pending, Declined)

案例搭好并实测通过(JDK 17.0.2,switch 模式匹配走 --enable-preview)。下面是逐份源码 + 真实运行与编译证据。

模型层:sealed 父类型 + record 叶子

PaymentOutcome

package model;

import java.math.BigDecimal;

/**
 * 支付受理结果:领域模型里的"结果"型代数数据类型(ADT)。
 *
 * 为什么父类型必须 sealed:
 *   业务上"一次支付受理"只可能有这 3 种结局,没有第四种。
 *   用 sealed 把这个业务事实写进编译器 —— 名单之外的类型无法成为子类型,
 *   于是所有消费方都可以安全地假设"穷尽了"。
 *
 * permits 规则:只能列【直接】子类型,三个 record 缺一不可;多列一个非直接子类型会报错。
 */
public sealed interface PaymentOutcome
        permits Paid, Pending, Declined {

    /** 此刻真正落袋的金额。父类型只声明契约,由各分支自己回答。 */
    BigDecimal settledAmount();
}
package model;

import java.math.BigDecimal;
import java.time.Instant;

/**
 * 成功:钱已到账,是这个 ADT 里唯一"终态且有钱"的分支。
 *
 * record 在这里是隐式 final 的,所以它天然满足 sealed 父类型的第二条硬规则
 * (直接子类型必须 final / sealed / non-sealed 之一)—— 一句修饰符都不用写。
 * 这正是"record 天生适合当叶子节点"的真正含义:不是像,是语法上刚好吻合。
 */
public record Paid(String transactionId, BigDecimal amount, Instant paidAt)
        implements PaymentOutcome {

    /**
     * 紧凑构造器:让非法状态不可表示(make illegal states unrepresentable)。
     * 校验写在这里,之后任何使用方拿到的 Paid 都保证 amount > 0,
     * 不必在业务代码里到处 if (amount != null && amount > 0)。
     */
    public Paid {
        if (transactionId == null || transactionId.isBlank()) {
            throw new IllegalArgumentException("transactionId must not be blank");
        }
        if (amount == null || amount.signum() <= 0) {
            throw new IllegalArgumentException("amount must be positive but was " + amount);
        }
        if (paidAt == null) {
            throw new IllegalArgumentException("paidAt must not be null");
        }
    }

    @Override
    public BigDecimal settledAmount() {
        return amount;          // 唯一贡献金额的分支
    }
}

Pending

package model;

import java.math.BigDecimal;
import java.time.Instant;

/**
 * 挂起:已受理但结果未定(等第三方回调、等风控复核)。
 * 它和 Paid / Declined 的根本区别是"还没结束",所以金额先记 0,由对账侧单独盯。
 */
public record Pending(String transactionId, Instant deadline, int retryCount)
        implements PaymentOutcome {

    public Pending {
        if (transactionId == null || transactionId.isBlank()) {
            throw new IllegalArgumentException("transactionId must not be blank");
        }
        if (deadline == null) {
            throw new IllegalArgumentException("deadline must not be null");
        }
        if (retryCount < 0) {
            throw new IllegalArgumentException("retryCount must not be negative: " + retryCount);
        }
    }

    @Override
    public BigDecimal settledAmount() {
        return BigDecimal.ZERO;      // 未定,不认钱
    }
}

Declined

package model;

import java.math.BigDecimal;

/**
 * 拒绝:终态,但没钱。
 * 载荷只放"原因 + 可读细节",不把整份上游报文塞进来 —— 领域模型只保留业务判据。
 */
public record Declined(DeclineReason reason, String detail)
        implements PaymentOutcome {

    public Declined {
        if (reason == null) {
            throw new IllegalArgumentException("reason must not be null");
        }
        if (detail == null) {
            detail = "";             // 紧凑构造器可以修正入参,赋回同名组件
        }
    }

    @Override
    public BigDecimal settledAmount() {
        return BigDecimal.ZERO;      // 拒绝,一分钱没收到
    }
}

DeclineReason

package model;

/**
 * 拒绝原因是"有限取值集合",正是 enum 的主场 —— 不要用 String 常量。
 * 它在 ADT 里扮演"叶子里的叶子":只承载分类,不承载结构。
 */
public enum DeclineReason {
    INSUFFICIENT_FUNDS,
    RISK_REJECTED,
    CARD_EXPIRED
}

消费层:这才兑现 sealed 的收益

PaymentLedger

package app;

import java.math.BigDecimal;
import java.util.List;
import model.Declined;
import model.Paid;
import model.PaymentOutcome;
import model.Pending;

/**
 * 消费侧:对账口径。
 * 这里才是 sealed 真正兑现的地方 —— switch 不写 `default` 也能穷尽,
 * 因为编译器已经知道 【PaymentOutcome】 只可能是那 3 个类型。
 */
public class PaymentLedger {

    /** 是否已是终态(不会再变)。 */
    public static boolean isFinal(PaymentOutcome outcome) {
        return switch (outcome) {
            case Paid p     -> true;
            case Declined d -> true;
            case Pending n  -> false;
        };                            // 没有 default —— 这是特性,不是遗漏
    }

    /** 已确认收入:只把 Paid 算进来,其余按 0 处理。 */
    public static BigDecimal totalCaptured(List<PaymentOutcome> outcomes) {
        return outcomes.stream()
                .map(PaymentOutcome::settledAmount)
                .reduce(BigDecimal.ZERO, BigDecimal::add);
    }

    /** 给运营看的对账文案:每个分支各说各话,同样不需要 default。 */
    public static String describe(PaymentOutcome outcome) {
        return switch (outcome) {
            case Paid p     -> "已收款 " + p.amount() + " txn=" + p.transactionId();
            case Pending n  -> "待定 txn=" + n.transactionId() + " retries=" + n.retryCount();
            case Declined d -> "已拒绝 " + d.reason() + " detail=" + d.detail();
        };
    }
}

真实运行输出

--- 穷尽 switch 的分支输出 ---
已收款 199.00 txn=T0001
待定 txn=T0002 retries=2
已拒绝 INSUFFICIENT_FUNDS detail=balance 0.00
--- 对账口径 ---
totalCaptured = 199.00
finalCount    = 2
--- 非法状态不可表示:紧凑构造器拦截 ---
blocked: transactionId must not be blank
--- 隐式 final / 隐式封闭 的反射真相 ---
Paid.isRecord            = true
Paid.isFinal(modifier)   = true
Paid.isSealed            = false
PaymentOutcome.permitted = [class model.Paid, class model.Pending, class model.Declined]

注意 new Paid("", -1, now) 被紧凑构造器直接拦死在构造阶段 —— 校验和数据结构长在一起,而不是散落在 N 个 service 里,这是 record 当叶子最实用的一面。

核心价值:新增分支,编译期就红

若把 Refunded 加进 permits 后重新编译,javac 立刻报:

PaymentLedger.java:19: error: the switch expression does not cover all possible input values
        return switch (outcome) {
               ^
PaymentLedger.java:35: error: the switch expression does not cover all possible input values
        return switch (outcome) {
               ^
2 errors

恰好 2 处,就是那两个 switch。这就是"不写 default"的代价与收益:default 会把这类漏洞吃掉,让你在生产环境凌晨三点发现退款没进对账口径。编译器替你做了全链路的影响面分析。

小结:把这个模式用对的几条经验

  1. 【父子职责】切干净:父接口只放"跨分支共有的契约"(settledAmount()),【分支间的差异】一律下沉到 record 叶子 自己回答,不要在接口里写一堆 if (this instanceof ...)。
  2. 【载荷】即【语义】:Pending 带 retryCount/deadline、Declined 带 reason —— 每个 record 的组件都是该分支特有的信息,而不是所有分支共用的字段堆在父类里的"最大公约数"。
  3. 【叶子上限】控制在 5 个左右。超过就说明你在用 ADT 硬扛一棵本该分层级的树,该抽出中间 sealed 层(像我上一版示例的 Rectangle → RoundedRect)。
  4. 别拿 record 当【可变 DTO】:它是【值对象】,equals/hashCode/toString 全是基于组件的自动实现,【语义】上适合"【既成事实】",【不适合需要回填字段的对象】。
  5. 【序列化】要单独验证:给这类模型接 Jackson 时,@JsonSubTypes 与 permits 是两套独立声明,得手动保持一致;且 visible = true 在 record 上容易撞 UnrecognizedPropertyException,务必做反序列化往返测试,而不是只看序列化能出 JSON。
  6. 严格说 Jackson 的 @JsonTypeInfo + sealed/record 组合有坑,实际上有实测记录可查。

Y 推荐文献

X 参考文献

posted @ 2026-11-11 15:16  千千寰宇  阅读(11)  评论(0)    收藏  举报