メインコンテンツまでスキップ

Goのクリーンアーキテクチャ

このパターンは、ユーザーを作成・取得できるGoのHTTP APIです。名前とメールをJSONで受け取り、PostgreSQLへ保存します。その小さなAPIを使って、「入力を読む処理」「業務のルール」「DBへ保存する処理」を分ける構成を学べます。

例えば、POST /usersへ{"name":" Taro ","email":"TARO@example.com"}を送ると、名前の前後の空白を除き、メールを小文字にそろえて保存します。作成に成功したら201とユーザーIDを返し、そのIDをGET /users/IDへ渡すと保存したユーザーを取得できます。同じメールでもう一度作ると409です。

この処理をひとつの関数にまとめず、役割ごとに分けるのがこの例の中心です。まず作成リクエストを追い、その後に設定・起動・検証を説明します。細かなlint設定は後半の折りたたみで確認できます。

全体像:どこに何を書くか​

go-clean/
├── cmd/api/main.go 起動と、各処理の組み立て
├── internal/
│ ├── domain/user/ 名前・メール・IDのルール
│ ├── usecase/ ユーザーを作成・取得する手順
│ ├── adapter/handler/ HTTPのJSONと業務処理の間の変換
│ ├── adapter/repository/ 業務処理が必要とする保存操作のSQL実装
│ └── infra/ 環境変数、DB接続、ログ
├── db/migrations/ テーブルを作る・戻すSQL
├── api/openapi.yaml 公開するAPIの仕様
├── setup/ 設定台帳、網羅性の照合表、出典
├── .agents/skills/setup/ 設定を質問して反映するスキル
├── scripts/ 設定の反映と検証
└── Makefile 準備・起動・テストの入口

domainは「正しいユーザーとは何か」を定義する層、usecaseは「どういう手順で作成するか」を定義する層です。HTTPやSQLに合わせた処理はadapterへ置きます。infraはDB接続などを作る土台で、cmd/api/main.goが必要なオブジェクトを組み立てます。

作成時の呼び出しは次の順です。

HTTP → handler → usecase → ユーザーの検証
→ 重複確認 → DBへ保存 → handlerからJSON応答

一方、ソースコードのimportは内側へ向けます。usecaseはPostgreSQLのrepositoryをimportせず、保存操作のinterfaceだけを知っています。実際にDBを使うことと、DBの実装にコードが依存することを分けるのが、クリーンアーキテクチャの要点です。この分離により、業務処理をDBなしでテストできます。

1. HTTPの入力を業務処理へ渡す​

internal/adapter/handler/router.goが、URLを処理へ振り分けます。

func NewRouter(users *UserHandler) http.Handler {
gin.SetMode(gin.ReleaseMode) // 起動時のデバッグ出力を止める。ログは logRequest で slog に出す

r := gin.New()
r.HandleMethodNotAllowed = true
r.Use(recoverPanic, logRequest)

r.GET("/healthz", func(c *gin.Context) { c.Status(http.StatusOK) })

r.POST("/users", users.Create)
r.GET("/users/:id", users.Get)

return r
}

gin.New()へ独自のpanic回復とリクエストログを付けています。POST /usersはUserHandler.Create、GET /users/:idはUserHandler.Getへ進みます。/healthzは本文なしの200を返すHTTPプロセスの応答確認で、起動後のDB疎通を検査するものではありません。

作成時はinternal/adapter/handler/user.goで、JSONをusecaseの入力へ詰め替えます。

func (h *UserHandler) Create(c *gin.Context) {
var req createUserRequest
if err := decodeJSON(c, &req); err != nil {
writeError(c, err)
return
}

out, err := h.users.Create(c.Request.Context(), usecase.CreateUserInput{Name: req.Name, Email: req.Email})
if err != nil {
writeError(c, err)
return
}

c.JSON(http.StatusCreated, newUserResponse(out))
}

ここでは名前やメールの正しさを判断しません。HTTPのリクエストを読むことと、結果をHTTPへ戻すことを担当します。DBや業務ルールが変わっても、HTTPの変換と切り分けて確認できるためです。

応答の日時形式はinternal/adapter/handler/dto.goのnewUserResponseでそろえます。

func newUserResponse(out *usecase.UserOutput) userResponse {
// 作成直後もDBからの取得後も、UTC・マイクロ秒精度で同じ日時を返す。
return userResponse{
ID: out.ID,
Name: out.Name,
Email: out.Email,
CreatedAt: out.CreatedAt.UTC().Truncate(time.Microsecond),
}
}

Goの時刻にはナノ秒の端数を持てますが、PostgreSQLのTIMESTAMPTZはマイクロ秒精度です。作成直後の時刻をそのまま返すと、保存後に取得した時刻と端数が異なる場合があります。そこでHTTP応答へ変換するときにUTCへそろえ、マイクロ秒より小さい端数を切り捨てます。例えば.123456789秒は.123456秒として返り、作成応答と取得応答が一致します。秒をまたぐ丸めは行いません。精度はPostgreSQLの日時型、切り捨てはGoのTime.Truncateで確認できます。

2. 名前・メールのルールをdomainで守る​

internal/domain/user/user.goは、名前の前後の空白を除き、空の名前と50文字を超える名前を拒否します。

const maxNameLength = 50

// User はユーザーエンティティ。フィールドを非公開にし、不正な状態で生成できないようにする。
type User struct {
id ID
name string
email Email
createdAt time.Time
}

// New は不変条件を検証してユーザーを生成する。
func New(name string, email Email, now time.Time) (*User, error) {
name = strings.TrimSpace(name)
if err := validateName(name); err != nil {
return nil, err
}

return &User{id: NewID(), name: name, email: email, createdAt: now}, nil
}
func validateName(name string) error {
if name == "" || utf8.RuneCountInString(name) > maxNameLength {
return ErrInvalidName
}

return nil
}

" Taro "は"Taro"となり、空白だけならErrInvalidNameです。文字数はバイト数ではなくutf8.RuneCountInStringで数えます。フィールドを非公開にし、生成関数とgetterを通して使うため、不正な名前をそのまま保存処理へ流しにくくしています。

メールはinternal/domain/user/email.goで検証します。

func NewEmail(s string) (Email, error) {
addr, err := mail.ParseAddress(s)
if err != nil || addr.Address != s {
return "", ErrInvalidEmail
}

return Email(strings.ToLower(s)), nil
}

メールの解析が成功し、解析結果と入力が一致するときだけ受け入れ、小文字へそろえます。TARO@example.comはtaro@example.comになり、表示名を含むTaro <taro@example.com>は拒否します。IDはinternal/domain/user/id.goの標準パッケージuuidで生成・解析します。

DBからの読み出しでは、新規入力用のNewではなくReconstructで保存済みユーザーを復元します。また、EmailとIDは直接キャストできる型なので、新規入力は必ず検証用の関数を通してください。domainにJSONタグやSQLの知識を持たせず、外部との形式変換はadapterへ置きます。

3. usecaseで作成手順を決める​

作成には「メールが登録済みか確認する」「ユーザーを保存する」という操作が必要です。internal/usecase/port.goは、その操作をinterfaceで定義します。

// UserRepository はユーザーの永続化を担う port。
type UserRepository interface {
Create(ctx context.Context, u *user.User) error
FindByID(ctx context.Context, id user.ID) (*user.User, error) // 見つからない場合は user.ErrNotFound
ExistsByEmail(ctx context.Context, email user.Email) (bool, error)
}

// TxManager は fn を1トランザクション内で実行する。fn が error を返すとロールバックする。
type TxManager interface {
Do(ctx context.Context, fn func(ctx context.Context) error) error
}

