Goサービス作業の進め方
同時実行性とマルチテナンシーが存在する環境でも、レイヤー化されたGoサービスを正しく保つための規約です。まず周辺のパッケージを読んでください。ここに書かれていることよりも、そのコードベースで一貫して適用されているローカルパターンが優先されます。
コードを書く前に
ツールチェーンを確認してください。go.modが使用可能な標準ライブラリと言語機能を決定し、同じワークスペース内のサービスでも異なるバージョンを使用していることがよくあります。ループ変数のキャプチャはGo 1.22未満では実際のバグですが、それ以降では問題になりません。errors.Join、slices、mapsはGo 1.21以降が必要です。最新バージョンを想定するのではなく、バージョンを確認してください。
次に、変更しようとしている判断を所有するレイヤーを見つけてください。ハンドラはトランスポートをドメインに変換するだけであり、それ以外は何もしません。サービスが判断を保持します。リポジトリがクエリを保持します。ハンドラに追加されたバリデーションは、サービスの他の呼び出し元からは見えません。
コンテキスト
コンテキストはリクエストに属し、リクエストとともに終了します。
- 最初のパラメータとして
ctxを渡し、データベース呼び出しまでずっと渡し続けてください。コンテキストを受け取らない関数はキャンセルできず、デッドラインを保持できません。 context.Contextを構造体のフィールドに決して保存しないでください。- リクエストコンテキストを、ハンドラよりも長く生存するゴルーチンに渡さないでください。切り離されたバックグラウンド作業には、独自のタイムアウトを持つ独自のコンテキストが必要であり、必要な値はハンドラが返る前に明示的にコピーしてください。
- 同じことは、リクエストから派生したハンドル(トランザクション、コネクション、リクエストスコープのデータベースアクセッサなど)にも当てはまります。ハンドラが返った後にこれらを使用することは、より親切なエラーメッセージ付きのuse-after-freeです。
エラー
%wでラップし、呼び出し元がまだ知らない情報(識別子、操作など)を追加してください。fmt.Errorf("load order %d: %w", id, err)。関数名を前置しないでください。それらが積み重なるとノイズになります。errors.Isとerrors.Asで比較してください。誰かがラップすると、直接の==比較は機能しなくなります。- トランスポートステータスへの変換は、ハンドラ境界のちょうど一箇所で行ってください。HTTPコードを返すリポジトリは、2つのレイヤーを漏洩しています。
sql.ErrNoRowsはドメインの結果であり、失敗ではありません。リポジトリの境界でドメインの「見つからない」にマップすることで、サービスがdatabase/sqlをインポートしないようにしてください。- コンパイラを満足させるためにエラーを決して破棄しないでください。本当に無視できるエラーであれば、コメント付きで
_に代入してください。
トランザクション
トランザクションは、不変条件を所有するレイヤー(通常はサービス、決してリポジトリではない)で開いてください。なぜなら、自分でトランザクションを開くリポジトリは、より大きなトランザクションに合成できないからです。トランザクションハンドルを下位に渡してください。
コミットとロールバックは、パニックを含むすべてのパスで行ってください。成功したコミット後のロールバックは無害である必要があります。これが、defer tx.Rollback() を安全にする理由です。
トランザクション内で、そのトランザクションとアトミックである必要のないI/Oを行わないでください。開いているトランザクション内で支払いプロバイダにHTTP呼び出しを行うと、他の誰かの障害の期間中、データベースロックを保持することになります。
テナンシー
サービスがマルチテナントの場合、テナント識別子はデータベースではなくコードで強制されます。すべてのリポジトリクエリ(読み取りと書き込みの両方)は、テナント述語を保持します。主キーだけでフィルタリングするクエリは、別のテナントの行を平気で返します。コードベースが既に使用しているリクエストコンテキストアクセッサから識別子を派生させ、どのアクセッサが正しいかを確認してください。サブテナントに代わって動作するサービスには通常2つのアクセッサがあり、明白な方がしばしば間違っているものです。
ゴルーチン
すべてのゴルーチンには、既知のライフタイムと既知の所有者が必要です。go と書く前に、誰がそれを待つのか、どのように停止するのか、そのエラーはどこに行くのかに答えてください。エラーがドロップされるゴルーチンは、サイレント障害です。
呼び出し元が待つ場合は errgroup を使用してください。適切でない場合は、明示的な sync.WaitGroup と収集されたエラーチャネルを使用してください。リクエスト処理内の裸の go f() は、ほとんどの場合、欠陥です。
テスト
テーブル駆動で、ケースごとに1つの t.Run を使用し、入力ではなく振る舞いに基づいて名前を付けてください。各ケースは、その入力と期待値を示し、それ以外は何も示しません。すべてのケースで共有されるセットアップはテーブルの上に属します。
テストを実行するときは、常にタイムアウトを渡してください:
go test -count=1 -timeout 60s ./...
-count=1 は結果キャッシュを無効にします。結果キャッシュは、変更したばかりのコードに対して合格を報告します。タイムアウトは見た目以上に重要です。タイムアウトなしのデッドロックしたテストは、マシンが停止するまでメモリを消費し続けます。
パッケージのエクスポートされた振る舞いをテストしてください。エクスポートされていない内部に到達するテストは、実装を固定化し、誠実なリファクタリングのたびに失敗します。
テストがflakyな場合、ほとんどの場合、実際の競合状態を報告しています。そうでないと結論付ける前に -race フラグ付きで実行し、スリープを追加して修正しないでください。
完了と呼ぶ前に
変更をカバーする最も狭いテストを実行し、共有契約が変更された場合は範囲を広げてください。終了コードを飲み込む可能性のあるmakeターゲットではなく、サービス内で golangci-lint run を実行してください。テストを弱めるのではなく、出力を添えて失敗を報告してください。