java接口不应声明受检异常，而应通过运行时异常（如commonexception）统一承载业务错误语义，配合文档、sdk和适配器实现语义兼容与分层解耦。
Java 接口本身无法“兼容受检异常”又保持灵活性——这不是接口设计的目标，而是对异常使用场景的常见误解。真正需要的不是让接口声明 throws 受检异常来追求“兼容”，而是通过分层设计，把异常语义从接口契约中解耦出来，让调用方获得清晰、稳定、可预期的错误反馈，同时不被编译器强制绑定具体异常类型。
接口定义应避免声明受检异常
Java 接口若在方法签名中显式抛出受检异常（如 throws IOException, ValidationException），会带来三重负担：
- 所有实现类必须处理或继续声明这些异常，破坏封装性
- 客户端每次调用都需写
try-catch或向上抛，代码冗余且与业务逻辑混杂 - 一旦新增业务异常类型，接口就要改、所有实现要改、所有调用方可能也要改，违背开闭原则
用运行时异常统一承载业务错误语义
将业务异常建模为继承 RuntimeException 的子类（如 CommonException），并在接口文档中约定其含义，而非写进方法签名：
- 接口方法保持干净：
UserDTO getUserById(String id)，不带throws - 实现内部按需抛出：
if (id == null) throw new CommonException(400, "ID 不能为空") - 异常码（code）、消息（msg）、HTTP 状态（status）由统一拦截器解析并转为标准 JSON 响应
通过文档与 SDK 实现“语义兼容”
接口的“兼容性”不靠 throws 保证，而靠契约一致性：
- 在 OpenAPI（Swagger）中明确定义每个 HTTP 状态码对应的错误码范围和含义，例如
404 → {"code": 1002, "msg": "用户不存在"} - 为合作方提供 Java SDK，封装远程调用 + 异常自动转换：调用
userApi.getUserById("x")失败时，SDK 直接抛出UserNotFoundException（运行时异常），而非原始IOException或HttpClientErrorException - 版本升级时，只扩展错误码枚举、不删旧码、不改已有 code/msg 语义，保障下游解析逻辑不变
必要时用适配器桥接遗留受检异常体系
当对接老系统或第三方 SDK（其方法强制抛受检异常）时，不修改接口定义，而是封装一层适配器：
- 适配器实现目标接口，内部捕获其
throws的受检异常 - 将其转为统一的
CommonException再抛出，例如：catch (SQLException e) { throw new CommonException(5001, "数据库查询失败", e); } - 对外暴露的仍是无
throws的干净接口，内部脏活由适配器消化
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
