包函数

DD 提供丰富的包级函数，可直接通过 dd. 前缀调用。这些函数均通过全局日志记录器（Default()）执行。

日志记录器创建

New

func New(cfg ...Config) (*Logger, error)

创建新的 Logger 实例。不传配置时使用默认设置。

// 默认配置
logger, _ := dd.New()

// 自定义配置
logger, _ := dd.New(dd.DefaultConfig())

// 注意：仅接受 0 或 1 个配置，传入多个会返回错误
// logger, _ := dd.New(cfg1, cfg2)  // 错误！

全局日志记录器

获取和设置

函数	签名	说明
`Default`	`func Default() *Logger`	获取全局日志记录器（懒初始化）
`SetDefault`	`func SetDefault(logger *Logger)`	设置全局日志记录器
`InitDefault`	`func InitDefault(cfg ...Config) error`	用配置初始化全局日志记录器
`DefaultWithErr`	`func DefaultWithErr() (*Logger, error)`	获取全局日志记录器和初始化错误
`DefaultInitError`	`func DefaultInitError() error`	获取初始化错误

初始化全局日志记录器

// 方式一：自动初始化（首次调用时创建）
dd.Default().Info("全局日志记录器自动创建")

// 方式二：显式初始化
err := dd.InitDefault(dd.JSONConfig())
if err != nil {
    log.Fatal(err)
}
dd.Default().Info("使用 JSON 配置的全局日志记录器")

// 方式三：替换全局日志记录器
custom, _ := dd.New(dd.Config{
    Level: dd.LevelInfo,
    Targets: []dd.OutputTarget{dd.FileOutput("logs/app.log")},
})
dd.SetDefault(custom)

// 方式四：检查初始化错误
logger, err := dd.DefaultWithErr()
if err != nil {
    log.Printf("全局日志记录器初始化失败: %v", err)
}

配置预设

函数	签名	说明
`DefaultConfig`	`func DefaultConfig() Config`	默认配置（Info 级别、文本格式）
`DevelopmentConfig`	`func DevelopmentConfig() Config`	开发配置（Debug 级别）
`JSONConfig`	`func JSONConfig() Config`	JSON 输出配置

cfg := dd.DefaultConfig()
cfg.Level = dd.LevelDebug
logger, _ := dd.New(cfg)

输出目标构造器

函数	签名	说明
`ConsoleOutput`	`func ConsoleOutput() OutputTarget`	控制台输出
`FileOutput`	`func FileOutput(path string) OutputTarget`	文件输出（支持轮换）
`CustomOutput`	`func CustomOutput(w io.Writer) OutputTarget`	自定义 Writer 输出

cfg := dd.DefaultConfig()
cfg.Targets = []dd.OutputTarget{
    dd.ConsoleOutput(),
    dd.FileOutput("logs/app.log"),
    dd.CustomOutput(customWriter),
}
logger, _ := dd.New(cfg)

基本日志（包级）

以下函数通过全局日志记录器输出日志：

函数	签名	说明
`Debug`	`func Debug(args ...any)`	Debug 级别日志
`Info`	`func Info(args ...any)`	Info 级别日志
`Warn`	`func Warn(args ...any)`	Warn 级别日志
`Error`	`func Error(args ...any)`	Error 级别日志
`Fatal`	`func Fatal(args ...any)`	Fatal 级别日志（默认调用 os.Exit(1)，defer 不会执行；可通过 FatalHandler 自定义）

dd.Info("应用启动完成")
dd.Errorf("用户 %s 登录失败", username)
dd.Warn("磁盘空间不足")

格式化日志（包级）

函数	签名	说明
`Debugf`	`func Debugf(format string, args ...any)`	Debug 级别格式化日志
`Infof`	`func Infof(format string, args ...any)`	Info 级别格式化日志
`Warnf`	`func Warnf(format string, args ...any)`	Warn 级别格式化日志
`Errorf`	`func Errorf(format string, args ...any)`	Error 级别格式化日志
`Fatalf`	`func Fatalf(format string, args ...any)`	Fatal 级别格式化日志（默认调用 os.Exit(1)，defer 不会执行；可通过 FatalHandler 自定义）

通用级别日志（包级）

