reason

package
v1.7.9 Latest Latest
Warning

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

 Go to latest Published: Jul 22, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrBadRequest           = NewError("ErrBadRequest", "请求参数有误")
	ErrNotFound             = NewError("ErrNotFound", "资源未找到")
	ErrConflict             = NewError("ErrConflict", "操作冲突，请稍后重试")
	ErrAborted              = NewError("ErrAborted", "操作被中止")
	ErrJSON                 = NewError("ErrJSON", "JSON 编解码出错")
	ErrUsedLogic            = NewError("ErrUsedLogic", "使用逻辑错误")
	ErrLoginLimiter         = NewError("ErrLoginLimiter", "触发登录限制")
	ErrFileUpload           = NewError("ErrFileUpload", "文件上传失败")
	ErrUnsupportedMediaType = NewError("ErrUnsupportedMediaType", "不支持的媒体类型")
)

客户端错误（HTTP 400）

参考：https://cloud.google.com/apis/design/errors

View Source 
var (
	ErrUnauthorized     = NewError("ErrUnauthorized", "未登录或凭证已过期").WithHTTPStatus(401)
	ErrPermissionDenied = NewError("ErrPermissionDenied", "没有该资源的权限").WithHTTPStatus(403)
	ErrFileTooLarge     = NewError("ErrFileTooLarge", "文件大小超出限制").WithHTTPStatus(413)
	ErrContentTooLarge  = NewError("ErrContentTooLarge", "请求体过大").WithHTTPStatus(413)
	ErrTooManyRequests  = NewError("ErrTooManyRequests", "请求频率过高").WithHTTPStatus(429)
)

客户端错误（非 400 状态码）

View Source 
var (
	ErrInternal     = NewError("ErrInternal", "服务器内部错误").WithHTTPStatus(500)
	ErrDB           = NewError("ErrStore", "数据发生错误").WithHTTPStatus(500)
	ErrServer       = NewError("ErrServer", "服务器发生错误").WithHTTPStatus(500)
	ErrNetworkError = NewError("ErrNetworkError", "网络连接错误").WithHTTPStatus(500)
)

服务端错误（HTTP 500）

View Source 
var (
	ErrUnimplemented      = NewError("ErrUnimplemented", "功能尚未实现").WithHTTPStatus(501)
	ErrServiceUnavailable = NewError("ErrServiceUnavailable", "服务暂时不可用").WithHTTPStatus(503)
	ErrTimeout            = NewError("ErrTimeout", "请求超时").WithHTTPStatus(504)
)

服务端错误（非 500 状态码）

View Source 
var (
	ErrNameOrPasswd    = NewError("ErrNameOrPasswd", "用户名或密码错误")
	ErrCaptchaWrong    = NewError("ErrCaptchaWrong", "验证码错误")
	ErrAccountDisabled = NewError("ErrAccountDisabled", "登录限制")
)

业务错误

View Source 
var ErrRateLimit = NewError("ErrRateLimit", "请求频率过高").WithHTTPStatus(429)

Deprecated: 使用 ErrTooManyRequests 代替。

View Source 
var ErrUnauthorizedToken = NewError("ErrUnauthorizedToken", "用户已过期或错误").WithHTTPStatus(401)

Deprecated: 使用 ErrUnauthorized 代替。

Functions

func IsCustomError added in v1.3.4 

func IsCustomError(err error) bool

IsCustomError 判断 err 是否实现了 CustomError 接口。 建议直接使用 err.(CustomError) 类型断言。

Types

type CustomError 

type CustomError interface {
	error
	ErrorInfoer

	// With 追加开发者排查信息到 details。
	With(args ...string) CustomError
	// Withf 格式化追加 details。
	Withf(format string, args ...any) CustomError
	// WithCause 包裹底层错误，保留 errors.Is/As 链路。
	WithCause(err error) CustomError
	// WithMsg 覆盖面向用户的提示信息。
	WithMsg(s string) CustomError
	// WithHTTPStatus 覆盖 HTTP 响应状态码。
	WithHTTPStatus(status int) CustomError

	// Deprecated: 使用 WithMsg 代替。
	SetMsg(s string) CustomError
	// Deprecated: 使用 WithHTTPStatus 代替。
	SetHTTPStatus(status int) CustomError
}

