快速开始

1. 创建日志记录器

DD 提供多种便捷构造函数，满足不同场景需求：

package main

import (
    "log"

    "github.com/cybergodev/dd"
)

func main() {
    // 方式一：默认全局日志记录器（零配置）
    dd.Info("使用全局日志记录器")

    // 方式二：开发模式（DEBUG 级别，带 caller）
    dev, err := dd.New(dd.DevelopmentConfig())
    if err != nil {
        log.Fatal(err)
    }
    defer dev.Close()
    dev.Info("开发模式输出")

    // 方式三：输出到文件
    file, err := dd.New(dd.Config{
        Targets: []dd.OutputTarget{dd.FileOutput("logs/app.log")},
    })
    if err != nil {
        log.Fatal(err)
    }
    defer file.Close()
    file.Info("文件输出")

    // 方式四：同时输出到控制台和文件
    all, err := dd.New(dd.Config{
        Targets: []dd.OutputTarget{
            dd.ConsoleOutput(),
            dd.FileOutput("logs/app.log"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    defer all.Close()
    all.Info("双目标输出")

    // 方式五：JSON 格式双目标输出
    jsonLogger, err := dd.New(dd.Config{
        Format: dd.FormatJSON,
        Targets: []dd.OutputTarget{
            dd.ConsoleOutput(),
            dd.FileOutput("logs/app.json"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    defer jsonLogger.Close()
    jsonLogger.Info("JSON 格式输出")
}

零值 Config 陷阱

上面方式三/四/五直接使用 dd.Config{...} 字面量，仅显式设置了 Targets/Format，其余字段保持零值：Level=Debug（不过滤）、IncludeTime=false（无时间戳）、IncludeLevel=false（无级别）、DynamicCaller=false（无调用者）、Security=nil（回退到 DefaultSecurityConfig() 基础过滤，仍开启约 36 类脱敏；如需关闭需显式 &dd.SecurityConfig{} 或 SecurityLevelDevelopment）。输出会缺失时间戳与级别等关键信息。

生产推荐：以 dd.DefaultConfig() 作为基础再修改字段，可一次性获得时间戳、级别、调用者与默认安全过滤：

cfg := dd.DefaultConfig()                 // Level=Info, Format=Text, 含时间/级别/caller/Security
cfg.Targets = []dd.OutputTarget{dd.FileOutput("logs/app.log")}
logger, err := dd.New(cfg)

类似地，dd.DevelopmentConfig()（DEBUG+caller）与 dd.JSONConfig()（DEBUG+JSON+RFC3339）也是预设了完整字段集的便捷起点。

2. 日志级别

DD 支持 5 个日志级别，从低到高：

dd.Debug("调试信息")   // LevelDebug
dd.Info("一般信息")    // LevelInfo（默认）
dd.Warn("警告信息")    // LevelWarn
dd.Error("错误信息")   // LevelError
dd.Fatal("致命错误")   // LevelFatal（调用 os.Exit）

格式化版本：

dd.Debugf("用户 %s 登录，耗时 %dms", name, elapsed)
dd.Infof("请求处理完成：status=%d", status)
dd.Warnf("连接池使用率 %d%%", usage)
dd.Errorf("数据库查询失败: %v", err)

3. 结构化日志

使用类型安全的字段构造器：

dd.InfoWith("请求处理完成",
    dd.String("method", "GET"),
    dd.String("path", "/api/users"),
    dd.Int("status", 200),
    dd.Duration("elapsed", 150*time.Millisecond),
)

输出示例（默认文本格式）：

[2026-04-16T21:16:48+08:00   INFO] main.go:13 请求处理完成 method=GET path=/api/users status=200 elapsed=150ms

JSON 格式输出

默认全局日志记录器使用文本格式。如需 JSON 格式输出，请使用 dd.New(dd.JSONConfig()) 创建 JSON 格式的日志记录器。

4. 字段链式传递

// 创建带预设字段的 Entry
requestLogger := dd.WithFields(
    dd.String("service", "api-gateway"),
    dd.String("version", "1.0.0"),
)

// 每次日志自动携带预设字段
requestLogger.Info("服务启动")
requestLogger.InfoWith("路由注册完成",
    dd.Int("routes", 42),
)

5. 文件轮换

通过 FileWriter 配置轮换策略：

// 默认 100MB, 30 天，10 个备份
fwCfg := dd.DefaultFileWriterConfig()
fwCfg.MaxBackups = 3
fwCfg.MaxSizeMB = 1
fwCfg.Compress = true

fw, err := dd.NewFileWriter("logs/app.log", fwCfg)
if err != nil {
    log.Fatal(err)
}
logger, err := dd.New(dd.Config{
    Level: dd.LevelInfo,
    Targets: []dd.OutputTarget{dd.CustomOutput(fw)},
})
if err != nil {
    log.Fatal(err)
}
defer logger.Close()

logger.Info("hello world")

6. 敏感数据过滤

DD 默认启用基础敏感数据过滤（密码、API Key、信用卡号等自动脱敏）：

// 默认配置已包含基础安全过滤
logger, err := dd.New(dd.DefaultConfig())
if err != nil {
    log.Fatal(err)
}
defer logger.Close()

// 密码字段自动脱敏
logger.InfoWith("用户登录",
    dd.String("username", "admin"),
    dd.String("password", "s3cr3t"),  // 输出：[REDACTED]
)

下一步

• 核心概念 -- 理解 Logger 体系与处理管道
• 结构化日志 -- 字段使用详解
• 文件输出与轮换 -- FileWriter 详解
• 敏感数据过滤 -- 安全过滤实战
• 速查表 -- 常用 API 速查