函数	签名	说明
`Log`	`func Log(level LogLevel, args ...any)`	指定级别日志
`Logf`	`func Logf(level LogLevel, format string, args ...any)`	指定级别格式化日志
`LogWith`	`func LogWith(level LogLevel, msg string, fields ...Field)`	指定级别结构化日志

dd.Log(dd.LevelDebug, "调试信息")
dd.Logf(dd.LevelWarn, "警告: %s", reason)
dd.LogWith(dd.LevelError, "请求失败",
    dd.String("path", "/api/users"),
    dd.Int("status", 500),
)

结构化日志（包级）

以下函数通过全局日志记录器输出结构化日志：

函数	签名	说明
`DebugWith`	`func DebugWith(msg string, fields ...Field)`	Debug 级别结构化日志
`InfoWith`	`func InfoWith(msg string, fields ...Field)`	Info 级别结构化日志
`WarnWith`	`func WarnWith(msg string, fields ...Field)`	Warn 级别结构化日志
`ErrorWith`	`func ErrorWith(msg string, fields ...Field)`	Error 级别结构化日志
`FatalWith`	`func FatalWith(msg string, fields ...Field)`	Fatal 级别结构化日志（默认调用 os.Exit(1)，defer 不会执行；可通过 FatalHandler 自定义）

dd.InfoWith("请求完成",
    dd.String("method", "GET"),
    dd.Int("status", 200),
)

dd.ErrorWith("数据库错误",
    dd.Err(err),
    dd.String("query", sql),
)

级别管理（包级）

函数	签名	说明
`SetLevel`	`func SetLevel(level LogLevel) error`	设置全局日志级别
`GetLevel`	`func GetLevel() LogLevel`	获取全局日志级别
`IsLevelEnabled`	`func IsLevelEnabled(level LogLevel) bool`	检查指定级别是否启用
`IsDebugEnabled`	`func IsDebugEnabled() bool`	检查 Debug 级别是否启用
`IsInfoEnabled`	`func IsInfoEnabled() bool`	检查 Info 级别是否启用
`IsWarnEnabled`	`func IsWarnEnabled() bool`	检查 Warn 级别是否启用
`IsErrorEnabled`	`func IsErrorEnabled() bool`	检查 Error 级别是否启用
`IsFatalEnabled`	`func IsFatalEnabled() bool`	检查 Fatal 级别是否启用

// 动态调整日志级别
dd.SetLevel(dd.LevelDebug)

// 条件日志（避免不必要的计算）
if dd.IsDebugEnabled() {
    dd.Debug(computeExpensiveDebugInfo())
}

字段链（包级）

函数	签名	说明
`WithFields`	`func WithFields(fields ...Field) *LoggerEntry`	创建带预设字段的 Entry
`WithField`	`func WithField(key string, value any) *LoggerEntry`	创建带单个预设字段的 Entry

dd.WithFields(dd.String("service", "api"), dd.String("version", "1.0")).
    Info("请求处理完成")

dd.WithField("request_id", "abc123").Info("处理请求")

生命周期（包级）

函数	签名	说明
`Flush`	`func Flush() error`	刷新全局日志缓冲

Writer 管理（包级）

函数	签名	说明
`AddWriter`	`func AddWriter(writer io.Writer) error`	添加输出写入器
`RemoveWriter`	`func RemoveWriter(writer io.Writer) error`	移除输出写入器
`WriterCount`	`func WriterCount() int`	获取写入器数量

采样控制（包级）

函数	签名	说明
`SetSampling`	`func SetSampling(config *SamplingConfig)`	设置采样配置
`GetSampling`	`func GetSampling() *SamplingConfig`	获取采样配置

Writer 构造器

函数	签名	说明
`NewFileWriter`	`func NewFileWriter(path string, cfg FileWriterConfig) (*FileWriter, error)`	创建文件写入器
`DefaultFileWriterConfig`	`func DefaultFileWriterConfig() FileWriterConfig`	默认文件写入器配置
`NewBufferedWriter`	`func NewBufferedWriter(w io.Writer, cfg BufferedWriterConfig) (*BufferedWriter, error)`	创建缓冲写入器
`DefaultBufferedWriterConfig`	`func DefaultBufferedWriterConfig() BufferedWriterConfig`	默认缓冲写入器配置
`NewMultiWriter`	`func NewMultiWriter(writers ...io.Writer) *MultiWriter`	创建多输出写入器

安全配置构造器

函数	签名	说明
`DefaultSecurityConfig`	`func DefaultSecurityConfig() *SecurityConfig`	默认安全配置（基础过滤）
`DefaultSecureConfig`	`func DefaultSecureConfig() *SecurityConfig`	完整安全配置
`HealthcareConfig`	`func HealthcareConfig() *SecurityConfig`	HIPAA 合规配置
`FinancialConfig`	`func FinancialConfig() *SecurityConfig`	PCI-DSS 合规配置
`GovernmentConfig`	`func GovernmentConfig() *SecurityConfig`	政府标准配置
`SecurityConfigForLevel`	`func SecurityConfigForLevel(level SecurityLevel) *SecurityConfig`	按级别获取安全配置

敏感数据过滤构造器

函数	签名	说明
`NewSensitiveDataFilter`	`func NewSensitiveDataFilter() *SensitiveDataFilter`	完整模式集过滤器
`NewEmptySensitiveDataFilter`	`func NewEmptySensitiveDataFilter() *SensitiveDataFilter`	空过滤器
`NewCustomSensitiveDataFilter`	`func NewCustomSensitiveDataFilter(patterns ...string) (*SensitiveDataFilter, error)`	自定义模式过滤器

钩子构造器

函数	签名	说明
`NewHookRegistry`	`func NewHookRegistry() *HookRegistry`	创建钩子注册表
`NewHooksFromConfig`	`func NewHooksFromConfig(cfg HooksConfig) *HookRegistry`	从配置创建钩子注册表

审计日志构造器

函数	签名	说明
`NewAuditLogger`	`func NewAuditLogger(cfg AuditConfig) (*AuditLogger, error)`	创建审计日志记录器
`DefaultAuditConfig`	`func DefaultAuditConfig() AuditConfig`	默认审计配置
`VerifyAuditEvent`	`func VerifyAuditEvent(entry string, signer IntegritySigner) AuditVerificationResult`	验证审计事件完整性

完整性签名构造器

函数	签名	说明
`NewIntegritySigner`	`func NewIntegritySigner(cfg IntegrityConfig) (*IntegritySigner, error)`	创建完整性签名器
`DefaultIntegrityConfigSafe`	`func DefaultIntegrityConfigSafe() (IntegrityConfig, error)`	安全随机密钥配置

测试辅助构造器

函数	签名	说明
`NewLoggerRecorder`	`func NewLoggerRecorder() *LoggerRecorder`	创建日志记录器（测试用）

上下文函数

函数	签名	说明
`WithTraceID`	`func WithTraceID(ctx context.Context, traceID string) context.Context`	设置 Trace ID
`WithSpanID`	`func WithSpanID(ctx context.Context, spanID string) context.Context`	设置 Span ID
`WithRequestID`	`func WithRequestID(ctx context.Context, requestID string) context.Context`	设置 Request ID
`GetTraceID`	`func GetTraceID(ctx context.Context) string`	获取 Trace ID
`GetSpanID`	`func GetSpanID(ctx context.Context) string`	获取 Span ID
`GetRequestID`	`func GetRequestID(ctx context.Context) string`	获取 Request ID

JSON 配置

函数	签名	说明
`DefaultJSONOptions`	`func DefaultJSONOptions() *JSONOptions`	默认 JSON 输出选项

字段构造器

用于创建结构化日志字段（Field），配合 *With 系列方法或 WithFields 使用。

