Class ConsoleFormatter

java.lang.Object
cloud.opencode.base.log.spi.ConsoleFormatter
public final class ConsoleFormatter extends Object
Console Log Formatter with Optional ANSI Color Support 控制台日志格式化器（可选 ANSI 颜色支持）

Formats log lines for console output with optional ANSI color codes. When color is enabled, the log level portion is colorized according to severity; when disabled, plain text is produced.

将日志行格式化为控制台输出，可选使用 ANSI 颜色代码。 启用颜色时，日志级别部分根据严重程度着色； 禁用时，生成纯文本。

Features | 主要功能:

  • Auto-detection of ANSI terminal support - 自动检测 ANSI 终端支持
  • Respects NO_COLOR environment variable (https://no-color.org/) - 遵循 NO_COLOR 环境变量
  • Configurable via system property "opencode.log.color" - 通过系统属性配置
  • Severity-based color mapping for log levels - 基于严重程度的级别颜色映射

Color Mapping | 颜色映射:

  • ERROR: Bold Red - 粗体红色
  • WARN: Bold Yellow - 粗体黄色
  • INFO: Bold Green - 粗体绿色
  • DEBUG: Bright Blue - 亮蓝色
  • TRACE: Bright Black (Gray) - 亮黑色（灰色）

Usage Examples | 使用示例:

// Auto-detect color support
ConsoleFormatter formatter = new ConsoleFormatter();

// Explicit color control
ConsoleFormatter colored = new ConsoleFormatter(true);
ConsoleFormatter plain = new ConsoleFormatter(false);

// Format a log line
String line = formatter.format(LogLevel.INFO, "2026-04-03 10:00:00",
        "main", "com.example.App", "Application started");

Security | 安全性:

  • Thread-safe: Yes (immutable after construction) - 线程安全: 是（构造后不可变）
Since:
JDK 25, opencode-base-log V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • ConsoleFormatter

      public ConsoleFormatter()
      Creates a formatter with auto-detected ANSI color support. 创建自动检测 ANSI 颜色支持的格式化器。

    • ConsoleFormatter

      public ConsoleFormatter(boolean colorEnabled)
      Creates a formatter with explicit color control. 创建显式控制颜色的格式化器。
      Parameters:
      colorEnabled - true to enable ANSI colors - true 启用 ANSI 颜色

  • Method Details

    • isAnsiSupported

      public static boolean isAnsiSupported()
      Detects whether the current environment supports ANSI escape codes. 检测当前环境是否支持 ANSI 转义码。

      Detection order | 检测顺序:

      1. System property "opencode.log.color" (explicit override) - 系统属性显式覆盖
      2. Environment variable "NO_COLOR" (if set, disable) - 环境变量（设置则禁用）
      3. System.console() presence (terminal detection) - 终端检测
      4. OS detection: macOS/Linux default true, others check TERM - 操作系统检测
      Returns:
      true if ANSI is supported - 如果支持 ANSI 则返回 true

    • format

      public String format(LogLevel level, String timestamp, String threadName, String loggerName, String message)
      Formats a log line with the standard pattern. 使用标准模式格式化日志行。

      Pattern: timestamp [threadName] LEVEL loggerName - message

      Parameters:
      level - the log level - 日志级别
      timestamp - the formatted timestamp - 格式化的时间戳
      threadName - the thread name - 线程名称
      loggerName - the logger name - 日志器名称
      message - the log message - 日志消息
      Returns:
      the formatted log line - 格式化后的日志行
      Throws:
      NullPointerException - if any argument is null - 如果任何参数为 null

    • formatWithColor

      public String formatWithColor(String text, AnsiColor color)
      Wraps text with the given ANSI color code. 使用给定的 ANSI 颜色代码包装文本。

      If color is disabled, returns the text unchanged.

      如果颜色禁用，返回未更改的文本。

      Parameters:
      text - the text to colorize - 要着色的文本
      color - the ANSI color - ANSI 颜色
      Returns:
      the colorized text, or plain text if color is disabled - 着色后的文本，或禁用颜色时返回纯文本
      Throws:
      NullPointerException - if text or color is null - 如果 text 或 color 为 null

    • isColorEnabled

      public boolean isColorEnabled()
      Returns whether ANSI color output is enabled. 返回是否启用 ANSI 颜色输出。
      Returns:
      true if color is enabled - 如果启用颜色则返回 true