接口定义

DD 定义了层次化的日志接口，支持不同级别的抽象需求。

接口层次

CoreLogger                  基础日志方法
├── LevelLogger             + 级别管理
└── ConfigurableLogger      + 配置/生命周期/Writer/Hook
    └── LogProvider         + 全部功能

CoreLogger

最基础的日志接口，仅包含日志输出方法。

type CoreLogger interface {
    // 基础日志
    Debug(args ...any)
    Info(args ...any)
    Warn(args ...any)
    Error(args ...any)
    Fatal(args ...any)

    // 格式化日志
    Debugf(format string, args ...any)
    Infof(format string, args ...any)
    Warnf(format string, args ...any)
    Errorf(format string, args ...any)
    Fatalf(format string, args ...any)

    // 结构化日志
    DebugWith(msg string, fields ...Field)
    InfoWith(msg string, fields ...Field)
    WarnWith(msg string, fields ...Field)
    ErrorWith(msg string, fields ...Field)
    FatalWith(msg string, fields ...Field)

    // 字段链
    WithFields(fields ...Field) *LoggerEntry
    WithField(key string, value any) *LoggerEntry
}

LevelLogger

扩展 CoreLogger，增加级别管理能力。

type LevelLogger interface {
    CoreLogger

    GetLevel() LogLevel
    SetLevel(level LogLevel) error
    IsLevelEnabled(level LogLevel) bool
    IsDebugEnabled() bool
    IsInfoEnabled() bool
    IsWarnEnabled() bool
    IsErrorEnabled() bool
    IsFatalEnabled() bool
}

ConfigurableLogger

扩展 CoreLogger，增加配置、生命周期、Writer、上下文提取器、钩子和采样管理。

type ConfigurableLogger interface {
    CoreLogger

    // 级别管理
    GetLevel() LogLevel
    SetLevel(level LogLevel) error

    // 输出目标
    AddWriter(writer io.Writer) error
    RemoveWriter(writer io.Writer) error
    WriterCount() int

    // 生命周期
    Flush() error
    Close() error
    IsClosed() bool

    // 配置
    SetSecurityConfig(config *SecurityConfig)
    GetSecurityConfig() *SecurityConfig
    SetWriteErrorHandler(handler WriteErrorHandler)

    // 上下文提取器
    AddContextExtractor(extractor ContextExtractor) error
    SetContextExtractors(extractors ...ContextExtractor) error
    GetContextExtractors() []ContextExtractor

    // 钩子
    AddHook(event HookEvent, hook Hook) error
    SetHooks(registry *HookRegistry) error
    GetHooks() *HookRegistry

    // 采样
    SetSampling(config *SamplingConfig)
    GetSampling() *SamplingConfig
}

LogProvider

完整的日志接口，组合所有能力。Logger 类型实现了此接口。

type LogProvider interface {
    // 级别管理
    GetLevel() LogLevel
    SetLevel(level LogLevel) error
    IsLevelEnabled(level LogLevel) bool
    IsDebugEnabled() bool
    IsInfoEnabled() bool
    IsWarnEnabled() bool
    IsErrorEnabled() bool
    IsFatalEnabled() bool

    // 通用日志
    Log(level LogLevel, args ...any)
    Logf(level LogLevel, format string, args ...any)
    LogWith(level LogLevel, msg string, fields ...Field)

    // 便捷日志 - Debug
    Debug(args ...any)
    Debugf(format string, args ...any)
    DebugWith(msg string, fields ...Field)

    // 便捷日志 - Info
    Info(args ...any)
    Infof(format string, args ...any)
    InfoWith(msg string, fields ...Field)

    // 便捷日志 - Warn
    Warn(args ...any)
    Warnf(format string, args ...any)
    WarnWith(msg string, fields ...Field)

    // 便捷日志 - Error
    Error(args ...any)
    Errorf(format string, args ...any)
    ErrorWith(msg string, fields ...Field)

    // 便捷日志 - Fatal
    Fatal(args ...any)
    Fatalf(format string, args ...any)
    FatalWith(msg string, fields ...Field)

    // 字段链
    WithFields(fields ...Field) *LoggerEntry
    WithField(key string, value any) *LoggerEntry

    // 输出目标
    AddWriter(writer io.Writer) error
    RemoveWriter(writer io.Writer) error
    WriterCount() int

    // 生命周期
    Flush() error
    Close() error
    IsClosed() bool

    // 配置
    SetSecurityConfig(config *SecurityConfig)
    GetSecurityConfig() *SecurityConfig
    SetWriteErrorHandler(handler WriteErrorHandler)

    // 上下文提取器
    AddContextExtractor(extractor ContextExtractor) error
    SetContextExtractors(extractors ...ContextExtractor) error
    GetContextExtractors() []ContextExtractor

    // 钩子
    AddHook(event HookEvent, hook Hook) error
    SetHooks(registry *HookRegistry) error
    GetHooks() *HookRegistry

    // 采样
    SetSampling(config *SamplingConfig)
    GetSampling() *SamplingConfig

    // 调试输出
    Print(args ...any)
    Println(args ...any)
    Printf(format string, args ...any)
    Text(data ...any)
    Textf(format string, args ...any)
    JSON(data ...any)
    JSONF(format string, args ...any)

    // 协程管理
    ActiveFilterGoroutines() int32
    WaitForFilterGoroutines(timeout time.Duration) bool
}

Logger 额外方法

具体类型 Logger 实现了 LogProvider 接口，还提供以下接口未包含的方法：

方法	签名	说明
Shutdown	(ctx context.Context) error	带超时的优雅关闭
SetLevelResolver	(resolver LevelResolver)	动态级别解析器
GetLevelResolver	() LevelResolver	获取级别解析器
SetFieldValidation	(config *FieldValidationConfig)	字段验证配置
GetFieldValidation	() *FieldValidationConfig	获取字段验证配置

这些方法在 Logger 页面中有详细文档。

Flusher

Writer 刷新接口。实现了此接口的 Writer 会在 Logger.Flush() 时被调用。

type Flusher interface {
    Flush() error
}

BufferedWriter 实现了此接口。

函数类型

类型	签名	说明
FatalHandler	func()	Fatal 级别的自定义处理函数
WriteErrorHandler	func(writer io.Writer, err error)	写入错误回调
LevelResolver	func(ctx context.Context) LogLevel	动态级别解析
ContextExtractor	func(ctx context.Context) []Field	上下文字段提取
Hook	func(ctx context.Context, hookCtx *HookContext) error	钩子函数
HookErrorHandler	func(event HookEvent, hookCtx *HookContext, err error)	钩子错误处理

使用场景

依赖注入

type Service struct {
    logger dd.CoreLogger  // 只依赖基础接口
}

func NewService(logger dd.CoreLogger) *Service {
    return &Service{logger: logger}
}

// 可传入 *Logger 或 *LoggerEntry
svc := NewService(logger)
svc.logger.Info("服务启动")

接口适配

// 接受任何实现了 CoreLogger 的类型
func process(logger dd.CoreLogger) {
    logger.InfoWith("处理开始", dd.String("item", "data"))
}

下一步

• Logger -- 实现 LogProvider 的具体类型
• LoggerEntry -- 实现 CoreLogger 的 Entry 类型
• 包函数 -- 全局函数