Class HealthRegistry

java.lang.Object
cloud.opencode.base.observability.health.HealthRegistry
public final class HealthRegistry extends Object
Registry for managing and executing health checks. 管理和执行健康检查的注册中心。

Maintains a thread-safe collection of named HealthCheck instances. The check() method executes all registered checks, records their duration, and catches any exceptions (producing a HealthStatus.DOWN result). The status() method aggregates all results into a single worst-case status.

维护一个线程安全的命名 HealthCheck 实例集合。 check() 方法执行所有已注册的检查，记录其耗时， 并捕获任何异常（生成 HealthStatus.DOWN 结果）。 status() 方法将所有结果聚合为单个最差状态。

Since:
JDK 25, opencode-base-observability V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static HealthRegistry create()
      Creates a new empty HealthRegistry with the default limit (1000). 使用默认上限（1000）创建一个新的空 HealthRegistry。
      Returns:
      a new registry instance | 新的注册中心实例

    • create

      public static HealthRegistry create(int maxChecks)
      Creates a new empty HealthRegistry with the specified limit. 使用指定上限创建一个新的空 HealthRegistry。
      Parameters:
      maxChecks - the maximum number of health checks | 最大健康检查数量
      Returns:
      a new registry instance | 新的注册中心实例
      Throws:
      ObservabilityException - if maxChecks is not positive | 如果 maxChecks 不为正

    • register

      public void register(String name, HealthCheck check)
      Registers a health check under the given name, replacing any existing check with the same name. 以给定名称注册健康检查，替换同名的已有检查。
      Parameters:
      name - the unique name for the check | 检查的唯一名称
      check - the health check to register | 要注册的健康检查
      Throws:
      ObservabilityException - if name is null/blank or check is null | 如果 name 为 null/空白或 check 为 null

    • unregister

      public boolean unregister(String name)
      Unregisters the health check with the given name. 取消注册给定名称的健康检查。
      Parameters:
      name - the name of the check to remove | 要移除的检查名称
      Returns:
      true if a check was removed, false otherwise | 如果移除了检查则返回 true，否则返回 false

    • check

      public Map<String, HealthResult> check()
      Executes all registered health checks and returns their results. 执行所有已注册的健康检查并返回结果。

      If a check throws an exception, a HealthStatus.DOWN result is produced with the exception class name and message as detail.

      如果检查抛出异常，将生成 HealthStatus.DOWN 结果， 异常类名和消息作为详情。

      Security note — No timeout enforcement | 安全注意事项 — 无超时保护: Health checks are executed synchronously on the calling thread with no built-in timeout. A blocking check (e.g., a database connection without a connect-timeout) will hang the calling thread indefinitely, which can disrupt Kubernetes readiness/liveness probes. Each registered HealthCheck implementation is responsible for enforcing its own timeout (e.g., via Future.get(long, java.util.concurrent.TimeUnit)).

      健康检查在调用线程上同步执行，无内置超时机制。阻塞性检查（如未设置连接超时的数据库连接） 将无限挂起调用线程，可能影响 Kubernetes readiness/liveness 探针。 每个 HealthCheck 实现应自行控制超时。

      Returns:
      an unmodifiable map of check name to result | 检查名称到结果的不可修改映射

    • status

      public HealthStatus status()
      Computes the aggregated health status of all registered checks. 计算所有已注册检查的聚合健康状态。
      Returns:
      the aggregated status | 聚合状态

    • names

      public Set<String> names()
      Returns the names of all registered health checks. 返回所有已注册健康检查的名称。
      Returns:
      an unmodifiable set of check names | 检查名称的不可修改集合

    • size

      public int size()
      Returns the number of registered health checks. 返回已注册的健康检查数量。
      Returns:
      the count of registered checks | 已注册检查的数量

    • clear

      public void clear()
      Removes all registered health checks. 移除所有已注册的健康检查。