상수와 오류

DD 는 로그 레벨 제어, 포맷팅, 오류 처리를 위한 풍부한 상수와 오류 타입을 정의합니다.

로그 레벨

type LogLevel int8 // 로그 레벨 타입

상수	값	설명
LevelDebug	0	디버그 레벨
LevelInfo	1	정보 레벨 (기본)
LevelWarn	2	경고 레벨
LevelError	3	오류 레벨
LevelFatal	4	치명적 레벨

LogLevel은 String() string 메서드 ("DEBUG"/"INFO"/"WARN"/"ERROR"/"FATAL" 반환, 알 수 없는 값은 "UNKNOWN") 와 IsValid() bool 메서드 (레벨이 LevelDebug~LevelFatal 유효 범위 내인지 판단) 를 구현합니다.

로그 형식

type LogFormat int8 // 출력 형식 타입

상수	값	설명
FormatText	0	텍스트 형식
FormatJSON	1	JSON 형식

LogFormat은 String() string 메서드 ("text"/"json" 반환, 알 수 없는 값은 "unknown") 를 구현합니다.

필드 검증 모드

type FieldValidationMode int // 필드 키 검증 모드

상수	값	설명
FieldValidationNone	0	검증 비활성화 (기본)
FieldValidationWarn	1	검증 실패 시 경고하되 여전히 수락
FieldValidationStrict	2	엄격 모드, 검증 실패 시 오류 기록

필드 명명 규칙

type FieldNamingConvention int // 필드 키 명명 규칙

상수	값	설명
NamingConventionAny	0	모든 형식 수락 (기본)
NamingConventionSnakeCase	1	snake_case(예: user_id)
NamingConventionCamelCase	2	camelCase(예: userId)
NamingConventionPascalCase	3	PascalCase(예: UserId)
NamingConventionKebabCase	4	kebab-case(예: user-id)

해시 알고리즘

type HashAlgorithm int // 무결성 서명 해시 알고리즘

상수	값	설명
HashAlgorithmSHA256	0	SHA-256 알고리즘 (무결성 서명에 사용)

기본값

상수	값	설명
DefaultTimeFormat	"2006-01-02T15:04:05Z07:00"	ISO 8601 시간 형식
DefaultLogPath	"logs/app.log"	기본 로그 파일 경로
DefaultMaxSizeMB	100	기본 파일 크기 제한 (MB)
DefaultMaxBackups	10	기본 백업 수
DefaultMaxAge	30 * 24 * time.Hour	기본 보존 일수 (30 일)

컨텍스트 키

상수	타입	값
ContextKeyTraceID	ContextKey	"trace_id"
ContextKeySpanID	ContextKey	"span_id"
ContextKeyRequestID	ContextKey	"request_id"

오류 코드

LoggerError.Code 필드는 머신 판독 가능한 오류 코드 문자열을 포함하여 오류 타입을 세밀하게 매칭하는 데 사용됩니다. 오류 코드는 내부 구현 세부사항이며, 센티넬 오류로 매칭할 것을 권장합니다.

센티넬 오류

각 오류 코드는 센티넬 오류 변수에 해당합니다.

var (
    ErrNilConfig          = errors.New("config cannot be nil")
    ErrNilWriter          = errors.New("writer cannot be nil")
    ErrNilFilter          = errors.New("filter cannot be nil")
    ErrNilHook            = errors.New("hook cannot be nil")
    ErrNilExtractor       = errors.New("context extractor cannot be nil")
    ErrLoggerClosed       = errors.New("logger is closed")
    ErrWriterNotFound     = errors.New("writer not found")
    ErrInvalidLevel       = errors.New("invalid log level")
    ErrInvalidFormat      = errors.New("invalid log format")
    ErrMaxWritersExceeded = errors.New("maximum writer count exceeded")
    ErrEmptyFilePath      = errors.New("file path cannot be empty")
    ErrPathTooLong        = errors.New("file path too long")
    ErrPathTraversal      = errors.New("path traversal detected")
    ErrNullByte           = errors.New("null byte in input")
    ErrInvalidPath        = errors.New("invalid file path")
    ErrSymlinkNotAllowed  = errors.New("symlinks not allowed")
    ErrHardlinkNotAllowed = errors.New("hardlinks not allowed")
    ErrOverlongEncoding   = errors.New("UTF-8 overlong encoding detected")
    ErrMaxSizeExceeded    = errors.New("maximum size exceeded")
    ErrMaxBackupsExceeded = errors.New("maximum backup count exceeded")
    ErrBufferSizeTooLarge = errors.New("buffer size too large")
    ErrInvalidPattern     = errors.New("invalid regex pattern")
    ErrEmptyPattern       = errors.New("pattern cannot be empty")
    ErrPatternTooLong     = errors.New("pattern length exceeds maximum")
    ErrReDoSPattern       = errors.New("pattern contains dangerous nested quantifiers that may cause ReDoS")
    ErrPatternFailed      = errors.New("failed to add pattern")
    ErrConfigValidation   = errors.New("configuration validation failed")
    ErrWriterAdd          = errors.New("failed to add writer")
    ErrMultipleConfigs    = errors.New("multiple configs provided, expected 0 or 1")
    ErrNilMultiWriter     = errors.New("multiwriter is nil")
)

오류 검사

if errors.Is(err, dd.ErrLoggerClosed) {
    // 로거가 이미 종료됨
}

if errors.Is(err, dd.ErrPathTraversal) {
    // 경로 순회 공격 감지
}

오류 타입

LoggerError

type LoggerError struct {
    Code    string
    Message string
    Cause   error
    Context map[string]any
}

메서드: Error(), Unwrap(), Is(target), WithContext(key, value), WithField(key, value)

// LoggerError 는 오류 코드, 메시지, 원인, 컨텍스트를 포함
// errors.Is 로 센티넬 오류 검사
if errors.Is(err, dd.ErrLoggerClosed) {
    // 로거가 이미 종료됨
}

WriterError

type WriterError struct {
    Index  int
    Writer io.Writer
    Err    error
}

메서드: Error(), Unwrap()

MultiWriterError

type MultiWriterError struct {
    Errors []WriterError
}

메서드: Error(), Unwrap(), HasErrors(), ErrorCount(), FirstError()

다음 단계

• 패키지 함수 -- 오류 처리 함수
• 보안 필터 -- 경로 보안 검증
• 훅 시스템 -- OnError 훅