このinterfaceをここではportと呼びます。usecaseが必要な操作を定義し、外側のrepositoryが実装します。interfaceを使う側で定義する方針はGoのレビュー指針にも沿っています。

internal/usecase/user.goのCreateは、domainで入力を検証してから、重複確認と保存を1トランザクションにまとめます。

func (uc *UserUsecase) Create(ctx context.Context, in CreateUserInput) (*UserOutput, error) {
email, err := user.NewEmail(in.Email)
if err != nil {
return nil, err
}

u, err := user.New(in.Name, email, uc.now())
if err != nil {
return nil, err
}

txErr := uc.tx.Do(ctx, func(ctx context.Context) error {
exists, err := uc.repo.ExistsByEmail(ctx, email)
if err != nil {
return fmt.Errorf("exists by email: %w", err)
}

if exists {
return user.ErrEmailAlreadyExists
}

if err := uc.repo.Create(ctx, u); err != nil {
return fmt.Errorf("create user: %w", err)
}

return nil
})
if txErr != nil {
return nil, txErr
}

return newUserOutput(u), nil
}

重複があれば保存せずErrEmailAlreadyExistsを返します。保存に失敗した場合は、%wで元のエラーに処理の文脈を加えます。handlerはerrors.Isで元の種類を判定できます。時刻はnowという関数から受け取るため、テストでは時刻を固定できます。

取得のGetは、ParseIDでIDを検証してからFindByIDを呼びます。どちらの処理もdomainをUserOutputへ詰め替えて返し、domainの内部構造をHTTPへ直接公開しません。

4. repositoryで同じトランザクションを使う​

internal/adapter/repository/tx.goのDoがトランザクションを開始し、contextへ入れてusecaseの処理を呼びます。成功ならcommit、エラーやpanicならrollbackです。すでにトランザクションがある場合はそこへ合流し、独立した入れ子やsavepointは作りません。

各SQLは、internal/adapter/repository/db.goの次の関数から接続を受け取ります。

func conn(ctx context.Context, db *sql.DB) querier { //nolint:ireturn // *sql.DB と *sql.Tx を同じ型で扱うため
if tx, ok := ctx.Value(txKey{}).(*sql.Tx); ok {
return tx
}

return db
}

contextにトランザクションがあればそれを使い、なければ通常のDB接続を使います。このため、同じcontextを受け取った重複確認とINSERTが同じトランザクションへ参加できます。repositoryでr.dbへ直接SQLを発行すると、この関係を壊すので避けます。

ただし、トランザクションで囲むだけでは、同時リクエストのメール重複を防ぎ切れません。保存時の最終的な保証はdb/migrations/000001_create_users.up.sqlにあります。

CREATE TABLE users (
id UUID PRIMARY KEY,
name VARCHAR(50) NOT NULL,
email VARCHAR(254) NOT NULL UNIQUE,
created_at TIMESTAMPTZ NOT NULL
);

PRIMARY KEYはIDの重複を、UNIQUEはメールの重複を防ぎます。repositoryはINSERTの一意制約違反(SQLSTATE 23505)をErrEmailAlreadyExistsへ変換するため、同時作成で重複した場合もHTTPには409を返せます。制約自体の意味はPostgreSQLの説明を参照してください。

5. HTTPの応答へ戻し、起動時に組み立てる​

internal/adapter/handler/error.goが、業務側のエラーをHTTPステータスへ変換します。

var errorMappings = []struct {
target error
status int
code string
}{
{errInvalidJSON, http.StatusBadRequest, "invalid_request"},
{user.ErrInvalidID, http.StatusBadRequest, codeInvalidArgument},
{user.ErrInvalidName, http.StatusBadRequest, codeInvalidArgument},
{user.ErrInvalidEmail, http.StatusBadRequest, codeInvalidArgument},
{user.ErrNotFound, http.StatusNotFound, "not_found"},
{user.ErrEmailAlreadyExists, http.StatusConflict, "already_exists"},
}

不正な名前・メール・IDなら400、未登録IDなら404、メール重複なら409です。対応表にないエラーは詳細をログへ残し、HTTPには500と一般的なメッセージを返します。新しいドメインエラーを追加するときは、この表とOpenAPIの応答を一緒に確認します。

最後に、cmd/api/main.goが実装同士をつなぎます。この組み立てをDI(依存性の注入)と呼びます。

txManager := repository.NewTxManager(db)
userRepo := repository.NewUserRepository(db)
userHandler := handler.NewUserHandler(usecase.NewUserUsecase(userRepo, txManager))

usecaseが受け取るinterfaceの実体は、ここで渡したPostgreSQLのrepositoryです。DIフレームワークを使わず、この数行を読めば何をつないだか分かる構成にしています。internal/usecase/fake_test.goでは同じinterfaceへフェイクを渡すため、DBを起動せず正常・重複・保存失敗を検証できます。

設定する値を確認する​

最初に決めるのはGoのモジュール名とDB接続先です。その後、必要なら待受ポート・接続数・タイムアウト・開発規約を調整します。setupはこれらをJSONの台帳と照合して反映します。

起動時の環境変数​

初回のサンプルは.env.exampleです。API本体が使う4項目を置き、検証専用のAPI_BASE_URLは省略しています。

APP_ADDR=:8080
DB_PORT=5432
DATABASE_URL=postgres://app:app@localhost:5432/app?sslmode=disable
LOG_LEVEL=info

Makefileが.envを読み、その値をmake runやマイグレーションへ渡します。Goプログラム自身は.envを読まないため、バイナリを直接実行するときは環境変数を別に渡します。

項目意味と、変更・省略した場合の動作
APP_ADDRAPIが待ち受けるアドレス。省略・空文字なら:8080。ローカルPCからだけ使うなら127.0.0.1:8080にする
DATABASE_URLAPIとmigrateが使うPostgreSQL接続先。必須で、未設定なら起動しない。ホスト・ポート・ユーザー・パスワード・DB名を含む
DB_PORT同梱ComposeのDBをホスト側へ公開するポート。省略・空文字なら5432。変更したら同梱DB用のDATABASE_URLのポートも合わせる
LOG_LEVEL出力するJSONログの下限。debug/info/warn/errorから選ぶ。省略・空文字はinfo。アプリは不正値もinfoへ戻すが、setupでは入力ミスとして拒否する
API_BASE_URLmake smokeの接続先。省略時はhttp://127.0.0.1:8080。APIの待受を変えた場合は、検証先も合わせる。通常は.envに追加せず、検証時の環境変数で渡してもよい

PostgreSQLの起動とデータ保存​

compose.yamlの設定は次のとおりです。

services:
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: app
POSTGRES_DB: app
ports:
- "${DB_PORT:-5432}:5432"
volumes:
- db-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d app"]
interval: 2s
timeout: 3s
retries: 15

volumes:
db-data:

postgres:16-alpineでDBを起動し、初期ユーザー・パスワード・DB名をappにします。portsがホストのDB_PORTからコンテナ内の5432へ接続を転送し、db-dataがDBファイルを保持します。停止してもボリュームは残るため、次回も同じデータを使えます。

healthcheck.testは接続準備の確認、intervalは確認間隔、timeoutは1回の期限、retriesは失敗回数です。make db-upはこの確認が成功するまで待ちます。ユーザーやDB名を変更するなら接続URLと確認コマンドも合わせます。ただし既存ボリュームのユーザー・パスワードは、この初期化用設定の変更だけでは更新されません。

DB接続数と待ち時間​

internal/infra/database/database.goでは、定数を次の呼び出しへ渡しています。

const (
maxOpenConns = 25
maxIdleConns = 25
connMaxLifetime = 5 * time.Minute
pingTimeout = 5 * time.Second
)
db.SetMaxOpenConns(maxOpenConns)
db.SetMaxIdleConns(maxIdleConns)
db.SetConnMaxLifetime(connMaxLifetime)
ctx, cancel := context.WithTimeout(ctx, pingTimeout)

