① domain/object：ビジネスルールを持つ#

まず、「メモとは何か」をドメインオブジェクトとして定義します。
ここがルールの本体で、不正な状態のオブジェクトはそもそも作れないようにします。

// app/domain/object/note/pending_note.go
package note

// PendingNote = まだDBに保存されていない（IDが決まっていない）メモ
type PendingNote struct {
    accountID uint64
    body      string
}

func NewPendingNote(accountID uint64, body string) (*PendingNote, error) {
    p := &PendingNote{}
    if accountID == 0 {
        return nil, errors.ErrBadRequest.WithDevMessage("account id must be more than 0")
    }
    p.accountID = accountID
    if len(body) == 0 || len(body) > 140 {
        return nil, errors.ErrBadRequest.WithDevMessage("body must be between 1 and 140 characters")
    }
    p.body = body
    return p, nil
}

func (p *PendingNote) AccountID() uint64 { return p.accountID }
func (p *PendingNote) Body() string      { return p.body }

フィールドが全部小文字（＝非公開）で、生成は NewPendingNote を通すしかないので、140文字を超えたメモはそもそも存在できません。
「保存前（PendingNote）」と「保存後（Note）」で型を分けているのも最初は「なんで？」となったのですが、保存前はIDが決まっていないので、ID が0の中途半端なオブジェクトを持ち回さなくて済むという意味でした。

② domain/repository：保存の「設計図」だけ書く#

次が、自分が一番「は？」となったところです。

// app/domain/repository/note.go
package repository

type Note interface {
    Insert(ctx context.Context, pendingNote *note.PendingNote) (*note.Note, error)
    FindByID(ctx context.Context, id uint64) (*note.Note, error)
}

interfaceしかありません。SQLは1行もありません。
「このドメインを永続化するときはこういう操作ができて、引数はこれで、返り値はこれ」という設計図だけをdomain層に置きます。

MySQL という単語も sqlx という単語も、ここには出てきません。これが大事です。

③ usecase：設計図を呼ぶ#

ユースケース層は、②の設計図（interface）を受け取って使います。

// app/usecase/note/create_note.go
type CreateNoteUseCaseImpl struct {
    noteRepo   repository.Note      // ← interface を持つ（実装ではない）
    transactor transactor.Transactor
}

func NewCreateNoteUseCase(noteRepo repository.Note, transactor transactor.Transactor) *CreateNoteUseCaseImpl {
    return &CreateNoteUseCaseImpl{noteRepo: noteRepo, transactor: transactor}
}

func (uc *CreateNoteUseCaseImpl) CreateNote(ctx context.Context, accountID uint64, body string) (*note.Note, error) {
    result, err := uc.transactor.TransactionWithValue(ctx, func(ctx context.Context) (any, error) {
        pendingNote, err := note.NewPendingNote(accountID, body) // ← ルールはドメインに聞く
        if err != nil {
            return nil, err
        }
        return uc.noteRepo.Insert(ctx, pendingNote) // ← 保存は設計図に投げる
    })
    // ...
}

usecaseがやっているのは、「ドメインオブジェクトを作って、リポジトリに渡す」という段取りだけです。
バリデーションのルールも知らないし、SQLも知りません。

さっきのMVC版の NoteService が *NoteRepository を持っていたのに対して、こっちは repository.Note（interface）を持っています。この違いが全部です。

④ infra：設計図を見ながら実装する#

そして実際にMySQLを叩くのがinfra層です。

// app/infra/note.go
package infra

// このコンパイル時アサーションが地味に効く
var _ repository.Note = (*NoteRepoImpl)(nil)

type NoteRepoImpl struct{}

type noteDTO struct {
    ID        uint64    `db:"id"`
    AccountID uint64    `db:"account_id"`
    Body      string    `db:"body"`
    CreatedAt time.Time `db:"created_at"`
}

func (r *NoteRepoImpl) Insert(ctx context.Context, pendingNote *note.PendingNote) (*note.Note, error) {
    tx, err := transaction.FetchTransaction(ctx)
    if err != nil {
        return nil, err
    }

    result, err := tx.ExecContext(ctx,
        `INSERT INTO note (account_id, body) VALUES (?, ?)`,
        pendingNote.AccountID(), pendingNote.Body(),
    )
    if err != nil {
        return nil, err
    }
    id, err := result.LastInsertId()
    if err != nil {
        return nil, err
    }

    var dto noteDTO
    if err := tx.GetContext(ctx, &dto,
        `SELECT id, account_id, body, created_at FROM note WHERE id = ?`, id); err != nil {
        return nil, err
    }
    // DTO（テーブルの形）→ ドメインオブジェクト（アプリの形）に詰め替える
    return note.ReconstructNote(dto.ID, dto.AccountID, dto.Body, dto.CreatedAt)
}

