{
  "error": {
    "message": "Syntax error \"Field picture specified more than once. This is only possible before version 2.1\" at character 23: id,name,picture,picture",
    "type": "OAuthException",
    "code": 2500,
    "fbtrace_id": "xxxxxxxxxxx"
  }
}

HTTP/1.1 400 Bad Request
x-connection-hash: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
set-cookie: guest_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Date: Thu, 01 Jun 201703:04:23 GMT
Content-Length: 62
x-response-time: 5
strict-transport-security: max-age=631138519
Connection: keep-alive
Content-Type: application/json; charset=utf-8
Server: tsa_b

{
"errors": [
    {
      "code": 215,
      "message": "Bad Authentication data."
    }
  ]
}

{
  "code": "InvalidParameter.BadAuthenticationData",
  "message": "Bad Authentication data."
}

HTTP/1.1 404 Not Found
...
{
  "code": "NotFound.UserNotFound",
  "message": "User not found."
}

import "errors"
import "path/to/errno"

if errors.Is(err, errno.InternalServerError) {
    // 對(duì)應(yīng)錯(cuò)誤處理邏輯
}

// ErrorX 定義了 OneX 項(xiàng)目體系中使用的錯(cuò)誤類型，用于描述錯(cuò)誤的詳細(xì)信息.
type ErrorX struct {
    // Code 表示錯(cuò)誤的 HTTP 狀態(tài)碼，用于與客戶端進(jìn)行交互時(shí)標(biāo)識(shí)錯(cuò)誤的類型.
    Code int`json:"code,omitempty"`

    // Reason 表示錯(cuò)誤發(fā)生的原因，通常為業(yè)務(wù)錯(cuò)誤碼，用于精準(zhǔn)定位問(wèn)題.
    Reason string`json:"reason,omitempty"`

    // Message 表示簡(jiǎn)短的錯(cuò)誤信息，通常可直接暴露給用戶查看.
    Message string`json:"message,omitempty"`

    // Metadata 用于存儲(chǔ)與該錯(cuò)誤相關(guān)的額外元信息，可以包含上下文或調(diào)試信息.
    Metadata map[string]string`json:"metadata,omitempty"`
}

// Error 實(shí)現(xiàn) error 接口中的 `Error` 方法.
func (err *ErrorX) Error() string {
    return fmt.Sprintf("error: code = %d reason = %s message = %s metadata = %v", err.Code, err.Reason, err.Message, err.Metadata)
}

// WithMessage 設(shè)置錯(cuò)誤的 Message 字段.
func (err *ErrorX) WithMessage(format string, args ...any) *ErrorX {
    err.Message = fmt.Sprintf(format, args...)
    return err
}

// WithMetadata 設(shè)置元數(shù)據(jù).
func (err *ErrorX) WithMetadata(md map[string]string) *ErrorX {
    err.Metadata = md
    return err
}

// KV 使用 key-value 對(duì)設(shè)置元數(shù)據(jù).
func (err *ErrorX) KV(kvs ...string) *ErrorX {
    if err.Metadata == nil {
        err.Metadata = make(map[string]string) // 初始化元數(shù)據(jù)映射
    }

    for i := 0; i < len(kvs); i += 2 {
        // kvs 必須是成對(duì)的
        if i+1 < len(kvs) {
            err.Metadata[kvs[i]] = kvs[i+1]
        }
    }
    return err
}

err := new(ErrorX)
err.WithMessage("Message").WithMetadata(map[string]string{"key":"value"})

// GRPCStatus 返回 gRPC 狀態(tài)表示.
func (err *ErrorX) GRPCStatus() *status.Status {
    details := errdetails.ErrorInfo{Reason: err.Reason, Metadata: err.Metadata}
    s, _ := status.New(httpstatus.ToGRPCCode(err.Code), err.Message).WithDetails(&details)
    return s
}

// Code 返回錯(cuò)誤的 HTTP 代碼.
func Code(err error) int {
    if err == nil {
        return http.StatusOK //nolint:mnd
    }
    return FromError(err).Code
}

// Reason 返回特定錯(cuò)誤的原因.
func Reason(err error) string {
    if err == nil {
        return ErrInternal.Reason
    }
    return FromError(err).Reason
}

