Persona: Go のデータ構造内部構造を理解するエンジニアです。メモリレイアウト、割り当てコスト、アクセスパターンを検討することで、最も使い慣れた構造ではなく、仕事に適切な構造を選択します。

Go データ構造

組み込みおよび標準ライブラリのデータ構造：内部構造、正しい使用法、選択ガイダンス。安全性の落とし穴（nil マップ、append エイリアシング、防御的コピー）については samber/cc-skills-golang@golang-safety スキルを参照してください。チャネルと同期プリミティブについては samber/cc-skills-golang@golang-concurrency スキルを参照してください。文字列/バイト/rune の選択については samber/cc-skills-golang@golang-design-patterns スキルを参照してください。

ベストプラクティス概要

1. スライスとマップを事前割り当てする make(T, 0, n) / make(map[K]V, n) を使用して、サイズが既知または推定可能な場合 — 繰り返しの成長コピーとリハッシングを回避します
2. 配列 はコンパイル時に既知のサイズ（ハッシュダイジェスト、IPv4 アドレス、行列寸法）に限り、スライスより優先すべきです
3. スライス容量増加のタイミングに依存しない — 成長アルゴリズムは Go のバージョン間で変更され、再度変更される可能性があります。コードは新しいバッキング配列がいつ割り当てられるかに依存すべきではありません
4. container/heap を優先度キューに、container/list は頻繁な中間挿入が必要な場合のみに、container/ring を固定サイズの循環バッファに使用します
5. strings.Builder は文字列構築に優先すべきです。bytes.Buffer は双方向 I/O に優先すべきです（io.Reader と io.Writer の両方を実装）
6. ジェネリックデータ構造は 最も厳密な制約 を使用すべきです — キーには comparable、順序付けにはカスタムインターフェース
7. unsafe.Pointer は Go スペックの 6 つの有効な変換パターンのみに従うべきです — 複数のステートメント間で uintptr 変数に保存してはいけません
8. weak.Pointer[T]（Go 1.24+）はキャッシュとカノニカライゼーションマップに使用すべきです。GC がエントリを回収できるようにします

スライス内部構造

スライスは 3 ワードのヘッダーです：ポインタ、長さ、容量。複数のスライスがバッキング配列を共有できます（→ エイリアシングの落とし穴とヘッダーダイアグラムについては samber/cc-skills-golang@golang-safety を参照）。

容量増加

• < 256 要素：容量が 2 倍になります

• = 256 要素：約 25% 増加します（newcap += (newcap + 3*256) / 4）

• 各増加はバッキング配列全体をコピーします — O(n)

事前割り当て

// 正確なサイズが既知
users := make([]User, 0, len(ids))

// 近似的なサイズが既知
results := make([]Result, 0, estimatedCount)

// 一括 append 前に事前拡張（Go 1.21+）
s = slices.Grow(s, additionalNeeded)

slices パッケージ（Go 1.21+）

重要な関数：Sort/SortFunc、BinarySearch、Contains、Compact、Grow。Clone、Equal、DeleteFunc については samber/cc-skills-golang@golang-safety スキルを参照してください。

スライス内部構造の詳細解説 — 完全な slices パッケージリファレンス、成長メカニズム、len vs cap、ヘッダーコピー、バッキング配列エイリアシング。

マップ内部構造

マップはハッシュテーブルで、8 エントリのバケットとオーバーフロー チェーンです。参照型です — マップを割り当てるとポインタをコピーし、データはコピーしません。

事前割り当て

m := make(map[string]*User, len(users)) // 生成時のリハッシングを回避

maps パッケージクイックリファレンス（Go 1.21+）

関数	目的
Collect(1.23+)	イテレータからマップを構築
Insert(1.23+)	イテレータからエントリを挿入
All(1.23+)	すべてのエントリに対するイテレータ
Keys、Values	キー/値に対するイテレータ

Clone、Equal、ソート済みイテレーション については samber/cc-skills-golang@golang-safety スキルを参照してください。

マップ内部構造の詳細解説 — Go マップがデータを保存およびハッシュする方法、バケットオーバーフロー チェーン、マップがなぜ縮小しないのか（およびその対策）、マップのパフォーマンスを代替案と比較。

配列

固定サイズ、値型。代入時に全体がコピーされます。コンパイル時に既知のサイズに使用します：

type Digest [32]byte           // 固定サイズ、値型
var grid [3][3]int             // 多次元
cache := map[[2]int]Result{}   // 配列は比較可能 — マップキーとして使用可能

他のすべてに対してはスライスを優先してください — 配列は成長できず、値で渡されます（大きなサイズでは高コスト）。

container/ 標準ライブラリ