var _ repository.Note = (*NoteRepoImpl)(nil) はGoのイディオムで、「NoteRepoImpl は repository.Note を満たしてますよね？」というのをコンパイル時にチェックさせる書き方です。
設計図にメソッドを1つ足したのに実装を忘れると、その場でビルドが落ちてくれるので、これはかなり便利でした。

⑤ server.go：ここで初めて全部つながる#

で、interfaceと実装をくっつけているのが server.go です。ここがDI（依存性注入）です。

// app/server/server.go
// Repository（infra の実装をここで作る）
noteRepo := infra.NewNoteRepository()

// UseCase（interface のところに実装を「注入」する）
createNoteUseCase := usecase_note.NewCreateNoteUseCase(noteRepo, transactor)

// Handler
noteHandler := api_note.NewNoteHandler(createNoteUseCase)

usecase は自分で infra を import しません。server.go が外から差し込みます。
usecaseは、自分が渡されたものがMySQL実装なのかどうかを最後まで知りません。

1. DBを乗り換えるときに、触る場所が2箇所で済む#

たとえば「MySQLをやめてPostgresにしたい」となったとします。

MVC版だと、NoteRepository の中身が書き換わって、それを直接持っている NoteService にも影響が出る可能性があります。

Onion版だと、domain/repository/note.go（設計図）は1文字も変わりません。
やることは、

1. infra に Postgres版の実装を新しく作る
2. server.go で渡すものを差し替える

これだけです。

// Before
noteRepo := infra.NewNoteRepository()          // MySQL実装

// After
noteRepo := infra.NewNotePostgresRepository()  // Postgres実装

usecase も domain も ui も、1行も変わりません。これが「変更容易性が高い」ということでした。

2. 段階移行できるし、切り戻しもできる#

しかもMySQL実装を消す必要がありません。両方infraに残しておいて、

var noteRepo repository.Note
if config.UsePostgres() {
    noteRepo = infra.NewNotePostgresRepository()
} else {
    noteRepo = infra.NewNoteRepository()
}

こうしておけば、移行先で問題が起きたときにフラグを戻すだけで元に戻せます。
「乗り換えやすい」だけじゃなくて「失敗しても戻れる」というのが、実務的にはかなりデカいんだろうなと思いました。

3. テストのときにDBが要らない#

usecase が持っているのはinterfaceなので、テストでは偽物を渡せます。

type fakeNoteRepo struct{}

func (f *fakeNoteRepo) Insert(ctx context.Context, p *note.PendingNote) (*note.Note, error) {
    return note.ReconstructNote(1, p.AccountID(), p.Body(), time.Now())
}
func (f *fakeNoteRepo) FindByID(ctx context.Context, id uint64) (*note.Note, error) {
    return nil, nil
}

// テスト側
uc := usecase_note.NewCreateNoteUseCase(&fakeNoteRepo{}, &fakeTransactor{})

MySQLを立ち上げずにユースケースのテストが書けます。
これも「interfaceに依存しているから」できることでした。

① 1機能作るのに触るファイルが多い#

「メモを投稿する」を作るだけで、触ったファイルはこれだけあります。

app/domain/object/note/pending_note.go   新規
app/domain/object/note/note.go           新規
app/domain/repository/note.go             新規
app/usecase/note/create_note.go            新規
app/infra/note.go                         新規
app/ui/api/note/request.go                新規
app/ui/api/note/response.go               新規
app/ui/api/note/note.go                  新規
app/server/server.go                       修正

9ファイル。MVCなら3ファイルで終わる内容です。
慣れていない状態でこれをやると、「今どこを書いているんだっけ」が本当にわからなくなります。
Day2で詰まった原因の半分はこれで、アーキテクチャの問題というより、自分の頭のワーキングメモリの問題でした。

② 「知っていてはいけないこと」がある#

これが一番カルチャーショックでした。

たとえば、usecase の中で「404を返したい」と思っても、net/http を import してはいけません。
HTTPステータスコードはUI層の知識なので、usecaseがそれを知った瞬間に usecase → ui という依存が生まれて、矢印が逆流するからです。

③ DTOとドメインオブジェクトの詰め替えが面倒に見えた#

infra層で、noteDTO にSELECTした結果を入れて、それを ReconstructNote でドメインオブジェクトに詰め替えています。

最初は「同じフィールドを移し替えてるだけじゃん、Note に直接 db:"id" タグを付ければよくない？」と思っていました。

でもこれをやると、ドメインオブジェクトがテーブル定義に引きずられます。
カラム名を変えたらドメインオブジェクトが変わるし、テーブルを分割したらドメインオブジェクトが壊れる。せっかく infra を切り離した意味がなくなります。