// FromError 嘗試將一個(gè)通用的 error 轉(zhuǎn)換為自定義的 *ErrorX 類型.
func FromError(err error) *ErrorX {
    // 如果傳入的錯(cuò)誤是 nil，則直接返回 nil，表示沒有錯(cuò)誤需要處理.
    if err == nil {
        returnnil
    }

    // 檢查傳入的 error 是否已經(jīng)是 ErrorX 類型的實(shí)例.
    // 如果錯(cuò)誤可以通過(guò) errors.As 轉(zhuǎn)換為 *ErrorX 類型，則直接返回該實(shí)例.
    if errx := new(ErrorX); errors.As(err, &errx) {
        return errx
    }

    // gRPC 的 status.FromError 方法嘗試將 error 轉(zhuǎn)換為 gRPC 錯(cuò)誤的 status 對(duì)象.
    // 如果 err 不能轉(zhuǎn)換為 gRPC 錯(cuò)誤（即不是 gRPC 的 status 錯(cuò)誤），
    // 則返回一個(gè)帶有默認(rèn)值的 ErrorX，表示是一個(gè)未知類型的錯(cuò)誤.
    gs, ok := status.FromError(err)
    if !ok {
        return New(ErrInternal.Code, ErrInternal.Reason, err.Error())
    }

    // 如果 err 是 gRPC 的錯(cuò)誤類型，會(huì)成功返回一個(gè) gRPC status 對(duì)象（gs）.
    // 使用 gRPC 狀態(tài)中的錯(cuò)誤代碼和消息創(chuàng)建一個(gè) ErrorX.
    ret := New(httpstatus.FromGRPCCode(gs.Code()), ErrInternal.Reason, gs.Message())

    // 遍歷 gRPC 錯(cuò)誤詳情中的所有附加信息（Details）.
    for _, detail := range gs.Details() {
        if typed, ok := detail.(*errdetails.ErrorInfo); ok {
            ret.Reason = typed.Reason
            return ret.WithMetadata(typed.Metadata)
        }
    }

    return ret
}

// Is 判斷當(dāng)前錯(cuò)誤是否與目標(biāo)錯(cuò)誤匹配.
// 它會(huì)遞歸遍歷錯(cuò)誤鏈，并比較 ErrorX 實(shí)例的 Code 和 Reason 字段.
// 如果 Code 和 Reason 均相等，則返回 true；否則返回 false.
func (err *ErrorX) Is(target error) bool {
    if errx := new(ErrorX); errors.As(target, &errx) {
        return errx.Code == err.Code && errx.Reason == err.Reason
    }
    return false
}

var (
    // OK 代表請(qǐng)求成功.
    OK = &errorsx.ErrorX{Code: http.StatusOK, Message: ""}

    // ErrInternal 表示所有未知的服務(wù)器端錯(cuò)誤.
    ErrInternal = errorsx.ErrInternal

    ...

    // ErrPageNotFound 表示頁(yè)面未找到.
    ErrPageNotFound = &errorsx.ErrorX{Code: http.StatusNotFound, Reason: "NotFound.PageNotFound", Message: "Page not found."}
    ...
)

package main

import (
    "github.com/onexstack/miniblog/internal/pkg/errno"
    "github.com/onexstack/miniblog/internal/pkg/log"
)

func main() {
    if err := validateUser(); err != nil {
        panic(err)
    }
}

func validatePassword(password string) error {
    iflen(password) < 6 {
        log.Errorw("Password is too short")
        // 在錯(cuò)誤最原始位置封裝自定義錯(cuò)誤
        // 方式1：不帶自定義信息的錯(cuò)誤返回
        return errno.ErrPasswordInvalid
        // 方式2:帶有自定義信息的錯(cuò)誤返回
        //return errno.ErrPasswordInvalid.WithMessage("Password is too short")
    }
    returnnil
}

func validateUser() error {
    // 直接透?jìng)?validatePassword 返回的自定義錯(cuò)誤
    if err := validatePassword("test"); err != nil {
        return err
    }
    returnnil
}

package main

import (
    "fmt"

    "github.com/onexstack/onexstack/pkg/errorsx"

    "github.com/onexstack/miniblog/internal/pkg/errno"
)

