Creates a new XError pointer instance with message.
+ +Signature: + +```go +type XError struct { + id string + message string + stack *stack + cause error + values map[string]any +} + +func New(format string, args ...any) *XError +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("error") + fmt.Println(err.Error()) + + // Output: + // error +} +``` + +### Wrap + +Creates a new XError pointer instance based on error object, and add message.
+ +Signature: + +```go +func Wrap(cause error, message ...any) *XError +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("wrong password") + wrapErr := xerror.Wrap(err, "error") + + fmt.Println(wrapErr.Error()) + + // Output: + // error: wrong password +} +``` + +### Unwrap + +Returns unwrapped XError from err by errors.As. If no XError, returns nil.
+ +Signature: + +```go +func Unwrap(err error) *XError +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/pkg/errors" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err1 := xerror.New("error").With("level", "high") + wrapErr := errors.Wrap(err1, "oops") + + err := xerror.Unwrap(err1) + + values := err.Values() + fmt.Println(values["level"]) + + // Output: + // high +} +``` + +### XError_Wrap + +Creates a new XError and copy message and id to new one.
+ +Signature: + +```go +func (e *XError) Wrap(cause error) *XError +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("wrong password") + wrapErr := xerror.Wrap(err, "error") + + fmt.Println(wrapErr.Error()) + + // Output: + // error: wrong password +} +``` + +### XError_Unwrap + +Compatible with github.com/pkg/errors.
+ +Signature: + +```go +func (e *XError) Unwrap() error +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err1 := xerror.New("error").With("level", "high") + err2 := err1.Wrap(errors.New("invalid username")) + + err := err2.Unwrap() + + fmt.Println(err.Error()) + + // Output: + // invalid username +} +``` + +### XError_With + +Adds key and value related to the error object.
+ +Signature: + +```go +func (e *XError) With(key string, value any) *XError +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("error").With("level", "high") + + errLevel := err.Values()["level"] + + fmt.Println(errLevel) + + // Output: + // high +} +``` + +### XError_Id + +Sets XError object id to check equality in XError.Is.
+ +Signature: + +```go +func (e *XError) Id(id string) *XError +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err1 := xerror.New("error").Id("e001") + err2 := xerror.New("error").Id("e001") + err3 := xerror.New("error").Id("e003") + + equal := err1.Is(err2) + notEqual := err1.Is(err3) + + fmt.Println(equal) + fmt.Println(notEqual) + + // Output: + // true + // false +} +``` + +### XError_Is + +Checks if target error is XError and Error.id of two errors are matched.
+ +Signature: + +```go +func (e *XError) Is(target error) bool +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err1 := xerror.New("error").Id("e001") + err2 := xerror.New("error").Id("e001") + err3 := xerror.New("error").Id("e003") + + equal := err1.Is(err2) + notEqual := err1.Is(err3) + + fmt.Println(equal) + fmt.Println(notEqual) + + // Output: + // true + // false +} +``` + +### XError_Values + +Returns map of key and value that is set by With. All wrapped xerror.XError key and values will be merged. Key and values of wrapped error is overwritten by upper xerror.XError.
+ +Signature: + +```go +func (e *XError) Values() map[string]any +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("error").With("level", "high") + + errLevel := err.Values()["level"] + + fmt.Println(errLevel) + + // Output: + // high +} +``` + + +### XError_StackTrace + +Returns stack trace which is compatible with pkg/errors.
+ +Signature: + +```go +func (e *XError) StackTrace() StackTrace +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("error") + + stacks := err.Stacks() + + fmt.Println(stacks[0].Func) + fmt.Println(stacks[0].Line) + + containFile := strings.Contains(stacks[0].File, "xxx.go") + fmt.Println(containFile) +} +``` + + +### XError_Info + +Returns information of xerror, which can be printed.
+ +Signature: + +```go +func (e *XError) Info() *errInfo +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + cause := errors.New("error") + err := xerror.Wrap(cause, "invalid username").Id("e001").With("level", "high") + + errInfo := err.Info() + + fmt.Println(errInfo.Id) + fmt.Println(errInfo.Cause) + fmt.Println(errInfo.Values["level"]) + fmt.Println(errInfo.Message) + + // Output: + // e001 + // error + // high + // invalid username +} +``` + + +### XError_Error + +Error implements standard error interface.
+ +Signature: + +```go +func (e *XError) Error() string +``` + +Example: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := New("error") + fmt.Println(err.Error()) + + // Output: + // error +} +``` ### TryUnwrapTryUnwrap if err is nil then it returns a valid value. If err is not nil, Unwrap panics with err.
diff --git a/docs/xerror_zh-CN.md b/docs/xerror_zh-CN.md index 8ebc0da..eb90caa 100644 --- a/docs/xerror_zh-CN.md +++ b/docs/xerror_zh-CN.md @@ -22,12 +22,433 @@ import ( ## 目录 +- [New](#New) +- [Wrap](#Wrap) +- [Unwrap](#Unwrap) +- [XError_Wrap](#XError_Wrap) +- [XError_Unwrap](#XError_Unwrap) +- [XError_With](#XError_With) +- [XError_Is](#XError_Is) +- [XError_Id](#XError_Id) +- [XError_Values](#XError_Values) +- [XError_StackTrace](#XError_StackTrace) +- [XError_Info](#XError_Info) +- [XError_Error](#XError_Error) - [TryUnwrap](#TryUnwrap) ## 文档 +### New + +创建XError对象实例。
+ +函数签名: + +```go +type XError struct { + id string + message string + stack *stack + cause error + values map[string]any +} + +func New(format string, args ...any) *XError +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("error") + fmt.Println(err.Error()) + + // Output: + // error +} +``` + +### Wrap + +根据error对象创建XError对象实例，可添加message。
+ +函数签名: + +```go +func Wrap(cause error, message ...any) *XError +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("wrong password") + wrapErr := xerror.Wrap(err, "error") + + fmt.Println(wrapErr.Error()) + + // Output: + // error: wrong password +} +``` + +### Unwrap + +从error对象中解构出XError。
+ +函数签名: + +```go +func Unwrap(err error) *XError +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/pkg/errors" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err1 := xerror.New("error").With("level", "high") + wrapErr := errors.Wrap(err1, "oops") + + err := xerror.Unwrap(err1) + + values := err.Values() + fmt.Println(values["level"]) + + // Output: + // high +} +``` + +### XError_Wrap + +创建新的XError对象并将消息和id复制到新的对象中。
+ +函数签名: + +```go +func (e *XError) Wrap(cause error) *XError +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("wrong password") + wrapErr := xerror.Wrap(err, "error") + + fmt.Println(wrapErr.Error()) + + // Output: + // error: wrong password +} +``` + +### XError_Unwrap + +解构XEerror为error对象。适配github.com/pkg/errors。
+ +函数签名: + +```go +func (e *XError) Unwrap() error +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err1 := xerror.New("error").With("level", "high") + err2 := err1.Wrap(errors.New("invalid username")) + + err := err2.Unwrap() + + fmt.Println(err.Error()) + + // Output: + // invalid username +} +``` + +### XError_With + +添加与XError对象的键和值。
+ +函数签名: + +```go +func (e *XError) With(key string, value any) *XError +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("error").With("level", "high") + + errLevel := err.Values()["level"] + + fmt.Println(errLevel) + + // Output: + // high +} +``` + +### XError_Id + +设置XError对象的id.
+ +函数签名: + +```go +func (e *XError) Id(id string) *XError +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err1 := xerror.New("error").Id("e001") + err2 := xerror.New("error").Id("e001") + err3 := xerror.New("error").Id("e003") + + equal := err1.Is(err2) + notEqual := err1.Is(err3) + + fmt.Println(equal) + fmt.Println(notEqual) + + // Output: + // true + // false +} +``` + +### XError_Is + +检查目标error是否为XError，两个错误中的error.id是否匹配。
+ +函数签名: + +```go +func (e *XError) Is(target error) bool +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err1 := xerror.New("error").Id("e001") + err2 := xerror.New("error").Id("e001") + err3 := xerror.New("error").Id("e003") + + equal := err1.Is(err2) + notEqual := err1.Is(err3) + + fmt.Println(equal) + fmt.Println(notEqual) + + // Output: + // true + // false +} +``` + +### XError_Values + +返回由With设置的键和值的映射。将合并所有XError键和值。
+ +函数签名: + +```go +func (e *XError) Values() map[string]any +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("error").With("level", "high") + + errLevel := err.Values()["level"] + + fmt.Println(errLevel) + + // Output: + // high +} +``` + + +### XError_StackTrace + +返回与pkg/error兼容的堆栈信息
+ +函数签名: + +```go +func (e *XError) StackTrace() StackTrace +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := xerror.New("error") + + stacks := err.Stacks() + + fmt.Println(stacks[0].Func) + fmt.Println(stacks[0].Line) + + containFile := strings.Contains(stacks[0].File, "xxx.go") + fmt.Println(containFile) +} +``` + + +### XError_Info + +返回可打印的XError对象信息。
+ +函数签名: + +```go +func (e *XError) Info() *errInfo +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + cause := errors.New("error") + err := xerror.Wrap(cause, "invalid username").Id("e001").With("level", "high") + + errInfo := err.Info() + + fmt.Println(errInfo.Id) + fmt.Println(errInfo.Cause) + fmt.Println(errInfo.Values["level"]) + fmt.Println(errInfo.Message) + + // Output: + // e001 + // error + // high + // invalid username +} +``` + + +### XError_Error + +实现标准库的error接口。
+ +函数签名: + +```go +func (e *XError) Error() string +``` + +示例: + +```go +package main + +import ( + "fmt" + "github.com/duke-git/lancet/v2/xerror" +) + +func main() { + err := New("error") + fmt.Println(err.Error()) + + // Output: + // error +} +``` + ### TryUnwrap检查error, 如果err为nil则展开，则它返回一个有效值，如果err不是nil则TryUnwrap使用err发生panic。