{
  "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) {
    // 對應錯誤處理邏輯
}

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

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

    // Message 表示簡短的錯誤信息，通?？芍苯颖┞督o用戶查看.
    Message string`json:"message,omitempty"`

    // Metadata 用于存儲與該錯誤相關的額外元信息，可以包含上下文或調試信息.
    Metadata map[string]string`json:"metadata,omitempty"`
}

// Error 實現(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 設置錯誤的 Message 字段.
func (err *ErrorX) WithMessage(format string, args ...any) *ErrorX {
    err.Message = fmt.Sprintf(format, args...)
    return err
}

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

// KV 使用 key-value 對設置元數(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 必須是成對的
        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 返回錯誤的 HTTP 代碼.
func Code(err error) int {
    if err == nil {
        return http.StatusOK //nolint:mnd
    }
    return FromError(err).Code
}

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

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

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

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

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

    // 遍歷 gRPC 錯誤詳情中的所有附加信息（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 判斷當前錯誤是否與目標錯誤匹配.
// 它會遞歸遍歷錯誤鏈，并比較 ErrorX 實例的 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 代表請求成功.
    OK = &errorsx.ErrorX{Code: http.StatusOK, Message: ""}

    // ErrInternal 表示所有未知的服務器端錯誤.
    ErrInternal = errorsx.ErrInternal

    ...

    // ErrPageNotFound 表示頁面未找到.
    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")
        // 在錯誤最原始位置封裝自定義錯誤
        // 方式1：不帶自定義信息的錯誤返回
        return errno.ErrPasswordInvalid
        // 方式2:帶有自定義信息的錯誤返回
        //return errno.ErrPasswordInvalid.WithMessage("Password is too short")
    }
    returnnil
}

func validateUser() error {
    // 直接透傳 validatePassword 返回的自定義錯誤
    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)建了一個 ErrorX 錯誤，表示數(shù)據(jù)庫連接失敗。
    // Code: 500，表明是服務器內部錯誤。
    // Reason: "InternalError.DBConnection"，表示錯誤的具體分類。
    // Message: "Something went wrong: DB connection failed"，表示該錯誤的具體信息。
    errx := errorsx.New(500, "InternalError.DBConnection", "Something went wrong: %s", "DB connection failed")

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

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

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

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

    // 再次打印 errx，此時的內容已經發(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ù)也會被一并輸出。
    fmt.Println(errx)

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

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

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

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