Day 020 — インターフェース設計の原則（小さいインターフェース）

📚 背景知識（読んでから問題へ）

Day 019では「型を増やすコスト」を意識してエラー型を設計しました。今日はその視点をインターフェース設計に広げます。テーマはGoコミュニティで最も有名な格言のひとつ、"Accept interfaces, return structs"（インターフェースを受け取り、構造体を返せ）です。

Goの標準ライブラリを見渡すと、インターフェースの多くが驚くほど小さいことに気づきます。

• io.Reader: Read(p []byte) (n int, err error) の1メソッドのみ
• io.Writer: Write(p []byte) (n int, err error) の1メソッドのみ
• sort.Interface: Len() Less(i, j int) bool Swap(i, j int) の3メソッドのみ
• error: Error() string の1メソッドのみ

これは偶然ではなく、Goの設計思想の核心です。理由は3つあります。

1. 実装しやすい: メソッドが少ないほど、そのインターフェースを満たす型を作るコストが下がる。1メソッドのインターフェースなら、既存のどんな型にも簡単にアダプタを書ける
2. テストしやすい: 関数が必要とするインターフェースが小さいほど、テスト用のフェイク実装が数行で書ける。巨大なインターフェースは「使わないメソッドまでダミー実装する」羽目になる
3. 依存が明確になる: 関数のシグネチャに小さいインターフェースが並ぶと、「この関数は本当は何が必要なのか」が一目でわかる。巨大な万能インターフェースを受け取る関数は、実際に何を使っているのか読まないとわからない

もう1つ重要なのが「インターフェースは実装側ではなく利用側（consumer）が定義する」という原則です。Javaなどでは「このクラスが実装するインターフェース」を実装側のパッケージで先に定義することが多いですが、Goでは逆で、「この関数が必要とする最小限の振る舞い」を呼び出し側のパッケージで定義するのが自然です。これにより、同じ具象型（例: DBクライアント）に対して、呼び出し側ごとに異なる粒度のインターフェースを自由に定義できます。

そして"return structs"の部分は、コンストラクタ（NewXxx）は具体的な構造体のポインタを返すべきで、インターフェースを返すべきではない、という指針です。呼び出し元がその構造体の全メソッドにアクセスできる状態を保ち、必要なメソッドだけを使いたい別の呼び出し元は、自分でその構造体を受け取れる小さいインターフェースを定義すればよい、という役割分担です。

📝 問題

あなたのチームには、以下のような「万能インターフェース」があります。データベースのキーバリューストアを表すDataStoreインターフェースで、複数の呼び出し元（レポート生成・バッチ削除処理・管理画面）がこれを直接受け取って使っています。

📋 コピーtype DataStore interface {
	Get(ctx context.Context, key string) (string, bool, error)
	Put(ctx context.Context, key, value string) error
	Delete(ctx context.Context, key string) error
	List(ctx context.Context, prefix string) ([]string, error)
	Close() error
}

このうち「レポート生成処理」は、指定されたキー一覧の値を取得して出力するだけの機能です。しかし現状のコードはfunc GenerateReport(store DataStore, keys []string, w io.Writer) errorのように、5メソッドすべてを持つDataStoreをまるごと受け取っています。

あなたのタスク

1. GenerateReportが本当に必要としているメソッドを見極め、利用側（report生成処理）で定義する最小限のインターフェースを設計すること
2. GenerateReportのシグネチャをその小さいインターフェースを受け取る形に変更すること
3. 具体的なデータストア実装としてPostgresStore構造体を実装し、DataStoreの5メソッドすべてを実装すること。コンストラクタNewPostgresStore()は具体的な構造体のポインタ（インターフェースではない）を返すこと
4. main関数でNewPostgresStore()の戻り値をそのままGenerateReportに渡し、Goのインターフェースが暗黙的に満たされることを実演すること（PostgresStoreが小さいインターフェースを「実装しています」と明示的に書く必要がないことを確認する）
5. テスト用のfakeStore型を実装すること。このときDataStoreの5メソッドをすべてダミー実装するのではなく、小さいインターフェースが要求する1メソッドだけを実装すればテストが書けることを、実際にgo testが通るテストコードで示すこと
6. 設計判断として、なぜこの粒度でインターフェースを切ったのか、「利用側が定義する」という原則をどう適用したかを1〜2文で説明すること

🔍 ヒント（段階的開示）

📋 コピー// report/report.go
package report

import (
	"context"
	"fmt"
	"io"
)

// DataGetter は GenerateReport が実際に必要とする最小限の振る舞いのみを表す。
// 利用側（report パッケージ）がここで定義する。
type DataGetter interface {
	// TODO: 必要なメソッド1つだけを定義する
}

func GenerateReport(ctx context.Context, store DataGetter, keys []string, w io.Writer) error {
	// TODO: keys を順に Get し、見つかった/見つからなかったを w に書き出す
	return nil
}

📋 コピー// store/postgres.go
package store