④ トランザクションをどこで貼るか#

これもOnionならではで悩みました。
トランザクションは「1つの処理の単位」なのでusecaseで貼りたい。でも *sqlx.Tx はinfraの知識なので、usecaseが持つわけにいきません。

答えは、これもinterfaceでした。

// app/usecase/transactor/transactor.go ← usecase側にinterface
type Transactor interface {
    Transaction(ctx context.Context, txFunc func(context.Context) error) error
    TransactionWithValue(ctx context.Context, txFunc func(context.Context) (any, error)) (any, error)
}

// app/infra/transaction/transaction.go ← infra側に実装
func (t *TransactorImpl) TransactionWithValue(
    ctx context.Context,
    txFunc func(ctx context.Context) (any, error),
) (any, error) {
    tx, err := t.db.Beginx()
    if err != nil {
        return nil, err
    }
    ctxWithTx := context.WithValue(ctx, transactionKey, tx)  // contextにtxを詰める
    result, err := txFunc(ctxWithTx)
    if err != nil {
        tx.Rollback()
        return nil, err
    }
    return result, tx.Commit()
}

// infra側はここでcontextからtxを取り出す
func FetchTransaction(ctx context.Context) (*sqlx.Tx, error) {
    tx, ok := ctx.Value(transactionKey).(*sqlx.Tx)
    if !ok {
        return nil, errors.ErrInternal.WithDevMessage("transaction not found in context")
    }
    return tx, nil
}

context に tx を詰めて渡して、infra側の FetchTransaction(ctx) で取り出す。
こうするとusecaseは「トランザクションで囲む」という意図だけを書けて、*sqlx.Tx の存在を知らずに済みます。

repositoryとまったく同じパターン（usecase側にinterface、infra側に実装）だと気づいたとき、「あ、これ全部同じ考え方でできてるんだ」となって、ここでやっと全体がつながった感じがありました。

① そのまま返す#

if err != nil {
    return nil, err
}

一番シンプル。ただし、これだけだとどこで失敗したのかがわからなくなります。

② fmt.Errorf と %w でラップする#

if err != nil {
    return nil, fmt.Errorf("failed to insert note: %w", err)
}

%w を使うと、元のエラーを包んだまま情報を足せます。
%v だと単なる文字列になって元のエラーが取り出せなくなるので、ここは %w です。

③ sentinel error と errors.Is#

あらかじめエラーを変数として定義しておいて、比較で判定するやり方です。

var ErrNotFound = errors.New("not found")

// 呼び出し側
if errors.Is(err, ErrNotFound) {
    // 404を返す、など
}

err == ErrNotFound ではなく errors.Is を使うのは、②でラップされていても中身まで辿って比較してくれるからです。

④ 独自エラー型と errors.As#

エラーに追加情報を持たせたいときは、自分で型を作ります。

type ValidationError struct {
    Field string
}
func (e *ValidationError) Error() string { return e.Field + " is invalid" }

// 呼び出し側
var vErr *ValidationError
if errors.As(err, &vErr) {
    fmt.Println(vErr.Field)  // 追加情報が取り出せる
}

errors.Is は「そのエラーかどうか」、errors.As は「その型として取り出せるか」。ここは最初ごちゃごちゃになりました。

⑤ panicは使わない#

Goには panic もありますが、「想定できるエラーは全部 error で返す」というのが基本でした。
panic を使うのは、本当に復帰できない状況だけ。
ただし最後の砦として、ミドルウェアで recover してサーバーが落ちないようにはしてあります。

r.Use(middleware.Recoverer)

1. 自前のステータスコードを定義する#

まず、HTTPから切り離した自分たちのコードを定義します。

// pkg/errors/code/code.go
package code

type StatusCode string

var (
    BadRequest   StatusCode = "BAD_REQUEST"  // 400
    Unauthorized StatusCode = "UNAUTHORIZED" // 401
    Forbidden    StatusCode = "FORBIDDEN"    // 403
    NotFound     StatusCode = "NOT_FOUND"    // 404
    Conflict     StatusCode = "CONFLICT"     // 409
    Internal     StatusCode = "INTERNAL"     // 500
)

コメントにHTTPの番号は書いてありますが、型としてはHTTPと無関係な文字列です。
これならdomainから使っても依存の矢印は逆流しません。

2. エラー型を作る#

そのコードを持つエラー型を定義します。

// pkg/errors/status.go
type Status struct {
    code       code.StatusCode
    uiMessage  string  // クライアントに返すメッセージ
    devMessage string  // 開発者向けの詳細
}

func (e *Status) Error() string {
    return fmt.Sprintf("code: %s, uiMessage: %s, devMessage: %v", e.code, e.uiMessage, e.devMessage)
}

// devMessageだけ差し替えた「新しい」Statusを返す
func (e *Status) WithDevMessage(devMessage string) *Status {
    return &Status{code: e.code, uiMessage: e.uiMessage, devMessage: devMessage}
}

この uiMessage と devMessage を分ける という発想が、個人的に一番「なるほど」となったところでした。

今までの自分は errors.New("account id must be more than 0") みたいに書いて、それをそのままレスポンスに出したりしていました。
でもこれ、内部の実装の言葉がそのまま外に漏れるんですよね。
外向けは「bad request」だけ、詳細はログにだけ出す。この分離が最初から型に組み込まれているのが良かったです。

3. 汎用エラーを用意しておく#

// pkg/errors/error.go
var (
    ErrBadRequest   = New(code.BadRequest, "bad request", "")
    ErrUnauthorized = New(code.Unauthorized, "unauthorized", "")
    ErrForbidden    = New(code.Forbidden, "forbidden", "")
    ErrNotFound     = New(code.NotFound, "not found", "")
    ErrConflict     = New(code.Conflict, "conflict", "")
    ErrInternal     = New(code.Internal, "internal server error", "internal server error occurred")
)

これで各層から、こう書けます。

// domain層：140文字を超えていた
return nil, errors.ErrBadRequest.WithDevMessage("body must be between 1 and 140 characters")

// domain層：アカウント名が重複していた
return nil, errors.ErrConflict

// infra層：トランザクションが取れなかった
return nil, errors.ErrInternal.WithDevMessage("transaction not found in context")

WithDevMessage が新しい Status を返す（元を書き換えない）ようになっているのがポイントで、グローバル変数の ErrBadRequest を汚さずに詳細だけ足せます。

4. UI層で、初めてHTTPに変換する#

そして最後、UI層でだけHTTPステータスコードに変換します。

// app/ui/api/pkg/errors/errors.go
var codes = map[code.StatusCode]int{
    code.BadRequest:   http.StatusBadRequest,
    code.Unauthorized: http.StatusUnauthorized,
    code.Forbidden:    http.StatusForbidden,
    code.NotFound:     http.StatusNotFound,
    code.Conflict:     http.StatusConflict,
    code.Internal:     http.StatusInternalServerError,
}

func Handle(w http.ResponseWriter, err error) {
    if err == nil {
        return
    }
    if v, ok := errors.AsType[*apperrors.Status](err); ok {
        slog.Info(v.UIMessage(), "code", v.Code())
        http.Error(w, v.UIMessage(), codes[v.Code()])   // uiMessageだけ外に出す
    } else {
        // Status型じゃないエラー = 想定外なので、中身を隠して500
        slog.Info(err.Error())
        http.Error(w, "internal server error", http.StatusInternalServerError)
    }
}

ハンドラ側は、エラーが来たらこれを呼ぶだけになります。

created, err := h.createNoteUseCase.CreateNote(ctx, accountID, req.Body)
if err != nil {
    ui_errors.Handle(w, err)   // 400か409か500かはHandleが判断する
    return
}

ハンドラに if errors.Is(err, ...) { 400 } else if ... { 409 } みたいな分岐が一切いらなくなりました。
そして**「HTTP」という単語が出てくるファイルが ui の下だけ**になります。ここでOnionの話とエラーハンドリングの話がきれいに合流したのが、個人的に一番気持ちよかったところです。

もう1つ良かったのが、Status 型じゃないエラー（＝どこかで変換し忘れた想定外のエラー）が来たら、問答無用で500にして中身を隠すようになっていることです。
うっかりSQLのエラー文がそのままクライアントに返る、みたいな事故が構造的に起きません。

ラップするか、しないか#

Status を返す設計にしたので、「どの種類のエラーか」は完璧にわかります。
でも fmt.Errorf("...: %w", err) でラップしていく方式と違って、どこを通ってきたエラーなのかがわかりません。

理想は「Status でコードを持ちつつ、%w で経路も残す」だと思うのですが、両立させる書き方をきれいに整理しきれませんでした。ここは持ち帰りの宿題です。

どこでログを出すか#

これも最初やらかしました。
「エラーが起きたところでログを出そう」と思って各層に slog を書いたら、1つのエラーでログが3行も4行も出ました。infraで1回、usecaseで1回、handlerで1回、みたいな感じで。

結局、ログを出すのは Handle の中だけ（＝一番外側で1回だけ）に統一しました。
途中の層は情報を足して返すだけ、出力するのは端っこ。これは他の言語でも同じだと思うのですが、Goだとエラーが手で流れていくぶん、やらかしやすいなと感じました。