Java密封类精确界定统一响应体错误结果集

Java密封接口（sealed interface）在统一响应体架构中，是用于精确控制的高效工具。通过声明sealed interface ApiError permits ValidationError, BusinessError, SystemError设定规则，每个实现类使用final record保证不可变和可枚举性。编译期即可杜绝遗漏或非法扩展，配合key-code精确映射与模式匹配，整套错误处理体系便清晰可控。

简而言之，密封类用于框定边界——哪些错误类型允许对外暴露，明确列出；若想新增，编译器直接拦截。这就让错误结果集真正实现了“封闭”且可枚举。

利用sealed interface构建统一错误契约

放弃抽象类，直接定义sealed interface ApiError作为顶层契约。所有对外暴露的错误类型都必须实现它，且只能是明确列出的那几个。具体做法如下：

• 声明时使用sealed interface ApiError permits ValidationError, BusinessError, SystemError
• 每个许可类必须用final修饰，确保不可再扩展
• 接口里定义统一的方法，如int code()、String message()、String key()，用于序列化和前端解析

为每类错误分配唯一、语义明确的code和key

密封性的另一优势，是在编译时保证错误码不重复、不遗漏。具体拆解如下：

• ValidationError，固定使用400系列的code，key统一为"validation.field.missing"这类标准化命名
• BusinessError，处理业务规则拒绝，code设为409或自定义422，key选用"order.inventory.shortage"等业务含义明确的名称
• SystemError，仅用于服务内部异常降级，code是500，key统一为"system.unexpected"，绝不暴露堆栈信息

前端拿到key，直接匹配i18n文案；后端无需字符串匹配，基于error type进行switch操作，代码清晰简洁。

在响应体中静态限定error字段类型

统一响应体如ApiResponse中的error字段，类型直接声明为ApiError，而非Object或Throwable。核心逻辑包括：

• JSON序列化时，Jackson依据实际类型自动写入type字段，配合@JsonTypeInfo即可完成
• 反序列化时，通过@JsonSubTypes绑定具体子类，由于密封限制，未声明的类型不会被接受
• Controller层返回时，只能构造几个许可类的实例，无法创建未知错误类型

配合record提升不可变性与可读性

每个具体错误类型，强烈推荐使用record实现。天然不可变，自带toString/equals，省心省力：

• final record ValidationError(String field, String reason) implements ApiError { ... }
• 构造时强制校验必填字段，基本避免空指针和无效状态
• 字段名即JSON属性名，省去@JsonProperty，前端直接解构error.field

record与sealed interface组合拳，既约束了类型边界，又简化了数据建模，错误意图一目了然。这才是企业级错误治理的实践思路。