使用者指南

1. 引入依赖

在 Gradle（Kotlin DSL）中：

dependencies {
    implementation("io.github.sinri:keel-logger-api:5.0.2")
}

Maven 请将 artifactId 与 version 换成与发布仓库一致的坐标。若使用 JPMS，在 module-info.java 中 requires io.github.sinri.keel.logger.api;。

2. 创建 Logger

2.1 直接使用 BaseLogger

适合快速脚本或单测：

import io.github.sinri.keel.logger.api.LogLevel;
import io.github.sinri.keel.logger.api.logger.BaseLogger;
import io.github.sinri.keel.logger.api.logger.Logger;

Logger logger = new BaseLogger("my-service");
logger.

visibleLevel(LogLevel.DEBUG);
logger.

info("服务启动");

第二个构造函数等价于 new BaseLogger(topic, BaseLogWriter.getInstance())，即输出到标准输出。

2.2 通过工厂（推荐与 Keel 一致）

import io.github.sinri.keel.logger.api.factory.BaseLoggerFactory;
import io.github.sinri.keel.logger.api.factory.LoggerFactory;

LoggerFactory factory = BaseLoggerFactory.getInstance();
Logger log = factory.createLogger(MyService.class);

使用 全局共享工厂（便于框架启动时注入统一适配器）：

LoggerFactory factory = LoggerFactory.getShared();
Logger log = factory.createLogger("auth");

框架初始化时可 LoggerFactory.replaceShared(customFactory) 替换实现。

3. 可见级别与 SILENT

• visibleLevel(LogLevel) 设置 最低可见级别：仅当 记录的级别 >= 该级别（按 LogLevel.severity()）时才会构建并投递日志。
• 各级 severity()：TRACE～FATAL 分别为 100～700（步长 100），SILENT 为 Integer.MAX_VALUE。详见《概述与设计》§3.1。
• LogLevel.SILENT：不记录任何日志（log 与各级便捷方法均提前返回）。

链式调用示例：

logger.visibleLevel(LogLevel.DEBUG).

debug("调试信息");

4. 记录方式概览

形式	示例	说明
纯文本	logger.info("hello")	最简
带上下文（LogContext）	logger.info("msg", ctx -> ctx.put("k", v))	结构化键值
完整构建（Consumer<T>）	logger.info(log -> log.message("x").context("a", 1))	异常、分类、多字段

Consumer 重载在写入前会 强制 将本条级别设为对应方法的级别（如 info(Consumer) 最终为 INFO），避免遗漏设级别。

5. 上下文 LogContext

LogContext 内部为 Map（TreeMap），适合序列化为 JSON 对象：

logger.warning("请求失败",ctx ->{
        ctx.

put("path","/api/x");
    ctx.

put("status",502);
});

在 Consumer<Log> 风格下也可：

logger.error(log ->{
        log.

message("处理失败");
    log.

context("orderId",orderId);
    log.

exception(e);
});

6. 异常与分类

logger.error(log ->{
        log.

message("订单处理异常");
    log.

exception(e);
    log.

classification(List.of("order", "payment"));
        });

异常文本由适配器侧渲染；默认实现会打印完整链与经折叠的堆栈（见 概述与设计）。

7. 指标（与日志独立）

import io.github.sinri.keel.logger.api.metric.MetricRecord;
import io.github.sinri.keel.logger.api.metric.MetricRecorder;

MetricRecord r = MetricRecord.create(
        "http.server.duration",
        12.3,
        Map.of("method", "GET", "route", "/health")
);
recorder.

recordMetric(r);

MetricRecorder 由应用或 Keel 集成模块提供；本库只定义数据形状与调用点。

8. 注意事项：message(LogLevel, String, Object...)

SpecificLogger 还提供了：

void message(LogLevel level, String message, Object... args);

该方法仅用 level 做 是否输出 的判断，实际交给适配器的 SpecificLog 默认构造级别仍为 INFO（未调用 level(...)）。若下游渲染依赖 log.level()，可能与参数 level 不一致。

建议：优先使用 trace/debug/…/fatal 系列或 Consumer<T> 重载，避免依赖 message(LogLevel, …) 的语义。

9. 与测试

• 不需输出时：可使用 SilentLoggerFactory（适配器吞掉写入），或构造 visibleLevel(SILENT) 的 BaseLogger，或使用 SilentLogger（不可改级别）。
• 单测断言：可实现自定义 LogWriterAdapter 将 accept 收到的 SpecificLog 写入队列再断言。