Go 開發者必修課：如何優雅的設計和實現 API 接口的錯誤返回
在 Go 項目開發中，有很多基礎的 Go 包需要我們去設計。其中，錯誤包是 Go 項目開發必須要考慮的一個設計。
錯誤包在 Go 項目開發中主要用來返回錯誤或者打印錯誤。返回錯誤時，既需在代碼內返回錯誤，又需要將錯誤返回給用戶。在設計和實現錯誤包的時候，需要考慮上述使用場景。
一、錯誤返回方法
在 Go 項目開發中，錯誤的返回方式通常有以下兩種：
- 始終返回 HTTP 200 狀態碼，并在 HTTP 返回體中返回錯誤信息；
- 返回 HTTP 400 狀態碼（Bad Request），并在 HTTP 返回體中返回錯誤信息。
方式一：成功返回，返回體中返回錯誤信息
例如 Facebook API 的錯誤返回設計，始終返回 200 HTTP 狀態碼：
{
"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 狀態碼始終固定返回 200，僅需關注業務錯誤碼，整體實現較為簡單。然而，此方式存在一個明顯的缺點：對于每一次 HTTP 請求，既需要檢查 HTTP 狀態碼以判斷請求是否成功，還需要解析響應體以獲取業務錯誤碼，從而判斷業務邏輯是否成功。理想情況下，我們期望客戶端對成功的 HTTP 請求能夠直接將響應體解析為需要的 Go 結構體，并進行后續的業務邏輯處理，而不用再判斷請求是否成功。
方式二：失敗返回，返回體中返回錯誤信息
Twitter API 的錯誤返回設計會根據錯誤類型返回對應的 HTTP 狀態碼，并在返回體中返回錯誤信息和自定義業務錯誤碼。成功的業務請求則返回 200 HTTP 狀態碼。例如：
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."
}
]
}方式二相比方式一，對于成功的請求不需要再次判錯。然而，方式二還可以進一步優化：整數格式的業務錯誤碼 215 可讀性較差，用戶無法從 215 直接獲取任何有意義的信息。建議將其替換為語義化的字符串，例如：NotFound.PostNotFound。
Twitter API 返回的錯誤是一個數組，在實際開發獲取錯誤時，需要先判斷數組是否為空，如不為空，再從數組中獲取錯誤，開發復雜度較高。建議采用更簡單的錯誤返回格式：
{
"code": "InvalidParameter.BadAuthenticationData",
"message": "Bad Authentication data."
}需要特別注意的是，message 字段會直接展示給外部用戶，因此必須確保其內容不包含敏感信息，例如數據庫的 id 字段、內部組件的 IP 地址、用戶名等信息。返回的錯誤信息中，還可以根據需要返回更多字段，例如：錯誤指引文檔 URL 等。
二、miniblog 錯誤返回設計和實現
miniblog 項目錯誤返回格式采用了方式二，在接口失敗時返回對應的 HTTP/gRPC 狀態碼，并在返回體中返回具體的錯誤信息，例如：
HTTP/1.1 404 Not Found
...
{
"code": "NotFound.UserNotFound",
"message": "User not found."
}在錯誤返回方式二中，需要返回一個業務錯誤碼。返回業務錯誤碼可以帶來以下好處：
- 快速定位問題：開發人員可以借助錯誤碼迅速定位問題，并精確到具體的代碼行。例如，錯誤碼可以直接指示問題的含義，同時通過工具（如 grep）輕松定位到錯誤碼在代碼中的具體位置；
- 便于排查問題：用戶能夠通過錯誤碼判斷接口失敗的原因，并將錯誤碼提供給開發人員，以便快速定位問題并進行排查；
- 承載豐富信息：錯誤碼通常包含了詳細的信息，例如錯誤的級別、所屬錯誤類別以及具體的錯誤描述。這些錯誤信息可以幫助用戶和開發者快速定位問題；
- 靈活定義：錯誤碼由開發者根據需要靈活定義，不依賴和受限于第三方框架，例如 net/http 和 google.golang.org/grpc；
- 便于邏輯判斷：在業務開發中，判斷錯誤類別以執行對應的邏輯處理是一個常見需求。通過自定義錯誤碼，可以輕松實現。例如：
import "errors"
import "path/to/errno"
if errors.Is(err, errno.InternalServerError) {
// 對應錯誤處理邏輯
}1. 制定錯誤碼規范
錯誤碼是直接暴露給用戶的，因此需要設計一個易讀、易懂且規范化的錯誤碼。在設計錯誤碼時可以根據實際需求自行設計，也可以參考其他優秀的設計方案。
一般來說，當調研某項技術實現時，建議優先參考各大公有云廠商的實現方式，例如騰訊云、阿里云、華為云等。這些公有云廠商直接面向企業和個人，專注于技術本身，擁有強大的技術團隊，因此它們的設計與實現具有很高的參考價值。
經過調研，此處采用了騰訊云 API 3.0 的錯誤碼設計規范，并將規范文檔保存在項目的文檔目錄中：docs/devel/zh-CN/conversions/error_code.md[2]。
騰訊云采用了兩級錯誤碼設計。以下是兩級錯誤碼設計相較于簡單錯誤碼（如 215、InvalidParameter）的優勢：
- 語義化： 語義化的錯誤碼可以通過名字直接反映錯誤的類型，便于快速理解錯誤；
- 更加靈活： 二級錯誤碼的格式為<平臺級.資源級>。其中，平臺級錯誤碼是固定值，用于指代某一類錯誤，客戶端可以利用該錯誤碼進行通用錯誤處理。資源級錯誤碼則用于更精確的錯誤定位。此外，服務端既可根據需求自定義錯誤碼，也可使用默認錯誤碼。
miniblog 項目預定義了一些平臺級錯誤碼，如下表所示。
錯誤碼 | 錯誤描述 | 錯誤類型 |
OK | 請求成功 | - |
InternalError | 內部錯誤 | 1 |
NotFound | 資源不存在 | 0 |
BindError | 綁定失敗，解析請求體失敗 | 0 |
InvalidArgument | 參數錯誤（包括參數類型、格式、值等錯誤） | 0 |
Unauthenticated | 認證失敗 | 0 |
PermissionDenied | 授權失敗 | 0 |
OperationFailed | 操作失敗 | 2 |
上表中，錯誤類型 0 代表客戶端錯誤，1 代表服務端錯誤，2 代表客戶端錯誤/服務端錯誤，- 代表請求成功。
2. miniblog 錯誤包設計
開發一個錯誤包，需要先為錯誤包起一個易讀、易理解的包名。在 Go 項目開發中，如果自定義包的名稱如 errors、context 等，會與 Go 標準庫中已存在的 errors 或 context 包發生命名沖突，如果代碼中需要同時使用自定義包與標準庫包時，通常會通過為標準庫包起別名的方式解決。例如，可以通過 import stderrors "errors" 來為標準庫的 errors 包定義別名。
為了避免頻繁使用這種起別名的操作，在開發自定義包時，可以從包命名上避免與標準庫包名沖突。建議將可能沖突的包命名為 <沖突包原始名>x，其名稱中的“x”代表擴展（extended）或實驗（experimental）。這種命名方式是一種擴展命名約定，通常用于表示此包是對標準庫中已有包功能的擴展或補充。需要注意的是，這并非 Go 語言的官方規范，而是開發者為了防止命名沖突、增強語義所采用的命名方式。miniblog 項目的自定義 contextx 包也采用了這種命名風格。
因此，為了避免與標準庫的 errors 包命名沖突，miniblog 項目的錯誤包命名為 errorsx，寓意為“擴展的錯誤處理包”。
由于 miniblog 項目的錯誤包命名為 errorsx，為保持命名一致性，定義了一個名為 ErrorX 的結構體，用于描述錯誤信息，具體定義如下：
// ErrorX 定義了 OneX 項目體系中使用的錯誤類型，用于描述錯誤的詳細信息.
type ErrorX struct {
// Code 表示錯誤的 HTTP 狀態碼，用于與客戶端進行交互時標識錯誤的類型.
Code int`json:"code,omitempty"`
// Reason 表示錯誤發生的原因，通常為業務錯誤碼，用于精準定位問題.
Reason string`json:"reason,omitempty"`
// Message 表示簡短的錯誤信息，通常可直接暴露給用戶查看.
Message string`json:"message,omitempty"`
// Metadata 用于存儲與該錯誤相關的額外元信息，可以包含上下文或調試信息.
Metadata map[string]string`json:"metadata,omitempty"`
}ErrorX 是一個錯誤類型，因此需要實現 Error 方法：
// Error 實現 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)
}Error() 返回的錯誤信息中，包含了 HTTP 狀態碼、錯誤發生的原因、錯誤信息和額外的錯誤元信息。通過這些詳盡的錯誤信息返回，幫助開發者快速定位錯誤。
提示
miniblog 項目屬于 OneX 技術體系中的一個實戰項目，其設計和實現方式跟 OneX 技術體系中的其他項目保持一致。考慮到包的復用性，errorsx 包的實現位于 onexstack[3] 項目根目錄下的 pkg/errorsx 目錄中。
在 Go 項目開發中，發生錯誤的原因有很多，大多數情況下，開發者希望將真實的錯誤信息返回給用戶。因此，還需要提供一個方法用來設置 ErrorX 結構體中的 Message 字段。同樣的，還需要提供設置 Metadata 字段的方法。為了滿足上述訴求，給 ErrorX 增加 WithMessage、WithMetadata、KV 三個方法。實現方式如下述代碼所示。
// WithMessage 設置錯誤的 Message 字段.
func (err *ErrorX) WithMessage(format string, args ...any) *ErrorX {
err.Message = fmt.Sprintf(format, args...)
return err
}
// WithMetadata 設置元數據.
func (err *ErrorX) WithMetadata(md map[string]string) *ErrorX {
err.Metadata = md
return err
}
// KV 使用 key-value 對設置元數據.
func (err *ErrorX) KV(kvs ...string) *ErrorX {
if err.Metadata == nil {
err.Metadata = make(map[string]string) // 初始化元數據映射
}
for i := 0; i < len(kvs); i += 2 {
// kvs 必須是成對的
if i+1 < len(kvs) {
err.Metadata[kvs[i]] = kvs[i+1]
}
}
return err
}在上述代碼中，設置 Message、Metadata 字段的方法名分別為 WithMessage、WithMetadata。WithXXX，在 Go 項目開發中是一種很常見的命名方式，寓意是：設置 XXX。KV 方法則以追加的方式給 Metadata 增加鍵值對。WithMessage、WithMetadata、KV 都返回了 *ErrorX 類型的實例，目的是為了實現鏈式調用，例如：
err := new(ErrorX)
err.WithMessage("Message").WithMetadata(map[string]string{"key":"value"})在 Go 項目開發中，鏈式調用（chained method calls）是一種常見的設計模式，該模式通過在方法中返回對象自身，使多個方法調用可以連續進行。鏈式調用的好處在于：簡化代碼、提高可讀性、減少錯誤可能性和增強擴展性，尤其是在對象構造或逐步修改操作時，非常高效直觀。合理使用鏈式調用可以顯著提升代碼的質量和開發效率，同時讓接口設計更加優雅。
errorsx 包的設計目標不僅適用于 HTTP 接口的錯誤返回，還適用于 gRPC 接口的錯誤返回。因此，ErrorX 結構體還實現了 GRPCStatus() 方法。GRPCStatus() 方法的作用是將自定義錯誤類型 ErrorX 轉換為 gRPC 的 status.Status 類型，用于生成 gRPC 標準化的錯誤返回信息（包括錯誤碼、錯誤消息及詳細錯誤信息），從而滿足 gRPC 框架的錯誤處理要求。GRPCStatus() 方法實現如下：
// GRPCStatus 返回 gRPC 狀態表示.
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
}在 Go 項目開發中，通常需要將一個 error 類型的錯誤 err，解析為 *ErrorX 類型，并獲取 *ErrorX 中的 Code 字段和 Reason 字段的值。Code 字段可用來設置 HTTP 狀態碼，Reason 字段可用來判斷錯誤類型。為此，errorsx 包實現了 FromError、Code、Reason 方法，具體實現如下：
// 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 狀態中的錯誤代碼和消息創建一個 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
}在 Go 項目開發中，經常還要對比一個 error 類型的錯誤 err 是否是某個預定義錯誤，因此 *ErrorX 也需要實現一個 Is 方法，Is 方法實現如下：
// 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
}Is 方法中，通過對比 Code 和 Reason 字段，來判斷 target 錯誤是否是指定的預定義錯誤。注意，Is 方法中，沒有對比 Message 字段的值，這是因為 Message 字段的值通常是動態的，而錯誤類型的定義不依賴于 Message。
至此，成功為 miniblog 開發了一個滿足項目需求的錯誤包 errorsx，代碼完整實現見 onexstack 項目的 pkg/errorsx/errorsx.go[4] 文件。
3. miniblog 錯誤碼定義
在實現了 errorsx 錯誤包之后，便可以根據需要預定義項目需要的錯誤。這些錯誤，可以在代碼中便捷的引用。通過直接引用預定義錯誤，不僅可以提高開發效率，還可以保持整個項目的錯誤返回是一致的。
miniblog 的預定義錯誤定義在 internal/pkg/errno[5] 目錄下。一些基礎錯誤定義如下：
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."}
...
)更完整的預定義錯誤，可直接查看 internal/pkg/errno 中的錯誤定義文件。預定義錯誤保存在 internal/pkg 目錄中，是因為這些錯誤跟 miniblog 項目耦合，不是通用的錯誤定義。
至此，miniblog 成功實現了錯誤返回代碼的實現，完整代碼見分支 feature/s08[6]。
4. miniblog 錯誤返回規范
為了標準化接口錯誤返回，提高接口錯誤返回的易讀性，miniblog 制定了以下錯誤返回規范：
- 所有接口都要返回 errorsx.ErrorX 類型的錯誤；
- 建議在錯誤的原始位置，使用 errno.ErrXXX 方式返回 miniblog 自定義錯誤類型，其他位置直接透傳自定義錯誤：
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
}三、minilbog 錯誤包測試
本節就來測試下 errorsx 錯誤包及 errno 錯誤碼。測試代碼保存在 examples/errorsx/main.go[7] 文件中，代碼如下：
package main
import (
"fmt"
"github.com/onexstack/onexstack/pkg/errorsx"
"github.com/onexstack/miniblog/internal/pkg/errno"
)
func main() {
// 創建了一個 ErrorX 錯誤，表示數據庫連接失敗。
// 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)
// 給錯誤添加元數據，增強錯誤的上下文信息，便于調試和追蹤。
errx.WithMetadata(map[string]string{
"user_id": "12345", // 添加用戶 ID 信息
"request_id": "abc-def", // 添加請求 ID 信息
})
// 繼續向錯誤中添加元數據，這次使用了 KV 方法，它是一種更加簡潔的方式，用 key-value 的模式逐一設置元數據。
// 這里添加 trace_id 信息，用于關聯分布式鏈路信息。
errx.KV("trace_id", "xyz-789")
// 使用 WithMessage 方法更新錯誤的 Message 字段。
// 更新后的 Message 是：Updated message: retry failed。
// Note: 更新消息字段并不會影響 Code、Reason 和 Metadata，它只是說明錯誤的上下文發生了變化。
errx.WithMessage("Updated message: %s", "retry failed")
// 再次打印 errx，此時的內容已經發生了變化：
// error: code = 500 reason = InternalError.DBConnection message = Updated message: retry failed metadata = map[request_id:abc-def trace_id:xyz-789 user_id:12345]
// 元數據也會被一并輸出。
fmt.Println(errx)
// 調用 doSomething 函數，生成一個錯誤，并打印它，這里返回一個更新過 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))
}
// 定義一個函數 doSomething，返回一個錯誤
func doSomething() error {
// 這里返回了一個已經定義的錯誤類型 errno.ErrUsernameInvalid，但動態地設置了 Message 字段為 "Username is too short"。
// 重點是：雖然錯誤的 Message 不同，但錯誤的 Code 和 Reason 是一致的，這方便使用 Is 方法進行類型判斷而不受具體內容影響。
return errno.ErrUsernameInvalid.WithMessage("Username is too short")
}上述代碼已有詳盡的代碼注釋，這里不再詳細介紹。
四、總結
本節課探討了錯誤返回的優秀實踐，比較了兩種常見的錯誤返回方式，并選擇了更符合企業級開發需求的第二種方式。
通過定義 ErrorX 結構體，miniblog 項目實現了包含 HTTP/gRPC 狀態碼、業務錯誤碼、錯誤信息及元數據的錯誤返回機制。此外，還為 ErrorX 提供了便捷的字段設置方法，方便開發者快速構造和返回錯誤。