パッケージ	データ構造	最適な用途
container/list	双方向リンクリスト	LRU キャッシュ、頻繁な中間挿入/削除
container/heap	最小ヒープ（優先度キュー）	Top-K、スケジューリング、Dijkstra
container/ring	循環バッファ	ローリングウィンドウ、ラウンドロビン
bufio	バッファ付きリーダー/ライター/スキャナー	小さな読み書きで効率的な I/O

コンテナ型は any を使用します（型安全性なし）— ジェネリックラッパーを検討してください。コンテナパターン、bufio、および例 — 各コンテナ型をいつ使用するか、型安全性を追加するジェネリックラッパー、効率的な I/O の bufio パターン。

strings.Builder vs bytes.Buffer

純粋な文字列連結には strings.Builder を使用します（String() のコピーを回避）、io.Reader またはバイト操作が必要な場合は bytes.Buffer を使用します。両方とも Grow(n) をサポートします。詳細と比較

ジェネリックコレクション（Go 1.18+）

最も厳密な制約を使用します。マップキーには comparable、ソートには cmp.Ordered、ドメイン固有の順序付けにはカスタムインターフェースを使用します。

type Set[T comparable] map[T]struct{}

func (s Set[T]) Add(v T)          { s[v] = struct{}{} }
func (s Set[T]) Contains(v T) bool { _, ok := s[v]; return ok }

ジェネリックデータ構造の記述 — Go 1.18+ ジェネリックを使用した型安全なコンテナ、制約の充足の理解、ドメイン固有のジェネリック型の構築。

ポインタ型

型	ユースケース	ゼロ値
*T	通常の間接参照、ミューテーション、オプション値	nil
unsafe.Pointer	FFI、低レベルメモリレイアウト（6 つのスペックパターンのみ）	nil
weak.Pointer[T](1.24+)	キャッシュ、カノニカライゼーション、弱参照	N/A

ポインタ型の詳細解説 — 通常のポインタ、unsafe.Pointer（6 つの有効なスペックパターン）、GC 安全なキャッシュの weak.Pointer[T]。

コピーセマンティクスクイックリファレンス

型	コピー動作	独立性
int、float、bool、string	値（ディープコピー）	完全に独立
array、struct	値（ディープコピー）	完全に独立
slice	ヘッダーコピー、バッキング配列共有	slices.Clone を使用
map	参照コピー	maps.Clone を使用
channel	参照コピー	同じチャネル
*T（ポインタ）	アドレスコピー	同じ基盤値
interface	値コピー（型 + 値ペア）	保持型に依存

サードパーティライブラリ

標準ライブラリを超える高度なデータ構造（ツリー、セット、キュー、スタック）の場合：

• emirpasic/gods — 包括的なコレクションライブラリ（ツリー、セット、リスト、スタック、マップ、キュー）
• deckarep/golang-set — スレッドセーフおよび非スレッドセーフなセット実装
• gammazero/deque — 高速な両端キュー

サードパーティライブラリを使用する場合は、現在の API シグネチャについて公式ドキュメントとコード例を参照してください。Context7 は検出プラットフォームとして役立ちます。

クロスリファレンス

• → samber/cc-skills-golang@golang-performance スキルについて、構造体フィールドの配置、メモリレイアウト最適化、キャッシュの局所性を参照してください
• → samber/cc-skills-golang@golang-safety スキルについて、nil マップ/スライス の落とし穴、append エイリアシング、防御的コピー、slices.Clone/Equal を参照してください
• → samber/cc-skills-golang@golang-concurrency スキルについて、チャネル、sync.Map、sync.Pool、およびすべての同期プリミティブを参照してください
• → samber/cc-skills-golang@golang-design-patterns スキルについて、string vs []byte vs []rune、イテレータ、ストリーミングを参照してください
• → samber/cc-skills-golang@golang-structs-interfaces スキルについて、構造体の構成、埋め込み、ジェネリック vs any を参照してください
• → samber/cc-skills-golang@golang-code-style スキルについて、スライス/マップ初期化スタイルを参照してください

よくある間違い

間違い	修正
ループでのスライス増加（事前割り当てなし）	各増加はバッキング配列全体をコピーします — 増加あたり O(n)。make([]T, 0, n) または slices.Grow を使用
スライスで十分な場合に container/list を使用	リンクリストはキャッシュの局所性が悪いです（各ノードは個別のヒープ割り当て）。まずベンチマークしてください
純粋な文字列構築に bytes.Buffer を使用	Buffer の String() は基盤バイトをコピーします。strings.Builder はこのコピーを回避します
ステートメント間で uintptr として保存された unsafe.Pointer	GC はステートメント間でオブジェクトを移動できます — uintptr はダングリング参照になります
マップ内の大きな構造体値（コピーオーバーヘッド）	マップアクセスは値全体をコピーします。大きな値型に対しては map[K]*V を使用してコピーを回避

リファレンス

• Go Data Structures (Russ Cox)
• The Go Memory Model
• Effective Go