core

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 12, 2025 License: Apache-2.0 Imports: 2 Imported by: 56

README

Core Package

核心接口和类型定义包，提供统一日志库的基础抽象。

📋 包含内容

  • Logger 接口：统一的日志记录接口
  • Level 类型：日志级别定义和解析
  • 级别相关的常量和函数

🚀 快速使用

日志级别 (Level)
package main

import (
    "fmt"
    "github.com/kart-io/logger/core"
)

func main() {
    // 使用预定义的日志级别
    fmt.Println(core.DebugLevel.String()) // "debug"
    fmt.Println(core.InfoLevel.String())  // "info"
    fmt.Println(core.WarnLevel.String())  // "warn"
    fmt.Println(core.ErrorLevel.String()) // "error"
    fmt.Println(core.FatalLevel.String()) // "fatal"

    // 从字符串解析级别
    level, err := core.ParseLevel("DEBUG")
    if err != nil {
        panic(err)
    }
    fmt.Println(level) // debug

    // 支持大小写不敏感解析
    level2, _ := core.ParseLevel("info")
    level3, _ := core.ParseLevel("INFO")
    fmt.Println(level2 == level3) // true
}
Logger 接口

Logger 接口定义了统一的日志记录方法，所有日志引擎都必须实现此接口。

type Logger interface {
    // 基础日志方法
    Debug(args ...interface{})
    Info(args ...interface{})
    Warn(args ...interface{})
    Error(args ...interface{})
    Fatal(args ...interface{})

    // 格式化日志方法
    Debugf(template string, args ...interface{})
    Infof(template string, args ...interface{})
    Warnf(template string, args ...interface{})
    Errorf(template string, args ...interface{})
    Fatalf(template string, args ...interface{})

    // 结构化日志方法
    Debugw(msg string, keysAndValues ...interface{})
    Infow(msg string, keysAndValues ...interface{})
    Warnw(msg string, keysAndValues ...interface{})
    Errorw(msg string, keysAndValues ...interface{})
    Fatalw(msg string, keysAndValues ...interface{})

    // 功能增强方法
    With(keysAndValues ...interface{}) Logger
    WithCtx(ctx context.Context) Logger
    WithCallerSkip(skip int) Logger
    SetLevel(level Level)
}

📊 日志级别

支持以下日志级别，按严重程度递增：

级别 值 描述 使用场景
DebugLevel -1 调试信息 开发调试，生产环境通常关闭
InfoLevel 0 一般信息 应用程序正常运行信息
WarnLevel 1 警告信息 需要注意但不影响运行的问题
ErrorLevel 2 错误信息 发生错误但程序可继续运行
FatalLevel 3 致命错误 严重错误，程序需要退出

🔧 级别解析

ParseLevel 函数支持以下格式：

// 支持的字符串格式（大小写不敏感）
validLevels := []string{
    "DEBUG", "debug",
    "INFO", "info",
    "WARN", "warn", "WARNING", "warning",
    "ERROR", "error",
    "FATAL", "fatal",
}

💡 设计理念

接口隔离

核心包只定义接口，不包含具体实现，遵循依赖倒置原则：

  • 高层模块（应用代码）不依赖低层模块（具体引擎）
  • 都依赖于抽象（Logger接口）
  • 具体实现在各自的引擎包中
方法分类

Logger 接口按调用风格分为三类：

  1. 基础方法: Debug(args...) - 类似 fmt.Print
  2. 格式化方法: Debugf(template, args...) - 类似 fmt.Printf
  3. 结构化方法: Debugw(msg, keyvals...) - 键值对结构化日志
级别一致性

所有级别相关功能都统一输出小写字符串：

  • Level.String() 返回小写级别名
  • 底层引擎配置确保输出一致性
  • 解析函数支持大小写不敏感输入

🔍 错误处理

// 解析错误示例
_, err := core.ParseLevel("INVALID")
if parseErr, ok := err.(*core.ParseLevelError); ok {
    fmt.Printf("无效的级别: %s\n", parseErr.Error())
}

🧪 测试支持

核心包提供了完整的测试覆盖：

go test github.com/kart-io/logger/core -v

📚 相关包

⚠️ 注意事项

  1. Fatal 级别的日志会调用 os.Exit(1) 终止程序
  2. 级别比较：数值越大级别越高，FatalLevel > ErrorLevel > WarnLevel > InfoLevel > DebugLevel
  3. 接口中的 keysAndValues 参数必须成对出现（key-value pairs）
  4. 上下文相关的方法（WithCtx, WithCallerSkip）返回新的Logger实例，不修改原实例

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type GlobalCallOptimizer added in v0.2.0 

type GlobalCallOptimizer interface {
	// CreateGlobalCallLogger returns a logger optimized for global function calls
	CreateGlobalCallLogger() Logger
}

GlobalCallOptimizer is an internal interface for engines that support optimized global call logging to avoid runtime call stack detection.

type Level 

type Level int8

Level represents the logging level. 

const (
	// DebugLevel logs are typically voluminous, and are usually disabled in production.
	DebugLevel Level = iota - 1
	// InfoLevel is the default logging priority.
	InfoLevel
	// WarnLevel logs are more important than Info, but don't need individual human review.
	WarnLevel
	// ErrorLevel logs are high-priority. If an application is running smoothly,
	// it shouldn't generate any error-level logs.
	ErrorLevel
	// FatalLevel logs a message, then calls os.Exit(1).
	FatalLevel
)

