Java自定义异常的Javadoc应准确声明具体异常类型（含完整包路径）及触发条件，按实际抛出顺序分行标注，不写未显式throw的异常。
Java 中自定义异常通过 @throws 标签写 Javadoc，核心是**准确声明该方法可能抛出的异常类型及其触发条件**，而不是只罗列类名。
明确标注具体异常类，不写父类或泛称
必须使用自定义异常的**完整类名（含包路径）**，且仅限当前方法实际 throw 的那个异常类型。即使该异常继承自 RuntimeException，也要写具体子类名。
- ✅ 正确：
@throws com.example.MyBusinessException - ❌ 错误：
@throws Exception或@throws RuntimeException（太宽泛，失去文档价值） - ❌ 错误：
@throws MyBusinessException（缺少包名，Javadoc 工具无法链接）
说明触发场景，而非重复异常类注释
@throws 后的描述应聚焦于“**什么情况下会抛这个异常**”，和异常类本身的 Javadoc 分工明确：类文档解释“它是什么”，方法文档解释“它何时发生”。
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- ✅ 清晰：
@throws com.example.UserNotFoundException 当用户 ID 不存在时抛出 - ✅ 具体：
@throws com.example.InvalidOrderStateException 当订单状态不允许执行此操作时抛出 - ❌ 模糊：
@throws com.example.UserNotFoundException 用户未找到（没说明谁/什么未找到） - ❌ 冗余：
@throws com.example.UserNotFoundException 抛出当用户不存在时（语法冗余，“抛出”已由标签表达）
按实际抛出顺序或重要性排列多个 @throws
一个方法若可能抛出多个自定义异常，每个 @throws 单独一行，建议按**业务逻辑中发生的常见顺序**或**严重程度降序**排列，便于调用方快速识别关键风险点。
立即学习“Java免费学习笔记（深入）”；
- 例如校验类方法可先写参数异常，再写业务约束异常：
@throws com.example.InvalidInputException 输入格式不合法<br>@throws com.example.DuplicateResourceException 资源已存在
- 避免混写多个异常在一行，也不用逗号分隔 —— Javadoc 规范要求每行一个
@throws。
不声明未显式 throw 的异常
即使方法内部调用了可能抛异常的第三方代码，只要当前方法没有 try-catch 后再 throw 或 throws 声明，就不应在 Javadoc 中添加对应 @throws。否则会误导调用方认为这是本方法契约的一部分。
- 比如方法里调用了
Files.readAllBytes()（抛IOException），但你用try-catch处理并转为自定义异常FileLoadFailedException，那么 Javadoc 只写后者，不写IOException。 - 若方法签名含
throws IOException，才需对应写@throws java.io.IOException—— 但这是检查型异常的强制要求，与自定义异常文档逻辑一致。