maxOpenConnsは開く接続の上限、maxIdleConnsは再利用のため保持する待機接続の上限です。25同士なので、最大25接続を開き、使用後も最大25接続を残せます。前者の0は上限なし、後者の0は待機接続を残さない意味になるため、同じ0でも動作が違います。

connMaxLifetimeは接続を再利用する期間、pingTimeoutは起動時の疎通確認の期限です。期限内にDBへ接続できなければ、APIの起動を止めます。database/sqlの接続プールがこれらの値を使います。

HTTPの待ち時間と本文サイズ​

cmd/api/main.goは、HTTPサーバーと終了処理の期限を決めます。

const (
readHeaderTimeout = 5 * time.Second
readTimeout = 10 * time.Second
writeTimeout = 10 * time.Second
idleTimeout = 60 * time.Second
shutdownTimeout = 10 * time.Second
)
srv := &http.Server{
Addr: cfg.Addr,
Handler: handler.NewRouter(userHandler),
ReadHeaderTimeout: readHeaderTimeout,
ReadTimeout: readTimeout,
WriteTimeout: writeTimeout,
IdleTimeout: idleTimeout,
}
shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
defer cancel()

if err := srv.Shutdown(shutdownCtx); err != nil {
return fmt.Errorf("shutdown server: %w", err)
}

ヘッダー読み取りは5秒、本文を含む読み取りと応答書き込みは10秒、次のリクエストを待つ時間は60秒です。終了シグナルを受けたら最大10秒、処理中リクエストの終了を待ちます。無制限に接続を待たないための設定ですが、長時間処理を追加する場合はその処理に合わせて見直します。net/http.Serverの各期限に対応します。

internal/adapter/handler/json.goは、JSONの読み取り方法も決めています。

const maxBodyBytes = 1 << 20

func decodeJSON(c *gin.Context, dst any) error {
dec := json.NewDecoder(http.MaxBytesReader(c.Writer, c.Request.Body, maxBodyBytes))
dec.DisallowUnknownFields()

if err := dec.Decode(dst); err != nil {
return fmt.Errorf("%w: %w", errInvalidJSON, err)
}

return nil
}

1 << 20は1MiBです。MaxBytesReaderが読み取りを制限し、DisallowUnknownFieldsがDTOにない項目を拒否します。一方、最初のJSONの後に別のJSONが続くかは検査していません。

接続数25や各秒数について、負荷測定に基づく採用理由は配布元に記録されていません。ここでは具体的な動作を説明し、利用先に対する最適値とは扱いません。

setup:JSONに何を保存し、どこへ反映するか​

setupには、全設定を記録する台帳と、利用者の回答を保存するファイルがあります。全設定を台帳へ載せることと、毎回すべて質問することを分けています。

ファイル保存する内容作成・更新のタイミング
setup/settings.catalog.json設定の意味、型、参照先、重要度、分類理由、変更可否、未設定時の扱い配布側が管理する。利用者の秘密情報は保存しない
setup/coverage.json台帳に含むキーと設定ファイルの範囲配布側が管理する。checkが実ファイルからの抽出結果と照合する
setup-answers.json最終値、確認状態、開始時の値、ファイルのハッシュinitで利用者ごとに生成する。回答を記入して保存する
.env・Goソース・各設定ファイルAPIや開発ツールが実際に読む値applyで反映する。APIは回答JSONを直接読まない

台帳は318項目です。起動設定、Compose、DBプール、HTTP期限、lint、エディター、API検証先、バージョン、API・DB契約まで含めています。そのうち178項目はsetupから変更でき、140項目は初期設定では維持します。後者にはバージョン、依存方向の制約、権限、API・DB契約などがあり、単に台帳から除外するのではなく、変更できない理由を記録しています。新しい設定が実ファイルへ追加され、台帳にない場合はcheckが失敗します。未使用のOSS機能の全APIまでを対象にするものではありません。

最初に質問範囲を選びます。

選択質問する範囲
重要のみ / importantモジュール名、DB接続URLの2項目
重要+普通 / normal上記に待受・DBポート、同梱DBの初期資格情報、DB接続数を加えた9項目
すべて / advancedログ、HTTP期限、lint・エディター・API検証先を含む変更可能な178項目

「すべて」でも、変更不可の項目に回答を要求しません。細かな規約は関連項目をまとめて提示し、現在値を維持する選択もできます。範囲外の項目はretained(現在値を維持)と記録し、利用者が値を確認したconfirmedとは区別します。

回答してから適用する​

ZIP展開先で$setupを指定すると、.agents/skills/setup/SKILL.mdがこの手順を案内します。CLIだけで行う場合も同じ操作です。準備方法は次の「導入と使用」を先に実施してください。

python3 scripts/setup.py init --level important --out setup-answers.json
python3 scripts/setup.py list --answers setup-answers.json --group runtime

生成したJSONで、希望する設定値と、その値を確認した記録を変更します。次は2項目の抜粋です。他のキーと、開始時の値・ハッシュは残してください。

{
"databaseTarget": "local",
"settings": {
"module": "github.com/acme/user-api",
"DATABASE_URL": "postgres://app:app@localhost:5432/app?sslmode=disable"
},
"reviews": {
"module": {
"status": "confirmed",
"value": "github.com/acme/user-api"
},
"DATABASE_URL": {
"status": "confirmed",
"value": "postgres://app:app@localhost:5432/app?sslmode=disable"
}
}
}

databaseTargetは同梱DBならlocal、既存DBならexternalです。未回答では適用できません。既存DBではComposeとDB_PORTを、元の値と理由を添えたnot-applicable(非該当)として維持できます。

settingsとreviews.valueが一致しなければ、確認後に値が変わったものとして拒否します。未回答も拒否します。範囲外を変更したい場合は、その項目を追加で確認してconfirmedへ変えます。

python3 scripts/setup.py validate --answers setup-answers.json
python3 scripts/setup.py plan --answers setup-answers.json
python3 scripts/setup.py apply --answers setup-answers.json
python3 scripts/setup.py check

planは変更ファイルと設定値の差分を示します。DB接続URLとComposeのパスワードは画面に出しません。内容を確認してからapplyします。モジュール名はGoのimportとlintの自プロジェクト参照も連動して変え、ほかの設定は台帳の参照先へ反映します。変更したGoファイルはgofmtで整形します。

回答開始後に対象ファイルが手編集されていたら、古い回答を適用せず停止します。その場合は差分を確認し、現在値から別名の回答ファイルを作り直します。適用後の再設定もinitから始めます。途中の書き込み・整形に失敗した場合は変更済みファイルを復元しますが、プロセスの強制終了までの復元は保証しません。

setupは値の型、確認状態、対象範囲、接続数と整形幅の整合を検査します。各OSSの全設定組み合わせを保証するものではないため、適用後にはmake checkも必要です。DBの起動やマイグレーションはapplyの処理に含めません。既存DBへ接続する場合は、同梱DBの初期化設定を変更せず、そのDBの管理手順に従います。

導入と使用​

1. ZIPを展開して準備する​

以下はmacOSまたはLinuxのBash/zsh向けです。Go 1.27.1、DockerとCompose v2、Make、Bash、curl、Perl、Python 3(3.10以上、venv・pipが使えるもの)を用意します。Goの依存はgo.mod/go.sum、setupの依存はrequirements-setup.txtで固定しています。掲載サイトのNode.js環境は不要です。

ZIPを任意の作業場所へ展開し、go-clean/をプロジェクトとして開きます。以降はすべてそのディレクトリから実行します。

