模块 linlang.api
程序包 api.linlang.audit.log

接口 LinLogger

public interface LinLogger
绑定到平台的具体琳琅日志服务实现

琳琅日志服务提供多种常用的参数使用方式：

  • 空占位符：按 {}顺序填入参数值
  • 准确占位符：用于格式化字符串中的精准替换
  • 尾部字段：未用于占位符的键值对会附加到消息末尾

Throwable 应通过带异常参数的 WARN 或 ERROR 重载传入， 以便运行时保留完整原因链。

  • 方法详细资料

    • write

      default void write(LogLevel level, LogChannel channel, LogTemplate template, Throwable cause, Object... kv)
      提交一条结构化日志记录。

      运行时实现会保留模板代码并在投递边界完成本地化。其他实现默认使用模板的 回退文本，以保持现有日志实现兼容。

      参数:
      level - 日志等级
      channel - 日志通道
      template - 日志模板
      cause - 异常原因，可以为 null
      kv - 占位参数或扩展字段

    • debug

      void debug(String msg, Object... kv)
      输出 DEBUG 级别日志。
      参数:
      msg - 日志消息，支持占位符格式
      kv - 键值对参数，用于填充消息中的占位符

    • debug

      default void debug(LogTemplate template, Object... kv)
      输出结构化 DEBUG 日志。
      参数:
      template - 日志模板
      kv - 占位参数或扩展字段

    • info

      void info(String msg, Object... kv)
      输出 INFO 级别日志。
      参数:
      msg - 日志消息，支持占位符格式
      kv - 键值对参数，用于填充消息中的占位符

    • info

      default void info(LogTemplate template, Object... kv)
      输出结构化 INFO 日志。
      参数:
      template - 日志模板
      kv - 占位参数或扩展字段

    • file

      default void file(String msg, Object... kv)
      仅向普通日志文件输出 INFO 级别日志。

      该通道不会向平台控制台投递。普通日志文件未启用时，记录将被忽略。

      参数:
      msg - 日志消息，支持占位符格式
      kv - 键值对参数，用于填充消息中的占位符

    • file

      default void file(LogTemplate template, Object... kv)
      仅向普通日志文件输出结构化 INFO 日志。
      参数:
      template - 日志模板
      kv - 占位参数或扩展字段

    • warn

      void warn(String msg, Object... kv)
      输出 WARN 级别日志
      参数:
      msg - 日志消息，支持占位符格式
      kv - 键值对参数，用于填充消息中的占位符

    • warn

      default void warn(LogTemplate template, Object... kv)
      输出结构化 WARN 日志。
      参数:
      template - 日志模板
      kv - 占位参数或扩展字段

    • warn

      void warn(String msg, Throwable t, Object... kv)
      输出 WARN 级别日志并保留异常原因链。
      参数:
      msg - 日志消息，支持占位符格式
      t - 异常对象
      kv - 占位参数或扩展字段

    • warn

      default void warn(LogTemplate template, Throwable t, Object... kv)
      输出结构化 WARN 日志并保留异常原因链。
      参数:
      template - 日志模板
      t - 异常对象
      kv - 占位参数或扩展字段

    • error

      void error(String msg, Throwable t, Object... kv)
      输出 ERROR 级日志，可选附带异常
      参数:
      msg - 日志消息，支持占位符格式
      t - 异常对象，可为 null
      kv - 键值对参数，用于填充消息中的占位符

    • error

      default void error(LogTemplate template, Throwable t, Object... kv)
      输出结构化 ERROR 日志并保留异常原因链。
      参数:
      template - 日志模板
      t - 异常对象，可以为 null
      kv - 占位参数或扩展字段

    • error

      default void error(LogTemplate template, Object... kv)
      输出不带异常的结构化 ERROR 日志。
      参数:
      template - 日志模板
      kv - 占位参数或扩展字段

    • error

      default void error(String msg, Object... kv)
      方便重载：没有 Throwable 时可以只传消息和 kv
      参数:
      msg - 日志消息，支持占位符格式
      kv - 键值对参数，用于填充消息中的占位符

    • op

      void op(String msg, Object... kv)
      输出 OP 通道日志：发送给在线 OP 或进入 OP 队列
      参数:
      msg - 日志消息，支持占位符格式
      kv - 键值对参数，用于填充消息中的占位符

    • op

      default void op(LogTemplate template, Object... kv)
      输出结构化 OP 通道日志。
      参数:
      template - 日志模板
      kv - 占位参数或扩展字段

    • startup

      void startup(String msg, Object... kv)
      输出启动通道日志：服务器尚未完全启动时进入 STARTUP 队列
      参数:
      msg - 日志消息，支持占位符格式
      kv - 键值对参数，用于填充消息中的占位符

    • startup

      default void startup(LogTemplate template, Object... kv)
      输出结构化启动日志。
      参数:
      template - 日志模板
      kv - 占位参数或扩展字段

    • init

      void init(String msg, Object... kv)
      输出 INIT 通道日志：通常用于模块/插件初始化阶段
      参数:
      msg - 日志消息，支持占位符格式
      kv - 键值对参数，用于填充消息中的占位符

    • init

      default void init(LogTemplate template, Object... kv)
      输出结构化初始化日志。
      参数:
      template - 日志模板
      kv - 占位参数或扩展字段

    • audit

      void audit(String event, Object... kv)
      记录一条审计事件
      参数:
      event - 审计事件名称
      kv - 审计事件相关的键值对数据

      新代码优先使用 LinAudit.record(String, Object...)。

    • flushStartupToConsole

      default void flushStartupToConsole()
      刷新 STARTUP 队列到控制台或广播

    • flushOpToOnlineOps

      default void flushOpToOnlineOps()
      刷新 OP 队列到在线 OP

    • flushOpTo

      default void flushOpTo(Object op)
      向指定 OP 刷新 OP 队列（平台自定义 op 类型）
      参数:
      op - 目标 OP 对象