Java中IOException必须显式处理，需用try-with-resources自动关闭资源、区分子类精准捕获、记录带上下文的日志，并避免异常压制与敏感信息泄露。
Java中IOException必须显式处理
Java的IO操作（如FileInputStream、BufferedReader、ObjectOutputStream）抛出的是受检异常（checked exception），编译器强制你处理IOException——不能忽略，也不能只靠throws往上甩就完事。常见错误是写成catch (Exception e) { }吞掉异常，结果文件读失败却静默返回空数据，排查时毫无线索。
- 优先用
try-with-resources自动关闭资源，避免因忘记close()导致句柄泄漏 - 不要捕获
Exception或Throwable来兜底；明确捕获IOException及其子类（如FileNotFoundException、SocketTimeoutException） - 对可恢复场景（如网络临时抖动），考虑重试逻辑；对不可恢复场景（如权限不足、路径不存在），应尽早抛出带上下文的异常
try-with-resources不是万能的，嵌套资源要小心
多个资源在同一个try语句中声明时，关闭顺序与声明顺序相反，且任一资源close()抛出异常会压制前面的异常（suppressed exception）。这容易掩盖真正的问题根源。
try (FileInputStream fis = new FileInputStream("a.txt");
BufferedInputStream bis = new BufferedInputStream(fis)) {
// 读取逻辑
} catch (IOException e) {
// 如果bis.close()失败，fis.close()的异常可能被压制
}
- 单个资源优先用
try-with-resources；多个强依赖资源（如流套流）建议拆开处理，或手动close()并分别捕获异常 - 检查
e.getSuppressed()可获取被压制的异常，调试时别漏看 - 自定义资源类必须实现
AutoCloseable，且close()内不应抛出未声明的异常
区分IOException子类才能做精准响应
同样是IOException，FileNotFoundException说明路径错了，SocketTimeoutException说明网络超时，EOFException常出现在反序列化中途断连——统一printStackTrace()只会让你在日志里反复猜。
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 按子类分别处理：
catch (FileNotFoundException e)提示用户检查路径；catch (SocketTimeoutException e)触发重试或降级 - 注意
java.nio.file包下的新异常体系（如NoSuchFileException、AccessDeniedException），它们是IOException的子类，但语义更精确 - 避免用
e.getMessage().contains("Permission")这种字符串匹配判断权限问题，既脆弱又国际化不友好
日志记录要包含IO上下文，不能只记e.toString()
生产环境里，只记录e.toString()等于没记：没有文件路径、没有操作类型（read/write）、没有当时传入的参数，等于把排查难度翻倍。
立即学习“Java免费学习笔记（深入）”；
- 记录关键上下文：操作目标（
"Reading config from: " + path）、操作动作（"Failed to write user data to DB backup"）、必要参数（如userId、fileSize） - 敏感信息（密码、token、身份证号）必须脱敏，但路径中的目录名通常可记（除非含用户ID等标识）
- 对高频IO操作（如日志写入本身），避免在异常处理中再触发IO（比如同步写磁盘日志），否则可能引发死锁或雪崩
IO异常最麻烦的不是报错，而是错误发生后程序状态是否可控、日志是否够用、资源是否真释放了——这些细节不盯紧，线上问题就会变成玄学。