cd go-clean
go mod download
make tools
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements-setup.txt
python3 scripts/setup.py check

各準備が成功してから次へ進みます。Goの自動取得、固定ツールの導入、Python依存の導入には初回のネットワーク接続が必要です。Pythonの仮想環境はAPI本体と切り離し、PyYAML 6.0.3だけを導入します。別ターミナルでもsetupを使うときはsource .venv/bin/activateを実行してください。

2. 初期設定する​

$setup、または前述のCLIで設定を保存・適用します。最小構成を手動で試す場合だけ、代わりに次を実行します。setup適用済みならこのコピーは不要です。

make rename MODULE=github.com/acme/user-api
cp .env.example .env

setupが扱う.envは引用符なしのKEY=value形式です。コメントと未知のキーは保持します。特殊文字を含むパスワードは接続URL内でエンコードし、シェル展開式は使いません。

3. DBとAPIを起動する​

同梱の開発用DBを選んだ場合に実行します。

make db-up
make migrate-up
make run

DB準備・マイグレーションが失敗したらAPIを起動しません。APIは初期設定ではhttp://localhost:8080で応答します。外部の既存DBを選んだ場合はmake db-upを使わず、マイグレーションの要否もそのDBの管理者・管理手順に合わせます。

4. 作成して、返ったIDで取得する​

別ターミナルから次を実行します。待受ポートを変更した場合はURLも合わせます。

curl -i -X POST http://localhost:8080/users -H 'Content-Type: application/json' -d '{"name":" Taro ","email":"TARO@example.com"}'

成功すると201と次の形式のJSONが返ります。これは応答形式の例で、IDと作成日時は実行ごとに変わります。

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Taro",
"email": "taro@example.com",
"created_at": "2026-10-19T10:00:00Z"
}

返ったidを変数へ入れて取得します。

USER_ID='550e8400-e29b-41d4-a716-446655440000' # 実際に返ったIDへ置き換える
curl -i "http://localhost:8080/users/$USER_ID"

200で同じユーザーが返れば、保存と取得ができています。作成を同じメールで繰り返すと409になります。終了はAPIのターミナルでCtrl+C、その後make db-downです。DBの停止だけでは保存データは消えません。

制約と、利用先で必要な確認​

このサンプルには認証・認可がありません。app:app、TLS無効、ホストへ公開するDBポートはローカル開発用です。公開運用では資格情報・アクセス制限・TLSを整えます。回答JSONと.envには秘密情報が含まれ得るため、Git・ZIP・Issueへ含めません。

名前の50文字制限はdomain・DB・OpenAPIにありますが、メールの254文字上限はDB側だけです。長いメールがdomainの解析を通るとINSERTが失敗し、500になる可能性があります。名前の上限やエラーコードなどは公開API・DB契約と合わせる必要があるため、setupでは維持します。

JSONの読み取り上限・未知フィールド拒否は実装されていますが、末尾に別のJSONが続くかの検査はありません。OpenAPIも内部エラー500や実装上の全制限を網羅していないため、利用先でAPI契約を決める際に照合してください。

開発規約の設定を詳しく見る​

基本の流れを理解した後、必要な箇所だけ開いてください。ここでは、配布している設定を親キー付きで示し、どういう検査や整形へつながるかを説明します。個別の数値・全ルールの採用理由が配布元に記録されていない箇所は、現在のチーム規約として示し、一般的な最適値とは扱いません。

lintの標準セットと追加ルール
linters:
default: standard
linters:
enable:
- asciicheck # 識別子に ASCII 以外を使わない
- bodyclose # HTTP レスポンスの Body を閉じる
- canonicalheader # HTTP ヘッダー名を正規形で書く
- containedctx # 構造体に context を持たせない
- copyloopvar # 不要な v := v
- depguard # 依存方向(docs/architecture.md)
- dogsled # 捨てる戻り値(_)を並べすぎない
- dupl # 重複コード
- dupword # 同じ単語の連続
- durationcheck # Duration どうしを掛けない
- embeddedstructfieldcheck # 埋め込みフィールドの後に空行
- err113 # エラーは定義済みのものを返す
- errname # ErrXxx / XxxError の命名
- errorlint # %w ラップと errors.Is の徹底
- exhaustive # 列挙型の switch を網羅する
- fatcontext # ループ内で ctx を上書きし続けない
- forbidigo # fmt.Print / log.Print を禁止し slog に統一
- forcetypeassert # ok を受け取らない型アサーション
- funcorder # 型 → コンストラクタ → 公開 → 非公開の並び順
- gochecknoinits # init を使わず main で DI する
- gocognit # 関数の複雑さの上限
- goconst # 繰り返す文字列は定数に
- gocritic # 同じ意味の書き方を 1 つに揃える
- godox # TODO / FIXME を残さない
- gomoddirectives # go.mod の replace などを制限
- gomodguard_v2 # 外部モジュールは許可したものだけ
- gosec # セキュリティ
- gosmopolitan # 文字列リテラルは英語
- iface # interface の重複・未使用メソッド
- inamedparam # interface のメソッド引数に名前を付ける
- interfacebloat # interface のメソッド数の上限
- intrange # for i := range n
- iotamixing # iota の const ブロックに別の定数を混ぜない
- ireturn # コンストラクタは struct を返す
- lll # 行長の上限
- makezero # 長さ付き make に append しない
- mirror # 不要な []byte / string 変換
- misspell
- mnd # マジックナンバー
- modernize # 新しい言語機能・標準ライブラリで書く
- musttag # JSON にする構造体にタグを付ける
- nestif # if のネストを浅く
- nilerr # err を握りつぶさない
- nilnil # return nil, nil を書かない
- noctx # HTTP リクエストに context を渡す
- nolintlint # nolint に対象と理由を書く
- nonamedreturns # 名前付きの戻り値を使わない
- nosprintfhostport # host:port は net.JoinHostPort で組み立てる
- paralleltest # テストで t.Parallel() を呼ぶ
- perfsprint # 不要な fmt.Sprintf
- reassign # 他パッケージの変数を書き換えない
- recvcheck # レシーバをポインタか値に揃える
- revive # 命名と書き方の統一
- rowserrcheck # rows.Err() を確認する
- sloglint # log/slog の書き方
- sqlclosecheck # Rows / Stmt を閉じる
- tagalign # 構造体タグの順序と位置を揃える
- tagliatelle # JSON タグは snake_case
- testableexamples # Example に Output コメントを書く
- thelper # テストヘルパーで t.Helper() を呼ぶ
- tparallel # t.Parallel() の呼び方を揃える
- unconvert # 不要な型変換
- unqueryvet # SELECT * / N+1 / トランザクションの閉じ忘れ
- usestdlibvars # http.MethodGet などの定数を使う
- usetesting # テストでは t.Setenv / t.Context などを使う
- whitespace # ブロック先頭・末尾の不要な空行
- wrapcheck # 外部パッケージのエラーは包んで返す
- wsl_v5 # ブロックや return の前後の空行

default: standardが標準セット、enableが追加する検査です。depguardはimportの依存方向、forbidigoは使ってはいけない呼び出しを検査します。この2つはsetupで無効にできません。その他の追加ルールも、下表の意味を確認した上で調整し、make checkを実行します。

