Class CaptchaMetrics

java.lang.Object
cloud.opencode.base.captcha.support.CaptchaMetrics
public final class CaptchaMetrics extends Object
Captcha Metrics - Lightweight metrics collection for CAPTCHA operations 验证码指标 - 轻量级验证码操作指标收集器

This class collects operational metrics for CAPTCHA generation and validation, including generation counts, validation success/failure rates, response times, and type distribution. All counters use LongAdder for high-throughput concurrent updates.

此类收集验证码生成和验证的操作指标，包括生成次数、验证成功/失败率、 响应时间和类型分布。所有计数器使用 LongAdder 以支持高吞吐量并发更新。

Features | 主要功能:

  • Generation count tracking by type - 按类型跟踪生成次数
  • Validation success/failure rate tracking - 验证成功/失败率跟踪
  • Average response time calculation - 平均响应时间计算
  • Immutable point-in-time snapshots - 不可变的时间点快照
  • Reset capability for metric rotation - 用于指标轮换的重置功能

Usage Examples | 使用示例:

CaptchaMetrics metrics = CaptchaMetrics.create();

// Record generation
metrics.recordGeneration(CaptchaType.ALPHANUMERIC);

// Record validation with response time
Instant start = Instant.now();
boolean success = validate(captchaId, answer);
metrics.recordValidation(success, Duration.between(start, Instant.now()));

// Take a snapshot
CaptchaMetrics.MetricsSnapshot snapshot = metrics.snapshot();
System.out.println("Success rate: " + snapshot.successRate());
System.out.println("Average response time: " + snapshot.averageResponseTime());

Performance | 性能特性:

  • Time complexity: O(1) for all recording operations - 时间复杂度: 所有记录操作 O(1)
  • Space complexity: O(T) where T is the number of CaptchaType values used - 空间复杂度: O(T)，T 为使用的 CaptchaType 值数量

Security | 安全性:

  • Thread-safe: Yes (uses LongAdder and ConcurrentHashMap) - 线程安全: 是（使用 LongAdder 和 ConcurrentHashMap）
  • Null-safe: No (CaptchaType must not be null) - 空值安全: 否（CaptchaType 不能为 null）
Since:
JDK 25, opencode-base-captcha V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static CaptchaMetrics create()
      Creates a new metrics instance. 创建新的指标实例。
      Returns:
      a new CaptchaMetrics instance | 新的 CaptchaMetrics 实例

    • recordGeneration

      public void recordGeneration(CaptchaType type)
      Records a CAPTCHA generation event. 记录一次验证码生成事件。
      Parameters:
      type - the CAPTCHA type that was generated | 生成的验证码类型
      Throws:
      NullPointerException - if type is null | 如果 type 为 null

    • recordValidation

      public void recordValidation(boolean success, Duration responseTime)
      Records a CAPTCHA validation result with response time. 记录一次验证码验证结果及响应时间。

      The response time is added to the cumulative total for average calculation. A null response time is silently ignored.

      响应时间会被累加到总计中用于计算平均值。null 响应时间会被静默忽略。

      Parameters:
      success - whether the validation was successful | 验证是否成功
      responseTime - the response time, or null if not measured | 响应时间，如果未测量则为 null

    • recordValidation

      public void recordValidation(boolean success)
      Records a CAPTCHA validation result without response time. 记录一次验证码验证结果（无响应时间）。
      Parameters:
      success - whether the validation was successful | 验证是否成功

    • snapshot

      public CaptchaMetrics.MetricsSnapshot snapshot()
      Takes an immutable point-in-time snapshot of all metrics. 获取所有指标的不可变时间点快照。

      Because individual counters are read independently, the snapshot may reflect a slightly inconsistent view under heavy concurrent updates. This is acceptable for monitoring purposes.

      由于各计数器独立读取，在高并发更新下快照可能反映略不一致的视图。 这对于监控目的是可接受的。

      Returns:
      an immutable metrics snapshot | 不可变的指标快照

    • reset

      public void reset()
      Resets all metrics counters and restarts the uptime clock. 重置所有指标计数器并重启运行时间计时。

      Note: This method is not atomic — a concurrent snapshot() may observe partially-reset state (e.g., successRate > 1.0). This is acceptable for monitoring; if exact atomicity is required, callers must provide external synchronization.

      注意: 此方法不是原子的 — 并发的 snapshot() 可能 观察到部分重置状态。这对于监控是可接受的；如需精确原子性，调用者须自行同步。