CustomError 是 goddd 统一错误接口。 所有方法均返回新对象，不修改原错误（不可变语义）。

func NewError 

func NewError(reason, msg string) CustomError

NewError 创建一个自定义错误。 该函数要求每个 reason 全局唯一，若发现重复定义会立即 panic， 目的是在程序启动阶段就暴露冲突，避免不同模块使用相同的 reason 导致错误判断语义混乱。

type Error 

type Error struct {
	Reason     string   `json:"reason"`
	Msg        string   `json:"msg"`
	Details    []string `json:"details"`
	HTTPStatus int      `json:"-"`
	Cause      error    `json:"-"`
}

Error 是 goddd 的统一错误结构体。 Reason 和 Msg 面向 API 消费者，Details 面向开发者排查， HTTPStatus 映射 HTTP 状态码，Cause 保留底层错误链路。

func (*Error) As 

func (e *Error) As(target any) bool

As 支持 errors.As 将错误提取为 *Error 类型。 匹配成功时将自身赋值给 target，符合标准库契约。

func (*Error) Error 

func (e *Error) Error() string

Error 拼接 Msg 和 Details 返回完整的错误文本。

func (*Error) GetDetails 

func (e *Error) GetDetails() []string

GetDetails 返回错误的详情列表。

func (*Error) GetHTTPCode 

func (e *Error) GetHTTPCode() int

GetHTTPCode 返回错误对应的 HTTP 状态码。

func (*Error) GetMessage 

func (e *Error) GetMessage() string

GetMessage 返回面向用户的提示信息。

func (*Error) GetReason 

func (e *Error) GetReason() string

GetReason 返回错误的机器可读标识。

func (*Error) Is 

func (e *Error) Is(err error) bool

Is 按 Reason 字符串比较错误，而非指针比较。 即使经过 With/WithMsg 产生了新对象，只要 Reason 相同就视为同一类错误。

func (*Error) SetHTTPStatus deprecated 

func (e *Error) SetHTTPStatus(status int) CustomError

SetHTTPStatus 是 WithHTTPStatus 的旧名称，保留以兼容已有代码。

Deprecated: 使用 WithHTTPStatus 代替。

func (*Error) SetMsg deprecated 

func (e *Error) SetMsg(s string) CustomError

SetMsg 是 WithMsg 的旧名称，保留以兼容已有代码。

Deprecated: 使用 WithMsg 代替。

func (*Error) Unwrap added in v1.7.8 

func (e *Error) Unwrap() error

Unwrap 返回当前错误包裹的底层错误，供 errors.Is/errors.As 使用。 没有底层错误时返回 nil。

func (*Error) With 

func (e *Error) With(args ...string) CustomError

With 追加开发者排查信息到 details，返回新错误副本。

func (*Error) WithCause added in v1.7.8 

func (e *Error) WithCause(err error) CustomError

WithCause 返回一个携带底层错误的新错误，用于 errors.Is/As 链路解包。 首次调用直接设置 Cause；再次调用时通过 errors.Join 并列累加而非覆盖， 链式调用不丢前因。原错误不会被修改，符合 CustomError 不可变语义。

func (*Error) WithHTTPStatus added in v1.7.8 

func (e *Error) WithHTTPStatus(status int) CustomError

WithHTTPStatus 返回一个使用新 HTTP 状态码的错误副本，原错误不变。

func (*Error) WithMsg added in v1.7.8 

func (e *Error) WithMsg(s string) CustomError

WithMsg 返回一个使用新用户提示信息的错误副本，原错误不变。

func (*Error) Withf 

func (e *Error) Withf(format string, args ...any) CustomError

Withf 格式化追加 details，返回新错误副本。

type ErrorInfoer 

type ErrorInfoer interface {
	GetReason() string
	GetHTTPCode() int
	GetMessage() string
	GetDetails() []string
}

ErrorInfoer 提供错误结构化信息的只读访问， 供 web.Fail 等响应层提取 reason/msg/details/HTTPStatus。

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.