import "context"

// DataStore は複数の呼び出し元（report・batch削除・管理画面）が
// 共通で参照する「実装側」の万能インターフェース定義（今回は比較用に残す）。
type DataStore interface {
	Get(ctx context.Context, key string) (string, bool, error)
	Put(ctx context.Context, key, value string) error
	Delete(ctx context.Context, key string) error
	List(ctx context.Context, prefix string) ([]string, error)
	Close() error
}

type PostgresStore struct {
	// TODO: 内部状態（今回はデモ用にmapで代用してよい）
}

func NewPostgresStore() *PostgresStore {
	// TODO: 具体的な構造体のポインタを返す（インターフェース型を返さない）
	return nil
}

// TODO: PostgresStore に DataStore の5メソッドをすべて実装する

✅ 模範解答

ファイル: report/report.go

📋 コピーpackage report

import (
	"context"
	"fmt"
	"io"
)

// ── 設計判断 ──────────────────────────────────────────
// GenerateReport が実際に呼び出しているのは Get の1メソッドのみ。
// Put/Delete/List/Close は一度も使われないため、report パッケージ
// （＝利用側）で「本当に必要な最小限」だけを持つ DataGetter を定義する。
// このインターフェースは store パッケージの DataStore とは無関係に、
// report パッケージが「自分にとって何が必要か」だけを基準に定義したもの。
// PostgresStore 側は DataGetter の存在を知らなくても、Get のシグネチャが
// 一致していれば自動的にこのインターフェースを満たす（暗黙的実装）。
// ─────────────────────────────────────────────────────

// DataGetter は GenerateReport が必要とする最小限の振る舞い。
// 利用側（report パッケージ）が定義する、いわゆる consumer-defined interface。
type DataGetter interface {
	Get(ctx context.Context, key string) (value string, found bool, err error)
}

// GenerateReport は keys のそれぞれについて値を取得し、w に書き出す。
// store には DataGetter という「Getできるものなら何でもよい」という
// 最小限の要求だけを課しているため、PostgresStore・フェイク・将来の
// Redisストアなど、Getさえ実装していればどんな型でも渡せる。
func GenerateReport(ctx context.Context, store DataGetter, keys []string, w io.Writer) error {
	for _, key := range keys {
		value, found, err := store.Get(ctx, key)
		if err != nil {
			return fmt.Errorf("generate report: get %q: %w", key, err)
		}
		if !found {
			fmt.Fprintf(w, "%s: (not found)\n", key)
			continue
		}
		fmt.Fprintf(w, "%s: %s\n", key, value)
	}
	return nil
}

ファイル: store/postgres.go

📋 コピーpackage store

import (
	"context"
	"fmt"
)

// DataStore は複数の呼び出し元（report・batch削除・管理画面）が
// 実際のDB操作をイメージしやすいよう、実装側でひとまとめに定義した
// リファレンス用インターフェース。これ自体は「万能インターフェース」の
// 例として残しているが、各呼び出し元が直接これを受け取ることは推奨しない。
type DataStore interface {
	Get(ctx context.Context, key string) (string, bool, error)
	Put(ctx context.Context, key, value string) error
	Delete(ctx context.Context, key string) error
	List(ctx context.Context, prefix string) ([]string, error)
	Close() error
}

// PostgresStore は DataStore の実運用実装（デモのため内部はmapで代用）。
type PostgresStore struct {
	data map[string]string
}

// NewPostgresStore は具体的な構造体のポインタを返す。
// インターフェース型（DataStore）を返さないことで、呼び出し元は
// PostgresStore が実際に持つ全メソッドにアクセスでき、必要な範囲だけを
// 使いたい呼び出し元は自分で小さいインターフェースを定義して受け取ればよい。
func NewPostgresStore() *PostgresStore {
	return &PostgresStore{data: map[string]string{
		"user:1:name":  "Alice",
		"user:2:name":  "Bob",
		"config:limit": "1000",
	}}
}

func (s *PostgresStore) Get(ctx context.Context, key string) (string, bool, error) {
	v, ok := s.data[key]
	return v, ok, nil
}

func (s *PostgresStore) Put(ctx context.Context, key, value string) error {
	s.data[key] = value
	return nil
}

func (s *PostgresStore) Delete(ctx context.Context, key string) error {
	delete(s.data, key)
	return nil
}

func (s *PostgresStore) List(ctx context.Context, prefix string) ([]string, error) {
	var keys []string
	for k := range s.data {
		if len(k) >= len(prefix) && k[:len(prefix)] == prefix {
			keys = append(keys, k)
		}
	}
	return keys, nil
}

func (s *PostgresStore) Close() error {
	fmt.Println("postgres connection closed")
	return nil
}

ファイル: main.go（同一モジュール内でexample.com/report・example.com/storeとしてimport）

📋 コピーpackage main

import (
	"context"
	"os"

	"example.com/report"
	"example.com/store"
)