ルール何を検査するか
asciicheck識別子に ASCII 以外を使わない
bodycloseHTTP レスポンスの Body を閉じる
canonicalheaderHTTP ヘッダー名を正規形で書く
containedctx構造体に context を持たせない
copyloopvar不要な v := v
depguard依存方向(docs/architecture.md)
dogsled捨てる戻り値(_)を並べすぎない
dupl重複コード
dupword同じ単語の連続
durationcheckDuration どうしを掛けない
embeddedstructfieldcheck埋め込みフィールドの後に空行
err113エラーは定義済みのものを返す
errnameErrXxx / XxxError の命名
errorlint%w ラップと errors.Is の徹底
exhaustive列挙型の switch を網羅する
fatcontextループ内で ctx を上書きし続けない
forbidigofmt.Print / log.Print を禁止し slog に統一
forcetypeassertok を受け取らない型アサーション
funcorder型 → コンストラクタ → 公開 → 非公開の並び順
gochecknoinitsinit を使わず main で DI する
gocognit関数の複雑さの上限
goconst繰り返す文字列は定数に
gocritic同じ意味の書き方を 1 つに揃える
godox作業メモを残した箇所を検査する
gomoddirectivesgo.mod の replace などを制限
gomodguard_v2外部モジュールは許可したものだけ
gosecセキュリティ
gosmopolitan文字列リテラルは英語
ifaceinterface の重複・未使用メソッド
inamedparaminterface のメソッド引数に名前を付ける
interfacebloatinterface のメソッド数の上限
intrangefor i := range n
iotamixingiota の const ブロックに別の定数を混ぜない
ireturnコンストラクタは struct を返す
lll行長の上限
makezero長さ付き make に append しない
mirror不要な []byte / string 変換
misspell英語の綴りの揺れを検査する。
mndマジックナンバー
modernize新しい言語機能・標準ライブラリで書く
musttagJSON にする構造体にタグを付ける
nestifif のネストを浅く
nilerrerr を握りつぶさない
nilnilreturn nil, nil を書かない
noctxHTTP リクエストに context を渡す
nolintlintnolint に対象と理由を書く
nonamedreturns名前付きの戻り値を使わない
nosprintfhostporthost:port は net.JoinHostPort で組み立てる
paralleltestテストで t.Parallel() を呼ぶ
perfsprint不要な fmt.Sprintf
reassign他パッケージの変数を書き換えない
recvcheckレシーバをポインタか値に揃える
revive命名と書き方の統一
rowserrcheckrows.Err() を確認する
sloglintlog/slog の書き方
sqlclosecheckRows / Stmt を閉じる
tagalign構造体タグの順序と位置を揃える
tagliatelleJSON タグは snake_case
testableexamplesExample に Output コメントを書く
thelperテストヘルパーで t.Helper() を呼ぶ
tparallelt.Parallel() の呼び方を揃える
unconvert不要な型変換
unqueryvetSELECT * / N+1 / トランザクションの閉じ忘れ
usestdlibvarshttp.MethodGet などの定数を使う
usetestingテストでは t.Setenv / t.Context などを使う
whitespaceブロック先頭・末尾の不要な空行
wrapcheck外部パッケージのエラーは包んで返す
wsl_v5ブロックや return の前後の空行
lintの個別設定:depguard

.golangci.ymlの該当箇所です。

linters:
settings:
depguard:
rules:
domain:
list-mode: strict
files:
- "**/internal/domain/**"
allow:
- $gostd
- example.com/go-clean/internal/domain
deny:
- pkg: database/sql
desc: "domain は永続化を知らない"
- pkg: net/http
desc: "domain は HTTP を知らない"

usecase:
list-mode: strict
files:
- "**/internal/usecase/**"
allow:
- $gostd
- example.com/go-clean/internal/domain
- example.com/go-clean/internal/usecase
deny:
- pkg: database/sql
desc: "usecase は port(interface) 経由で永続化する"
- pkg: net/http
desc: "usecase は HTTP を知らない"

nolog:
list-mode: lax
files:
- "**/internal/domain/**"
- "**/internal/usecase/**"
- "**/internal/adapter/**"
- "!**/internal/adapter/handler/**"
deny:
- pkg: log/slog
desc: "ログは handler の writeError でだけ出す。エラーは %w で包んで返す"

nodir:
list-mode: lax
files:
- $all
deny:
- pkg: example.com/go-clean/pkg
desc: "pkg/ ディレクトリを作らない。置き場所は層で決める"
- pkg: example.com/go-clean/internal/helper
desc: "helper パッケージを作らない。置き場所は層で決める"
- pkg: example.com/go-clean/internal/shared
desc: "shared パッケージを作らない。置き場所は層で決める"

adapter:
list-mode: lax
files:
- "**/internal/adapter/**"
deny:
- pkg: example.com/go-clean/internal/adapter
desc: "adapter 同士は依存しない(つなぐのは cmd の DI)"
- pkg: example.com/go-clean/internal/infra
desc: "adapter は infra に依存しない(必要なものは cmd から注入で受け取る)"

handler:
list-mode: lax
files:
- "**/internal/adapter/handler/**"
deny:
- pkg: database/sql
desc: "handler は DB を直接触らない"

repository:
list-mode: lax
files:
- "**/internal/adapter/repository/**"
deny:
- pkg: net/http
desc: "repository は HTTP を知らない"
- pkg: github.com/gin-gonic/gin
desc: "repository は HTTP を知らない"

infra:
list-mode: lax
files:
- "**/internal/infra/**"
deny:
- pkg: example.com/go-clean/internal/domain
desc: "infra は技術的な土台のみ。ビジネスロジックに依存しない"
- pkg: example.com/go-clean/internal/usecase
desc: "infra は技術的な土台のみ。ビジネスロジックに依存しない"
- pkg: example.com/go-clean/internal/adapter
desc: "infra は adapter に依存しない"

filesが対象ファイル、allow/denyが許可・禁止するimport。list-modeが判定方式を決め、descが違反時の説明になる。

domainとusecaseは標準ライブラリを許可しつつ、SQL・HTTPを明示的に禁止します。adapter同士、adapterからinfra、infraから業務層へのimportも別ルールで禁止します。nologは内側のログを制限し、nodirは曖昧な共通パッケージを増やさないための規約です。モジュール名を変えると、allow/deny内の自プロジェクト参照は連動して変わります。

lintの個別設定:copyloopvar

.golangci.ymlの該当箇所です。

linters:
settings:
copyloopvar:
check-alias: true

check-aliasはループ変数を別名に写した場合も不要なコピーとして調べる。

lintの個別設定:dupl

.golangci.ymlの該当箇所です。

linters:
settings:
dupl:
threshold: 75

thresholdは重複コードとして報告するトークン数の境界。小さいほど短い重複も拾う。

lintの個別設定:embeddedstructfieldcheck

.golangci.ymlの該当箇所です。

linters:
settings:
embeddedstructfieldcheck:
empty-line: true

empty-lineは埋め込みフィールドと通常フィールドの間の空行を要求する。

lintの個別設定:errcheck

.golangci.ymlの該当箇所です。

linters:
settings:
errcheck:
check-blank: true # _ に代入して捨てるエラーも検出する

check-blankはエラーを_に代入して捨てた場合も検査する。

lintの個別設定:exhaustive

.golangci.ymlの該当箇所です。

linters:
settings:
exhaustive:
check:
- switch
- map
default-signifies-exhaustive: true

checkでswitch/mapを対象にし、default-signifies-exhaustiveでdefault節を網羅済みと扱う。

lintの個別設定:forbidigo

.golangci.ymlの該当箇所です。

linters:
settings:
forbidigo:
analyze-types: true # 型で判定する(r.db が *sql.DB かどうか)
forbid:
- pattern: ^fmt\.Print.*$
msg: ログは log/slog を使う
- pattern: ^log\.(Print|Fatal|Panic).*$
msg: ログは log/slog を使う
- pattern: ^print(ln)?$
msg: ログは log/slog を使う
- pattern: ^sql\.DB\.(Exec|Query|QueryRow)Context$
msg: repository は conn(ctx, r.db) 経由で DB にアクセスする(トランザクションに自動で参加するため)
- pattern: ^gin\.H$
msg: レスポンスは dto.go の構造体で返す
- pattern: ^gin\.Context\.(Bind|ShouldBind|MustBind)\w*$
msg: リクエストの JSON は decodeJSON で読む(未知のフィールドの拒否とサイズの上限のため)
- pattern: ^gin\.Default$
msg: gin.New を使う(ログとパニック回復は自前のミドルウェアで行う)
- pattern: ^time\.Now$
msg: 現在時刻は usecase の now フィールドから受け取る
- pattern: ^context\.(Background|TODO)$
msg: 呼び出し元から受け取った ctx を使う
- pattern: ^os\.(Getenv|LookupEnv|Environ)$
msg: 環境変数は infra/config でだけ読む
- pattern: ^sql\.Open$
msg: DB 接続は infra/database でだけ作る
- pattern: ^http\.DefaultClient$
msg: http.Client は cmd で作ってコンストラクタで受け取る
- pattern: ^usecase\.New\w+$
msg: usecase の生成(DI)は cmd/api/main.go でだけ行う
- pattern: ^user\.User$ # 集約を足したら、そのエンティティのパターンと exclusions の 1 行を足す
msg: 他の集約は ID だけで参照する(user.User)
- pattern: ^usecase\.\w+Usecase\.[A-Z]\w*$ # XxxUsecase のメソッド呼び出し(フィールドは小文字なので対象外)
msg: usecase から他の usecase を呼ばない。必要なデータは port から取り、共通の処理は domain へ寄せる

patternに一致する呼び出しを禁止し、msgを診断に出す。analyze-typesは同名の関数を型で区別する。

lintの個別設定:funcorder

.golangci.ymlの該当箇所です。

linters:
settings:
funcorder:
function: true # 公開関数を非公開関数より前に置く

functionは公開関数を非公開関数より前へ置く並び順の検査を有効にする。

lintの個別設定:gocognit

.golangci.ymlの該当箇所です。

linters:
settings:
gocognit:
min-complexity: 15

min-complexity以上の認知的複雑度を持つ関数を報告する。深い分岐を分割する目安になる。

lintの個別設定:gocritic

.golangci.ymlの該当箇所です。

linters:
settings:
gocritic:
enabled-tags:
- style
- diagnostic
enabled-checks: # performance タグのうち、読みやすさも上がるもの
- appendCombine
- equalFold
- preferFprint
disabled-checks:
- unnamedResult # nonamedreturns と逆のルールなので無効にする
- sloppyReassign # defer で参照する名前付き err を := で隠してしまう

enabled-tagsとenabled-checksで採用する指摘、disabled-checksで重複・矛盾する指摘を指定する。

lintの個別設定:godox

.golangci.ymlの該当箇所です。

linters:
settings:
godox:
keywords:
- TODO
- BUG
- FIXME
- HACK
- XXX

keywordsに挙げた作業メモをコードに残すと報告する。未完了の修正を持ち込まないための設定。

lintの個別設定:gomoddirectives

.golangci.ymlの該当箇所です。

linters:
settings:
gomoddirectives:
go-debug-forbidden: true
toolchain-forbidden: true # Go のバージョンは go ディレクティブだけで決める
tool-forbidden: true # ツールは Makefile で固定する

go.modに許可しないディレクティブを指定する。ツールやGo版を複数箇所で管理しないために使う。

lintの個別設定:gomodguard_v2

.golangci.ymlの該当箇所です。

linters:
settings:
gomodguard_v2:
allowed:
- module: github.com/jackc/pgx/v5
- module: github.com/gin-gonic/gin

allowedは直接依存として採用する外部モジュールの一覧。他のモジュール追加をレビュー対象にする。

lintの個別設定:govet

.golangci.ymlの該当箇所です。

linters:
settings:
govet:
enable-all: true
disable:
- fieldalignment

enable-allですべての解析を有効にし、disableでこのテンプレートに採用しない解析を除外する。

lintの個別設定:iface

.golangci.ymlの該当箇所です。

linters:
settings:
iface:
enable:
- identical
- unused
- unusedmethod

enableは同形interface、未使用interface、未使用メソッドの検査を選ぶ。

lintの個別設定:ireturn

.golangci.ymlの該当箇所です。

linters:
settings:
ireturn:
allow:
- error
- empty
- stdlib

allowはinterfaceを返してよい型の分類。errorや標準ライブラリのinterface等を例外にする。

lintの個別設定:lll

.golangci.ymlの該当箇所です。

linters:
settings:
lll:
line-length: 120
tab-width: 4 # golines の tab-len と揃える

line-lengthは行長の上限、tab-widthはタブを何文字と数えるか。golinesの整形とそろえる。

lintの個別設定:misspell

.golangci.ymlの該当箇所です。

linters:
settings:
misspell:
locale: US

localeは綴りの基準。USでは米国英語へそろえる。

lintの個別設定:nestif

.golangci.ymlの該当箇所です。

linters:
settings:
nestif:
min-complexity: 4

min-complexity以上の入れ子になったifを報告し、分岐の分割を促す。

lintの個別設定:nilnil

.golangci.ymlの該当箇所です。

linters:
settings:
nilnil:
detect-opposite: true # エラーと一緒に有効な値を返さない

detect-oppositeはnilと有効値の組み合わせに加え、値とエラーを同時に返す逆の組み合わせも検査する。

lintの個別設定:nolintlint

.golangci.ymlの該当箇所です。

linters:
settings:
nolintlint:
allow-unused: false
require-explanation: true
require-specific: true

allow-unusedは不要な抑制、require-explanationは理由、require-specificは対象linterの指定を検査する。

lintの個別設定:perfsprint

.golangci.ymlの該当箇所です。

linters:
settings:
perfsprint:
err-error: true

err-errorはfmt.Sprintfでエラーを文字列化する箇所も簡潔な書き方にできるか調べる。

lintの個別設定:reassign

.golangci.ymlの該当箇所です。

linters:
settings:
reassign:
patterns:
- ".*"

patternsに一致する他パッケージの変数への再代入を報告する。.*は全名を対象にする。

lintの個別設定:revive

.golangci.ymlの該当箇所です。

linters:
settings:
revive:
rules:
- name: argument-limit
arguments:
- 5
- name: blank-imports
- name: bool-literal-in-expr
- name: call-to-gc
- name: confusing-naming
- name: context-as-argument
- name: deep-exit
- name: defer
- name: early-return
arguments:
- allow-jump
- name: empty-block
- name: enforce-map-style
arguments:
- literal
- name: enforce-slice-style
arguments:
- literal
- name: error-return
- name: exported
arguments:
- check-private-receivers
- name: filename-format
arguments:
- "^[_a-z][_a-z0-9]*\\.go$"
- name: forbidden-call-in-wg-go
- name: function-result-limit
arguments:
- 3
- name: get-return
- name: identical-ifelseif-branches
- name: identical-ifelseif-conditions
- name: identical-switch-branches
- name: identical-switch-conditions
- name: if-return
- name: import-alias-naming
- name: increment-decrement
- name: indent-error-flow
- name: inefficient-map-lookup
- name: marshal-receiver
- name: modifies-value-receiver
- name: multiline-if-init
- name: nested-structs
- name: package-directory-mismatch
- name: package-naming
- name: receiver-naming
arguments:
- max-length: 2
- name: redundant-import-alias
- name: redundant-test-main-exit
- name: struct-tag
- name: superfluous-else
- name: time-date
- name: time-equal
- name: time-naming
- name: unconditional-recursion
- name: unexported-naming
- name: unexported-return
- name: unnecessary-if
- name: unnecessary-stmt
- name: unsecure-url-scheme
- name: unused-parameter
- name: unused-receiver
- name: use-any
- name: use-slices-concat
- name: use-slices-sort
- name: useless-fallthrough
- name: var-declaration
- name: var-naming

rulesのnameで検査を選び、argumentsでその検査の許容範囲を指定する。ルール名と引数は対で扱う。

引数を持つルールでは、argument-limitの5が引数数、function-result-limitの3が戻り値数、receiver-namingの2がレシーバ名の長さの上限です。filename-formatはファイル名の正規表現です。exportedは非公開レシーバの公開メソッドもコメント検査へ含め、early-returnのallow-jumpはジャンプ文で分岐を抜ける形を許します。残りのnameは、このテンプレートが採用する命名・不要処理・誤用の検査を選びます。

lintの個別設定:sloglint

.golangci.ymlの該当箇所です。

linters:
settings:
sloglint:
kv-only: true
key-naming-case: snake
static-msg: true
context: scope
forbidden-keys:
- time
- level
- msg
- source
msg-style: lowercased

構造化ログのキーと値の書式を統一する。kv-onlyはキー値形式、contextはcontextがある範囲での使用、forbidden-keysは標準フィールドとの衝突防止。

key-naming-caseのsnakeはキーをsnake_caseへそろえ、static-msgはメッセージを固定文字列にします。msg-styleのlowercasedはメッセージを小文字始まりに統一します。ログ標準のtime/level/msg/sourceを任意キーとして上書きしません。

lintの個別設定:staticcheck

.golangci.ymlの該当箇所です。

linters:
settings:
staticcheck:
checks:
- all # v1 の staticcheck / stylecheck / gosimple を含む
- -ST1000 # パッケージコメントは必須にしない

checksで解析セットを指定する。allを使い、-ST1000だけ除いてパッケージコメントを必須にしない。

lintの個別設定:tagliatelle

.golangci.ymlの該当箇所です。

linters:
settings:
tagliatelle:
case:
rules:
json: snake
use-field-name: true # タグ名をフィールド名の snake_case と一致させる

case.rules.jsonはJSONタグの命名、use-field-nameはGoフィールド名との対応を検査する。snakeはsnake_case。

lintの個別設定:unqueryvet

.golangci.ymlの該当箇所です。

linters:
settings:
unqueryvet:
check-n1: true
check-tx-leaks: true

check-n1はN+1の疑い、check-tx-leaksはトランザクションの閉じ忘れを検査する。

lintの個別設定:unused

.golangci.ymlの該当箇所です。

linters:
settings:
unused:
field-writes-are-uses: false # 書き込むだけのフィールドも未使用とみなす

field-writes-are-usesは書き込むだけのフィールドを使用済みと数えるかを決める。falseでは未使用のまま扱う。

lintの個別設定:usestdlibvars

.golangci.ymlの該当箇所です。

linters:
settings:
usestdlibvars:
time-month: true
time-layout: true
crypto-hash: true
default-rpc-path: true
sql-isolation-level: true
tls-signature-scheme: true
constant-kind: true
time-date-month: true

各項目は曜日・時刻書式・暗号方式・HTTP等の定数を標準ライブラリの名前へそろえる検査を選ぶ。

time-month/time-date-monthは月、time-layoutは時刻書式、crypto-hashはハッシュ、default-rpc-pathはRPCの既定パス、sql-isolation-levelは分離レベル、tls-signature-schemeはTLS署名方式、constant-kindは定数の種類について名前付き定数の利用を促します。

lintの個別設定:usetesting

.golangci.ymlの該当箇所です。

linters:
settings:
usetesting:
context-background: true
context-todo: true
os-temp-dir: true

各項目はテストのcontextや一時領域にtestingパッケージのAPIを使う検査を選ぶ。

lintの個別設定:wrapcheck

.golangci.ymlの該当箇所です。