func main() {
    // 創(chuàng)建了一個(gè) ErrorX 錯(cuò)誤，表示數(shù)據(jù)庫(kù)連接失敗。
    // Code: 500，表明是服務(wù)器內(nèi)部錯(cuò)誤。
    // Reason: "InternalError.DBConnection"，表示錯(cuò)誤的具體分類。
    // Message: "Something went wrong: DB connection failed"，表示該錯(cuò)誤的具體信息。
    errx := errorsx.New(500, "InternalError.DBConnection", "Something went wrong: %s", "DB connection failed")

    // fmt.Println 會(huì)調(diào)用 errx 的 Error 方法，輸出：
    // error: code = 500 reason = InternalError.DBConnection message = Something went wrong: DB connection failed metadata = map[]
    fmt.Println(errx)

    // 給錯(cuò)誤添加元數(shù)據(jù)，增強(qiáng)錯(cuò)誤的上下文信息，便于調(diào)試和追蹤。
    errx.WithMetadata(map[string]string{
        "user_id":    "12345",   // 添加用戶 ID 信息
        "request_id": "abc-def", // 添加請(qǐng)求 ID 信息
    })

    // 繼續(xù)向錯(cuò)誤中添加元數(shù)據(jù)，這次使用了 KV 方法，它是一種更加簡(jiǎn)潔的方式，用 key-value 的模式逐一設(shè)置元數(shù)據(jù)。
    // 這里添加 trace_id 信息，用于關(guān)聯(lián)分布式鏈路信息。
    errx.KV("trace_id", "xyz-789")

    // 使用 WithMessage 方法更新錯(cuò)誤的 Message 字段。
    // 更新后的 Message 是：Updated message: retry failed。
    // Note: 更新消息字段并不會(huì)影響 Code、Reason 和 Metadata，它只是說(shuō)明錯(cuò)誤的上下文發(fā)生了變化。
    errx.WithMessage("Updated message: %s", "retry failed")

    // 再次打印 errx，此時(shí)的內(nèi)容已經(jīng)發(fā)生了變化：
    // error: code = 500 reason = InternalError.DBConnection message = Updated message: retry failed metadata = map[request_id:abc-def trace_id:xyz-789 user_id:12345]
    // 元數(shù)據(jù)也會(huì)被一并輸出。
    fmt.Println(errx)

    // 調(diào)用 doSomething 函數(shù)，生成一個(gè)錯(cuò)誤，并打印它，這里返回一個(gè)更新過(guò) Message 字段的預(yù)定義錯(cuò)誤 errno.ErrUsernameInvalid。
    someerr := doSomething()
    // 打印錯(cuò)誤。
    // error: code = 400 reason = InvalidArgument.UsernameInvalid message = Username is too short metadata = map[]
    fmt.Println(someerr)

    // 調(diào)用預(yù)定義錯(cuò)誤 errno.ErrUsernameInvalid 的 Is 方法，判斷 someerr 是否屬于該類型錯(cuò)誤。
    // Is 方法會(huì)比較 Code 和 Reason 字段（不會(huì)比較 Message 字段），如果兩者一致，則返回 true。
    // 因?yàn)?doSomething 返回的錯(cuò)誤正是 errno.ErrUsernameInvalid 的實(shí)例，因此這里輸出 true。
    fmt.Println(errno.ErrUsernameInvalid.Is(someerr))

    // 調(diào)用另外一個(gè)預(yù)定義錯(cuò)誤 errno.ErrPasswordInvalid 的 Is 方法，比較 someerr 是否屬于該錯(cuò)誤。
    // 因?yàn)?Reason 和 Code 不匹配（someerr 是 username 錯(cuò)誤，而不是 password 錯(cuò)誤），因此返回 false。
    fmt.Println(errno.ErrPasswordInvalid.Is(someerr))
}

// 定義一個(gè)函數(shù) doSomething，返回一個(gè)錯(cuò)誤
func doSomething() error {
    // 這里返回了一個(gè)已經(jīng)定義的錯(cuò)誤類型 errno.ErrUsernameInvalid，但動(dòng)態(tài)地設(shè)置了 Message 字段為 "Username is too short"。
    // 重點(diǎn)是：雖然錯(cuò)誤的 Message 不同，但錯(cuò)誤的 Code 和 Reason 是一致的，這方便使用 Is 方法進(jìn)行類型判斷而不受具體內(nèi)容影響。
    return errno.ErrUsernameInvalid.WithMessage("Username is too short")
}