函数	签名	说明
`Any`	`func Any(key string, value any) Field`	任意类型字段
`String`	`func String(key, value string) Field`	字符串字段
`Bool`	`func Bool(key string, value bool) Field`	布尔字段
`Int`	`func Int(key string, value int) Field`	int 字段
`Int8`	`func Int8(key string, value int8) Field`	int8 字段
`Int16`	`func Int16(key string, value int16) Field`	int16 字段
`Int32`	`func Int32(key string, value int32) Field`	int32 字段
`Int64`	`func Int64(key string, value int64) Field`	int64 字段
`Uint`	`func Uint(key string, value uint) Field`	uint 字段
`Uint8`	`func Uint8(key string, value uint8) Field`	uint8 字段
`Uint16`	`func Uint16(key string, value uint16) Field`	uint16 字段
`Uint32`	`func Uint32(key string, value uint32) Field`	uint32 字段
`Uint64`	`func Uint64(key string, value uint64) Field`	uint64 字段
`Float32`	`func Float32(key string, value float32) Field`	float32 字段
`Float64`	`func Float64(key string, value float64) Field`	float64 字段
`Duration`	`func Duration(key string, value time.Duration) Field`	时间段字段
`Time`	`func Time(key string, value time.Time) Field`	时间字段
`Err`	`func Err(err error) Field`	错误字段（key 为 "error"）
`ErrWithKey`	`func ErrWithKey(key string, err error) Field`	自定义 key 的错误字段
`ErrWithStack`	`func ErrWithStack(err error) Field`	含堆栈跟踪的错误字段

dd.InfoWith("请求完成",
    dd.String("method", "GET"),
    dd.Int("status", 200),
    dd.Duration("elapsed", 100*time.Millisecond),
    dd.Err(err),
)

类型安全建议

优先使用类型明确的构造器（如 Int、String），而非 Any，可在编译期捕获类型错误，避免运行时因类型不符产生问题。

字段验证配置

函数	签名	说明
`DefaultFieldValidationConfig`	`func DefaultFieldValidationConfig() *FieldValidationConfig`	默认字段验证（无验证）
`StrictSnakeCaseConfig`	`func StrictSnakeCaseConfig() *FieldValidationConfig`	严格 snake_case 验证
`StrictCamelCaseConfig`	`func StrictCamelCaseConfig() *FieldValidationConfig`	严格 camelCase 验证

调试输出函数

函数	签名	说明
`Print`	`func Print(args ...any)`	输出到全局日志 Writer（LevelInfo，受安全过滤）
`Println`	`func Println(args ...any)`	同 Print（底层 Log() 已自动换行，受安全过滤）
`Printf`	`func Printf(format string, args ...any)`	格式化输出（LevelInfo，受安全过滤）
`JSON`	`func JSON(data ...any)`	紧凑 JSON 格式输出到 stdout（含调用者信息，不经过安全过滤）
`JSONF`	`func JSONF(format string, args ...any)`	格式化字符串作为紧凑 JSON 输出到 stdout（含调用者信息，不经过安全过滤）
`Text`	`func Text(data ...any)`	美化打印格式输出到 stdout（不经过安全过滤）
`Textf`	`func Textf(format string, args ...any)`	格式化文本输出到 stdout（不经过安全过滤）
`Exit`	`func Exit(data ...any)`	带调用者信息的文本输出后退出（exit code 0），复杂类型自动美化打印，不经过安全过滤
`Exitf`	`func Exitf(format string, args ...any)`	带调用者信息的格式化输出后退出（exit code 0，不经过安全过滤）

调试函数安全提示

Print/Println/Printf 经过安全过滤，但 JSON/JSONF/Text/Textf/Exit/Exitf 直接输出原始数据，不经过安全过滤。

下一步

Logger -- Logger 实例方法详解
LoggerEntry -- 预设字段的日志 Entry
配置 -- Config 结构体
调试输出 -- 调试可视化函数

包函数 ​

日志记录器创建 ​

New ​

全局日志记录器 ​

获取和设置 ​

初始化全局日志记录器 ​

配置预设 ​

输出目标构造器 ​

基本日志（包级） ​

格式化日志（包级） ​

通用级别日志（包级） ​

结构化日志（包级） ​

级别管理（包级） ​

字段链（包级） ​

生命周期（包级） ​

Writer 管理（包级） ​

采样控制（包级） ​

Writer 构造器 ​

安全配置构造器 ​

敏感数据过滤构造器 ​

钩子构造器 ​

审计日志构造器 ​

完整性签名构造器 ​

测试辅助构造器 ​

上下文函数 ​

JSON 配置 ​

字段构造器 ​

字段验证配置 ​

调试输出函数 ​

下一步 ​

包函数