Go テックスタック（採用構成）

決定日: 2026-08-27
クラウド: GCP Cloud Run（低 UU・費用優先）
アプリケーション: 個別技術は一般的なベストプラクティス。採用の方向性は、実績のある既存 Go バックエンド（層分割・契約駆動・RDB・Gateway・UseCase でのトランザクション）に合わせる。個別リポのアレンジ（古いピン、特定ライブラリ、運用固有ルール）は引き継がない
前提: トラフィック・UU はかなり少ない
契約設計の型は .cursor/docs/TECHNOLOGY_STACK_UNIFIED_DESIGN.md に準ずる（OpenAPI First、実装から契約を逆生成しない）
本キットの docs/tech-stack.md（TypeScript / Cloudflare）は未変更。本ファイルは Go サービス用

契約前に Cloud Run pricing を再確認すること。

選定の原則

方向性（実績のある Go サービスと同じ置き方）
  層を分ける / 契約を実装の外に置く / RDB とマイグレーションを分離する
  外部 I/O は Gateway / トランザクションはアプリケーション層 / 生成物は手編集しない

個別技術（その時点の一般解）
  言語・ルータ・ORM 相当・ログ・観測は現行安定のベストプラクティス
  特定コードベースのピンや独自パッケージをコピーしない

統一設計書と同じ思想:

OpenAPI = API 契約の正本
Go 実装 = 契約を満たすサーバー
CI      = 契約違反を検出する門番
Cloud Run / R2 / RDB = 費用制約下の実行基盤

核心は型安全性ではなく API 契約の独立性である。

採用するクラウド（Cloud Run）

Internet
    │
    ▼
Cloud Run（Go コンテナ, request-based, min-instances=0）
    │
    ├── Postgres（scale-to-zero 可能なホスト）  … 状態
    ├── Cloudflare R2                            … オブジェクト（egress $0）
    └── Cloud Run Jobs                           … 定期・バッチ

役割	採用	拘束
実行	Cloud Run Services	request-based、min-instances=0、concurrency 80、max-instances 3
プロトコル	HTTPS（OpenAPI の REST）。HTTP/1.1 で足りる	初期から gRPC / HTTP/2 必須にしない
リージョン	us-central1	無料枠が効く Tier 1
イメージ	Artifact Registry 同一リージョン	distroless/static。256Mi から
DB ホスト	Postgres の scale-to-zero（例: Neon Free）	Cloud SQL は最小インスタンスの床があるので使わない
ファイル	Cloudflare R2	GCS / S3 / AWS SDK は使わない
定期処理	Cloud Run Jobs + Cloud Scheduler	リクエスト経路に常駐 cron を置かない
観測	`log/slog`。クラウドへはエラー中心	有料 APM を初期固定費にしない

採用しないクラウド: AWS（Lambda / S3 / SDK を含む）、Cloud SQL、VPC コネクタ、NAT、GKE、min-instances≥1、instance-based billing、グローバル LB（初期）。

Cloud Run 拘束設定

platform: managed
region: us-central1
cpu: 1
memory: 256Mi
concurrency: 80
min-instances: 0
max-instances: 3
billing: request-based
PORT を読む（8080）

コールドスタートは許容する。min-instances で買わない。

出典: Cloud Run pricing

アプリケーション構成

方向性は「実績のある Go バックエンドと同じ責務分割」。中身のライブラリは現行の一般解。

技術スタック一覧

レイヤ	採用（ベストプラクティス）	方向性として合わせる点	採用しない（アレンジ / 旧来）
言語	Go 1.27（調査日の現行安定。2026-08-19 リリース）	静的型・単一バイナリのバックエンド	特定リポの古い `go` 行をコピーする
配置	Standard Go Project Layout（`cmd/` / `internal/`）	エントリとビジネスの分離	ビジネスロジックを `main` に置く
アーキテクチャ	Clean Architecture 4 層	Presentation / Application / Domain / Infrastructure	フレームワークの Context にドメインを溶かす
DI	手動のコンストラクタ注入（composition root に明示配線）	実装ではなく IF を渡す。テストで差し替え可能	Wire（2025-08 アーカイブ、メンテ終了）。fx/dig を小規模サービスの既定にしない
API 契約	OpenAPI 3.1 が正本	契約は実装の外。PR で契約をレビューする	コードから spec 逆生成、protobuf を HTTP API の正本にする
サーバー実装	`net/http` ServeMux（1.22+）+ OpenAPI から生成したサーバ stub（oapi-codegen 等）	ハンドラは薄く、ユースケースを呼ぶだけ	Gin/Fiber/goa を既定。Huma を契約の正本にしない
契約ツール	Spectral / Redocly（lint・bundle・breaking diff）	CI が門番	手作業の仕様書だけ
DB	Postgres + pgx + sqlc	RDB、SQL をリポジトリの裏に閉じる	MySQL 固定、GORM、sqlx を既定
マイグレーション	goose（`.sql`）	スキーマはアプリ起動と別コマンド	起動時 auto-migrate、ORM 任せ
Mock	go.uber.org/mock	インターフェースに対するテスト	手書き巨大スタブを既定
設定	環境変数 → 構造体（envconfig で可）	設定とコードの分離	秘密情報をイメージに焼く
ログ	`log/slog`	構造化ログ	logrus 等のサードパーティを既定
エラー	ドメインの型付きエラー + `%w` ラップ	層をまたいで握りつぶさない	エラー無視、`panic` で業務エラー
外部 I/O	Gateway（Infrastructure）。タイムアウト必須	ユースケースから生 HTTP を叩かない	コントローラから SDK 直呼び
トランザクション	Application（UseCase）境界	書き込みはトランザクション内	リポジトリ実装の奥で勝手に commit
時刻	UTC で永続化。表示だけタイムゾーン変換	境界で変換する	DB 値を常に特定タイムゾーン前提にする
オブジェクト	Cloudflare R2 + 公式 Go SDK（`cloudflare-go`）	Gateway 経由	aws-sdk-go-v2、S3、アプリ層でのバケット操作

