Go インターフェースと構成

利用可能なスクリプト

• scripts/check-interface-compliance.sh — コンパイル時の適合チェック (var _ I = (*T)(nil)) が不足しているエクスポートされたインターフェースを検出します。オプションについては bash scripts/check-interface-compliance.sh --help を実行してください。

---

インターフェースを受け取る、具象型を返す

インターフェースは、実装するパッケージではなく、値を利用するパッケージに属します。コンストラクタから具象型（通常はポインタまたはストラクト型）を返すことで、リファクタリングなしに新しいメソッドを追加できます。

// Good: コンシューマーが必要なインターフェースを定義する
package consumer

type Thinger interface { Thing() bool }

func Foo(t Thinger) string { ... }

// Good: プロデューサーが具象型を返す
package producer

type Thinger struct{ ... }
func (t Thinger) Thing() bool { ... }
func NewThinger() Thinger { return Thinger{ ... } }

// Bad: プロデューサーが独自のインターフェースを定義して返す
package producer

type Thinger interface { Thing() bool }
type defaultThinger struct{ ... }
func NewThinger() Thinger { return defaultThinger{ ... } }

使用される前にインターフェースを定義しないでください。 実際の使用例がなければ、インターフェースが本当に必要かどうかを判断するのは非常に困難です。

---

一般性：実装を隠蔽し、インターフェースを露出する

型がそのインターフェースのみを実装し、そのインターフェース以外にエクスポートされたメソッドがない場合は、コンストラクタからインターフェースを返して実装を隠蔽します：

func NewHash() hash.Hash32 {
    return &myHash{}  // unexported type
}

メリット：実装を変更する際に呼び出し元に影響を与えない、アルゴリズムの代替はコンストラクタの呼び出しを変更するだけです。

---

型アサーション：カンマOK イディオム

チェックなしで型アサーションが失敗するとランタイムパニックが発生します。安全にテストするためにカンマOK イディオムを常に使用してください：

str, ok := value.(string)
if ok {
    fmt.Printf("string value is: %q\n", str)
}

値がインターフェースを実装しているかチェックするには：

if _, ok := val.(json.Marshaler); ok {
    fmt.Printf("value %v implements json.Marshaler\n", val)
}

---

型スイッチ

変数名を再利用する (t := t.(type)) のは慣例的です — 各ケースブランチで変数は正しい型になります。ケースが複数の型をリストアップする場合 (case int, int64:)、変数はインターフェース型になります。

---

埋め込み

パブリックストラクトへの型の埋め込みは避けてください — 内側の型の完全なメソッドセットがパブリックAPIの一部になります。代わりにエクスポートされていないフィールドを使用してください。

ストラクト埋め込みを構成に使用する場合、埋め込まれたメソッドをオーバーライドする場合、名前の競合を解決する場合、HandlerFunc アダプターパターンを適用する場合、またはパブリックAPI型に埋め込みを適用するかどうかを判断する場合は、references/EMBEDDING.md を参照してください。

---

インターフェース適合チェック

ブランク識別子の割り当てを使用して、型がコンパイル時にインターフェースを実装しているかどうかを確認します：

var _ json.Marshaler = (*RawMessage)(nil)

*RawMessage が json.Marshaler を実装していない場合、コンパイルエラーが発生します。

このパターンは以下の場合に使用してください：

• インターフェースを自動的に検証する静的変換がない場合
• 正しい動作のために型がインターフェースを満たす必要がある場合（例：カスタムJSON マーシャリング）
• インターフェースの変更によってサイレント劣化するのではなくコンパイルが中断する場合

すべてのインターフェースにこれらのチェックを追加しないでください — 他の静的変換でエラーを捕捉できない場合のみです。

検証：インターフェースまたは実装を定義した後、bash scripts/check-interface-compliance.sh を実行して、すべての具象型がコンパイル時の var _ I = (*T)(nil) チェックを持っていることを確認します。

---

レシーバー型

疑わしい場合はポインタレシーバーを使用してください。単一の型にレシーバー型を混ぜないでください — いずれかのメソッドがポインタを必要とする場合、すべてのメソッドにポインタを使用してください。値レシーバーは小さく不変な型 (Point、time.Time) または基本型のみで使用してください。

新しい型のポインタレシーバーと値レシーバーを決定する場合、特に同期プリミティブまたは大きなストラクトを持つ型の場合は、references/RECEIVER-TYPE.md を参照してください。

---

クイックリファレンス

概念	パターン	注記
コンシューマーがインターフェースを所有する	使用されている場所でインターフェースを定義する	実装パッケージではない
安全な型アサーション	v, ok := x.(Type)	ゼロ値 + false を返す
型スイッチ	switch v := x.(type)	ケースごとに変数が正しい型になる
インターフェース埋め込み	type RW interface { Reader; Writer }	メソッドの結合
ストラクト埋め込み	type S struct { *T }	T のメソッドを昇格
インターフェースチェック	var _ I = (*T)(nil)	コンパイル時検証
一般性	コンストラクタからインターフェースを返す	実装を隠蔽

---

関連スキル

• インターフェース命名：インターフェース命名（-er サフィックス慣例）またはレシーバー名の選択については、go-naming を参照してください
• エラー型：error インターフェースの実装、カスタムエラー型、または errors.As マッチングについては、go-error-handling を参照してください
• ジェネリクス対インターフェース：ジェネリクスが必要か、またはインターフェースで十分かを判断する場合は、go-generics を参照してください
• 関数型オプション：柔軟なコンストラクタのためのインターフェースベースの Option パターンを使用する場合は、go-functional-options を参照してください
• コンパイル時チェック：API境界で var _ I = (*T)(nil) 適合チェックを追加する場合は、go-defensive を参照してください