如何在 Java 中使用 CountDownLatch 让主线程等待多个初始化服务全部就绪

CountDownLatch 的用法看似简单，但实际中踩坑的人不少。几个关键点必须咬死：构造参数要和服务实例数严格对齐；countDown() 必须塞进 finally；主线程的 await() 必须设超时并检查返回值；而且这东西是一次性的，别指望复用。如果记不住，后面跑出 Bug 再回头排查，那代价可就大了。

CountDownLatch 构造参数为什么必须是服务数量，不能写死为 1

原因其实很简单：计数器是倒着扣的，初始化时传入的值就是它要等待的总次数。假设你有 3 个服务要初始化，那必须传 new CountDownLatch(3)。如果图省事传了 1，那就意味着只要任意一个服务跑完 countDown()，主线程就立刻被唤醒——其他服务还没启动呢，主线程已经开始干活了，直接翻车。

这类问题最常见的表现就是日志里出现 main thread resumed too early，然后发现某些服务的 init() 还没执行完，主线程已经开始调业务逻辑了。记住三个要点：

• 构造参数必须严格等于并发初始化的服务实例数（不是线程数，是实例数）。
• 如果服务列表是动态生成的，务必在创建 CountDownLatch 之前确定好 size，比如 new CountDownLatch(services.size())。
• 不要在循环外面提前 new，否则服务数变化后计数直接就歪了。

每个服务怎么安全调用 countDown() —— 必须放在 finally 块里

初始化过程随时可能抛异常——数据库连不上、配置缺失、网络超时，什么情况都可能出现。如果只在 try 块末尾调 countDown()，一旦异常发生，这句代码就直接跳过了，计数器永远卡在那，主线程的 await() 永远等不到信号，应用就死在那了。

正确做法是把 countDown() 放进 finally，确保无论成功还是失败都减一：

service.init();
latch.countDown(); // ❌ 错误：异常时不会执行

try {
    service.init();
} finally {
    latch.countDown(); // ✅ 正确：无论如何都触发
}

几个要提醒的细节：

• 就算 init() 抛出的是 RuntimeException 或 Error，finally 也照样能执行。
• 千万别在 catch 里重试或吞异常，然后漏掉 countDown()。
• 多个服务共用同一个 CountDownLatch 实例，别各自 new，否则计数就乱了。

主线程 await() 要不要加超时？必须加

不设超时的 latch.await() 完全不可控：某个服务卡死、死锁、网络 hang 住，主线程就永久挂起，整个应用起都起不来。生产环境里用无参 await() 就是给自己埋雷。

推荐用带超时的重载，并且一定要检查返回值：

if (!latch.await(30, TimeUnit.SECONDS)) {
    throw new IllegalStateException("Services init timeout: " + latch.getCount() + " remaining");
}

这里有几个实践经验：

• 超时时间建议略大于最慢服务的预期初始化耗时（比如 30 秒），避免偶发延迟导致误判。
• 如果 await() 返回 false，用 latch.getCount() 看看还剩几个没完成，方便定位是哪个服务卡住了。
• 绝对不要忽略返回值直接往下走——这是最常见的坑，以为等到了，其实根本没等全。

CountDownLatch 用完还能 reuse 吗？不能，且容易和 CyclicBarrier 混淆

CountDownLatch 是一次性消耗品。一旦计数归零，后续所有 await() 都会立即返回 true，countDown() 也再没效果。想重复用，只能重新 new 一个实例。

如果场景是“每次初始化都要等齐，而且能反复来”，那其实更适合 CyclicBarrier。不过要注意，CyclicBarrier 要求所有参与者都在同一轮里调 await()，不太适合“主线程等子任务”这种主从模式，别搞混了。

另外几个容易忽视的点：

• 初始化完成后，不要再对同一个 CountDownLatch 实例做任何假设性操作。
• 不要把它当全局单例长期持有，尤其在 Spring Bean 中被多处注入时，很容易复用出错。
• 调试时也要小心：IDE 断点停在 await() 之后，手动 step over 可能会触发唤醒，掩盖真实的阻塞问题。

实际项目中最难处理的，其实是服务初始化里混杂了异步回调（比如 Netty 启动、消息监听器注册）。这种情况下 CountDownLatch 本身感知不到完成信号，必须靠回调里显式调 countDown()，而且还得确保回调一定被执行——这就已经超出单纯的同步等待范围了，需要额外设计超时和兜底机制。