创建带错误码的 error

NewCode/NewCodef

• 说明：功能同 New/Newf 方法，用于创建一个自定义错误信息的 error 对象，并包含堆栈信息，并增加错误码对象的输入。

• 格式：

  // NewCode creates and returns an error that has error code and given text.
  NewCode(code gcode.Code, text ...string) error
  
  // NewCodef returns an error that has error code and formats as the given format and args.
  NewCodef(code gcode.Code, format string, args ...interface{}) error

• 实例：

  func ExampleNewCode() {
      err := gerror.NewCode(gcode.New(10000, "", nil), "My Error")
      fmt.Println(err.Error())
      fmt.Println(gerror.Code(err))
  
      // Output:
      // My Error
      // 10000
  }
  
  func ExampleNewCodef() {
      err := gerror.NewCodef(gcode.New(10000, "", nil), "It's %s", "My Error")
      fmt.Println(err.Error())
      fmt.Println(gerror.Code(err).Code())
  
      // Output:
      // It's My Error
      // 10000
  }

WrapCode/WrapCodef

• 说明：功能同 Wrap/Wrapf 方法，用于包裹其他错误 error 对象，构造成多级的错误信息，包含堆栈信息，并增加错误码参数的输入。

• 格式：

  // WrapCode wraps error with code and text.
  // It returns nil if given err is nil.
  WrapCode(code gcode.Code, err error, text ...string) error
  
  // WrapCodef wraps error with code and format specifier.
  // It returns nil if given `err` is nil.
  WrapCodef(code gcode.Code, err error, format string, args ...interface{}) error

• 示例：

  func ExampleWrapCode() {
      err1 := errors.New("permission denied")
      err2 := gerror.WrapCode(gcode.New(10000, "", nil), err1, "Custom Error")
      fmt.Println(err2.Error())
      fmt.Println(gerror.Code(err2).Code())
  
      // Output:
      // Custom Error: permission denied
      // 10000
  }
  
  func ExampleWrapCodef() {
      err1 := errors.New("permission denied")
      err2 := gerror.WrapCodef(gcode.New(10000, "", nil), err1, "It's %s", "Custom Error")
      fmt.Println(err2.Error())
      fmt.Println(gerror.Code(err2).Code())
  
      // Output:
      // It's Custom Error: permission denied
      // 10000
  }

NewCodeSkip/NewCodeSkipf

• 说明：功能同 NewCode/NewCodef，用于创建一个带错误码的 error 对象，但忽略部分堆栈信息（按照当前调用方法位置往上忽略）。

• 格式：

  // NewCodeSkip creates and returns an error which has error code and is formatted from given text.
  // The parameter `skip` specifies the stack callers skipped amount.
  func NewCodeSkip(code, skip int, text string) error
  
  // NewCodeSkipf returns an error that has error code and formats as the given format and args.
  // The parameter `skip` specifies the stack callers skipped amount.
  func NewCodeSkipf(code, skip int, format string, args ...interface{}) error

WrapCodeSkip/WrapCodeSkipf

• 说明：功能同 WrapCodeSkip/WrapCodeSkipf，用于包裹一个带错误码的 error 对象，但忽略部分堆栈信息（按照当前调用方法位置往上忽略）。

• 格式：

  // WrapCodeSkip wraps error with code and text.
  // It returns nil if given err is nil.
  // The parameter `skip` specifies the stack callers skipped amount.
  func WrapCodeSkip(code gcode.Code, skip int, err error, text ...string) error
  
  // WrapCodeSkipf wraps error with code and text that is formatted with given format and args.
  // It returns nil if given err is nil.
  // The parameter `skip` specifies the stack callers skipped amount.
  func WrapCodeSkipf(code gcode.Code, skip int, err error, format string, args ...interface{}) error

Code

• 说明：获取错误对象中的错误码。该方法会递归获取，如果当前错误对象不存在错误码时，该方法会追溯查找其上一级错误对象的错误码，以此类推。当给定的 error 参数不带有错误码信息时，该方法返回预定义的错误码 gcode.CodeNil。

• 格式：

  // Code returns the error code of `current error`.
  // It returns `CodeNil` if it has no error code neither it does not implement interface Code.
  func Code(err error) gcode.Code

• 示例：

  func ExampleCode() {
      err1 := gerror.NewCode(gcode.CodeInternalError, "permission denied")
      err2 := gerror.Wrap(err1, "operation failed")
      fmt.Println(gerror.Code(err1))
      fmt.Println(gerror.Code(err2))
  
      // Output:
      // 50:Internal Error
      // 50:Internal Error
  }

HasCode

• 说明：该方法判断给定的错误对象中是否包含指定的错误码。与Code方法类似，该方法也会追溯查找上一级错误的错误码。

• 格式：

  // HasCode checks and reports whether `err` has `code` in its chaining errors.
  func HasCode(err error, code gcode.Code) bool

• 示例：

  func ExampleHasCode() {
      err1 := gerror.NewCode(gcode.CodeInternalError, "permission denied")
      err2 := gerror.Wrap(err1, "operation failed")
      fmt.Println(gerror.HasCode(err1, gcode.CodeOK))
      fmt.Println(gerror.HasCode(err2, gcode.CodeInternalError))
  
      // Output:
      // false
      // true
  }