Java IO异常属检查型异常，须显式处理；推荐用try-with-resources自动管理资源，按语义分类捕获子类异常，记录日志并封装再抛，合理声明throws。
Java 输入输出异常（IOException 及其子类，如 FileNotFoundException、EOFException 等）属于检查型异常（checked exception），必须显式处理——要么捕获，要么声明抛出。标准的异常处理规范强调明确性、可恢复性、不掩盖问题、资源安全释放，而不是简单地 printStackTrace() 或空 catch。
用 try-with-resources 自动管理资源（推荐）
涉及文件、流、Socket 等需手动关闭的资源时，优先使用 try-with-resources 语句。它能确保资源在 try 块结束时（无论是否异常）自动调用 close()，避免资源泄漏。
- 资源类必须实现
AutoCloseable接口（InputStream、OutputStream、BufferedReader等都满足） - 多个资源用分号分隔，关闭顺序与声明顺序相反
- 即使发生异常，close() 仍会执行；若 close() 本身也抛异常，会被抑制（suppressed），可通过
getSuppressed()获取
try (FileInputStream fis = new FileInputStream("data.txt");
BufferedReader reader = new BufferedReader(new InputStreamReader(fis))) {
String line;
while ((line = reader.readLine()) != null) {
System.out.println(line);
}
} catch (FileNotFoundException e) {
// 文件不存在：属于预期外但可识别的业务问题
System.err.println("配置文件未找到：" + e.getMessage());
} catch (IOException e) {
// 其他 IO 问题：读取中断、磁盘满、权限不足等
System.err.println("读取文件时发生 I/O 错误：" + e.getMessage());
// 可选：记录完整堆栈到日志系统（如 SLF4J）
// logger.error("Failed to read config", e);
}
按异常语义分类处理，不笼统 catch IOException
IOException 是父类，涵盖大量具体场景。标准做法是捕获更具体的子类，并分别响应：
-
FileNotFoundException→ 检查路径/权限，提示用户确认文件是否存在 -
SecurityException→ 权限不足，应拒绝操作并明确告知（尤其在沙箱或受限环境） -
EOFException→ 通常表示数据格式异常或提前结束，需校验输入完整性 -
SocketTimeoutException（继承自IOException）→ 属网络超时，适合重试或降级
避免只写 catch (IOException e) 并统一打印——这会丢失关键上下文，不利于定位和恢复。
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
立即学习“Java免费学习笔记（深入）”；
不吞异常、不裸 throw，做好上下文包装与日志记录
捕获后不应静默忽略（空 catch），也不应直接把底层异常原样抛给上层（除非上层明确要处理 IO 细节）。推荐做法：
- 记录日志：用日志框架（如 Logback/SLF4J）记录 ERROR 级别，包含原始异常（作为 cause）
- 封装再抛：构造更有业务含义的运行时异常（如
DataLoadException），将IOException作为 cause 传入，保持异常链完整 - 向用户反馈友好信息：比如“无法加载用户配置，请检查网络连接”，而非 “java.io.IOException: Connection reset”
try (Reader reader = Files.newBufferedReader(Paths.get("user.json"))) {
return objectMapper.readValue(reader, User.class);
} catch (JsonProcessingException e) {
throw new DataLoadException("JSON 格式错误，无法解析用户数据", e);
} catch (IOException e) {
logger.error("读取 user.json 失败", e);
throw new DataLoadException("无法从本地加载用户数据，请稍后重试", e);
}
方法签名中合理声明 throws（仅当上层应负责处理时）
如果当前方法无法恢复异常（例如工具类中的通用读取方法），且调用方更清楚如何应对（重试？换源？提示用户？），才用 throws IOException 向上传递。
- 不要为了省事在每个方法都加
throws Exception—— 违反 API 明确性原则 - 公共 API 方法若可能触发 IO，应在 Javadoc 中明确说明抛出的检查异常及其含义
- 在 Spring 等框架中，常将检查异常转为非检查异常（如
ResourceAccessException），由全局异常处理器统一响应
