Semaphore是许可证计数器，用于限流而非锁或通信；设总数后acquire()扣证、release()还证，典型场景如连接池限流；需成对调用且release()必放finally，避免泄漏；非公平模式默认高吞吐，公平模式可预测但性能低；仅单JVM有效，不可作分布式锁。
Java里Semaphore到底用来干啥
它不是锁，也不是线程通信工具，而是「许可证计数器」——你设好总数（比如5张票），每次acquire()就扣一张，release()就还一张。谁拿不到许可证，就阻塞或失败，不进临界区。
典型场景：限制数据库连接池最大活跃连接数、控制API调用频次、避免大量线程同时写磁盘。
常见错误现象：acquire()后忘了release()，导致许可证永远被占着；或者在异常路径里漏掉release()，资源彻底卡死。
- 构造时传
new Semaphore(3)表示最多3个并发，传true第二个参数启用公平模式（按等待顺序分配，性能略低但可预测） - 别用
Semaphore替代synchronized——它不保证临界区内代码的原子性，只管“能不能进” - 如果想非阻塞获取，用
tryAcquire()，返回boolean；想带超时，用tryAcquire(long, TimeUnit)
acquire()和release()必须成对出现在同一作用域
很多人把acquire()放在try前，release()扔进finally，看着没问题，但一旦acquire()本身被中断（比如线程被interrupt()），就会抛InterruptedException，跳过finally，许可证没释放。
立即学习“Java免费学习笔记（深入）”；
正确做法是：先确保拿到许可证，再进业务逻辑；释放操作必须包裹在try-finally里，且acquire()调用要处理中断。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
semaphore.acquire(); // 可能抛 InterruptedException
try {
// 业务逻辑
} finally {
semaphore.release(); // 这里必须执行
}
- 如果业务逻辑可能抛异常，不影响
release()执行，因为已在finally中 - 不要在
catch里调用release()——那是重复释放，会多加许可证，破坏限流逻辑 - 若用
tryAcquire()非阻塞方式，成功才进try-finally，失败直接走其他路径
公平模式 vs 非公平模式的实际影响
默认是非公平的：new Semaphore(5)，新线程可能插队抢到许可证，老线程一直等。公平模式new Semaphore(5, true)会让等待最久的线程优先获得。
性能差异明显：非公平吞吐高，公平模式上下文切换多、延迟略高，尤其在高竞争下更明显。
- 限流类场景（如API网关）通常用非公平——响应快比排队准更重要
- 调试或压测时开启公平模式，更容易复现资源争用问题
- 注意：公平性只影响等待队列里的线程，不保证
acquire()调用顺序和执行顺序一致
别把Semaphore当分布式锁用
Semaphore只在单JVM内有效。同一应用多个实例、微服务部署、容器重启后状态全丢——它不持久、不跨进程、不跨网络。
常见踩坑：用Semaphore做“全局请求限流”，结果每个Pod都自己算自己的5个并发，实际总并发变成5×Pod数。
- 真要跨实例限流，得上Redis + Lua（如
redisson.getSemaphore()）或专门的限流服务（Sentinel、Resilience4j） - 本地限流+兜底可以保留
Semaphore，但必须明确它是“最后一道本地防线”，不是唯一控制点 - 监控时注意区分：JVM内许可证剩余数（可用
availablePermits()查）和真实业务并发量可能不等——比如一个请求拿了证但卡在下游，许可证已占但没干活
真正难的从来不是调用acquire()，而是想清楚“这个许可证代表什么资源”“谁该还”“还错一次会发生什么”。限流逻辑一旦混进业务异常流，比没限更危险。
