errors

package module

v1.0.0 Latest Latest Go to latest Published: Jan 12, 2026 License: Apache-2.0 Imports: 11 Imported by: 1

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/go-anyway/framework-errors

Links

Open Source Insights

README ¶

framework-errors

Go framework package for errors.

Installation

go get github.com/go-anyway/framework-errors@v1.0.0

Usage

See documentation for usage examples.

License

Apache License 2.0

Documentation ¶

Index ¶

Constants
Variables
func GetMessage(code int32, customMessage string) string
func LogAndReturnError(ctx context.Context, err StatusError) error
func NewAndLogError(ctx context.Context, code int32, message string, opts ...Option) error
func ToGRPCError(err StatusError) error
func ToGRPCStatus(err StatusError) *status.Status
func WrapAndLogError(ctx context.Context, err error, code int32, message string, opts ...Option) error
type CodeDefinition
- func GetCodeDefinition(code int32) CodeDefinition
type Extension
type Option
- func Extra(k, v string) Option
- func Param(k, v string) Option
type StatusError

Constants ¶

View Source

const (
	CodeSuccess int32 = 200

	// 通用错误 1000-1999
	CodeInvalidParam   int32 = 1001
	CodeUnauthorized   int32 = 1002
	CodeForbidden      int32 = 1003
	CodeNotFound       int32 = 1004
	CodeAlreadyExists  int32 = 1005
	CodeInternalError  int32 = 1006
	CodeRequestTimeout int32 = 1007

	// 业务错误 2000-2999
	CodeUserNotFound      int32 = 2001
	CodeUserAlreadyExist  int32 = 2002
	CodeRateLimitExceeded int32 = 2003
	CodeTokenExpired      int32 = 2004
)

业务错误码（使用 int32 以兼容 gRPC）

Variables ¶

View Source

var CodeDefinitions = map[int32]CodeDefinition{
	CodeSuccess: {
		Message:           "success",
		IsAffectStability: false,
	},
	CodeInvalidParam: {
		Message:           "参数无效",
		IsAffectStability: false,
	},
	CodeUnauthorized: {
		Message:           "未授权",
		IsAffectStability: false,
	},
	CodeForbidden: {
		Message:           "禁止访问",
		IsAffectStability: false,
	},
	CodeNotFound: {
		Message:           "资源未找到",
		IsAffectStability: false,
	},
	CodeAlreadyExists: {
		Message:           "资源已存在",
		IsAffectStability: false,
	},
	CodeInternalError: {
		Message:           "内部服务器错误",
		IsAffectStability: true,
	},
	CodeUserNotFound: {
		Message:           "用户不存在",
		IsAffectStability: false,
	},
	CodeUserAlreadyExist: {
		Message:           "用户已存在",
		IsAffectStability: false,
	},
	CodeRateLimitExceeded: {
		Message:           "请求过于频繁",
		IsAffectStability: false,
	},
	CodeTokenExpired: {
		Message:           "认证令牌已过期",
		IsAffectStability: false,
	},
	CodeRequestTimeout: {
		Message:           "请求超时",
		IsAffectStability: false,
	},
}

CodeDefinitions 是预定义的错误码及其定义的映射业务可以在自己的包中通过 init() 函数向此 map 添加自定义的错误码

Functions ¶

func GetMessage ¶

func GetMessage(code int32, customMessage string) string

GetMessage 获取错误码对应的消息，如果提供了自定义消息则优先使用

func LogAndReturnError ¶

func LogAndReturnError(ctx context.Context, err StatusError) error

LogAndReturnError 记录错误日志并返回 gRPC error 如果 err 是 StatusError，会自动记录包含错误码、消息和扩展信息的日志 logger 从 ctx 中通过 log.FromContext 获取

func NewAndLogError ¶

func NewAndLogError(ctx context.Context, code int32, message string, opts ...Option) error

NewAndLogError 创建新的 StatusError，记录日志并返回 gRPC error

func ToGRPCError ¶

func ToGRPCError(err StatusError) error

ToGRPCError 将 StatusError 转换为 gRPC error 这是一个便捷函数，用于在服务层直接返回 gRPC 错误

func ToGRPCStatus ¶

func ToGRPCStatus(err StatusError) *status.Status

ToGRPCStatus 将 StatusError 转换为 gRPC status，使用 details 传递状态错误信息

func WrapAndLogError ¶

func WrapAndLogError(ctx context.Context, err error, code int32, message string, opts ...Option) error

WrapAndLogError 包装普通 error 为 StatusError，记录日志并返回 gRPC error

Types ¶

type CodeDefinition ¶

type CodeDefinition struct {
	Message           string // 错误消息
	IsAffectStability bool   // 是否影响系统稳定性，可用于告警分级
}

CodeDefinition 定义了错误码的详细信息

func GetCodeDefinition ¶

func GetCodeDefinition(code int32) CodeDefinition

GetCodeDefinition 获取错误码定义，如果不存在则返回默认定义

type Extension ¶

type Extension struct {
	IsAffectStability bool
	Extra             map[string]string
}

Extension 包含了错误的扩展信息

type Option ¶

type Option func(ws *withStatus)

Option 是一个用于修改 withStatus 错误的函数. withStatus 是我们内部用来包装 statusError 的结构体，将在 errors.go 中定义.

func Extra ¶

func Extra(k, v string) Option

Extra 用于向错误添加额外的键值对元数据. 这些数据可以用于日志记录、监控或调试.

func Param ¶

func Param(k, v string) Option

Param 用于替换错误消息中的占位符. 例如，如果消息是 "user {name} not found"，使用 Param("name", "zampo") 将会把消息格式化为 "user zampo not found".

type StatusError ¶

type StatusError interface {
	error
	Code() int32
	IsAffectStability() bool
	Msg() string
	Extra() map[string]string
}

StatusError 状态错误接口

func FromGRPCStatus ¶

func FromGRPCStatus(st *status.Status) StatusError

FromGRPCStatus 从 gRPC status 解析状态错误

func NewStatusError ¶

func NewStatusError(code int32, message string, data interface{}) StatusError

NewStatusError 创建状态错误如果 message 为空，则使用 CodeDefinitions 中定义的默认消息

func NewWithStatus ¶

func NewWithStatus(code int32, message string, opts ...Option) StatusError

NewWithStatus 创建一个带堆栈的 StatusError，支持 Option 模式

func WithStack ¶

func WithStack(err StatusError) StatusError

WithStack 为 StatusError 添加调用堆栈信息

func WrapWithStatus ¶

func WrapWithStatus(err error, code int32, message string, data interface{}) StatusError

WrapWithStatus 将一个普通 error 包装为带状态的 StatusError

func WrapWithStatusOptions ¶

func WrapWithStatusOptions(err error, code int32, message string, opts ...Option) StatusError

WrapWithStatusOptions 将一个普通 error 包装为带状态的 StatusError，支持 Option 模式

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL