errx

README

errx 包 Package

errx 定义稳定错误分类、严重性、操作名、错误码、可重试标记和 cause 包装。

Use NewError for ordinary classified errors and WrapError when preserving an underlying cause.

Documentation

Overview

Package errx 定义 L0 错误分类和可序列化错误契约。

Index

• func IsKind(err error, kind ErrorKind) bool
• type Error
  • func AsError(err error) (*Error, bool)
  • func NewError(kind ErrorKind, op string, message string) *Error
  • func WrapError(kind ErrorKind, op string, message string, cause error) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
  • func (e *Error) WithCode(code string) *Error
  • func (e *Error) WithRetryable(retryable bool) *Error
  • func (e *Error) WithSeverity(severity Severity) *Error
• type ErrorKind
• type Severity

Examples

• NewError

Functions

func IsKind

func IsKind(err error, kind ErrorKind) bool

IsKind reports whether err contains an Error with the given kind.

Types

type Error

type Error struct {
	Kind      ErrorKind `json:"kind"`
	Code      string    `json:"code,omitempty"`
	Severity  Severity  `json:"severity,omitempty"`
	Op        string    `json:"op,omitempty"`
	Message   string    `json:"message"`
	Cause     error     `json:"-"`
	Retryable bool      `json:"retryable"`
}

Error is the common kernel error type for infrastructure contracts.

func AsError

func AsError(err error) (*Error, bool)

AsError extracts an Error from an error chain.

func NewError

func NewError(kind ErrorKind, op string, message string) *Error

NewError creates an Error without a wrapped cause.

Example

package main

import (
	"github.com/ZoneCNH/kernel/errx"
)

func main() {
	_ = errx.NewError(errx.ErrorKindValidation, "user.Create", "invalid name").
		WithCode("INVALID_NAME").
		WithSeverity(errx.SeverityWarning)
}

func WrapError

func WrapError(kind ErrorKind, op string, message string, cause error) *Error

WrapError creates an Error that unwraps to cause.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap exposes the underlying cause for errors.Is and errors.As.

func (*Error) WithCode

func (e *Error) WithCode(code string) *Error

WithCode sets a stable machine-readable code and returns the same pointer.

Use only during Error construction; do not call on errors already shared or returned.

func (*Error) WithRetryable

func (e *Error) WithRetryable(retryable bool) *Error

WithRetryable sets whether the operation may be retried by an upper layer. It mutates the receiver and returns the same pointer for construction-time annotation.

Use only during Error construction; do not call on errors already shared or returned.

func (*Error) WithSeverity

func (e *Error) WithSeverity(severity Severity) *Error

WithSeverity sets operator-facing impact and returns the same pointer.

Use only during Error construction; do not call on errors already shared or returned.

type ErrorKind

type ErrorKind string

ErrorKind classifies infrastructure-level failures without binding to a specific driver or business domain.

const (
	ErrorKindConfig       ErrorKind = "config"
	ErrorKindValidation   ErrorKind = "validation"
	ErrorKindConnection   ErrorKind = "connection"
	ErrorKindUnavailable  ErrorKind = "unavailable"
	ErrorKindTimeout      ErrorKind = "timeout"
	ErrorKindAuth         ErrorKind = "auth"
	ErrorKindConflict     ErrorKind = "conflict"
	ErrorKindRateLimit    ErrorKind = "rate_limit"
	ErrorKindCanceled     ErrorKind = "canceled"
	ErrorKindNotFound     ErrorKind = "not_found"
	ErrorKindAlreadyExist ErrorKind = "already_exists"
	ErrorKindInternal     ErrorKind = "internal"
)

type Severity

type Severity string

Severity describes operator-facing impact without choosing logging policy.

const (
	SeverityInfo     Severity = "info"
	SeverityWarning  Severity = "warning"
	SeverityError    Severity = "error"
	SeverityCritical Severity = "critical"
)