如何借助Java密封类在统一响应体架构中精确界定允许暴露给外部的错误结果集

Java密封接口（sealed interface）适合统一响应体架构中精确控制错误类型，通过sealed interface ApiError permits ValidationError, BusinessError, SystemError声明契约，各实现类用final record确保不可变与可枚举，编译期杜绝遗漏或非法扩展，支持key-code精准映射与模式匹配。

Java密封类（Sealed Classes）非常适合在统一响应体架构中精确控制可暴露的错误类型——它强制限定所有子类型必须显式声明，杜绝意外新增或遗漏，让错误结果集真正“封闭”且可枚举。

用sealed interface定义统一错误契约

不推荐用抽象类，而应定义一个sealed interface ApiError作为顶层契约，所有对外暴露的错误类型都必须实现它，且只能是明确列出的几个具体类型：

• 声明时使用sealed interface ApiError permits ValidationError, BusinessError, SystemError
• 每个许可类需用final修饰（或至少非sealed），确保不可再扩展
• 接口中定义公共方法如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文案，后端无需字符串匹配即可switch on error type。

立即学习“Java免费学习笔记（深入）”；

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

统一响应体如ApiResponse<T>中的error字段，类型直接声明为ApiError而非Object或Throwable：

• JSON序列化时，Jackson会根据实际类型自动写入type字段（配合@JsonTypeInfo）
• 反序列化时，通过@JsonSubTypes绑定具体子类，且因密封限制，不会接受未声明的类型
• Controller层返回时，只能构造那几个许可类的实例，无法new出未知错误类型

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

每个具体错误类型建议用record实现，天然不可变、自带toString/equals：

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

record与sealed interface组合，既约束类型边界，又简化数据建模，错误意图一目了然。