Java接口异常设计是契约的一部分，需区分检查型与非检查型异常：前者强制处理，适用于可恢复业务异常；后者用于编程错误；应封装底层异常为语义明确的自定义异常，避免滥用，配合文档与规范确保一致性。
Java接口设计中，异常不是“出错了才加”的补丁，而是契约的一部分——它明确告诉调用方：哪些情况属于正常业务流转的分支，哪些是必须处理的失败场景。
区分检查型异常与非检查型异常，决定API的强制约束力
检查型异常（Exception及其子类，但不包括RuntimeException）在编译期强制要求调用方处理（try-catch或throws），适合表达调用者有能力且应当预判并恢复的业务异常，比如文件不存在、权限不足、第三方服务暂时不可用。非检查型异常（RuntimeException及其子类）不强制捕获，适用于编程错误或不可恢复的系统问题，如空指针、数组越界、非法参数等。
- 对外暴露的公共API接口，慎用检查型异常——过度使用会加重调用方负担，导致大量模板式try-catch，反而掩盖真实业务逻辑
- 若必须用检查型异常，确保其语义清晰、粒度合理，例如定义
InsufficientBalanceException比泛化的BusinessException更利于调用方做差异化处理 - 运行时异常更适合表达“调用方用法错误”，如传入null值、违反前置条件，此时应配合Javadoc明确标注@throws
用自定义异常统一语义，避免底层异常泄漏
直接抛出SQLException、IOException等具体技术异常，会把实现细节暴露给上层，破坏接口抽象性，也迫使调用方依赖特定技术栈。应封装为领域语义明确的异常类型。
- 每个核心业务动作可对应1–2个专属异常，如
UserNotFoundException、DuplicateUsernameException - 自定义异常建议继承RuntimeException（除非有强契约要求），并提供带业务码、消息、原始异常cause的构造器，便于日志追踪和前端友好提示
- 避免为每种错误新建异常类，可通过枚举+统一异常基类（如
ApiException）管理错误码与消息，提升可维护性
异常不应替代返回值，关键状态仍需显式建模
异常表示“非预期但可定义的失败路径”，不是控制流工具。不要用抛异常来返回常规业务结果，比如“用户已存在”本是注册流程的合法分支，更适合用Result或布尔+输出参数方式表达。
立即学习“Java免费学习笔记（深入）”；
- 当失败原因直接影响后续逻辑分支（如支付失败需跳转到重试页），异常可作为信号；但若只是需要记录+忽略，考虑返回Optional或状态对象更自然
- REST API中，异常通常映射为HTTP状态码（400/404/500等），此时异常类可携带status字段，由全局异常处理器统一转换，而非在每个方法里手动setStatus
- 异步或响应式接口（如WebFlux）中，异常传播机制不同，应优先利用Mono.error()或Flux.onErrorResume等原生方式，而非混用传统throw
文档与一致性比异常本身更重要
再精巧的异常设计，如果没被理解或未被遵守，就失去了意义。Javadoc、OpenAPI规范、示例代码三者需同步体现异常行为。
- 接口方法的JavaDoc必须明确列出所有可能抛出的异常及触发条件，例如“当账户余额低于订单金额时抛出InsufficientBalanceException”
- 在Swagger/OpenAPI中通过@ApiResponse标注各HTTP状态码对应异常场景，让前端/测试人员一目了然
- 团队内约定异常命名规范（如后缀Exception）、包结构（如xxx.exception.business）、错误码规则（如BUS-001），并通过Checkstyle或ArchUnit做基础校验
