この新しいフレームワークでエラーの増加を防ぐ

Go でのエラー処理はシンプルで柔軟ですが、構造化されていません。 を返して 単純なはずですよね? error 、メッセージでラップして、先に進むだけです。しかし、コードベースがパッケージや開発者、そして永久に残る「クイック フィックス」が増えるにつれて、その単純さはすぐに混乱に変わります。時間が経つにつれて、ログは「これを実行できませんでした」や「予期しないあれ」でいっぱいになり、それがユーザーのせいなのか、サーバーのせいなのか、バグのあるコードなのか、それとも単に星の配置がずれているだけなのか、誰にもわかりません。 エラーは一貫性のないメッセージで作成されます。各パッケージには、独自のスタイル、定数、またはカスタム エラー タイプのセットがあります。エラー コードは任意に追加されます。実装を詳しく調べなければ、どの関数からどのエラーが返されるかを簡単に知る方法はありません。 そこで、私は新しいエラー フレームワークを作成するという課題に取り組みました。エラーを意味のあるものにし、追跡可能にし、そして最も重要なことに、安心感を与えるために、名前空間コードを使用した構造化された集中型システムを採用することにしました。 これは、私たちがどのようにして単純なエラー処理アプローチから始め、問題が大きくなるにつれて完全にイライラし、最終的に独自のエラー フレームワークを構築したかというストーリーです。設計上の決定、実装方法、学んだ教訓、そしてそれがエラー管理へのアプローチを変えた理由についてです。皆さんにも何かアイデアが浮かぶことを願っています。 Goエラーは単なる値です Go には、エラーを処理する簡単な方法があります。エラーは単なる値です。エラーは、単一のメソッド で インターフェイスを実装する単なる値です。例外をスローして現在の実行フローを中断する代わりに、Go 関数は他の結果とともに 値を返します。呼び出し元は、その処理方法 (値をチェックして決定を下す、新しいメッセージとコンテキストでラップする、または単にエラーを返して親の呼び出し元に処理ロジックを残す) を決定できます。 Error() string error error メソッドを追加することで、任意の型を にすることができます。この柔軟性により、各パッケージは独自のエラー処理戦略を定義し、最適なものを選択できます。これは Go の構成可能性の哲学ともうまく統合されており、必要に応じてエラーを簡単にラップ、拡張、またはカスタマイズできます。 Error() string error すべてのパッケージはエラーに対処する必要がある 一般的な方法は、 インターフェイスを実装するエラー値を返し、呼び出し元が次に何を行うかを決定できるようにすることです。次に典型的な例を示します。 error func loadCredentials() (Credentials, error) { data, err := os.ReadFile("cred.json") if errors.Is(err, os.ErrNotExist) { return nil, fmt.Errorf("file not found: %w", err) } if err != nil { return nil, fmt.Errorf("failed to read file: %w", err) } cred, err := verifyCredentials(cred); if err != nil { return nil, fmt.Errorf("invalid credentials: %w", err) } return cred, nil } Go には、エラーを処理するためのユーティリティがいくつか用意されています。 単純なエラーを生成するための と 。 エラーの作成: errors.New() fmt.Errorf() と 動詞を使用して、エラーを追加のコンテキストでラップします。 エラーのラップ: fmt.Errorf() %w 複数のエラーを 1 つに結合します。 エラーの結合: errors.Join() 特定の値を持つエラーを照合し、 特定の型を持つエラーを照合し、 基になるエラーを取得します。 エラーの確認と処理: errors.Is() errors.As() errors.Unwrap() 実際には、次のようなパターンがよく見られます。 または を使用して単純なエラーを返します。 標準パッケージの使用: errors.New() fmt.Errorf() たとえば、 と 再利用可能なエラー変数を定義します。 定数または変数のエクスポート: go-redis gorm.io は などのライブラリは、多くの場合、追加のコンテキスト用の関連コードを含む特殊なエラー タイプを作成します。 カスタム エラー タイプ: lib/pq grpc/status.Error インターフェース ベースのアプローチを使用して、さまざまな実装でエラー タイプを定義します。 実装によるエラー インターフェース: aws-sdk-go は、 エラーを分類および管理するための複数のインターフェースを定義する など。 または複数のインターフェース: Docker の errdefs 私たちは共通のアプローチから始めました 初期の頃は、多くの Go 開発者と同様に、私たちも Go の一般的なプラクティスに従い、エラー処理を最小限に抑えながらも機能的にしていました。数年間は問題なく動作していました。 当時人気のパッケージであった 使用してスタックトレースを組み込みます。 pkg/errors を パッケージ固有のエラーの定数または変数をエクスポートします。 特定のエラーを確認するには、 を使用します。 errors.Is() エラーを新しいメッセージとコンテキストでラップします。 API エラーの場合、Protobuf 列挙型を使用してエラー タイプとコードを定義します。 pkg/errors にスタックトレースを含める 当時人気のあったエラー処理パッケージである を使用して、エラーにスタックトレースを含めました。これは、アプリケーションのさまざまな部分にわたるエラーの原因をトレースできるため、デバッグに特に役立ちました。 pkg/errors スタックトレースを使用してエラーを作成、ラップ、および伝播するために、 、 、 などの関数を実装しました。以下は、初期の実装の例です。 Newf() NewValuef() Wrapf() type xError struct { msg message, stack: callers(), } func Newf(msg string, args ...any) error { return &xError{ msg: fmt.Sprintf(msg, args...), stack: callers(), // 👈 stacktrace } } func NewValuef(msg string, args ...any) error { return fmt.Errorf(msg, args...) // 👈 no stacktrace } func Wrapf(err error, msg string, args ...any) error { if err == nil { return nil } stack := getStack(err) if stack == nil { stack = callers() } return &xError{ msg: fmt.Sprintf(msg, args...), stack: stack, } } エラー変数のエクスポート コードベース内の各パッケージは独自のエラー変数を定義しており、多くの場合、一貫性のないスタイルになっています。 package database var ErrNotFound = errors.NewValue("record not found") var ErrMultipleFound = errors.NewValue("multiple records found") var ErrTimeout = errors.NewValue("request timeout") package profile var ErrUserNotFound = errors.NewValue("user not found") var ErrBusinessNotFound = errors.NewValue("business not found") var ErrContextCancel = errors.NewValue("context canceled") 、追加のコンテキストでラップする errors.Is() でエラーをチェックし res, err := repo.QueryUser(ctx, req) switch { case err == nil: // continue case errors.Is(database.NotFound): return nil, errors.Wrapf(ErrUserNotFound, "user not found (id=%v)", req.UserID) default: return nil, errors.Wrapf(ctx, "failed to query user (id=%v)", req.UserID) } これにより、エラーがより詳細に伝わるようになりましたが、ログの冗長性、重複、不明瞭さが生じることがよくありました。 internal server error: failed to query user: user not found (id=52a0a433-3922-48bd-a7ac-35dd8972dfe5): record not found: not found Protobuf で外部エラーを定義する 外部向け API については、 にヒントを得た Protobuf ベースのエラー モデルを採用しました。 Meta の Graph API message Error { string message = 1; ErrorType type = 2; ErrorCode code = 3; string user_title = 4; string user_message = 5; string trace_id = 6; map details = 7; } enum ErrorType { ERROR_TYPE_UNSPECIFIED = 1; ERROR_TYPE_AUTHENTICATION = 2; ERROR_TYPE_INVALID_REQUEST = 3; ERROR_TYPE_RATE_LIMIT = 4; ERROR_TYPE_BUSINESS_LIMIT = 5; ERROR_TYPE_WEBHOOK_DELIVERY = 6; } enum ErrorCode { ERROR_CODE_UNSPECIFIED = 1 [(error_type = UNSPECIFIED)]; ERROR_CODE_UNAUTHENTICATED = 2 [(error_type = AUTHENTICATION)]; ERROR_CODE_CAMPAIGN_NOT_FOUND = 3 [(error_type = NOT_FOUND)]; ERROR_CODE_META_CHOSE_NOT_TO_DELIVER = 4 /* ... */; ERROR_CODE_MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS = 5; } このアプローチはエラーの構造化に役立ちましたが、時間が経つにつれて、明確な計画なしにエラーの種類とコードが追加され、不整合や重複が生じました。 そして問題は時間とともに拡大した いたるところでエラーが宣言された 各パッケージは、集中化されたシステムなしで独自のエラー定数を定義しました。 定数とメッセージがコードベース全体に散在していたため、関数がどのエラーを返すかが不明瞭でした。ああ、 なのか、 なのか、それとも両方なのか? gorm.ErrRecordNotFound user.ErrNotFound ランダムなエラーラッピングにより、一貫性のない任意のログが生成される 多くの関数は、独自のエラー タイプを宣言せずに、任意の一貫性のないメッセージでエラーをラップしていました。 ログは冗長かつ冗長で、検索や監視が困難でした。 エラー メッセージは一般的なもので、何が問題なのか、どのように発生したのかが説明されていないことがよくありました。また、脆弱で、気付かれないまま変更される傾向がありました。 unexpected gorm error: failed to find business channel: error received when invoking API: unexpected: context canceled 標準化されていないため、エラー処理が不適切になる 各パッケージはエラーを異なる方法で処理するため、関数がエラーを返したか、ラップしたか、または変換したかを知ることが困難になります。 エラーが広がるにつれて、コンテキストが失われることがよくありました。 上位層は、根本的な原因が明確でない漠然とした を受け取りました。 500 内部サーバー エラー 分類がないため監視は不可能 エラーは重大度や動作によって分類されていません エラーは、ユーザーがブラウザ タブを閉じるときの通常の動作である可能性がありますが、そのクエリがランダムに遅いためにリクエストがキャンセルされた場合は重要です。 context.Canceled 重要な問題はノイズの多いログに埋もれてしまい、特定するのが困難でした。 分類しないと、エラーの頻度、重大度、影響を効果的に監視することは不可能でした。 エラー処理を一元化する時期が来た 計画に戻る 増大する課題に対処するために、 という中核的なアイデアに基づいて、より優れたエラー戦略を構築することにしました。 集中化され構造化されたエラー コード エラーはあらゆる場所で宣言されています → 整理と追跡可能性を向上させるために、エラー宣言を 1 か所に集中させます。 一貫性がなく恣意的なログ → 明確で一貫性のあるフォーマットで構造化されたエラー コード。 不適切なエラー処理 → 包括的なヘルパー セットを使用して タイプでのエラーの作成とチェックを標準化します。 、新しい Error 分類なし → ログとメトリックを通じて効果的に監視するために、エラー コードをタグで分類します。 設計上の決定 すべてのエラー コードは、名前空間構造を持つ集中的な場所で定義されます。 名前空間を使用して、明確で意味のある拡張可能なエラー コードを作成します。例: 「ユーザーが見つかりません。」の場合は 。 PRFL.USR.NOT_FOUND 「フロー ドキュメントが見つかりません。」の場合は 。 FLD.NOT_FOUND どちらも、基礎となるベースコード 「PostgreSQL でレコードが見つかりません」を意味する) を共有できます。 DEPS.PG.NOT_FOUND 。 サービスまたはライブラリの各レイヤーは、独自の名前空間コードのみを返す必要があります サービス、リポジトリ、またはライブラリの各レイヤーは、独自のエラー コード セットを宣言します。 レイヤーが依存関係からエラーを受け取った場合、それを返す前に独自の名前空間コードでラップする必要があります。 たとえば、依存関係からエラー 受け取った場合、「database」パッケージはそれを としてラップする必要があります。その後、「profile/user」サービスはそれを として再度ラップする必要があります。 gorm.ErrRecordNotFound DEPS.PG.NOT_FOUND PRFL.USR.NOT_FOUND を実装する必要があります。 すべてのエラーは Error インターフェース これにより、サードパーティ ライブラリからのエラー ( ) と内部 の間に明確な境界が作成されます。 error Error これは、移行済みのパッケージとまだ移行されていないパッケージを区別することで、移行の進行にも役立ちます。 エラーは 1 つまたは複数のエラーをラップできます。それらが一緒になってツリーを形成します。 [FLD.INVALID_ARGUMENT] invalid argument → [TPL.INVALID_PARAMS] invalid input params 1. [TPL.PARAM.EMPTY] name can not be empty 2. [TPL.PARAM.MALFORM] invalid format for param[2] が必要です 常に context.Context 。エラーにコンテキストを添付できます。 コンテキストや がなく、どこから来たのかわからないスタンドアロン エラーのログを何度も目にしました。 trace_id エラーに追加のキー/値を添付して、ログや監視に使用できます。 エラーがサービス境界を越えて送信される場合、最上位レベルのエラー コードのみが公開されます。 呼び出し元は、そのサービスの内部実装の詳細を確認する必要はありません。 外部エラーの場合は、現在の Protobuf ErrorCode と ErrorType を引き続き使用します。 これにより下位互換性が確保されるため、クライアントはコードを書き直す必要がありません。 名前空間エラー コードを Protobuf コード、HTTP ステータス コード、タグに自動マップします。 エンジニアは一元的な場所でマッピングを定義し、フレームワークは各エラー コードを対応する Protobuf 、 、gRPC ステータス、HTTP ステータス、およびログ/メトリックのタグにマッピングします。 ErrorCode ErrorType これにより一貫性が確保され、重複が削減されます。 名前空間エラーフレームワーク コアパッケージとタイプ 新しいエラー処理フレームワークの基盤を形成するコア パッケージがいくつかあります。 connectly.ai/go/pkgs/ : 種類とコードを定義するメイン パッケージ。 errors Error : フロントエンドまたは外部 API にエラーを送信します。 errors/api : ドットインポートで使用することを目的としたヘルパーパッケージ。 errors/E : 名前空間エラーを処理するためのテスト ユーティリティ。 testing Error と Code インターフェースは標準 インターフェースの拡張であり、 返すメソッドが追加されています。 は として実装されています。 Error error Code Code uint16 package errors // import "connectly.ai/go/pkgs/errors" type Error interface { error Code() Code } type Code struct { code uint16 } type CodeI interface { CodeDesc() CodeDesc } type GroupI interface { /* ... */ } type CodeDesc struct { /* ... */ } すべてのエラーコードと一般的なタイプをエクスポートします パッケージ errors/E package E // import "connectly.ai/go/pkgs/errors/E" import "connectly.ai/go/pkgs/errors" type Error = errors.Error var ( DEPS = errors.DEPS PRFL = errors.PRFL ) func MapError(ctx context.Context, err error) errors.Mapper { /* ... */ } func IsErrorCode(err error, codes ...errors.CodeI) { /* ... */ } func IsErrorGroup(err error, groups ...errors.GroupI) { /* ... */ } 使用例 エラーコードの例: // dependencies → postgres DEPS.PG.NOT_FOUND DEPS.PG.UNEXPECTED // sdk → hash SDK.HASH.UNEXPECTED // profile → user PRFL.USR.NOT_FOUND PFRL.USR.UNKNOWN // profile → user → repository PRFL.USR.REPO.NOT_FOUND PRFL.USR.REPO.UNKNOWN // profile → auth PRFL.AUTH.UNAUTHENTICATED PRFL.AUTH.UNKNOWN PRFL.AUTH.UNEXPECTED パッケージ : database package database // import "connectly.ai/go/pkgs/database" import "gorm.io/gorm" import . "connectly.ai/go/pkgs/errors/E" type DB struct { gorm: gorm.DB } func (d *DB) Exec(ctx context.Context, sql string, params ...any) *DB { tx := d.gorm.WithContext(ctx).Exec(sql, params...) return wrapTx(tx) } func (x *DB) Error(msgArgs ...any) Error { return wrapError(tx.Error()) // 👈 convert gorm error to 'Error' } func (x *DB) SingleRowError(msgArgs ...any) Error { if err := x.Error(); err != nil { return err } switch { case x.RowsAffected == 1: return nil case x.RowsAffected == 0: return DEPS.PG.NOT_FOUND.CallerSkip(1). New(x.Context(), formatMsgArgs(msgArgs)) default: return DEPS.PG.UNEXPECTED.CallerSkip(1). New(x.Context(), formatMsgArgs(msgArgs)) } } パッケージ : pb/services/profile package profile // import "connectly.ai/pb/services/profile" // these types are generated from services/profile.proto type QueryUserRequest struct { BusinessId string UserId string } type LoginRequest struct { Username string Password string } パッケージ : service/profile package profile import uuid "github.com/google/uuid" import . "connectly.ai/go/pkgs/errors/E" import l "connectly.ai/go/pkgs/logging/l" import profilepb "connectly.ai/pb/services/profile" // repository requests type QueryUserByUsernameRequest struct { Username string } // repository layer → query user func (r *UserRepository) QueryUserByUsernameAuth( ctx context.Context, req *QueryUserByUsernameRequest, ) (*User, Error) { if req.Username == "" { return PRFL.USR.REPO.INVALID_ARGUMENT.New(ctx, "empty request") } var user User sqlQuery := `SELECT * FROM "user" WHERE username = ? LIMIT 1` tx := r.db.Exec(ctx, sqlQuery, req.Username).Scan(&user) err := tx.SingleRowError() switch { case err == nil: return &user, nil case IsErrorCode(DEPS.PG.NOT_FOUND): return PRFL.USR.REPO.USER_NOT_FOUND. With(l.String("username", req.Username)) Wrap(ctx, "user not found") default: return PRFL.USR.REPO.UNKNOWN. Wrap(ctx, "failed to query user") } } // user service layer → query user func (u *UserService) QueryUser( ctx context.Context, req *profilepb.QueryUserRequest, ) (*profilepb.QueryUserResponse, Error) { // ... rr := QueryUserByUsernameRequest{ Username: req.Username } err := u.repo.QueryUserByUsername(ctx, rr) if err != nil { return nil, MapError(ctx, err). Map(PRFL.USR.REPO.NOT_FOUND, PRFL.USR.NOT_FOUND, "the user %q cannot be found", req.UserName, api.UserTitle("User Not Found"), api.UserMsg("The requested user id %q can not be found", req.UserId)). KeepGroup(PRFL.USR). Default(PRFL.USR.UNKNOWN, "failed to query user") } // ... return resp, nil } // auth service layer → login user func (a *AuthService) Login( ctx context.Context, req *profilepb.LoginRequest, ) (*profilepb.LoginResponse, *profilepb.LoginResponse, Error) { vl := PRFL.AUTH.INVALID_ARGUMENT.WithMsg("invalid request") vl.Vl(req.Username != "", "no username", api.Detail("username is required")) vl.Vl(req.Password != "", "no password", api.Detail("password is required")) if err := vl.ToError(ctx); err != nil { return err } hashpwd, err := hash.Hash(req.Password) if err != nil { return PRFL.AUTH.UNEXPECTED.Wrap(ctx, err, "failed to calc hash") } usrReq := profilepb.QueryUserByUsernameRequest{/*...*/} usrRes, err := a.userServiceClient.QueryUserByUsername(ctx, usrReq) if err != nil { return nil, MapError(ctx, err). Map(PRFL.USR.NOT_FOUND, PRFL.AUTH.UNAUTHENTICATED, "unauthenticated"). Default(PRFL.AUTH.UNKNOWN, "failed to query by username") } // ... } さて、上記のコードには多くの新しい機能と概念があります。それらを順を追って見ていきましょう。 エラーの作成とラップ をインポートします。 まず、ドットインポートを使用してパッケージ errors/E これにより、 の代わりに などの一般的なタイプを直接使用し、 の代わりに でコードにアクセスできるようになります。 errors.Error Error errors.PRFL.USR.NOT_FOUND PRFL.USR.NOT_FOUND import . "connectly.ai/go/pkgs/errors/E" CODE.New() 使用して新しいエラーを作成する 無効なリクエストを受け取った場合は、次の方法で新しいエラーを作成できます。 err := PRFL.USR.INVALID_ARGUMENT.New(ctx, "invalid request") は です。 PRFL.USR.INVALID_ARGUMENT Code 新しいエラーを作成するための や などのメソッドを公開します。 Code New() Wrap() 関数は、最初の引数として を受け取り、その後にメッセージとオプションの引数を受け取ります。 New() context.Context で印刷します: fmt.Print(err) [PRFL.USR.INVALID_ARGUMENT] invalid request または、 を使用して詳細を表示します。 fmt.Printf("%+v") [PRFL.USR.INVALID_ARGUMENT] invalid request connectly.ai/go/services/profile.(*UserService).QueryUser /usr/i/src/go/services/profile/user.go:1234 connectly.ai/go/services/profile.(*UserRepository).QueryUser /usr/i/src/go/services/profile/repo/user.go:2341 CODE.Wrap() を使用してエラーを新しいエラー内にラップします。 dbErr := DEPS.PG.NOT_FOUND.Wrap(ctx, gorm.ErrRecordNotFound, "not found") usrErr := PRFL.USR.NOT_FOUND.Wrap(ctx, dbErr, "user not found") を使用すると、次の出力が生成されます。 fmt.Print(usrErr) [PRFL.USR.NOT_FOUND] user not found → [DEPS.PG.NOT_FOUND] not found → record not found または を使用します fmt.Printf("%+v", usrErr) [PRFL.USR.NOT_FOUND] user not found → [DEPS.PG.NOT_FOUND] not found → record not found connectly.ai/go/services/profile.(*UserService).QueryUser /usr/i/src/go/services/profile/user.go:1234 スタックトレースは最も内側の から取得されます。ヘルパー関数を記述している場合は、 を使用してフレームをスキップできます。 Error CallerSkip(skip) func mapUserError(ctx context.Context, err error) Error { switch { case IsErrorCode(err, DEPS.PG.NOT_FOUND): return PRFL.USR.NOT_FOUND.CallerSkip(1).Wrap(ctx, err, "...") default: return PRFL.USR.UNKNOWN.CallerSkip(1).Wrap(ctx, err, "...") } } エラーにコンテキストを追加する With() 使用してエラーにコンテキストを追加する を使用して、エラーに追加のキー/値のペアを追加できます。 .With(l.String(...)) 、ログ記録用のシュガー関数をエクスポートするためのヘルパー パッケージです。 logging/l を返し、 を返します。 l.String("flag", flag) Tag{String: flag} l.UUID("user_id, userID) Tag{Stringer: userID} import l "connectly.ai/go/pkgs/logging/l" usrErr := PRFL.USR.NOT_FOUND. With(l.UUID("user_id", req.UserID), l.String("flag", flag)). Wrap(ctx, dbErr, "user not found") タグは で出力できます: fmt.Printf("%+v", usrErr) [PRFL.USR.NOT_FOUND] user not found {"user_id": "81febc07-5c06-4e01-8f9d-995bdc2e0a9a", "flag": "ABRW"} → [DEPS.PG.NOT_FOUND] not found {"a number": 42} → record not found 、 、または 。 New() Wrap() MapError() 内でエラーにコンテキストを直接追加します 関数とそのファミリーを活用することで、 や同様の関数は書式設定引数の中からタグをスマートに検出できます。別の関数を導入する必要はありません。 l.String() New() err := INF.HEALTH.NOT_READY.New(ctx, "service %q is not ready (retried %v times)", req.ServiceName, l.String("flag", flag) countRetries, l.Number("count", countRetries), ) 出力は次のようになります: [INF.HEALTH.NOT_READY] service "magic" is not ready (retried 2 times) {"flag": "ABRW", "count": 2} さまざまなタイプ: 、 、 Error0 VlError ApiError 現在、 インターフェースを実装するタイプは 3 つあります。必要に応じて、タイプをさらに追加できます。それぞれに異なる構造を持たせることができ、特定のニーズに合わせてカスタム メソッドを追加できます。 Error Goの標準 Error error インターフェース の拡張です type Error interface { error Code() Message() Fields() []tags.Field StackTrace() stacktrace.StackTrace _base() *base // a private method } これには、 パッケージの外部で新しい タイプを誤って実装しないようにするためのプライベート メソッドが含まれています。今後、より多くの使用パターンを経験したときに、この制限を解除する可能性があります (または解除しない可能性があります)。 errors Error 標準 error インターフェイスを使用して型アサーションを使用するのはなぜでしょうか? サードパーティのエラーと内部エラーを区別したいからです。内部コード内のすべてのレイヤーとパッケージは、常に 返す必要があります。こうすることで、サードパーティのエラーを変換する必要があるときと、内部エラーコードのみを処理する必要がある場合を安全に把握できます。 Error また、移行済みのパッケージとまだ移行されていないパッケージの間に境界が作成されます。 いいえ、そのような未来はまだ来ていません。いつか来るかもしれませんが、今のところは、パッケージを 1 つずつ移行する必要があります。 現実に戻ると、新しいタイプを宣言し、魔法の杖を振って プロンプトをささやくだけで、何百万行ものコードがすべて魔法のように変換され、バグなしでシームレスに動作するということはできません。 呪文 デフォルトの タイプです Error0 Error ほとんどのエラー コードは 値 これには とオプションのサブエラーが含まれます。NewX 使用して、 インターフェイスの代わりに具体的な 構造体を返すことができますが、 必要です。 Error0 を生成します 。 base NewX() Error *Error0 注意が type Error0 struct { base err error } var errA: Error = DEPS.PG.NOT_FOUND.New (ctx, "not found") var errB: *Error0 = DEPS.PG.NOT_FOUND.NewX(ctx, "not found") 、 、 、 、 などの共通機能を提供するために、すべての 実装で共有される共通構造体です。 base Code() Message() StackTrace() Fields() Error type base struct { code Code msg string kv []tags.Field stack stacktrace.StackTrace } VlError は検証エラー用です 複数のサブエラーを含めることができ、検証ヘルパーを操作するための便利なメソッドを提供します。 type VlError struct { base errs []error } 他の と同様の 作成できます。 Error VlError err := PRFL.USR.INVALID_ARGUMENT.New(ctx, "invalid request") または、 を作成し、それにエラーを追加して、それを に変換します。 VlBuilder VlError userID, err0 := parseUUID(req.UserId) err1 := validatePassword(req.Password) vl := PRFL.USR.INVALID_ARGUMENT.WithMsg("invalid request") vl.Add(err0, err1) vlErr := vl.ToError(ctx) そして、通常どおりキー/値のペアを含めます。 vl := PRFL.USR.INVALID_ARGUMENT. With(l.Bool("testingenv", true)). WithMsg("invalid request") userID, err0 := parseUUID(req.UserId) err1 := validatePassword(req.Password) vl.Add(err0, err1) vlErr := vl.ToError(ctx, l.String("user_id", req.UserId)) を使用すると、次のように出力されます。 fmt.Printf("%+v", vlErr) [PRFL.USR.INVALID_ARGUMENT] invalid request {"testingenv": true, "user_id": "A1234567890"} ApiError APIエラーを移行するためのアダプタです 以前は、フロントエンドと外部クライアントに API エラーを返すために別の 構造体を使用していました。これには ように として が含まれます。 api.Error 、前述の ErrorCode ErrorType package api import errorpb "connectly.ai/pb/models/error" // Deprecated type Error struct { pbType errorpb.ErrorType pbCode errorpb.ErrorCode cause error msg string usrMsg string usrTitle string // ... } この型は現在非推奨です。代わりに、すべてのマッピング ( 、 、 gRPC コード、 HTTP コード) を一元的に宣言し、対応する境界で変換します。コード宣言については で説明します。 ErrorType ErrorCode 次のセクション 新しい名前空間エラー フレームワークへの移行を行うために、 を追加しました。すべての コードになります。 一時的な名前空間 ZZZ.API_TODO ErrorCode ZZZ.API_TODO ZZZ.API_TODO.UNEXPECTED ZZZ.API_TODO.INVALID_REQUEST ZZZ.API_TODO.USERNAME_ ZZZ.API_TODO.META_CHOSE_NOT_TO_DELIVER ZZZ.API_TODO.MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS そして、 はアダプターとして作成されます。以前は を返していたすべての関数は、代わりに ( によって実装) を返すように変更されました。 ApiError *api.Error Error *ApiError package api import . "connectly.ai/go/pkgs/errors/E" // previous func FailPreconditionf(err error, msg string, args ...any) *Error { return &Error{ pbType: ERROR_TYPE_FAILED_PRECONDITION, pbCode: ERROR_CODE_MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS, cause: err, msg: fmt.Sprintf(msg, args...) } } // current: this is deprecated, and serves and an adapter func FailPreconditionf(err error, msg string, args ...any) *Error { ctx := context.TODO() return ZZZ.API_TODO.MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS. CallerSkip(1). // correct the stacktrace by 1 frame Wrap(ctx, err, msg, args...) } すべての移行が完了すると、以前の使用法は次のようになります。 wabaErr := verifyWabaTemplateStatus(tpl) apiErr := api.FailPreconditionf(wabaErr, "template cannot be edited"). WithErrorCode(ERROR_CODE_MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS). WithUserMsg("According to WhatsApp, the message template can be only edited once in 24 hours. Consider creating a new message template instead."). ErrorOrNil() 次のように変更します。 CPG.TPL.EDIT_ONCE_IN_24_HOURS.Wrap( wabaErr, "template cannot be edited", api.UserMsg("According to WhatsApp, the message template can be only edited once in 24 hours. Consider creating a new message template instead.")) 内部名前空間コードから暗黙的に派生していることに注意してください。毎回明示的に割り当てる必要はありません。しかし、コード間の関係をどのように宣言するのでしょうか? 次のセクションで説明します。 ErrorCode 新しいエラーコードの宣言 この時点で、既存のコードから新しいエラーを作成する方法がすでにわかっています。コードについて、また新しいコードを追加する方法について説明します。 値 コード Code uint16 として実装され 、対応する文字列表現を持ちます。 type Code struct { code: uint16 } fmt.Printf("%q", DEPS.PG.NOT_FOUND) // "DEPS.PG.NOT_FOUND" これらの文字列を格納するために、利用可能なすべての の配列があります。 CodeDesc const MaxCode = 321 // 👈 this value is generated var allCodes [MaxCode]CodeDesc type CodeDesc { c int // 42 code string // DEPS.PG.NOT_FOUND api APICodeDesc } type APICodeDesc { ErrorType errorpb.ErrorType ErrorCode errorpb.ErrorCode HttpCode int DefMessage string UserMessage string UserTitle string } コードの宣言方法は次のとおりです。 var DEPS deps // dependencies var PRFL prfl // profile var FLD fld // flow document type deps struct { PG pg // postgres RD rd // redis } // tag:postgres type pg struct { NOT_FOUND Code0 // record not found CONFLICT Code0 // record already exist MALFORM_SQL Code0 } // tag:profile type PRFL struct { REPO prfl_repo USR usr AUTH auth } // tag:profile type prfl_repo struct { NOT_FOUND Code0 // internal error code INVALID_ARGUMENT VlCode // internal error code } // tag:usr type usr struct { NOT_FOUND Code0 `api-code:"USER_NOT_FOUND"` INVALID_ARGUMENT VlCode `api-code:"INVALID_ARGUMENT"` DISABlED_ACCOUNT Code0 `api-code:"DISABLED_ACCOUNT"` } // tag:auth type auth struct { UNAUTHENTICATED Code0 `api-code:"UNAUTHENTICATED"` PERMISSION_DENIED Code0 `api-code:"PERMISSION_DENIED"` } 新しいコードを宣言した後、生成スクリプトを 必要があります。 実行する run gen-errors 生成されたコードは次のようになります。 // Code generated by error-codes. DO NOT EDIT. func init() { // ... PRFL.AUTH.UNAUTHENTICATED = Code0{Code{code: 143}} PRFL.AUTH.PERMISSION_DENIED = Code0{Code{code: 144}} // ... allCodes[143] = CodeDesc{ c: 143, code: "PRFL.AUTH.UNAUTHENTICATED", tags: []string{"auth", "profile"}, api: APICodeDesc{ ErrorType: ERROR_TYPE_UNAUTHENTICATED, ErrorCode: ERROR_CODE_UNAUTHENTICATED, HTTPCode: 401, DefMessage: "Unauthenticated error", UserMessage: "You are not authenticated.", UserTitle: "Unauthenticated error", })) } があります 各 Error タイプには対応する Code タイプ を作成し、 作成するのはなぜか、疑問に思ったことはありませんか? それは、異なるコード タイプを使用しているためです。 PRFL.USR.NOT_FOUND.New() *Error0 PRFL.USR.INVALID_ARGUMENTS.New() *VlError また、各 タイプは異なる タイプを返し、それぞれ独自の追加メソッドを持つことができます。 Code Error type Code0 struct { Code } type VlCode struct { Code } func (c Code0) New(/*...*/) Error { return &Error0{/*...*/} } func (c VlCode) New(/*...*/) Error { return &VlError{/*...*/} } // extra methods on VlCode to create VlBuilder func (c VlCode) WithMsg(msg string, args ...any) *VlBuilder {/*...*/} type VlBuilder struct { code VlCode msg string args []any } func (b *VlBuilder) ToError(/*...*/) Error { return &VlError{Code: code, /*...*/ } } 外部APIで利用可能なコードをマークするには api-code 使用します 名前空間エラー コードは内部で使用する必要があります。 外部 HTTP API で返せるコードを作成するには、 でマークする必要があります。値は対応する です。 api-code errorpb.ErrorCode エラー コードが でマークされていない場合は、内部コードであり、一般的な として表示されます。 api-code Internal Server Error は外部コードですが、 内部コードであることに注意してください。 PRFL.USR.NOT_FOUND PRFL.USR.REPO.NOT_FOUND enum オプションを使用して、protobuf 内の 。 ErrorCode 、 ErrorType 、および gRPC/HTTP コード 間のマッピングを宣言します // error/type.proto ERROR_TYPE_PERMISSION_DENIED = 707 [(error_type_detail_option) = { type: "PermissionDeniedError", grpc_code: PERMISSION_DENIED, http_code: 403, // Forbidden message: "permission denied", user_title: "Permission denied", user_message: "The caller does not have permission to execute the specified operation.", }]; // error/code.proto ERROR_CODE_DISABlED_ACCOUNT = 70020 [(error_code_detail_option) = { error_type: ERROR_TYPE_DISABlED_ACCOUNT, grpc_code: PERMISSION_DENIED, http_code: 403, // Forbidden message: "account is disabled", user_title: "Account is disabled", user_message: "Your account is disabled. Please contact support for more information.", }]; コードと コード UNEXPECTED UNKNOWN 各レイヤーには通常、 と 2 つの汎用コードがあります。これらは、目的が若干異なります。 UNEXPECTED UNKNOWN コードは、決して発生しないはずのエラーに使用されます。 UNEXPECTED 明示的に処理されないエラーには コードが使用されます。 UNKNOWN エラーを新しいコードにマッピングする 関数から返されたエラーを受け取った場合は、それを処理する必要があります。つまり、サードパーティのエラーを内部名前空間エラーに変換し、エラー コードを内部レイヤーから外部レイヤーにマップする必要があります。 サードパーティのエラーを内部名前空間エラーに変換する エラーの処理方法は、サードパーティ パッケージが返す内容とアプリケーションに必要なものによって異なります。たとえば、データベース エラーまたは外部 API エラーを処理する場合: switch { case errors.Is(err, sql.ErrNoRows): // map a database "no rows" error to an internal "not found" error return nil, PRFL.USR.NOT_FOUND.Wrap(ctx, err, "user not found") case errors.Is(err, context.DeadlineExceeded): // map a context deadline exceeded error to a timeout error return nil, PRFL.USR.TIMEOUT.Wrap(ctx, err, "query timeout") default: // wrap any other error as unknown return nil, PRFL.USR.UNKNOWN.Wrap(ctx, err, "unexpected error") } 内部名前空間エラーに対するヘルパーの使用 : エラーに指定されたコードが含まれているかどうかを確認します。 IsErrorCode(err, CODES...) : エラーが入力グループに属している場合は true を返します。 IsErrorGroup(err, GROUP) 一般的な使用パターン: user, err := queryUser(ctx, userReq) switch { case err == nil: // continue case IsErrorCode(PRL.USR.REPO.NOT_FOUND): // check for specific error code and convert to external code // and return as HTTP 400 Not Found return nil, PRFL.USR.NOT_FOUND.Wrap(ctx, err, "user not found") case IsGroup(PRL.USR): // errors belong to the PRFL.USR group are returned as is return nil, err default: return nil, PRL.USR.UNKNOWN.Wrap(ctx, err, "failed to query user") } マッピング コードを簡単に記述するための MapError() : エラー コードのマッピングは一般的なパターンであるため、コードの記述を高速化するための ヘルパーがあります。上記のコードは次のように書き直すことができます。 MapError() user, err := queryUser(ctx, userReq) if err != nil { return nil, MapError(ctx, err). Map(PRL.USR.REPO.NOT_FOUND, PRFL.USR.NOT_FOUND, "user not found"). KeepGroup(PRF.USR). Default(PRL.USR.UNKNOWN, "failed to query user") } 通常どおり引数をフォーマットし、キー/値のペアを追加できます。 return nil, MapError(ctx, err). Map(PRL.USR.REPO.NOT_FOUND, PRFL.USR.NOT_FOUND, "user %v not found", username, l.String("flag", flag)). KeepGroup(PRF.USR). Default(PRL.USR.UNKNOWN, "failed to query user", l.Any("retries", retryCount)) 名前空間 を使用したテスト Error テストは、あらゆる本格的なコード ベースにとって重要です。フレームワークは、テストでのエラー条件の記述とアサートをより簡単に、より表現豊かにするために、 などの特殊なヘルパーを提供します。 ΩxError() // 👉 return true if the error contains the message ΩxError(err).Contains("not found") // 👉 return true if the error does not contain the message ΩxError(err).NOT().Contains("not found") 他にも多くのメソッドがあり、それらを連鎖させることもできます。 ΩxError(err). MatchCode(DEPS.PG.NOT_FOUND). // match any code in top or wrapped errors TopErrorMatchCode(PRFL.TPL.NOT_FOUND) // only match code from the top error MatchAPICode(API_CODE.WABA_TEMPLATE_NOTE_FOUND). // match errorpb.ErrorCode MatchExact("exact message to match") ? Ω(err).To(testing.MatchCode()) の代わりにメソッドを使用するのはなぜですか メソッドの方が見つけやすいからです。testing.MatchValues のような関数が多数ある場合、どれが で機能し、どれが機能しないかを知るのは困難です。メソッドを使用すると、ドット を入力するだけで、IDE は をアサートするために特別に設計された利用可能なすべてのメソッドを一覧表示します。 testing.MatchValues() Error . Error 移住 フレームワークは物語の半分に過ぎません。コードを書くのは簡単な部分です。本当の課題は、数十人のエンジニアが毎日変更をプッシュし、顧客はすべてが完璧に動作することを期待し、システムの実行を停止できない、大規模で生きたコードベースにそれを組み込む必要があるときに始まります。 移行には責任が伴います。コードの細かい部分 注意深く分割し、一度に小さな変更を加え、その過程で大量のテストを中断します。その後、手動で 1 つずつ検査して修正し、メイン ブランチにマージし、本番環境にデプロイし、ログとアラートを監視します。これを何度も繰り返します... を 移行の過程で学んだいくつかのヒントを以下に示します。 まず、古いパターンを新しいフレームワークに置き換えます。このプロセスで発生したコンパイルの問題を修正します。 検索と置換から始めます。 たとえば、このパッケージ内のすべての に置き換えます。 error Error type ProfileController interface { LoginUser(req *LoginRequest) (*LoginResponse, error) QueryUser(req *QueryUserRequest) (*QueryUserResponse, error) } 新しいコードは次のようになります。 import . "connectly.ai/go/pkgs/errors" type ProfileController interface { LoginUser(req *LoginRequest) (*LoginResponse, Error) QueryUser(req *QueryUserRequest) (*QueryUserResponse, Error) } 最下位レベルのパッケージから始めて、徐々に上位レベルのパッケージに移行します。この方法では、上位レベルのパッケージに進む前に、下位レベルのパッケージが完全に移行されていることを確認できます。 一度に 1 つのパッケージを移行します。 コードベースの一部にテストが不足している場合は、追加します。変更に自信がない場合は、テストを追加します。テストは、変更によって既存の機能が損なわれないようにするのに役立ちます。 不足している単体テストを追加する: 関連する関数を DEPRECATED に変更してから、新しい タイプで新しい関数を追加することを検討してください。 パッケージが上位レベルのパッケージの呼び出しに依存している場合は、 Error メソッドを持つデータベース パッケージを移行していると仮定します。 Transaction() package database func (db *DB) Transaction(ctx context.Context, fn func(tx *gorm.DB) error) error { return db.gorm.Transaction(func(tx *gorm.DB) error { return fn(tx) }) } これはユーザー サービス パッケージで使用されます。 err = s.DB(ctx).Transaction(func(tx *database.DB) error { user, usrErr := s.repo.CreateUser(ctx, tx, user) if usrErr != nil { return usrErr } } 最初に パッケージを移行するため、 と他の多数のパッケージはそのままになります。s.repo.CreateUser 呼び出しは依然として古い タイプを返しますが、 メソッドは新しい タイプを返す必要があります。Transaction メソッドを に変更し、新しい メソッドを追加できます。 database user s.repo.CreateUser() error Transaction() Error Transaction() DEPRECATED TransactionV2() package database // DEPRECATED: use TransactionV2 instead func (db *DB) Transaction_DEPRECATED(ctx context.Context, fn func(tx *gorm.DB) error) error { return db.gorm.Transaction(func(tx *gorm.DB) error { return fn(tx) }) } func (db *DB) TransactionV2(ctx context.Context, fn func(tx *gorm.DB) error) Error { err := db.gorm.Transaction(func(tx *gorm.DB) error { return fn(tx) }) return adaptToErrorV2(err) } 。既存のエラー コードに当てはまらないエラーが発生した場合は、新しいコードを追加します。これにより、時間の経過とともに包括的なエラー コード セットを構築できるようになります。他のパッケージのコードは、常に参照として利用できます。 必要に応じて新しいエラー コードを追加します 結論 Go でのエラー処理は、最初は単純に感じられます。 を返して先に進むだけです。しかし、コードベースが大きくなるにつれて、そのシンプルさは、あいまいなログ、一貫性のない処理、そして終わりのないデバッグ セッションの絡み合った混乱に変わりました。 error 一歩下がってエラーの処理方法を再考することで、私たちは自分たちにとって不利ではなく有利に働くシステムを構築しました。集中化され構造化された名前空間コードによって明確さがもたらされ、エラーのマッピング、ラッピング、テストを行うツールによって作業が楽になりました。ログの海を泳ぎ回る代わりに、何が問題でどこを調べるべきかを教えてくれる意味のある追跡可能なエラーが手に入るようになりました。 このフレームワークは、コードをよりきれいにするだけではありません。時間を節約し、フラストレーションを軽減し、未知の状況に備えるのに役立ちます。これはまだ旅の始まりに過ぎません。私たちはまだ多くのパターンを発見しているところですが、その結果、エラー処理に何らかの安心感をもたらすシステムが生まれました。皆さんのプロジェクトにも、このフレームワークがヒントを与えてくれることを願っています! 😊 著者 私は Oliver Nguyen です。主に Go と JavaScript で作業するソフトウェア メーカーです。毎日、学習して自分自身が成長していくのを楽しんでいます。時々、新しいオープン ソース プロジェクトを立ち上げます。旅の途中で知識や考えを共有します。 この投稿は と でも公開されています 👋 blog.connectly.ai olivernguyen.io