func main() {
	ctx := context.Background()

	// NewPostgresStore() は *PostgresStore という具体的な構造体を返す。
	// PostgresStore は report.DataGetter の存在を知らないが、
	// Get(ctx, key) (string, bool, error) というシグネチャを持つため
	// 暗黙的に report.DataGetter を満たしている。
	pg := store.NewPostgresStore()

	keys := []string{"user:1:name", "user:2:name", "config:limit", "config:missing"}

	if err := report.GenerateReport(ctx, pg, keys, os.Stdout); err != nil {
		panic(err)
	}

	_ = pg.Close()
}

ファイル: report/report_test.go

📋 コピーpackage report

import (
	"bytes"
	"context"
	"strings"
	"testing"
)

// fakeStore は report.DataGetter が要求する Get メソッドだけを実装する。
// store.DataStore の Put/Delete/List/Close は一切実装していないが、
// GenerateReport が要求するインターフェースはこれで満たしているため
// コンパイル・テストともに問題なく通る。
type fakeStore struct {
	data map[string]string
}

func (f *fakeStore) Get(ctx context.Context, key string) (string, bool, error) {
	v, ok := f.data[key]
	return v, ok, nil
}

func TestGenerateReport(t *testing.T) {
	fs := &fakeStore{data: map[string]string{"a": "1", "b": "2"}}
	var buf bytes.Buffer

	err := GenerateReport(context.Background(), fs, []string{"a", "b", "c"}, &buf)
	if err != nil {
		t.Fatalf("unexpected error: %v", err)
	}

	got := buf.String()
	wantLines := []string{"a: 1", "b: 2", "c: (not found)"}
	for _, line := range wantLines {
		if !strings.Contains(got, line) {
			t.Errorf("output missing line %q, got:\n%s", line, got)
		}
	}
}

$ go run .
user:1:name: Alice
user:2:name: Bob
config:limit: 1000
config:missing: (not found)
postgres connection closed

$ go test ./...
ok  	example.com/report	0.002s

※ report・storeパッケージとmain.goを1つのモジュール（go.modでmodule example.com/xxxと宣言し、report/report.go・store/postgres.goを配置）として実行しています。

🪜 Step-by-Step 解説

📋 コピーtype DataGetter interface {
	Get(ctx context.Context, key string) (value string, found bool, err error)
}

📋 コピーfunc NewPostgresStore() *PostgresStore {
	return &PostgresStore{...}
}

📋 コピーtype fakeStore struct{ data map[string]string }
func (f *fakeStore) Get(ctx context.Context, key string) (string, bool, error) { ... }

💡 設計思想・なぜこう書くのか

🌐 他言語との比較

Goで際立つのは、「暗黙的実装」と「利用側でのインターフェース定義」がセットになっている点です。実装側がインターフェースの存在を知らなくてよいため、後から新しい利用文脈（新しい小さいインターフェース）を追加しても、既存の実装コードに一切手を入れる必要がありません。これはJava的な「先にインターフェースを設計してから実装する」ワークフローとは順序が逆で、「まず具体的な実装を書き、必要になった時点で利用側からインターフェースを切り出す」というボトムアップの設計がGoでは自然です。

🏆 実務での使いどころ

• テスト容易性の確保: DBクライアント・外部APIクライアント・ファイルシステムアクセスなど、外部依存を持つ関数を書くときは、その関数が本当に必要とする操作だけを持つ小さいインターフェースを利用側で定義しておくと、テストで本物のDB/APIを使わずにフェイクへ差し替えられる
• 段階的なマイクロサービス分割: reportパッケージがDataGetterしか要求していなければ、将来PostgresをRedisやリモートAPI経由のストアに置き換えるときも、reportパッケージのコードは一切変更不要（Getさえ実装していれば何でも渡せる）
• 依存関係の可視化: 関数シグネチャに並ぶ小さいインターフェース群を見るだけで、コードレビュー時に「この関数は何に依存しているか」が一目でわかる。巨大インターフェースだとレビュアーが実装を読まないと依存範囲を把握できない
• 標準ライブラリとの親和性: io.Reader/io.Writerのような標準の小さいインターフェースに準拠して自作の型を設計しておくと、io.Copyやbufioなど標準ライブラリの関数群にそのまま接続できる

⚠️ よくある誤解・ミス

🚀 次のステップ

• 発展: batchパッケージ（キーの一括削除処理）を想定し、DataDeleterという別の1メソッドインターフェースを定義して、同じ*store.PostgresStoreをreport.DataGetterとbatch.DataDeleterの両方に渡せることを確認してみましょう。1つの具象型が複数の異なる利用側インターフェースを同時に満たせることを体感できます
• 次回予告: Day 021 — embedding（構造体・インターフェースの埋め込み）（実装）。継承ではなくコンポジションでコードを再利用するGoの仕組みを、今日の「小さいインターフェース」の考え方の延長として学びます

🎯 自己評価

自分の回答

気づき・メモ