func ParseLevel 

func ParseLevel(text string) (Level, error)

ParseLevel parses a level based on the lower-case or all-caps ASCII representation of the log level. If the provided ASCII representation is invalid an error is returned.

func (Level) String 

func (l Level) String() string

String returns a lower-case ASCII representation of the log level.

type Logger 

type Logger interface {
	// Basic logging methods with variadic arguments
	Debug(args ...interface{})
	Info(args ...interface{})
	Warn(args ...interface{})
	Error(args ...interface{})
	Fatal(args ...interface{})

	// Printf-style logging methods with format templates
	Debugf(template string, args ...interface{})
	Infof(template string, args ...interface{})
	Warnf(template string, args ...interface{})
	Errorf(template string, args ...interface{})
	Fatalf(template string, args ...interface{})

	// Structured logging methods with key-value pairs
	Debugw(msg string, keysAndValues ...interface{})
	Infow(msg string, keysAndValues ...interface{})
	Warnw(msg string, keysAndValues ...interface{})
	Errorw(msg string, keysAndValues ...interface{})
	Fatalw(msg string, keysAndValues ...interface{})

	// Logger enhancement methods
	With(keyValues ...interface{}) Logger
	WithCtx(ctx context.Context, keyValues ...interface{}) Logger
	WithCallerSkip(skip int) Logger

	// Configuration methods
	SetLevel(level Level)

	// Buffer management methods
	Flush() error
}

Logger defines the standard logging interface used throughout the application. It provides structured logging capabilities with context support and multiple output formats.

func NewNoOpLogger added in v0.2.0 

func NewNoOpLogger(err error) Logger

NewNoOpLogger creates a new no-operation logger.

type NoOpLogger added in v0.2.0 

type NoOpLogger struct {
	// contains filtered or unexported fields
}

NoOpLogger implements Logger interface but performs no actual logging. Used as a fallback when logger creation fails to prevent application crashes.

func (*NoOpLogger) Debug added in v0.2.0 

func (n *NoOpLogger) Debug(args ...interface{})

Basic logging methods - all no-op

func (*NoOpLogger) Debugf added in v0.2.0 

func (n *NoOpLogger) Debugf(template string, args ...interface{})

Printf-style methods - all no-op

func (*NoOpLogger) Debugw added in v0.2.0 

func (n *NoOpLogger) Debugw(msg string, keysAndValues ...interface{})

Structured logging methods - all no-op

func (*NoOpLogger) Error added in v0.2.0 

func (n *NoOpLogger) Error(args ...interface{})

func (*NoOpLogger) Errorf added in v0.2.0 

func (n *NoOpLogger) Errorf(template string, args ...interface{})

func (*NoOpLogger) Errorw added in v0.2.0 

func (n *NoOpLogger) Errorw(msg string, keysAndValues ...interface{})

func (*NoOpLogger) Fatal added in v0.2.0 

func (n *NoOpLogger) Fatal(args ...interface{})

func (*NoOpLogger) Fatalf added in v0.2.0 

func (n *NoOpLogger) Fatalf(template string, args ...interface{})

func (*NoOpLogger) Fatalw added in v0.2.0 

func (n *NoOpLogger) Fatalw(msg string, keysAndValues ...interface{})

func (*NoOpLogger) Flush added in v0.2.0 

func (n *NoOpLogger) Flush() error

Buffer management - always returns nil

func (*NoOpLogger) GetLastError added in v0.2.0 

func (n *NoOpLogger) GetLastError() error

GetLastError returns the last error that caused this no-op logger to be created.

func (*NoOpLogger) Info added in v0.2.0 

func (n *NoOpLogger) Info(args ...interface{})

func (*NoOpLogger) Infof added in v0.2.0 

func (n *NoOpLogger) Infof(template string, args ...interface{})

func (*NoOpLogger) Infow added in v0.2.0 

func (n *NoOpLogger) Infow(msg string, keysAndValues ...interface{})

func (*NoOpLogger) SetLevel added in v0.2.0 

func (n *NoOpLogger) SetLevel(level Level)

Configuration methods - no-op

func (*NoOpLogger) Warn added in v0.2.0 

func (n *NoOpLogger) Warn(args ...interface{})

func (*NoOpLogger) Warnf added in v0.2.0 

func (n *NoOpLogger) Warnf(template string, args ...interface{})

func (*NoOpLogger) Warnw added in v0.2.0 

func (n *NoOpLogger) Warnw(msg string, keysAndValues ...interface{})

func (*NoOpLogger) With added in v0.2.0 

func (n *NoOpLogger) With(keyValues ...interface{}) Logger

Enhancement methods - return self to maintain chain

func (*NoOpLogger) WithCallerSkip added in v0.2.0 

func (n *NoOpLogger) WithCallerSkip(skip int) Logger

func (*NoOpLogger) WithCtx added in v0.2.0 

func (n *NoOpLogger) WithCtx(ctx context.Context, keyValues ...interface{}) Logger

type ParseLevelError 

type ParseLevelError struct {
	// contains filtered or unexported fields
}

ParseLevelError is returned when parsing an invalid level string.

func (*ParseLevelError) Error 

func (e *ParseLevelError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.