gRPC は「内部サービス間で protobuf が既に契約になっている」場合の追加であり、初期の HTTP API 正本にはしない。統一設計書の OpenAPI First を優先する。

DI の補足: 方向性は「コンストラクタで依存を渡す」ことであり、コード生成ツールではない。google/wire は 2025-08-25 にアーカイブされ、README でメンテ終了が明示されている。最終タグ v0.7.0 はアーカイブ直前の x/tools 破損修正であり、Go 1.27 以降のツールチェーン追従は期待できない。新規に Wire を正としない。グラフが大きくなったら維持されている手段（手配線の分割、必要なら fx）を再審する。

層責務

依存方向: Presentation → Application → Domain ← Infrastructure。Domain は他層に依存しない。

ディレクトリ	層	許可 / 禁止
`cmd/<service>/`	起動	設定・DI 初期化のみ。ビジネスロジック禁止
`internal/app/controller/`	Presentation	HTTP 入出力・認証境界・OpenAPI との接続。ビジネスロジック禁止
`internal/app/usecase/`	Application	フロー結合・トランザクション境界。ドメイン規則の本体や直接外部 API 禁止
`internal/app/domain/`	Domain	entity / vo / repository IF / ドメインエラー。インフラ型禁止
`internal/app/infrastructure/`	Infrastructure	sqlc 利用、`*_gateway/`。ドメイン規則禁止
`internal/di/` または `cmd` 直下	composition root	コンストラクタを手で組み立てる。生成 DI に依存しない
`openapi/`	契約正本	破壊的変更は CI で検出。実装から逆生成しない
`internal/gen/` 等	生成物	手編集禁止
`db/migrations/`	goose	破壊的変更は提案のみ

データとオブジェクト

Postgres

ホスト: scale-to-zero（Neon Free 等）。停止中 compute $0 を維持する
アクセス: sqlc + pgxpool。クエリは .sql が正で、生成 Go は従
接続プールは小さく（例: max 5）
同時更新が本物の競合になる箇所だけ楽観ロック（version）。全テーブル必須にはしない
Cloud SQL は使わない

出典: Neon Pricing

R2

egress $0。Infrastructure の R2 Gateway からのみ触る。クライアントは Cloudflare 公式の cloudflare-go（R2 API）とする。

R2 のワイヤプロトコルが S3 互換であることは実装の都合であり、AWS を採用したことにはしない。 aws-sdk-go-v2 は依存に加えない。

出典: R2 pricing / Cloudflare Go API（R2）

トポロジ

flowchart LR
  C[クライアント] -->|HTTPS OpenAPI| CR[Cloud Run]
  CR --> PG[Postgres scale-to-zero]
  CR --> R2[Cloudflare R2]
  SCH[Cloud Scheduler] --> JOB[Cloud Run Job]
  JOB --> PG
  AR[Artifact Registry] --> CR
  AR --> JOB

HTTP サービスと定期処理は 別プロセス（Service と Job）。常駐スケジューラを Web プロセスに載せない。

契約駆動の実装順（統一設計書に合わせる）

OpenAPI 3.1 を書く（レビュー対象）
Spectral / Redocly で lint。破壊的変更は CI
oapi-codegen 等でサーバ stub / クライアント型を生成
UseCase / Domain を実装し、stub から呼び出す
sqlc の SQL を書き、リポジトリ実装を Infrastructure に置く
契約テスト（モックサーバまたは応答スキーマ検証）

コードを先に書いて spec を合わせる方式は採用しない。

デプロイ（最小）

CGO_ENABLED=0 で linux/amd64（pgx は pure Go）
Artifact Registry us-central1 へ push
gcloud run deploy で拘束設定を毎回明示
DSN / R2 資格情報は Secret Manager 可
goose は Job または CI。サービス起動時に migrate しない

費用の守り方

min-instances ≥ 1 にしない
instance-based billing にしない
Cloud SQL + VPC コネクタを足さない
有料 APM を初期から入れない
Service 内常駐 poller を置かない
イメージを太い distro にしない
契約をコードに埋め込んで OpenAPI を捨てない

このリポジトリとの関係

kit docs/tech-stack.md: Cloudflare + Hono + Next.js（フロント / TS の正）
Go サービス: 本ファイル。契約の型（OpenAPI First）は統一設計書と揃える
kit の tech_stack へ取り込む場合は manifest + ADR（D-DEPENDENCY）が別判断

一次情報

対象	URL
統一設計書（契約の型）	`.cursor/docs/TECHNOLOGY_STACK_UNIFIED_DESIGN.md`
Go 1.27	https://go.dev/blog/go1.27
Cloud Run 料金	https://cloud.google.com/run/pricing
Neon 料金	https://neon.com/pricing
R2 料金	https://developers.cloudflare.com/r2/pricing/
Cloudflare Go SDK	https://pkg.go.dev/github.com/cloudflare/cloudflare-go/v7
OpenAPI 3.1	https://spec.openapis.org/oas/v3.1.0.html

不確実性

Go 1.27.0 はリリース直後。パッチ（1.27.x）が出たらパッチ追従する
Neon Free は CU / 容量上限で月内停止しうる
コールドスタートと DB suspend が重なると最初の 1 リクエストが遅い
内部が既に gRPC 契約だけの場合は、OpenAPI に加え gRPC を足す判断が別途必要

Goの統一設計書作成 #83

Description

Activity

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions