02 · 依存方向と責任
| 場所 | 責任 | 依存・境界 |
|---|
| cmd/api | 設定読込、loggerとDB生成、全DI、HTTP起動・終了 | handler / repository / usecase / infra を組み立てる |
| internal/adapter/handler | HTTPをusecase入力に変換し、出力をJSON DTOへ変換 | gin / net/http。handler内の userUsecase interface を使う |
| internal/usecase | Create / Get の業務手順と入出力型 | domain と標準ライブラリ。永続化・Txはport経由 |
| internal/domain/user | User / ID / Email の生成、検証、復元、ドメインエラー | 標準ライブラリのみ。非公開フィールド、JSON / DBタグなし |
| internal/adapter/repository | usecaseのport実装、SQL、DBエラー変換、Userの復元 | usecase / domain / database/sql / pgconn。infraへのimportなし |
| internal/infra | 環境設定・接続プール・構造化logger | 技術基盤。ビジネス層へ依存しない |
internal/usecase/port.go · 9行目
元ファイルを開く
9 // usecase が必要とする外部依存(port)。実装は adapter 層が持つ。
10
11 // UserRepository はユーザーの永続化を担う port。
12 type UserRepository interface {
13 Create(ctx context.Context, u *user.User) error
14 FindByID(ctx context.Context, id user.ID) (*user.User, error) // 見つからない場合は user.ErrNotFound
15 ExistsByEmail(ctx context.Context, email user.Email) (bool, error)
16 }
17
18 // TxManager は fn を1トランザクション内で実行する。fn が error を返すとロールバックする。
19 type TxManager interface {
20 Do(ctx context.Context, fn func(ctx context.Context) error) error
21 }
internal/adapter/handler/user.go · 13行目
元ファイルを開く
13 type userUsecase interface {
14 Create(ctx context.Context, in usecase.CreateUserInput) (*usecase.UserOutput, error)
15 Get(ctx context.Context, in usecase.GetUserInput) (*usecase.UserOutput, error)
16 }
17
18 // UserHandler はユーザー API のハンドラ。
19 type UserHandler struct {
20 users userUsecase
21 }
22
23 // NewUserHandler は UserHandler を生成する。
24 func NewUserHandler(users userUsecase) *UserHandler {
25 return &UserHandler{users: users}
26 }
internal/adapter/repository/user.go · 10行目
元ファイルを開く
10 "example.com/go-clean/internal/domain/user"
11 "example.com/go-clean/internal/usecase"
12 )
13
14 var _ usecase.UserRepository = (*UserRepository)(nil)
15
16 // UserRepository は usecase.UserRepository の PostgreSQL 実装。
17 type UserRepository struct {
18 db *sql.DB
19 }
20
21 // NewUserRepository は UserRepository を生成する。
22 func NewUserRepository(db *sql.DB) *UserRepository {
23 return &UserRepository{db: db}
24 }
.golangci.yml · 94行目
元ファイルを開く
94 list-mode: strict
95 files:
96 - "**/internal/usecase/**"
97 allow:
98 - $gostd
99 - example.com/go-clean/internal/domain
100 - example.com/go-clean/internal/usecase
101 deny:
102 - pkg: database/sql
103 desc: "usecase は port(interface) 経由で永続化する"
104 - pkg: net/http
105 desc: "usecase は HTTP を知らない"
106
107 nolog:
108 list-mode: lax
109 files:
110 - "**/internal/domain/**"
111 - "**/internal/usecase/**"
112 - "**/internal/adapter/**"
113 - "!**/internal/adapter/handler/**"
114 deny:
115 - pkg: log/slog
116 desc: "ログは handler の writeError でだけ出す。エラーは %w で包んで返す"
117
118 nodir:
119 list-mode: lax
120 files:
121 - $all
122 deny:
123 - pkg: example.com/go-clean/pkg
124 desc: "pkg/ ディレクトリを作らない。置き場所は層で決める"
125 - pkg: example.com/go-clean/internal/helper
126 desc: "helper パッケージを作らない。置き場所は層で決める"
127 - pkg: example.com/go-clean/internal/shared
128 desc: "shared パッケージを作らない。置き場所は層で決める"
129
130 adapter:
131 list-mode: lax
132 files:
133 - "**/internal/adapter/**"
134 deny:
135 - pkg: example.com/go-clean/internal/adapter
136 desc: "adapter 同士は依存しない(つなぐのは cmd の DI)"
137 - pkg: example.com/go-clean/internal/infra
138 desc: "adapter は infra に依存しない(必要なものは cmd から注入で受け取る)"
139
140 handler:
141 list-mode: lax
142 files:
143 - "**/internal/adapter/handler/**"
144 deny:
145 - pkg: database/sql
146 desc: "handler は DB を直接触らない"
147
148 repository:
149 list-mode: lax
150 files:
151 - "**/internal/adapter/repository/**"
152 deny:
153 - pkg: net/http
154 desc: "repository は HTTP を知らない"
155 - pkg: github.com/gin-gonic/gin
156 desc: "repository は HTTP を知らない"
157
158 infra:
159 list-mode: lax
160 files:
161 - "**/internal/infra/**"
162 deny:
163 - pkg: example.com/go-clean/internal/domain
164 desc: "infra は技術的な土台のみ。ビジネスロジックに依存しない"
165 - pkg: example.com/go-clean/internal/usecase
166 desc: "infra は技術的な土台のみ。ビジネスロジックに依存しない"
167 - pkg: example.com/go-clean/internal/adapter
168 desc: "infra は adapter に依存しない"
169
170 copyloopvar:
171 check-alias: true
172
173 dupl:
174 threshold: 75
175
176 embeddedstructfieldcheck:
177 empty-line: true
178
179 errcheck:
180 check-blank: true # _ に代入して捨てるエラーも検出する
181
182 exhaustive:
183 check:
184 - switch
185 - map
186 default-signifies-exhaustive: true
187
188 forbidigo:
189 analyze-types: true # 型で判定する(r.db が *sql.DB かどうか)
190 forbid:
191 - pattern: ^fmt\.Print.*$
192 msg: ログは log/slog を使う
193 - pattern: ^log\.(Print|Fatal|Panic).*$
194 msg: ログは log/slog を使う
195 - pattern: ^print(ln)?$
196 msg: ログは log/slog を使う
197 - pattern: ^sql\.DB\.(Exec|Query|QueryRow)Context$
198 msg: repository は conn(ctx, r.db) 経由で DB にアクセスする(トランザクションに自動で参加するため)
199 - pattern: ^gin\.H$
200 msg: レスポンスは dto.go の構造体で返す
03 · POST /users:作成から応答まで
- recoverPanic と logRequest を通り、UserHandler.Create がJSONをdecodeJSONで読みます。ボディ上限は1 MiBで、未知フィールドを拒否します。
- Name / Email を CreateUserInput に詰め替え、リクエストの context を usecase へ渡します。
- NewEmail が構文を検証し小文字化します。User.New は名前をTrimSpaceし、1〜50文字を検証してUUIDと作成日時を設定します。この時点ではTxを開始していません。
- TxManager.Do がTxを開始し、そのTxを含む context で ExistsByEmail を実行します。重複なら ErrEmailAlreadyExists を返し、INSERT は実行しません。
- 重複がなければ同じTxでINSERTします。メールのUNIQUE制約が並行作成の競合も防ぎます。
- Commit成功後、domain → UserOutput → userResponse と変換して201を返します。失敗はhandlerのerrorMappingsでHTTPへ変換します。
internal/adapter/handler/json.go · 11行目
元ファイルを開く
11 const maxBodyBytes = 1 << 20
12
13 func decodeJSON(c *gin.Context, dst any) error {
14 dec := json.NewDecoder(http.MaxBytesReader(c.Writer, c.Request.Body, maxBodyBytes))
15 dec.DisallowUnknownFields()
16
17 if err := dec.Decode(dst); err != nil {
18 return fmt.Errorf("%w: %w", errInvalidJSON, err)
19 }
20
21 return nil
22 }
internal/adapter/handler/user.go · 29行目
元ファイルを開く
29 func (h *UserHandler) Create(c *gin.Context) {
30 var req createUserRequest
31 if err := decodeJSON(c, &req); err != nil {
32 writeError(c, err)
33 return
34 }
35
36 out, err := h.users.Create(c.Request.Context(), usecase.CreateUserInput{Name: req.Name, Email: req.Email})
37 if err != nil {
38 writeError(c, err)
39 return
40 }
41
42 c.JSON(http.StatusCreated, newUserResponse(out))
43 }
44
45 // Get は GET /users/:id を処理する。
46 func (h *UserHandler) Get(c *gin.Context) {
47 out, err := h.users.Get(c.Request.Context(), usecase.GetUserInput{ID: c.Param("id")})
internal/usecase/user.go · 42行目
元ファイルを開く
42 // Create はメールアドレスの重複を確認してユーザーを作成する。
43 func (uc *UserUsecase) Create(ctx context.Context, in CreateUserInput) (*UserOutput, error) {
44 email, err := user.NewEmail(in.Email)
45 if err != nil {
46 return nil, err
47 }
48
49 u, err := user.New(in.Name, email, uc.now())
50 if err != nil {
51 return nil, err
52 }
53
54 txErr := uc.tx.Do(ctx, func(ctx context.Context) error {
55 exists, err := uc.repo.ExistsByEmail(ctx, email)
56 if err != nil {
57 return fmt.Errorf("exists by email: %w", err)
58 }
59
60 if exists {
61 return user.ErrEmailAlreadyExists
62 }
63
64 if err := uc.repo.Create(ctx, u); err != nil {
65 return fmt.Errorf("create user: %w", err)
66 }
67
68 return nil
69 })
70 if txErr != nil {
71 return nil, txErr
72 }
73
74 return newUserOutput(u), nil
75 }
internal/adapter/repository/user.go · 26行目
元ファイルを開く
26 // Create はユーザーを保存する。メールアドレスが重複していれば user.ErrEmailAlreadyExists を返す。
27 func (r *UserRepository) Create(ctx context.Context, u *user.User) error {
28 const q = `
29 INSERT INTO users (
30 id,
31 name,
32 email,
33 created_at
34 )
35 VALUES (
36 $1,
37 $2,
38 $3,
39 $4
40 )
41 `
42
43 _, err := conn(ctx, r.db).ExecContext(ctx, q, u.ID().String(), u.Name(), u.Email().String(), u.CreatedAt())
44 if isUniqueViolation(err) {
45 return user.ErrEmailAlreadyExists
46 }
47
48 if err != nil {
49 return fmt.Errorf("insert user: %w", err)
50 }
51
52 return nil
53 }
04 · GET /users/:id と /healthz
Get は文字列IDを ParseID で検証・正規化し、FindByIDで1行を取得します。sql.ErrNoRows は ErrNotFound に変換され、DBの値は Reconstruct でUserへ復元します。Get は TxManager.Do を呼ばず、通常は接続プールから読み取ります。
/healthz はrouter内で200を返すだけで、DBへのクエリを行いません。DBへの PingContext は起動時の database.Open で実行されます。
internal/usecase/user.go · 77行目
元ファイルを開く
77 // Get は ID でユーザーを取得する。
78 func (uc *UserUsecase) Get(ctx context.Context, in GetUserInput) (*UserOutput, error) {
79 id, err := user.ParseID(in.ID)
80 if err != nil {
81 return nil, err
82 }
83
84 u, err := uc.repo.FindByID(ctx, id)
85 if err != nil {
86 return nil, err
87 }
88
89 return newUserOutput(u), nil
90 }
91
92 func newUserOutput(u *user.User) *UserOutput {
93 return &UserOutput{
94 ID: u.ID().String(),
95 Name: u.Name(),
96 Email: u.Email().String(),
97 CreatedAt: u.CreatedAt(),
98 }
99 }
internal/adapter/repository/user.go · 55行目
元ファイルを開く
55 // FindByID は ID でユーザーを取得する。見つからなければ user.ErrNotFound を返す。
56 func (r *UserRepository) FindByID(ctx context.Context, id user.ID) (*user.User, error) {
57 const q = `
58 SELECT
59 id,
60 name,
61 email,
62 created_at
63 FROM
64 users
65 WHERE
66 id = $1
67 `
68
69 var (
70 rowID, name, email string
71 createdAt time.Time
72 )
73
74 err := conn(ctx, r.db).QueryRowContext(ctx, q, id.String()).Scan(&rowID, &name, &email, &createdAt)
75 if errors.Is(err, sql.ErrNoRows) {
76 return nil, user.ErrNotFound
77 }
78
79 if err != nil {
80 return nil, fmt.Errorf("select user: %w", err)
81 }
82
83 return user.Reconstruct(user.ID(rowID), name, user.Email(email), createdAt), nil
84 }
internal/adapter/handler/router.go · 10行目
元ファイルを開く
10 func NewRouter(users *UserHandler) http.Handler {
11 gin.SetMode(gin.ReleaseMode) // 起動時のデバッグ出力を止める。ログは logRequest で slog に出す
12
13 r := gin.New()
14 r.HandleMethodNotAllowed = true
15 r.Use(recoverPanic, logRequest)
16
17 r.GET("/healthz", func(c *gin.Context) { c.Status(http.StatusOK) })
18
19 r.POST("/users", users.Create)
20 r.GET("/users/:id", users.Get)
21
22 return r
23 }
05 · トランザクションとエラーの経路
TxManager と UserRepository は同じ *sql.DB を持ちます。Txを含むcontextをcallbackへ渡し、repositoryのconnが *sql.Tx を選ぶことで、重複確認とINSERTが同じTxに参加します。すでにTxがある場合はcallbackをそのまま実行して合流します。
callbackのエラー、またはCommit失敗ではRollbackを試みます。Rollback失敗はerrors.Joinで元のエラーと結合します。panic時はRollbackを試みて再panicし、HTTPミドルウェアが500へ変換します。この経路では、Rollback失敗のログをrepository側で記録する例外があります。
| 原因 | HTTP | JSON error.code |
|---|
| JSONのdecode失敗 | 400 | invalid_request |
| ID / Name / Emailの検証失敗 | 400 | invalid_argument |
| 該当ユーザーなし | 404 | not_found |
| メール重複 / SQLSTATE 23505 | 409 | already_exists |
| 未対応エラー / panic | 500 | internal |
errors.Isでラップ済みのエラーを判定します。未知エラーは詳細をslogに残し、レスポンスには固定の internal server error を返します。23505の変換は制約名を見ず、すべてのunique violationをメール重複として扱う現実装です。
internal/adapter/repository/tx.go · 25行目
元ファイルを開く
25 // Do は fn をトランザクション内で実行する。既にトランザクション中なら合流する。
26 func (m *TxManager) Do(ctx context.Context, fn func(ctx context.Context) error) (err error) {
27 if _, ok := ctx.Value(txKey{}).(*sql.Tx); ok {
28 return fn(ctx)
29 }
30
31 tx, err := m.db.BeginTx(ctx, nil)
32 if err != nil {
33 return fmt.Errorf("begin tx: %w", err)
34 }
35
36 defer func() {
37 if p := recover(); p != nil {
38 if rbErr := tx.Rollback(); rbErr != nil {
39 slog.ErrorContext(ctx, "rollback after panic", "error", rbErr)
40 }
41
42 panic(p)
43 }
44
45 if err == nil {
46 return
47 }
48
49 if rbErr := tx.Rollback(); rbErr != nil {
50 err = errors.Join(err, fmt.Errorf("rollback: %w", rbErr))
51 }
52 }()
53
54 if err = fn(context.WithValue(ctx, txKey{}, tx)); err != nil {
55 return err
56 }
57
58 if err = tx.Commit(); err != nil {
59 return fmt.Errorf("commit: %w", err)
60 }
61
62 return nil
63 }
internal/adapter/repository/db.go · 17行目
元ファイルを開く
17 type txKey struct{}
18
19 // conn は ctx にトランザクションがあればそれを、なければ db を返す。
20 func conn(ctx context.Context, db *sql.DB) querier { //nolint:ireturn // *sql.DB と *sql.Tx を同じ型で扱うため
21 if tx, ok := ctx.Value(txKey{}).(*sql.Tx); ok {
22 return tx
23 }
24
25 return db
26 }
27
28 func isUniqueViolation(err error) bool {
29 var pgErr *pgconn.PgError
30 return errors.As(err, &pgErr) && pgErr.Code == "23505"
31 }
internal/adapter/handler/error.go · 18行目
元ファイルを開く
18 var errorMappings = []struct {
19 target error
20 status int
21 code string
22 }{
23 {errInvalidJSON, http.StatusBadRequest, "invalid_request"},
24 {user.ErrInvalidID, http.StatusBadRequest, codeInvalidArgument},
25 {user.ErrInvalidName, http.StatusBadRequest, codeInvalidArgument},
26 {user.ErrInvalidEmail, http.StatusBadRequest, codeInvalidArgument},
27 {user.ErrNotFound, http.StatusNotFound, "not_found"},
28 {user.ErrEmailAlreadyExists, http.StatusConflict, "already_exists"},
29 }
30
31 func writeError(c *gin.Context, err error) {
32 for _, m := range errorMappings {
33 if errors.Is(err, m.target) {
34 c.JSON(m.status, errorResponse{Error: errorBody{Code: m.code, Message: m.target.Error()}})
35 return
36 }
37 }
38
39 slog.ErrorContext(
40 c.Request.Context(),
41 "unhandled error",
42 "error",
43 err,
44 "method",
45 c.Request.Method,
46 "path",
47 c.Request.URL.Path,
48 )
49 c.JSON(http.StatusInternalServerError, errorResponse{
50 Error: errorBody{Code: "internal", Message: "internal server error"},
51 })
52 }
internal/adapter/handler/middleware.go · 30行目
元ファイルを開く
30 defer func() {
31 if v := recover(); v != nil {
32 slog.ErrorContext(
33 c.Request.Context(),
34 "panic recovered",
35 "panic",
36 v,
37 "method",
38 c.Request.Method,
39 "path",
40 c.Request.URL.Path,
41 )
42 c.AbortWithStatusJSON(http.StatusInternalServerError, errorResponse{
43 Error: errorBody{Code: "internal", Message: "internal server error"},
44 })
45 }
46 }()
47
48 c.Next()
49 }
06 · User集約とusersテーブル
| 列 | SQLの型・制約 | domainでの扱い |
|---|
| id | UUID · PRIMARY KEY | ID値オブジェクト。標準uuidで生成・ParseIDで正規化 |
| name | VARCHAR(50) · NOT NULL | 前後空白を除去、Unicodeの文字数で1〜50を検証 |
| email | VARCHAR(254) · NOT NULL · UNIQUE | net/mailで検証。表示名付きは拒否し、文字列全体を小文字化 |
| created_at | TIMESTAMPTZ · NOT NULL | usecase.now()をNewへ渡す。SQLに明示的に保存 |
現時点のマイグレーションはusersの1テーブルで、外部キーや他集約との関係はありません。Reconstructは保存済みデータの復元専用で再検証しません。メール254文字の上限はDB側にあり、NewEmailには同じ長さ制限の明示チェックはありません。
db/migrations/000001_create_users.up.sql · 1行目
元ファイルを開く
1 CREATE TABLE users (
2 id UUID PRIMARY KEY,
3 name VARCHAR(50) NOT NULL,
4 email VARCHAR(254) NOT NULL UNIQUE,
5 created_at TIMESTAMPTZ NOT NULL
6 );
internal/domain/user/user.go · 9行目
元ファイルを開く
9 const maxNameLength = 50
10
11 // User はユーザーエンティティ。フィールドを非公開にし、不正な状態で生成できないようにする。
12 type User struct {
13 id ID
14 name string
15 email Email
16 createdAt time.Time
17 }
18
19 // New は不変条件を検証してユーザーを生成する。
20 func New(name string, email Email, now time.Time) (*User, error) {
21 name = strings.TrimSpace(name)
22 if err := validateName(name); err != nil {
23 return nil, err
24 }
25
26 return &User{id: NewID(), name: name, email: email, createdAt: now}, nil
27 }
28
29 // Reconstruct は永続化層からの復元専用。検証済みのデータであることを前提とする。
30 func Reconstruct(id ID, name string, email Email, createdAt time.Time) *User {
31 return &User{id: id, name: name, email: email, createdAt: createdAt}
32 }
33
34 // ID はユーザー ID を返す。
35 func (u *User) ID() ID { return u.id }
36
37 // Name は名前を返す。
38 func (u *User) Name() string { return u.name }
39
40 // Email はメールアドレスを返す。
41 func (u *User) Email() Email { return u.email }
42
43 // CreatedAt は作成日時を返す。
44 func (u *User) CreatedAt() time.Time { return u.createdAt }
45
46 func validateName(name string) error {
47 if name == "" || utf8.RuneCountInString(name) > maxNameLength {
48 return ErrInvalidName
49 }
50
51 return nil
52 }
internal/domain/user/email.go · 8行目
元ファイルを開く
8 // Email は検証済みのメールアドレスを表す値オブジェクト。
9 type Email string
10
11 // NewEmail はメールアドレスを検証して Email に変換する。
12 func NewEmail(s string) (Email, error) {
13 addr, err := mail.ParseAddress(s)
14 if err != nil || addr.Address != s {
15 return "", ErrInvalidEmail
16 }
17
18 return Email(strings.ToLower(s)), nil
19 }
20
21 func (e Email) String() string { return string(e) }
internal/domain/user/id.go · 3行目
元ファイルを開く
3 import "uuid"
4
5 // ID は UUID 形式のユーザー識別子。
6 type ID string
7
8 // NewID は新しい ID をランダムに生成する。
9 func NewID() ID {
10 return ID(uuid.New().String())
11 }
12
13 // ParseID は文字列を検証して ID に変換する。大文字などの表記揺れは小文字のハイフン区切りにそろえる。
14 func ParseID(s string) (ID, error) {
15 u, err := uuid.Parse(s)
16 if err != nil {
17 return "", ErrInvalidID
18 }
19
20 return ID(u.String()), nil
21 }
22
23 func (id ID) String() string { return string(id) }
07 · 起動・接続プール・終了
| 項目 | 現実装 |
|---|
| 設定 | APP_ADDRは既定 :8080、DATABASE_URLは必須、LOG_LEVELは既定 info |
| ログ | slogのJSONHandler → stdout。不正なlevelはinfoへフォールバック |
| DB接続 | database/sql + pgx/v5/stdlib。Open後のPingは5秒のtimeout |
| 接続プール | 最大接続25、最大idle25、接続寿命5分 |
| DI | TxManager → UserRepository → UserUsecase → UserHandler → Router。各実装を手書きで生成 |
| HTTP timeout | ReadHeader 5秒 / Read 10秒 / Write 10秒 / Idle 60秒 |
| 終了 | SIGINT / SIGTERM → Shutdownを最大10秒待つ → deferでDBを閉じる |
| ローカルDB | postgres:16-alpine、既定公開ポート5432、db-data volume、pg_isready healthcheck |
| マイグレーション | make migrate-upで別途実施。API起動時に自動適用する処理はない |
cmd/api/main.go · 23行目
元ファイルを開く
23 readHeaderTimeout = 5 * time.Second
24 readTimeout = 10 * time.Second
25 writeTimeout = 10 * time.Second
26 idleTimeout = 60 * time.Second
27 shutdownTimeout = 10 * time.Second
28 )
29
30 func main() {
31 if err := run(); err != nil {
32 slog.Error("server exited", "error", err)
33 os.Exit(1)
34 }
35 }
36
37 func run() error {
38 ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
39 defer stop()
40
41 cfg, err := config.Load()
42 if err != nil {
43 return err
44 }
45
46 slog.SetDefault(logger.New(cfg.LogLevel))
47
48 db, err := database.Open(ctx, cfg.DatabaseURL)
49 if err != nil {
50 return err
51 }
52 defer db.Close()
53
54 // --- DI: 依存の組み立てはここだけで行う ---
55 txManager := repository.NewTxManager(db)
56 userRepo := repository.NewUserRepository(db)
57 userHandler := handler.NewUserHandler(usecase.NewUserUsecase(userRepo, txManager))
58
59 srv := &http.Server{
60 Addr: cfg.Addr,
61 Handler: handler.NewRouter(userHandler),
62 ReadHeaderTimeout: readHeaderTimeout,
63 ReadTimeout: readTimeout,
64 WriteTimeout: writeTimeout,
65 IdleTimeout: idleTimeout,
66 }
67
68 errCh := make(chan error, 1)
69
70 go func() {
71 slog.Info("server started", "addr", cfg.Addr)
72
73 if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
74 errCh <- err
75 }
76
77 close(errCh)
78 }()
79
80 select {
81 case err := <-errCh:
82 return err
83 case <-ctx.Done():
84 }
85
86 slog.Info("shutting down")
87
88 shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
89 defer cancel()
90
91 if err := srv.Shutdown(shutdownCtx); err != nil {
92 return fmt.Errorf("shutdown server: %w", err)
93 }
94
95 return nil
96 }
internal/infra/database/database.go · 9行目
元ファイルを開く
9 _ "github.com/jackc/pgx/v5/stdlib" // database/sql 用 PostgreSQL ドライバ
10 )
11
12 const (
13 maxOpenConns = 25
14 maxIdleConns = 25
15 connMaxLifetime = 5 * time.Minute
16 pingTimeout = 5 * time.Second
17 )
18
19 // Open は PostgreSQL に接続し、疎通を確認した *sql.DB を返す。
20 func Open(ctx context.Context, dsn string) (*sql.DB, error) {
21 db, err := sql.Open("pgx", dsn)
22 if err != nil {
23 return nil, fmt.Errorf("open db: %w", err)
24 }
25
26 db.SetMaxOpenConns(maxOpenConns)
27 db.SetMaxIdleConns(maxIdleConns)
28 db.SetConnMaxLifetime(connMaxLifetime)
29
30 ctx, cancel := context.WithTimeout(ctx, pingTimeout)
31 defer cancel()
32
33 if err := db.PingContext(ctx); err != nil {
34 _ = db.Close()
35 return nil, fmt.Errorf("ping db: %w", err)
36 }
37
38 return db, nil
39 }
internal/infra/config/config.go · 18行目
元ファイルを開く
18 // Load は環境変数から設定を読み込む。
19 func Load() (Config, error) {
20 cfg := Config{
21 Addr: getenv("APP_ADDR", ":8080"),
22 DatabaseURL: os.Getenv("DATABASE_URL"),
23 LogLevel: getenv("LOG_LEVEL", "info"),
24 }
25 if cfg.DatabaseURL == "" {
26 return Config{}, ErrMissingDatabaseURL
27 }
28
29 return cfg, nil
30 }
31
32 func getenv(key, fallback string) string {
33 if v, ok := os.LookupEnv(key); ok && v != "" {
34 return v
35 }
36
37 return fallback
38 }
internal/infra/logger/logger.go · 8行目
元ファイルを開く
8 // New は JSON 形式の構造化ロガーを返す。level は debug / info / warn / error。
9 func New(level string) *slog.Logger {
10 var l slog.Level
11 if err := l.UnmarshalText([]byte(level)); err != nil {
12 l = slog.LevelInfo
13 }
14
15 return slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: l}))
16 }
compose.yaml · 1行目
元ファイルを開く
1 services:
2 db:
3 image: postgres:16-alpine
4 environment:
5 POSTGRES_USER: app
6 POSTGRES_PASSWORD: app
7 POSTGRES_DB: app
8 ports:
9 - "${DB_PORT:-5432}:5432"
10 volumes:
11 - db-data:/var/lib/postgresql/data
12 healthcheck:
13 test: ["CMD-SHELL", "pg_isready -U app -d app"]
14 interval: 2s
15 timeout: 3s
16 retries: 15
17
18 volumes:
19 db-data:
08 · 実装範囲と検証の読み方
この成果物は2026年10月2日のローカルコードを調査したものです。Goはgo.modの1.27.1、直接依存はgin v1.12.0とpgx v5.7.2です。Composeが定義するのはローカルDBのみです。本番のクラウド、ロードバランサー、認証、キャッシュ、キュー、外部サービスの配置はこのプロジェクトに実装されていません。
domainとusecaseのテーブル駆動テストがあります。手書きfakeTxManagerはcallbackを呼ぶだけで、実DBのCommit・Rollbackや並行競合は再現しません。make checkはbuild → vet → test → lint、make testはrace付きです。
図のJSONとHTMLのハッシュ、9項目のshowcase検証結果はdeliveryレシートに記録しています。Chromeによる画面検査の結果はvisual-checkレシートを確認してください。自動検証と目視確認は別の検証です。
編集可能な図の仕様 · 配布レシート · 画面検査レシート
go.mod · 1行目
元ファイルを開く
1 module example.com/go-clean
2
3 go 1.27.1
4
5 require (
6 github.com/gin-gonic/gin v1.12.0
7 github.com/jackc/pgx/v5 v5.7.2
8 )
internal/usecase/fake_test.go · 64行目
元ファイルを開く
64 func (fakeTxManager) Do(ctx context.Context, fn func(ctx context.Context) error) error {
65 return fn(ctx)
66 }
Makefile · 28行目
元ファイルを開く
28
29 test: ## テストを実行(race 検出付き)
30 go test -race ./...
31
32 lint: $(GOLANGCI_LINT) ## golangci-lint(依存方向チェックを含む)
33 $(GOLANGCI_LINT) run ./...
34
35 fmt: $(GOLANGCI_LINT) ## コードを整形
36 $(GOLANGCI_LINT) fmt ./...
37 $(GOLANGCI_LINT) run --fix --enable-only whitespace ./...
38
39 check: $(GOLANGCI_LINT) ## 完了前の検証一式(build → vet → test → lint)
40 go build ./...
41 go vet ./...
42 go test ./...
43 $(GOLANGCI_LINT) run ./...
44
45 db-up: ## PostgreSQL を起動
46 docker compose up -d --wait db
47
48 db-down: ## PostgreSQL を停止
49 docker compose down
50
51 migrate-up: ## マイグレーションを適用