linters:
settings:
wrapcheck:
ignore-package-globs:
- example.com/go-clean/*

ignore-package-globsに一致する自プロジェクトのエラーは再ラップを要求せず、外部境界のエラーへ文脈を加える。

lintの個別設定:wsl_v5

.golangci.ymlの該当箇所です。

linters:
settings:
wsl_v5:
allow-first-in-block: true
allow-whole-block: false
branch-max-lines: 2
case-max-lines: 3 # 4 行以上の case の後に空行
enable:
- assign-expr # 式の直後に代入を詰めない

空行を置く条件と許す省略を指定する。行数しきい値は短い分岐と長い分岐を区別する。

allow-first-in-blockはブロック先頭の密着を許し、allow-whole-blockはブロック全体の空行省略を許すかを決めます。branch-max-linesとcase-max-linesは、分岐やcaseの後に空行を要求する境界です。assign-exprは式の直後へ代入を詰める書き方を検査します。

lintから除外する条件
linters:
exclusions:
generated: lax
# comments プリセットは使わない(公開識別子のドキュメントコメントを必須にするため)
presets:
- common-false-positives
- legacy
- std-error-handling
rules:
- path: _test\.go
linters:
- dupl
- err113
- forbidigo # Example テストでは fmt.Println を使う
- goconst
- gosmopolitan # テストのケース名は日本語で書く
- path-except: internal/adapter/repository/ # conn 経由のルールは repository だけに適用する
linters:
- forbidigo
text: conn\(ctx, r\.db\)
- path: internal/adapter/repository/tx\.go # パニック中のロールバック失敗は返す先がないのでログに残す
linters: [depguard]
text: ログは handler の writeError
- path-except: internal/(domain|usecase|adapter/repository)/
linters: [forbidigo]
text: 現在時刻は usecase の now
- path: internal/usecase/
linters: [forbidigo]
text: 現在時刻は usecase の now
source: 'now:\s+time\.Now' # コンストラクタで now の既定値を入れる行だけは許す
- path: cmd/
linters: [forbidigo]
text: 呼び出し元から受け取った ctx|http\.Client は cmd|usecase の生成
- path: internal/infra/config/
linters: [forbidigo]
text: 環境変数は infra/config
- path: internal/infra/database/
linters: [forbidigo]
text: DB 接続は infra/database
- path-except: internal/domain/ # 他の集約の参照は domain だけで止める
linters: [forbidigo]
text: 他の集約は ID だけで参照する
- path: internal/domain/user/ # 自分の集約のエンティティは使ってよい
linters: [forbidigo]
text: ID だけで参照する(user\.User)
- path-except: internal/usecase/ # usecase を呼ばないルールは usecase の中だけに適用する
linters:
- forbidigo
text: usecase から他の usecase を呼ばない
paths:
- third_party$
- builtin$
- examples$

generated: laxは生成コードの扱い、presetsは既知の誤検出への対処です。commentsのpresetは使わず、公開識別子のコメント検査を残しています。

rulesでは、テストの重複・日本語名・例示出力を許す例外、repositoryにだけ適用するconn経由のDBアクセス制限、panic中のrollback失敗だけログを許す例外、時刻・context・環境変数・DIを各担当層で使う例外を指定します。他集約のエンティティ参照はdomain内で検査し、自集約は除きます。pathは含める場所、path-exceptはそれ以外、lintersは対象検査、textは診断、sourceは対象コードを絞ります。これらを組み合わせるので、例外は全体の検査停止にはなりません。

pathsは第三者コードやサンプルを対象外にするパターンです。依存方向と例外の範囲は設計規約なのでsetupでは維持し、変更する場合はコードと一緒にレビューします。

整形器と、行長・import順の設定
formatters:
enable:
- gofmt # rewrite-rules による書き換えだけに使う
- gofumpt # gofmt より厳しい整形
- goimports
- golines # 長い行の自動折り返し
settings:
gofmt:
rewrite-rules:
- pattern: interface{}
replacement: any
- pattern: a[b:len(a)]
replacement: a[b:]
gofumpt:
extra:
group-params: true # 同じ型が続く引数をまとめる
goimports:
local-prefixes:
- example.com/go-clean
golines:
max-len: 120
tab-len: 4
exclusions:
generated: lax
paths:
- third_party$
- builtin$
- examples$

enableのgofmtは書き換え規則、gofumptは基本書式、goimportsはimportの整理、golinesは長い行の折り返しを担当します。gofmtのrewrite-rulesはinterface{}をanyへ、末尾までのスライスを簡潔な形へそろえます。gofumptのgroup-paramsは同型引数をまとめます。

goimportsのlocal-prefixesは自プロジェクトのimportをまとめる指定です。モジュール名の変更時にはこの参照も同期します。golinesのmax-len/tab-lenはlllのline-length/tab-widthと同じ値にし、整形した結果が直後のlintで違反にならないようにします。exclusionsは生成コードと対象外パスです。

VS Code・EditorConfig・エージェントの設定

.vscode/settings.json

{
"go.lintTool": "golangci-lint-v2",
"go.lintOnSave": "package",
"go.formatTool": "custom",
"go.formatFlags": ["fmt", "--stdin"],
"go.alternateTools": {
"golangci-lint-v2": "${workspaceFolder}/bin/golangci-lint-v2.14.0",
"customFormatter": "${workspaceFolder}/bin/golangci-lint-v2.14.0"
},
"[go]": {
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.organizeImports": "never"
}
},
"files.eol": "\n",
"files.insertFinalNewline": true
}

lintToolとalternateToolsでプロジェクト内の固定版を使います。lintOnSaveは保存したパッケージを検査し、formatTool/formatFlagsは同じ固定版のfmtへ標準入力を渡します。formatOnSaveは保存時整形、organizeImportsのneverは別処理でimport整理を二重に行わない指定です。files.eolとinsertFinalNewlineは改行を統一します。

.vscode/extensions.json

{
"recommendations": ["golang.go", "editorconfig.editorconfig"]
}

Goの言語支援とEditorConfigの拡張を推奨として表示します。APIの依存でも、自動インストールの指定でもありません。

.editorconfig

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.go]
indent_style = tab
indent_size = 4

[Makefile]
indent_style = tab

[*.sql]
indent_size = 4

[*.md]
trim_trailing_whitespace = false

root=trueで上位の設定探索を止め、基本はUTF-8・LF・末尾改行・末尾空白除去・2スペースです。GoとMakefileはタブ、SQLは4スペースへ分けます。Markdownだけは末尾空白を保持し、明示改行の書式を壊さないようにします。

.claude/settings.json

{
"permissions": {
"allow": [
"Bash(make check)",
"Bash(make test)",
"Bash(make lint)",
"Bash(make fmt)",
"Bash(make build)",
"Bash(make tools)",
"Bash(make help)",
"Bash(make migrate-new:*)",
"Bash(go build:*)",
"Bash(go vet:*)",
"Bash(go test:*)"
],
"deny": [
"Bash(golangci-lint:*)",
"Bash(go get:*)",
"Bash(go mod edit -go:*)",
"Read(./.env)",
"Read(./.env.*)"
]
}
}

allowは固定ツール経由のビルド・テスト等の操作、denyはグローバルlint・依存更新・Go版の単独変更・.env読取の制限です。エージェント権限は初期設定で増やさないため、setupではこの設定を維持します。Codex向けsetup本体は別の.agents/skills/setup/SKILL.mdです。

Go・開発ツール・API/DB契約の固定範囲

go.modの直接依存とGoバージョンです。間接依存も同じファイル、ダウンロードの検証情報はgo.sumにあります。

module example.com/go-clean

go 1.27.1

require (
github.com/gin-gonic/gin v1.12.0
github.com/jackc/pgx/v5 v5.7.2
)

Makefileの固定値です。

-include .env
export

MIGRATIONS_DIR := db/migrations

# golangci-lint はプロジェクトの bin/ に固定バージョンで入れる(他のプロジェクトに影響させない)
GOLANGCI_LINT_VERSION := v2.14.0
GOLANGCI_LINT := $(CURDIR)/bin/golangci-lint-$(GOLANGCI_LINT_VERSION)

# golang-migrate も同じく bin/ に固定バージョンで入れる(postgres ドライバ付きでビルドする)
MIGRATE_VERSION := v4.20.1
MIGRATE := $(CURDIR)/bin/migrate-$(MIGRATE_VERSION)

Go 1.27.1に合わせ、ginはhandler、pgxはDB接続で使います。golangci-lintとmigrateは指定版をプロジェクトのbinへ導入し、他プロジェクトのグローバル版へ依存しません。Goの自動取得はツールチェーン選択によります。

MIGRATIONS_DIRはSQLを置く場所です。APIの公開形式はapi/openapi.yaml、保存形式はdb/migrations/です。これらと名前の上限・エラーコードは台帳に含めますが、変更するならdomain、handler、repository、OpenAPI、migrationをそろえる必要があるためsetupでは維持します。

検証方法と結果​

ZIPを別の場所へ展開し、READMEの準備に成功してから次を実行します。本物の文書・設定に異常例を追加せず、setupのテストは一時コピーで行います。

make test-setup
make check
make test
make check-deps

make test-setupは、質問範囲の選択、範囲外の設定維持、未回答・未確認変更・古い回答の拒否、実ファイルへの反映、再適用、失敗時復元、台帳にない項目の検出を確認します。make checkはbuild・vet・単体テスト・lint、make testはrace検出付きのテストです。make check-depsは一時コピーに禁止importを追加し、depguardが実際に拒否することを確認します。

同梱DBとAPIの起動に成功したら、別ターミナルで次を実行します。専用の検証用DBでユーザーを1件作成するので、運用DBでは行いません。

API_BASE_URL=http://127.0.0.1:8080 make smoke

healthz、作成・取得、名前とメールの正規化、重複409、入力不正400、未知フィールド400、不正ID400、未登録ID404を確認します。全検査成功時はAPI smoke: ... passed、失敗時は非0で終了します。

確認日:2026年10月19日。環境:macOS arm64、Go 1.27.1、Docker Engine 28.4.0 / Compose 2.40.0、PostgreSQL 16、Python 3 / PyYAML 6.0.3。検証結果は次のとおりです。

対象期待結果実際の結果
設定台帳・setup全対象の照合、設定反映、未確認変更の拒否、失敗時復元318項目を照合。15テスト成功。初期状態と設定変更済みのZIPの両方で確認
ZIP単体のGo検証build・vet・テスト・lintとrace検出が成功モジュール名・接続数・待ち時間・lint等を変更後、すべて成功。lintは0 issues。禁止importの検出も成功
DBとAPI設定変更後も作成・取得と各エラー応答が一致DBの資格情報・DB名・公開ポートとAPIポートを変更して成功。READMEの作成・取得例、マイグレーションの巻き戻し・再適用も成功
サイト・ZIP説明の表示、検索、取得、必要ファイルの収録共通テスト45件・E2E 6件成功。実ページで導線・折りたたみ・検索・PC/モバイル表示・ZIP内容を確認

CIはci.jsonに指定したbash scripts/verify-ci.shをZIP展開先で実行します。依存導入、設定確認、Goテスト、DB・API確認をこのスクリプトにまとめ、パターンごとのジョブは共通ワークフローに追加しません。2026-10-19、macOS上でこの入口からの一括検証も成功し、API・検証DB・ボリュームの終了と削除を確認しました。Ubuntu上の検証は共通CIで実行し、最新の実行結果はGitHub Actionsで確認します。人間による説明・成果物確認、同時実行時の競合、DB障害、公開運用は未確認です。自動テストの成功とは分けて扱います。

参考資料​

ダウンロード​

実装をダウンロード