Java sealed interface 扩展失败时怎么检查 permits 列表

Java 的 sealed interface 扩展失败，通常不是方法没实现，而是类型层级没有满足 sealed 的编译约束。排查时把问题压缩成五项：permits 里的类型是否可访问、是否直接 implements 或 extends、是否声明了正确的续封修饰符、是否处在允许的包或模块边界内，以及编译器是否拿到了完整的类型定义。

先用一个最小层级重现错误

先不要把业务接口、泛型和构建插件一起带进来。用两类直接实现类型做基线，能把错误范围从“整个项目编不过”缩小到声明关系。下面的示例把两个类型分别放在自己的源文件中：

// PaymentMethod.java：只允许两种直接实现类型
public sealed interface PaymentMethod
        permits CardPayment, WalletPayment {
}

// CardPayment.java：叶子类型用 final 结束层级
public final class CardPayment implements PaymentMethod {
}

// WalletPayment.java：允许未来继续出现未知子类型
public non-sealed class WalletPayment implements PaymentMethod {
}

这组代码的基线不是“能运行出什么结果”，而是能否通过编译。若把 UnknownPayment 写成 implements PaymentMethod，编译器会拒绝它；若把 WalletPayment 的 non-sealed 删除，也会拒绝这个直接实现类。先记录这两个边界，再进入项目代码，定位会快很多。

按三个编译判据检查 permits 列表

遇到“无法扩展 sealed interface”时，先对 permits 逐项做三次核对。Oracle 的语言说明和 JLS 第 9.1.4 节都把许可类型限定为可访问、直接实现或直接扩展该接口的类或接口。

例如 PaymentMethod permits CardPayment 时，CardPayment 必须直接写 implements PaymentMethod。如果它只继承了另一个实现类，或者只是拥有相同的方法签名，都不算直接实现。反过来，permits 中列了一个类型，但该类型没有直接关系，也同样会触发编译错误。

续封规则可以记成一句话：叶子类用 final，还要继续收敛就用 sealed，明确放开后续扩展才用 non-sealed。接口直接 extends sealed interface 时，也要在 sealed 和 non-sealed 之间做出选择。不要用“它的方法已经实现了”来代替声明上的继承关系。

模块与包边界是第二个高频误判点

如果单文件示例能编译、项目拆成多个包后失败，优先检查模块模型。对于 named module，sealed interface 和 permits 中的类或接口必须属于同一个 module，但可以分布在该 module 的不同 package。对于 unnamed module，JLS 要求它们属于同一个 package。

// module-info.java：许可类型仍须和接口处在同一 module
module com.example.payments {
    // 只导出 API，不改变 sealed 层级的同模块约束
    exports com.example.payments;
}

// com.example.payments/PaymentMethod.java
package com.example.payments;

public sealed interface PaymentMethod
        permits com.example.payments.impl.CardPayment {
}

// com.example.payments.impl/CardPayment.java
package com.example.payments.impl;

public final class CardPayment implements com.example.payments.PaymentMethod {
}

上面示例中的两个 package 属于同一个 named module，所以可以成立。若 CardPayment 被挪到另一个 module，哪怕类是 public、模块也能在构建脚本里看到对方，仍不能形成这组互相引用的 sealed 层级。非模块项目则更简单：把接口和所有许可类型放回同一个 package，再重新编译。

没有 permits 时检查同一编译单元推断

permits 不是永远必须手写。如果 sealed interface 与它的直接实现类或子接口写在同一个 compilation unit 中，Java 可以根据同文件中的顶层或成员类型推断许可集合。但这个省略方式有两个容易忽略的边界：推断对象必须是直接关系，且不能靠局部类或匿名类充当许可类型。

// 同一个 Payment.java：许可类型可由编译单元推断
sealed interface Payment {
}

// 这是直接实现类型，属于推断出的许可集合
final class CashPayment implements Payment {
}

// 这是另一个直接实现类型，也属于推断出的许可集合
non-sealed class VoucherPayment implements Payment {
}

如果省略 permits 后同一编译单元里没有任何合格的直接子类型，仍然会失败。项目里采用显式 permits 更容易做代码审查；只有层级很小、类型确实共置在一个源文件时，才适合省略。

用五项清单完成反向验证

修正后不要只删掉报错行。按下面的顺序重新检查，能避免把 sealed 改成普通 interface 这种“编译通过但设计失效”的修复：

1. 名单：permits 每一项都是预期的直接类或直接子接口，没有重复名称。
2. 关系：每个类直接 implements，每个接口直接 extends 当前 sealed interface。
3. 修饰符：直接子类型明确选择 final、sealed 或 non-sealed。
4. 边界：named module 检查同 module，unnamed module 检查同 package。
5. 输入：编译命令或 IDE 模块路径包含接口和全部许可类型，不能只编译其中一个源文件。

这个五项矩阵比反复改 permits 文本更可靠：前四项对应语言规则，最后一项负责排除构建输入不完整造成的假象。确认层级后，再把接口方法、泛型约束或模式匹配逻辑加回去。

常见问题

permits 里能写间接子类吗？

不能。它只描述 sealed interface 的直接实现类和直接子接口；间接层级应由直接子类型自己的 sealed 规则继续声明。

为什么 public 类型仍然不能放进 permits？

public 只解决访问性，不会绕过同 module 或同 package 的 sealed 边界。先看模块归属，再看包路径。

把 sealed interface 改成普通 interface 可以吗？

技术上可能编译通过，但会放弃编译器对实现集合的约束。只有确实需要第三方扩展、且不再依赖穷举层级时，才应这样改。

规则原文可继续查看 Oracle Sealed Classes and Interfaces 与 Java Language Specification 9.1.4。