IllegalStateException比IllegalArgumentException更合适，因为前者精准表达“对象当前状态不支持该操作”，如Scanner未调用hasNext()就调用next()；后者易误导调用者检查参数而非对象生命周期。
为什么 IllegalStateException 比 IllegalArgumentException 更合适？
当对象的内部状态（比如是否已初始化、是否已关闭、是否处于运行中）不满足当前方法调用的前提时，抛 IllegalStateException 是语义最准确的选择。它明确告诉调用方：“不是参数错了，是这个对象现在‘不能干这事’”。比如 Scanner 在调用 next() 前未调用 hasNext()，或 Thread 对已启动的线程重复调用 start()，JDK 都用它。
如果错用 IllegalArgumentException，会模糊问题本质——调用者可能去检查传入的参数值，而实际该检查的是对象生命周期或状态流转逻辑。
如何在自定义类中正确抛出 IllegalStateException
关键是在方法入口处做状态校验，且校验逻辑要与业务状态强绑定。不要只写“if (!ready) throw new IllegalStateException()”，而要带明确定义的状态描述。
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 状态判断必须基于 final 或 volatile 修饰的字段，或通过同步块保护的可变状态，避免竞态导致误判
- 异常消息应说明“当前状态”和“期望状态”，例如：
"Cannot write to buffer: state=FLUSHED, expected=OPEN" - 避免在 getter 或纯计算方法中抛此异常——它们不该依赖可变状态；若依赖，说明设计有耦合问题
public void writeToBuffer(byte[] data) {
if (state != State.OPEN) {
throw new IllegalStateException(
String.format("Cannot write: buffer is %s, expected OPEN", state)
);
}
// ... actual write logic
}
IllegalStateException 和并发场景下的陷阱
多线程环境下，状态检查与后续操作之间存在时间窗口，单纯 if-throw 不足以保证线程安全。常见错误是“先检查后执行”导致状态突变。
立即学习“Java免费学习笔记（深入）”；
- 不要这样写：
if (isRunning()) { doWork(); }——isRunning()返回 true 后，另一线程可能立刻调用stop() - 推荐把状态检查和动作合并进原子操作，例如使用
AtomicInteger的compareAndSet，或加锁后完成整个判断+执行 - 日志中记录抛出异常时的完整状态快照（如枚举值、时间戳、线程名），否则线上很难复现“为何当时状态非法”
测试 IllegalStateException 是否被正确触发
单元测试必须覆盖非法状态路径，且验证异常类型和消息内容，不能只测“正常流程”。JUnit 5 推荐用 assertThrows 显式断言。
- 对每个可能引发异常的状态组合，单独写一个测试用例（如 “testWriteWhenClosed”, “testStartWhenRunning”）
- 消息断言要宽松匹配关键子串，避免因格式微调导致测试失败：
assertTrue(e.getMessage().contains("buffer is CLOSED")) - 注意：某些框架（如 Spring AOP）可能包装原始异常，需用
getCause()向下查找
assertThrows<IllegalStateException>(() -> buffer.write(new byte[0]))
.getMessage()
.contains("buffer is CLOSED");
状态校验的边界往往藏在文档没写的隐含契约里——比如“调用 close() 后所有读写方法均不可再用”，这种契约必须在代码里用 IllegalStateException 硬性落实，而不是靠注释提醒。 
