クリーンアーキテクチャの​実践編:経費精算の​承認を​作って​テストする

クリーンアーキテクチャを、​手を​動かして​確かめる​記事です。​経費精算の​「申請を​承認する」を​題材に、​業務の​規則から、​画面に​返す形、​データベース、​テストまで、​動く​コード (TypeScript) を全部​載せます。

この記事は 2 本組みの​「実践編」です。

  • 理論編:何のために​分けるのか、​どこから​来た​考えか、​依存性の​ルール、​境界の​越え方、​設計の​原則、​誤解と​批判を、​確かめられる​原典を​引きながら解説
  • 実践編 (この記事):経費精算の​実例、​ディレクトリ構成、​テスト戦略、​DDD・​CQRS・​フロントエンドとの​関係、​既存の​システムへの​入れ方、​チェックリスト

どちらから​読んでも​分かるように​書いています。​理論編を​まだ​読んでいなくても、​次の​「3 行で​振り返る」だけで​コードは​読めます。

クリーンアーキテクチャを 3 行で​振り返る

source code dependencies can only point inwards.

(ソースコードの​依存は、​内側へだけ向けてよい)

— Robert C. Martin​「The Clean Architecture」​(2012 年の​ブログ)

  1. 内側に​業務の​規則 (Entities とユースケース)、​外側に​画面・​データベース・​フレームワークを置く
  2. ソースコードの​依存 (import) は​外から​内へだけ向ける。​内側は​外側の​名前を​一切​書かない
  3. 内側から​外側を​呼びたい​とき (ユースケース → Presenter、​ユースケース → データベース) は、内側に​インターフェース (Port) を置き、​外側が​それを​実装する
4 つの層の入れ子の図。外側から Frameworks and Drivers、Interface Adapters、Use Cases、Entities。矢印は、外側から内側へ向かうソースコードの依存を表す Frameworks & DriversWeb・DB・外部のサービス・mainInterface AdaptersController・Presenter・Gateway の実装Use Casesこのアプリだけの業務ルールEntities会社全体の業務ルールExpenseReport・Money承認権限規程・職務の分離
4 つの​層と​依存の​向き。​中央下の​矢印は、​ソースコードの​依存 (import) が​外から​内へだけ向く​ことを​表します。​中の​例は、​実践編で​作る​経費精算の​コードの​名前です。

4 つの​層の​名前は 2012 年の​ブログの​ものです。​同じ​ブログは、​円は​模式図で 4 つでなければならない​わけではない、​とも書いています。​なぜこうするのか、​どこから​来た​考えかは​理論編で​詳しく​書いています。

この記事の​読み方

  • コードは​手元で​動かして​確かめました。 Node.js 25.9 と TypeScript 7.0 で、​型チェック (tsc --noEmit) と 24 件の​テスト (node --test) が通る​ことを 2026 年 10 月 8 日に​確かめています。​記事の​コードは、​テストを​通した​ファイルを​そのまま​差し込んでいます
  • 実行には​追加の​パッケージは​要りません (データベースは Node に​入っている node:sqlite を使います)。​型チェックには typescript と @types/node が要ります (package.json の devDependencies。npm install で入ります)
  • Node.js 22.18.0 以降が​要ります。 Node.js の​公式の資料 (TypeScript のページ・​SQLite の​ページ の変更履歴) に​よると、​型を​書いたまま .ts を実行する​機能が​既定で​有効に​なったのは 22.18.0 (23 系では 23.6.0)、node:sqlite がフラグなしで​使えるようになったのは 22.13.0 (23 系では 23.4.0) です。この​記事で​実際に​動かしたのは 25.9 です
  • 原典に​書いてある​ことには​資料名を​添え、​後の​解釈や​実務の​工夫は​黄色の​線の​枠に​入れます。​資料名の​ない​説明や​意見は、​この​記事の​考えです
  • 承認の​金額の​区切りや​社員の​名前は、​この​記事の​ための​例です

1. 決まりごと (仕様)

  • 申請は​明細 (日付・内容・​金額) の​集まり。​金額は 1 円単位の​整数で、​0 円の​明細は​作れない
  • 承認の​段数は​合計額で​決まる (承認権限規程)。​3 万円未満は​上長、​3 万円以上 10 万円未満は​上長 → 部長、​10 万円以上は​上長 → 部長 → 経理。区切りの​金額は​この​記事の​例です
  • 承認は​段の​順に​進む。​今の​段の​承認者以外は​承認できない
  • 申請者本人は、​承認者に​指定されていても​承認できない (職務の分離)
  • 最後の​段が​承認したら​申請は​「承認済み」に​なり、​経理に​支払いを​依頼する
  • 承認の​記録と​支払依頼は、​両方​残るか、​両方とも​残らないかの​どちらか
  • 結果は JSON で​返す。​金額は​「45,800円」の​形、​日時は​日本時間

申請を​作る (下書き → 申請)、​差し戻す、​代理で​承認する、は​この​記事では​扱いません。​どこを​足せば​よいかは、​10 章の​表に​書きました。

2. ディレクトリ構成

expense-app/
├── package.json
├── tsconfig.json
├── compare/
│   └── all-in-one.ts                   12 章で比べるための版 (層に分けない書き方)
├── src/
│   ├── expense/                        最上位は「経費」(何のシステムか分かる名前)
│   │   ├── entities/                   Entities
│   │   │   ├── money.ts
│   │   │   └── expense-report.ts
│   │   ├── use-cases/                  Use Cases
│   │   │   ├── gateways.ts             外の世界に求めること (Repository など)
│   │   │   └── approve-expense-report/
│   │   │       ├── boundary.ts         入出力のデータと Port
│   │   │       └── interactor.ts
│   │   └── adapters/                   Interface Adapters
│   │       ├── web/
│   │       │   ├── approve-controller.ts
│   │       │   └── approve-presenter.ts
│   │       └── persistence/
│   │           ├── in-memory.ts
│   │           └── sqlite.ts
│   └── main/                           Frameworks & Drivers と Main
│       ├── composition-root.ts
│       ├── server.ts
│       └── seed.ts
└── test/
    ├── fixtures.ts
    ├── entities.test.ts
    ├── approve-expense-report.test.ts
    ├── presenter.test.ts
    ├── repository-contract.test.ts
    ├── app.test.ts
    └── dependency-rule.test.ts

機能 (経費) の​中を​層で​分ける​形に​しました。​経費の​ほかに​出張の​手配のような​機能が​増えたら、expense/ と並べて travel/ を作ります。​Simon Brown は、自分の​サイトの​「Modular monolith and “package by component”」​のページで、​層ごと・​機能ごと・​Ports and Adapters・​コンポーネントごとの 4 つの​まとめ方を​比べています。​どれを​選んでも、​依存の​向きを​検査できる​ことが​大事だと​この​記事では​考えます (9 章の dependency-rule.test.ts)。

package.json と tsconfig.json です。Node は TypeScript の型を​消して​実行するので、​型を​消すだけでは​動かない​書き方 (enum、​コンストラクタの​引数での​フィールド宣言など) を erasableSyntaxOnly で禁止しています。​コンストラクタで​フィールドに​代入しているのは​この​ためです。

package.json

{
  "name": "expense-app",
  "private": true,
  "type": "module",
  "scripts": {
    "typecheck": "tsc --noEmit",
    "test": "node --test 'test/*.test.ts'",
    "start": "node src/main/server.ts"
  },
  "devDependencies": {
    "@types/node": "^24.0.0",
    "typescript": "^7.0.2"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "es2023",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "types": ["node"]
  },
  "include": ["src", "test", "compare"]
}

3. Entities:​申請と金額

まず金額です。​浮動小数点の​誤差を​入れないよう、​円の​整数で​持ちます。

src/expense/entities/money.ts

/** 円の金額。経費精算では 1 円未満を扱わないので、整数で持つ (小数の誤差を入れない) */
export class Money {
  readonly yen: number;

  private constructor(yen: number) {
    this.yen = yen;
  }

  static yen(amount: number): Money {
    if (!Number.isSafeInteger(amount)) throw new RangeError(`金額は整数の円で指定します: ${amount}`);
    if (amount < 0) throw new RangeError(`金額は 0 円以上です: ${amount}`);
    return new Money(amount);
  }

  static readonly zero = new Money(0);

  add(other: Money): Money {
    return Money.yen(this.yen + other.yen);
  }

  isAtLeast(other: Money): boolean {
    return this.yen >= other.yen;
  }
}

次に、経費の​申請です。​この​アプリの​業務の​規則は、​すべて​この​ファイルに​あります。

src/expense/entities/expense-report.ts

import { Money } from './money.ts';

export type EmployeeId = string;
export type ApproverRole = 'manager' | 'department-head' | 'accounting';

/**
 * 承認権限規程 (会社全体の規則): 合計額で、承認が何段必要かを決める。
 * 金額の区切りは例として置いたもの。
 */
export function requiredApprovals(total: Money): ApproverRole[] {
  if (total.isAtLeast(Money.yen(100_000))) return ['manager', 'department-head', 'accounting'];
  if (total.isAtLeast(Money.yen(30_000))) return ['manager', 'department-head'];
  return ['manager'];
}

export type ExpenseLine = { spentOn: string; description: string; amount: Money };
export type ReportStatus = 'submitted' | 'approved';
export type ApprovalViolation = 'not-submitted' | 'self-approval' | 'not-current-approver';
export type ApproveResult =
  | { ok: true; completed: boolean }
  | { ok: false; violation: ApprovalViolation };

/** 保存と復元のための、ただのデータ (振る舞いを持たない) */
export type ExpenseReportSnapshot = {
  id: string;
  applicantId: EmployeeId;
  status: ReportStatus;
  lines: { spentOn: string; description: string; amountYen: number }[];
  steps: { role: ApproverRole; approverId: EmployeeId; approvedAt: Date | null }[];
};

type Step = { role: ApproverRole; approverId: EmployeeId; approvedAt: Date | null };

/** 経費の申請 1 件。承認の規則はこのクラスの中だけに書く */
export class ExpenseReport {
  readonly id: string;
  readonly applicantId: EmployeeId;
  readonly lines: readonly ExpenseLine[];
  #status: ReportStatus;
  #steps: Step[];

  private constructor(id: string, applicantId: EmployeeId, lines: ExpenseLine[], status: ReportStatus, steps: Step[]) {
    if (lines.length === 0) throw new Error('明細が 1 行もない申請は作れません');
    if (lines.some((line) => line.amount.yen === 0)) throw new Error('0 円の明細は作れません');
    const roles = requiredApprovals(sum(lines));
    if (steps.length !== roles.length || steps.some((s, i) => s.role !== roles[i])) {
      throw new Error(`承認の段が規程と合いません: 必要 ${roles.join('→')}、指定 ${steps.map((s) => s.role).join('→')}`);
    }
    const done = steps.every((s) => s.approvedAt !== null);
    if ((status === 'approved') !== done) throw new Error(`状態 ${status} と承認の記録が合いません`);
    this.id = id;
    this.applicantId = applicantId;
    this.lines = lines;
    this.#status = status;
    this.#steps = steps;
  }

  /** 申請された直後の状態を作る。approvers は規程の段の順に並べる */
  static submitted(props: { id: string; applicantId: EmployeeId; lines: ExpenseLine[]; approvers: EmployeeId[] }): ExpenseReport {
    const roles = requiredApprovals(sum(props.lines));
    if (props.approvers.length !== roles.length) {
      throw new Error(`承認者は ${roles.length} 人必要です (${roles.join('→')})`);
    }
    const steps = roles.map((role, i) => ({ role, approverId: props.approvers[i]!, approvedAt: null }));
    return new ExpenseReport(props.id, props.applicantId, [...props.lines], 'submitted', steps);
  }

  /** 保存したデータから戻す。戻すときも規則を検査する */
  static restore(s: ExpenseReportSnapshot): ExpenseReport {
    const lines = s.lines.map((l) => ({ spentOn: l.spentOn, description: l.description, amount: Money.yen(l.amountYen) }));
    const steps = s.steps.map((step) => ({ ...step }));
    return new ExpenseReport(s.id, s.applicantId, lines, s.status, steps);
  }

  get status(): ReportStatus {
    return this.#status;
  }

  total(): Money {
    return sum(this.lines);
  }

  /** いま承認を待っている段。承認が終わっていれば null */
  currentStep(): Readonly<Step> | null {
    return this.#steps.find((s) => s.approvedAt === null) ?? null;
  }

  approve(approverId: EmployeeId, at: Date): ApproveResult {
    if (this.#status !== 'submitted') return { ok: false, violation: 'not-submitted' };
    // 職務の分離: 自分の申請は、承認者に指定されていても承認できない
    if (approverId === this.applicantId) return { ok: false, violation: 'self-approval' };
    const step = this.#steps.find((s) => s.approvedAt === null);
    if (!step || step.approverId !== approverId) return { ok: false, violation: 'not-current-approver' };
    step.approvedAt = at;
    const completed = this.#steps.every((s) => s.approvedAt !== null);
    if (completed) this.#status = 'approved';
    return { ok: true, completed };
  }

  toSnapshot(): ExpenseReportSnapshot {
    return {
      id: this.id,
      applicantId: this.applicantId,
      status: this.#status,
      lines: this.lines.map((l) => ({ spentOn: l.spentOn, description: l.description, amountYen: l.amount.yen })),
      steps: this.#steps.map((s) => ({ ...s })),
    };
  }
}

function sum(lines: readonly ExpenseLine[]): Money {
  return lines.reduce((total, line) => total.add(line.amount), Money.zero);
}

ポイントは 5 つです。

  • import しているのは money.ts だけです。データベースも HTTP も、​ユースケースの​層も​知りません
  • 規則に​反する​状態を​作れないように​しています。 コンストラクタは private で、作る​口は submitted (申請された​直後) と restore (保存した​ものから​戻す) の 2 つだけです。​どちらの​口も、​コンストラクタの​中の​同じ​検査 (明細が​ある、​0 円が​ない、​承認の​段が​規程と​合う、​状態と​記録が​合う) を​通ります
  • 承認の​段は #steps (外から​触れない private フィールド) に持ち、​変えられるのは approve だけです。getter と setter を​全部の​項目に​用意すると、​規則を​外から​破れるようになります (理論編で​取り上げた、​Martin Fowler のいう​貧血ドメインモデル)
  • 規則に​反した​承認は、​例外ではなく​結果の​値で​返します。 「順番ではない​人が​押した」は、​業務の​上では​普通に​起きる​ことなので、​呼び出し側が​場合分けを​書き忘れにくい形に​しました。​TypeScript の判別可能な​ユニオン型 (ok で分かれる​型) を​使っています。​例外で​表す​書き方も​あり、​どちらでも​クリーンアーキテクチャの​考え方からは​外れません
  • 保存の​ために​スナップショット (振る舞いを​持たない、ただの​データ) を​出し入れします。 Entity は SQL を​知らず、​Repository の実装が​スナップショットと​表の​行を​相互に​変換します

4. Use Cases:Port と Interactor

ユースケースが​外の​世界に​求める​ことを、​インターフェースと​して​内側で​定義します。​名前は​「SQL の​クライアント」​のような​技術の​言葉ではなく、​「申請の​保管場所」​「支払依頼」のような​業務の​言葉にします。

src/expense/use-cases/gateways.ts

import type { EmployeeId, ExpenseReport } from '../entities/expense-report.ts';

// ユースケースが外の世界に求めること。内側 (この層) が定義し、外側のアダプターが実装する

export interface ExpenseReportRepository {
  findById(id: string): Promise<ExpenseReport | null>;
  save(report: ExpenseReport): Promise<void>;
}

export interface EmployeeDirectory {
  findById(id: EmployeeId): Promise<{ id: EmployeeId; name: string } | null>;
}

/** 経理への支払依頼 (会計システムへの連携) */
export interface PaymentRequests {
  request(order: { reportId: string; payeeId: EmployeeId; amountYen: number }): Promise<void>;
}

export interface Clock {
  now(): Date;
}

/** work の中の書き込みを、全部反映するか全部取り消すかのどちらかにする */
export interface TransactionRunner {
  run<T>(work: () => Promise<T>): Promise<T>;
}

TransactionRunner は 2012 年の​ブログには​出てきません (この記事の​工夫です)。​「承認の​記録と​支払依頼は、​両方​残るか​両方残らないか」は​この​ユースケースの​規則ですが、​それを​実現する​手段 (データベースの​トランザクション) は​外側の​詳細です。​そこで、​規則の​側を Port と​して​内側に​置き、​手段は​外側で​実装しました。

次に、ユースケースの​入口と​出口です。

src/expense/use-cases/approve-expense-report/boundary.ts

// 「申請を承認する」の入口と出口。ここに出てくる型は、どれもただのデータ

export type ApproveExpenseReportInput = {
  reportId: string;
  approverId: string;
};

/** 断った理由。画面の文言は決めない (それは Presenter の仕事) */
export type RefusalReason = 'closed' | 'own-report' | 'not-your-turn';

export type ApproveExpenseReportOutput =
  | {
      kind: 'approved';
      reportId: string;
      totalYen: number;
      approvedAt: Date;
      /** 次の承認者の名前。最後の段まで終わったら null */
      nextApproverName: string | null;
    }
  | { kind: 'refused'; reportId: string; reason: RefusalReason }
  | { kind: 'not-found'; target: 'report' | 'approver' };

/** Input Port: Controller はこの型だけを知る */
export interface ApproveExpenseReportInputPort {
  execute(input: ApproveExpenseReportInput): Promise<void>;
}

/** Output Port: ユースケースはこの型だけを知り、Presenter が実装する */
export interface ApproveExpenseReportOutputPort {
  present(output: ApproveExpenseReportOutput): void;
}

断った理由 (RefusalReason) は、Entities の ApprovalViolation をそのまま​使わず、​別の​型に​しています。​Entities の​内部の​名前が Presenter や​画面の​文言まで​届かないように​する​ためです。​ただ、​この​程度の​対応づけなら​同じ型を​使い回してもかまいません (理論編の​「DTO の​変換地獄」)。

そして、​ユースケースの​本体 (Interactor) です。

src/expense/use-cases/approve-expense-report/interactor.ts

import type { ApprovalViolation } from '../../entities/expense-report.ts';
import type { Clock, EmployeeDirectory, ExpenseReportRepository, PaymentRequests, TransactionRunner } from '../gateways.ts';
import type {
  ApproveExpenseReportInput,
  ApproveExpenseReportInputPort,
  ApproveExpenseReportOutput,
  ApproveExpenseReportOutputPort,
  RefusalReason,
} from './boundary.ts';

export type ApproveExpenseReportDeps = {
  reports: ExpenseReportRepository;
  employees: EmployeeDirectory;
  payments: PaymentRequests;
  clock: Clock;
  transaction: TransactionRunner;
};

/** ユースケース「申請を承認する」。手順だけを書き、規則そのものは ExpenseReport に任せる */
export class ApproveExpenseReport implements ApproveExpenseReportInputPort {
  readonly #deps: ApproveExpenseReportDeps;
  readonly #output: ApproveExpenseReportOutputPort;

  constructor(deps: ApproveExpenseReportDeps, output: ApproveExpenseReportOutputPort) {
    this.#deps = deps;
    this.#output = output;
  }

  async execute(input: ApproveExpenseReportInput): Promise<void> {
    const { reports, employees, payments, clock, transaction } = this.#deps;

    const output = await transaction.run(async (): Promise<ApproveExpenseReportOutput> => {
      const approver = await employees.findById(input.approverId);
      if (!approver) return { kind: 'not-found', target: 'approver' };
      const report = await reports.findById(input.reportId);
      if (!report) return { kind: 'not-found', target: 'report' };

      const approvedAt = clock.now();
      const result = report.approve(approver.id, approvedAt);
      if (!result.ok) return { kind: 'refused', reportId: report.id, reason: toReason(result.violation) };

      await reports.save(report);
      if (result.completed) {
        await payments.request({ reportId: report.id, payeeId: report.applicantId, amountYen: report.total().yen });
      }
      const next = report.currentStep();
      const nextApprover = next ? await employees.findById(next.approverId) : null;
      return {
        kind: 'approved',
        reportId: report.id,
        totalYen: report.total().yen,
        approvedAt,
        nextApproverName: next ? (nextApprover?.name ?? '(名簿にない社員)') : null,
      };
    });

    // 書き込みが確定してから結果を渡す (取り消された承認を「承認しました」と見せない)
    this.#output.present(output);
  }
}

function toReason(violation: ApprovalViolation): RefusalReason {
  switch (violation) {
    case 'not-submitted':
      return 'closed';
    case 'self-approval':
      return 'own-report';
    case 'not-current-approver':
      return 'not-your-turn';
  }
}
  • 手順だけを​書き、​規則の​判断は report.approve に任せています。 Interactor の中に​「承認者が​申請者と​同じなら」のような if 文は​ありません
  • 結果を Presenter に​渡すのは、​トランザクションが​確定した後です。支払依頼の​書き込みに​失敗して​全体が​取り消されたのに、​画面には​「承認しました」と​出る、と​いう​ことが​起きません
  • toReason の switch は、​ケースを 1 つ​書き漏らすと​型エラーに​なります。 戻り値の​型が​決まっていて、strict のもとでは、​すべての​ケースを​書かないと​「最後まで​行くと​値を​返さない」と​判定されるからです。​Entities に​違反の​種類を​足したら、​ここで​気づけます

5. Interface Adapters:​Controller と Presenter

Presenter は、​ユースケースの​結果を​画面 (ここでは JSON) に​そのまま​出せる​形に​変えます。

src/expense/adapters/web/approve-presenter.ts

import type {
  ApproveExpenseReportOutput,
  ApproveExpenseReportOutputPort,
} from '../../use-cases/approve-expense-report/boundary.ts';

/** 画面 (ここでは JSON) にそのまま出せる形。文字列にするところまで Presenter が済ませる */
export type ApproveViewModel = {
  status: 200 | 403 | 404 | 409;
  message: string;
  total: string | null;
  approvedAt: string | null;
};

const yen = new Intl.NumberFormat('ja-JP');
const tokyo = new Intl.DateTimeFormat('ja-JP', {
  timeZone: 'Asia/Tokyo',
  year: 'numeric',
  month: '2-digit',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit',
});

export class ApproveExpenseReportPresenter implements ApproveExpenseReportOutputPort {
  viewModel: ApproveViewModel | null = null;

  present(output: ApproveExpenseReportOutput): void {
    this.viewModel = toViewModel(output);
  }
}

export function toViewModel(output: ApproveExpenseReportOutput): ApproveViewModel {
  switch (output.kind) {
    case 'approved':
      return {
        status: 200,
        message:
          output.nextApproverName === null
            ? '承認しました。最後の承認だったので、経理に支払いを依頼しました。'
            : `承認しました。次は ${output.nextApproverName} さんの承認です。`,
        total: `${yen.format(output.totalYen)}円`,
        approvedAt: tokyo.format(output.approvedAt),
      };
    case 'refused': {
      const messages = {
        closed: { status: 409, message: 'この申請は、いま承認を受け付けていません。' },
        'own-report': { status: 403, message: '自分の申請は承認できません。' },
        'not-your-turn': { status: 403, message: 'いまはあなたが承認する順番ではありません。' },
      } as const;
      return { ...messages[output.reason], total: null, approvedAt: null };
    }
    case 'not-found':
      return output.target === 'report'
        ? { status: 404, message: '申請が見つかりません。', total: null, approvedAt: null }
        : { status: 403, message: '承認者として登録されていません。', total: null, approvedAt: null };
  }
}

HTTP の​状態コード (200・​403・​404・​409) を決めているのも Presenter です。これは Web 用の Presenter なので、​Web の​都合を​知っていてかまいません。​同じ​ユースケースを​コマンドラインから​使うなら、​終了コードと​標準出力を​決める​別の Presenter を​作ります。​ユースケースは​変わりません。

Controller は、HTTP の​要求を​ユースケースの​入力に​変え、​ユースケースを​呼びます。

src/expense/adapters/web/approve-controller.ts

import type {
  ApproveExpenseReportInputPort,
  ApproveExpenseReportOutputPort,
} from '../../use-cases/approve-expense-report/boundary.ts';
import { ApproveExpenseReportPresenter } from './approve-presenter.ts';

/** フレームワークに依存しない、HTTP の要求と応答の最小の形 */
export type WebRequest = { method: string; path: string; userId: string | null };
export type WebResponse = { status: number; body: string };

/** Presenter は 1 回の要求の結果を持つので、要求ごとにユースケースを組み立てる */
export type UseCaseFactory = (output: ApproveExpenseReportOutputPort) => ApproveExpenseReportInputPort;

export class ApproveExpenseReportController {
  readonly #useCaseFor: UseCaseFactory;

  constructor(useCaseFor: UseCaseFactory) {
    this.#useCaseFor = useCaseFor;
  }

  async handle(request: WebRequest): Promise<WebResponse | null> {
    const match = /^\/expense-reports\/([\w-]+)\/approve$/.exec(request.path);
    if (request.method !== 'POST' || !match) return null; // このコントローラーの担当ではない
    if (!request.userId) return json(401, { message: 'ログインしてください。' });

    const presenter = new ApproveExpenseReportPresenter();
    await this.#useCaseFor(presenter).execute({ reportId: match[1]!, approverId: request.userId });
    const vm = presenter.viewModel;
    if (!vm) throw new Error('ユースケースが結果を渡しませんでした');
    const { status, ...body } = vm;
    return json(status, body);
  }
}

/** View: ViewModel を JSON に書き出すだけ。判断はしない */
function json(status: number, body: object): WebResponse {
  return { status, body: JSON.stringify(body) };
}

6. 保存:メモリと SQLite

同じ Port に、​2 つの​実装を​用意します。​メモリ版は​テストと​試作用です。

src/expense/adapters/persistence/in-memory.ts

import { ExpenseReport, type EmployeeId, type ExpenseReportSnapshot } from '../../entities/expense-report.ts';
import type {
  Clock,
  EmployeeDirectory,
  ExpenseReportRepository,
  PaymentRequests,
  TransactionRunner,
} from '../../use-cases/gateways.ts';

/** テストと試作用。オブジェクトそのものではなくスナップショットを持つので、save し忘れはテストで落ちる */
export class InMemoryExpenseReportRepository implements ExpenseReportRepository {
  readonly #rows = new Map<string, ExpenseReportSnapshot>();

  async findById(id: string): Promise<ExpenseReport | null> {
    const row = this.#rows.get(id);
    return row ? ExpenseReport.restore(row) : null;
  }

  async save(report: ExpenseReport): Promise<void> {
    this.#rows.set(report.id, report.toSnapshot());
  }
}

export class InMemoryEmployeeDirectory implements EmployeeDirectory {
  readonly #names: Map<EmployeeId, string>;

  constructor(names: Record<EmployeeId, string>) {
    this.#names = new Map(Object.entries(names));
  }

  async findById(id: EmployeeId) {
    const name = this.#names.get(id);
    return name === undefined ? null : { id, name };
  }
}

export class RecordingPaymentRequests implements PaymentRequests {
  readonly requested: { reportId: string; payeeId: EmployeeId; amountYen: number }[] = [];

  async request(order: { reportId: string; payeeId: EmployeeId; amountYen: number }): Promise<void> {
    this.requested.push(order);
  }
}

export class FixedClock implements Clock {
  readonly #at: Date;

  constructor(iso: string) {
    this.#at = new Date(iso);
  }

  now(): Date {
    return new Date(this.#at);
  }
}

/** メモリ上では取り消す仕組みがないので、そのまま実行する */
export const noTransaction: TransactionRunner = { run: (work) => work() };

メモリ版の Repository は、オブジェクト​その​ものではなく​スナップショットを​保存します。​もしオブジェクトを​そのまま​持つと、​Interactor が save を呼び忘れても、​メモリ上の​オブジェクトが​書き換わっているので​テストが​通ってしまいます。​スナップショットなら、​保存し忘れは​テストで​見つかります (わざと save を消して、​4 件の​テストが​落ちる​ことを​確かめました)。

SQLite 版は Node に​入っている node:sqlite を使います。​SQL は​この​ファイルの​外に​出しません。

SQLite 版のコード (138 行) を開く

src/expense/adapters/persistence/sqlite.ts

import type { DatabaseSync } from 'node:sqlite';
import { ExpenseReport, type ApproverRole, type EmployeeId, type ReportStatus } from '../../entities/expense-report.ts';
import type {
  EmployeeDirectory,
  ExpenseReportRepository,
  PaymentRequests,
  TransactionRunner,
} from '../../use-cases/gateways.ts';

// SQL はこのファイルの外に出さない。内側はテーブルの形を知らない

export function migrate(db: DatabaseSync): void {
  db.exec(`
    CREATE TABLE IF NOT EXISTS employees (id TEXT PRIMARY KEY, name TEXT NOT NULL);
    CREATE TABLE IF NOT EXISTS expense_reports (
      id TEXT PRIMARY KEY, applicant_id TEXT NOT NULL, status TEXT NOT NULL);
    CREATE TABLE IF NOT EXISTS expense_lines (
      report_id TEXT NOT NULL, line_no INTEGER NOT NULL, spent_on TEXT NOT NULL,
      description TEXT NOT NULL, amount_yen INTEGER NOT NULL, PRIMARY KEY (report_id, line_no));
    CREATE TABLE IF NOT EXISTS approval_steps (
      report_id TEXT NOT NULL, step_no INTEGER NOT NULL, role TEXT NOT NULL,
      approver_id TEXT NOT NULL, approved_at TEXT, PRIMARY KEY (report_id, step_no));
    CREATE TABLE IF NOT EXISTS payment_requests (
      report_id TEXT PRIMARY KEY, payee_id TEXT NOT NULL, amount_yen INTEGER NOT NULL);
  `);
}

type ReportRow = { id: string; applicant_id: string; status: ReportStatus };
type LineRow = { spent_on: string; description: string; amount_yen: number };
type StepRow = { role: ApproverRole; approver_id: string; approved_at: string | null };

export class SqliteExpenseReportRepository implements ExpenseReportRepository {
  readonly #db: DatabaseSync;

  constructor(db: DatabaseSync) {
    this.#db = db;
  }

  async findById(id: string): Promise<ExpenseReport | null> {
    const report = this.#db.prepare('SELECT * FROM expense_reports WHERE id = ?').get(id) as ReportRow | undefined;
    if (!report) return null;
    const lines = this.#db
      .prepare('SELECT * FROM expense_lines WHERE report_id = ? ORDER BY line_no')
      .all(id) as LineRow[];
    const steps = this.#db
      .prepare('SELECT * FROM approval_steps WHERE report_id = ? ORDER BY step_no')
      .all(id) as StepRow[];
    return ExpenseReport.restore({
      id: report.id,
      applicantId: report.applicant_id,
      status: report.status,
      lines: lines.map((l) => ({ spentOn: l.spent_on, description: l.description, amountYen: l.amount_yen })),
      steps: steps.map((s) => ({
        role: s.role,
        approverId: s.approver_id,
        approvedAt: s.approved_at === null ? null : new Date(s.approved_at),
      })),
    });
  }

  async save(report: ExpenseReport): Promise<void> {
    const s = report.toSnapshot();
    this.#db
      .prepare(
        `INSERT INTO expense_reports (id, applicant_id, status) VALUES (?, ?, ?)
         ON CONFLICT (id) DO UPDATE SET status = excluded.status`,
      )
      .run(s.id, s.applicantId, s.status);
    this.#db.prepare('DELETE FROM expense_lines WHERE report_id = ?').run(s.id);
    this.#db.prepare('DELETE FROM approval_steps WHERE report_id = ?').run(s.id);
    const line = this.#db.prepare('INSERT INTO expense_lines VALUES (?, ?, ?, ?, ?)');
    s.lines.forEach((l, i) => line.run(s.id, i, l.spentOn, l.description, l.amountYen));
    const step = this.#db.prepare('INSERT INTO approval_steps VALUES (?, ?, ?, ?, ?)');
    s.steps.forEach((st, i) => step.run(s.id, i, st.role, st.approverId, st.approvedAt?.toISOString() ?? null));
  }
}

export class SqliteEmployeeDirectory implements EmployeeDirectory {
  readonly #db: DatabaseSync;

  constructor(db: DatabaseSync) {
    this.#db = db;
  }

  async findById(id: EmployeeId) {
    const row = this.#db.prepare('SELECT id, name FROM employees WHERE id = ?').get(id) as
      | { id: string; name: string }
      | undefined;
    return row ? { id: row.id, name: row.name } : null;
  }
}

/**
 * 支払依頼は、同じデータベースの表に書いておく (別の処理が会計システムへ送る)。
 * 承認の記録と同じトランザクションに入るので、「承認したのに依頼が無い」状態が残らない
 */
export class SqlitePaymentRequests implements PaymentRequests {
  readonly #db: DatabaseSync;

  constructor(db: DatabaseSync) {
    this.#db = db;
  }

  async request(order: { reportId: string; payeeId: EmployeeId; amountYen: number }): Promise<void> {
    this.#db
      .prepare('INSERT INTO payment_requests (report_id, payee_id, amount_yen) VALUES (?, ?, ?)')
      .run(order.reportId, order.payeeId, order.amountYen);
  }
}

/**
 * 1 本の接続を共有するので、トランザクションを 1 つずつ順に流す
 * (await の間に別の要求の書き込みが混ざらないように)
 */
export class SqliteTransactionRunner implements TransactionRunner {
  readonly #db: DatabaseSync;
  #queue: Promise<unknown> = Promise.resolve();

  constructor(db: DatabaseSync) {
    this.#db = db;
  }

  run<T>(work: () => Promise<T>): Promise<T> {
    const next = this.#queue.then(async () => {
      this.#db.exec('BEGIN IMMEDIATE');
      try {
        const result = await work();
        this.#db.exec('COMMIT');
        return result;
      } catch (error) {
        this.#db.exec('ROLLBACK');
        throw error;
      }
    });
    this.#queue = next.catch(() => undefined);
    return next;
  }
}

例を短く​する​ために、​保存の​たびに​明細と​承認の​段を​消して​入れ直しています。​実際の​システムでは、​同じ​申請を 2 人が​同時に​承認しようとした​ときに​備えて、​更新の​衝突を​検出する​仕組みが​要ります。​版番号の​列などで​衝突を​検出して​取り消すやり方は、​Martin Fowler のパターンの​カタログで Optimistic Offline Lock (楽観的ロック) として​説明されています。​また 1 本の​接続を​共有しているので、​トランザクションを​順番に​流しています。​PostgreSQL などを​使うなら、​接続プールから​要求ごとに​接続を​借り、​その​接続で​トランザクションを​張る​形に​なります。

7. Main:部品の​組み立て

すべての​具体的な​部品を​知っているのは、​この 1 か所だけです。

src/main/composition-root.ts

import type { DatabaseSync } from 'node:sqlite';
import { ApproveExpenseReportController, type WebRequest, type WebResponse } from '../expense/adapters/web/approve-controller.ts';
import {
  migrate,
  SqliteEmployeeDirectory,
  SqliteExpenseReportRepository,
  SqlitePaymentRequests,
  SqliteTransactionRunner,
} from '../expense/adapters/persistence/sqlite.ts';
import { ApproveExpenseReport } from '../expense/use-cases/approve-expense-report/interactor.ts';
import type { Clock } from '../expense/use-cases/gateways.ts';

/** すべての具体的な部品を知っている唯一の場所。ここで組み立てて、外からは handle だけを見せる */
export function createApp(db: DatabaseSync, clock: Clock = { now: () => new Date() }) {
  migrate(db);
  const deps = {
    reports: new SqliteExpenseReportRepository(db),
    employees: new SqliteEmployeeDirectory(db),
    payments: new SqlitePaymentRequests(db),
    clock,
    transaction: new SqliteTransactionRunner(db),
  };
  const controllers = [new ApproveExpenseReportController((output) => new ApproveExpenseReport(deps, output))];

  return {
    async handle(request: WebRequest): Promise<WebResponse> {
      for (const controller of controllers) {
        const response = await controller.handle(request);
        if (response) return response;
      }
      return { status: 404, body: JSON.stringify({ message: 'ページが見つかりません。' }) };
    },
  };
}

HTTP サーバーは、​Node の node:http で書いた​接着剤のような​コードです。​Express や Fastify に​替えても、​変わるのは​この​ファイルだけです。

src/main/server.ts

import { createServer } from 'node:http';
import { DatabaseSync } from 'node:sqlite';
import { createApp } from './composition-root.ts';

const db = new DatabaseSync(process.env.DB_FILE ?? 'expense.db');
const app = createApp(db);
const port = Number(process.env.PORT ?? 3000);

// 例なので、この PC の中 (127.0.0.1) からの接続だけを受け付ける
createServer(async (req, res) => {
  try {
    const response = await app.handle({
      method: req.method ?? 'GET',
      path: new URL(req.url ?? '/', 'http://localhost').pathname,
      // 例のための簡略化。本物はセッションやトークンを検証して社員 ID を取り出す
      userId: req.headers['x-employee-id']?.toString() ?? null,
    });
    res.writeHead(response.status, { 'content-type': 'application/json; charset=utf-8' }).end(response.body);
  } catch (error) {
    console.error(error);
    res.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
    res.end(JSON.stringify({ message: 'サーバーでエラーが起きました。' }));
  }
}).listen(port, '127.0.0.1', () => console.log(`http://127.0.0.1:${port}`));

試すための​データを​入れる​スクリプトです。

src/main/seed.ts

import { DatabaseSync } from 'node:sqlite';
import { migrate, SqliteExpenseReportRepository } from '../expense/adapters/persistence/sqlite.ts';
import { ExpenseReport } from '../expense/entities/expense-report.ts';
import { Money } from '../expense/entities/money.ts';

// 試すためのデータ: 申請者 e1 の 45,800 円の申請 (承認は上長 e2 → 部長 e3 の 2 段)
const db = new DatabaseSync(process.env.DB_FILE ?? 'expense.db');
migrate(db);
const insert = db.prepare('INSERT OR REPLACE INTO employees (id, name) VALUES (?, ?)');
for (const [id, name] of [['e1', '佐藤'], ['e2', '鈴木'], ['e3', '高橋']] as const) insert.run(id, name);
// 何度実行しても同じ状態から試せるように、前回の支払依頼を消してから申請を作り直す
db.prepare('DELETE FROM payment_requests WHERE report_id = ?').run('r-2026-001');
await new SqliteExpenseReportRepository(db).save(
  ExpenseReport.submitted({
    id: 'r-2026-001',
    applicantId: 'e1',
    lines: [
      { spentOn: '2026-10-01', description: '大阪出張 新幹線 往復', amount: Money.yen(29_000) },
      { spentOn: '2026-10-01', description: '大阪出張 宿泊', amount: Money.yen(16_800) },
    ],
    approvers: ['e2', 'e3'],
  }),
);
console.log('r-2026-001 を作りました');

8. 動かしてみる

cd expense-app
node src/main/seed.ts
node src/main/server.ts

サーバーは、​この PC の​中 (127.0.0.1) からの​接続だけを​受け付けます。​別の​ターミナルの​ウィンドウから​承認してみます。​順番ではない​部長 (e3) が​先に​押すと​断られ、​上長 (e2)、​部長 (e3) の​順に​押すと​承認が​終わります。

curl -X POST -H 'x-employee-id: e3' 127.0.0.1:3000/expense-reports/r-2026-001/approve
# {"message":"いまはあなたが承認する順番ではありません。","total":null,"approvedAt":null}  (403)

curl -X POST -H 'x-employee-id: e2' 127.0.0.1:3000/expense-reports/r-2026-001/approve
# {"message":"承認しました。次は 高橋 さんの承認です。","total":"45,800円","approvedAt":"2026/10/08 12:36"}

curl -X POST -H 'x-employee-id: e3' 127.0.0.1:3000/expense-reports/r-2026-001/approve
# {"message":"承認しました。最後の承認だったので、経理に支払いを依頼しました。","total":"45,800円","approvedAt":"2026/10/08 12:36"}

curl -X POST -H 'x-employee-id: e3' 127.0.0.1:3000/expense-reports/r-2026-001/approve
# {"message":"この申請は、いま承認を受け付けていません。","total":null,"approvedAt":null}  (409)

(# の行は​手元で​実行した​ときの​応答です。​日時は​実行した​時刻に​なります。) 最初から​やり直す​ときは、​もう​一度 node src/main/seed.ts を実行します。​seed は​前回の​支払依頼の​行を​消してから、​申請を​「申請直後」の​状態に​作り直します (2 回実行しても​最後まで​承認できる​ことを、​通しの​テストで​確かめています)。

9. テスト

テストは 6 つの​ファイル、​24 件です。​まず、​規則の​テスト。​データベースも HTTP も​使いません。

test/fixtures.ts

import { ExpenseReport } from '../src/expense/entities/expense-report.ts';
import { Money } from '../src/expense/entities/money.ts';

/** 申請者 e1、合計 45,800 円 (承認は 上長 e2 → 部長 e3 の 2 段) */
export function twoStepReport(id = 'r1'): ExpenseReport {
  return ExpenseReport.submitted({
    id,
    applicantId: 'e1',
    lines: [
      { spentOn: '2026-10-01', description: '新幹線', amount: Money.yen(29_000) },
      { spentOn: '2026-10-01', description: '宿泊', amount: Money.yen(16_800) },
    ],
    approvers: ['e2', 'e3'],
  });
}

export const names = { e1: '佐藤', e2: '鈴木', e3: '高橋', e9: '田中' };

test/entities.test.ts

import assert from 'node:assert/strict';
import { test } from 'node:test';
import { ExpenseReport, requiredApprovals } from '../src/expense/entities/expense-report.ts';
import { Money } from '../src/expense/entities/money.ts';
import { twoStepReport } from './fixtures.ts';

const at = new Date('2026-10-08T05:00:00Z');

test('承認の段の数は、合計額の区切りで決まる', () => {
  assert.equal(requiredApprovals(Money.yen(29_999)).length, 1);
  assert.equal(requiredApprovals(Money.yen(30_000)).length, 2);
  assert.equal(requiredApprovals(Money.yen(99_999)).length, 2);
  assert.equal(requiredApprovals(Money.yen(100_000)).length, 3);
});

test('2 段の承認が順に進み、最後の段で承認済みになる', () => {
  const report = twoStepReport();
  assert.deepEqual(report.approve('e2', at), { ok: true, completed: false });
  assert.equal(report.status, 'submitted');
  assert.deepEqual(report.approve('e3', at), { ok: true, completed: true });
  assert.equal(report.status, 'approved');
  assert.equal(report.currentStep(), null);
});

test('順番を飛ばした承認・承認済みへの承認は断る', () => {
  const report = twoStepReport();
  assert.deepEqual(report.approve('e3', at), { ok: false, violation: 'not-current-approver' });
  report.approve('e2', at);
  report.approve('e3', at);
  assert.deepEqual(report.approve('e3', at), { ok: false, violation: 'not-submitted' });
});

test('承認者に指定されていても、自分の申請は承認できない', () => {
  const report = ExpenseReport.submitted({
    id: 'r2',
    applicantId: 'e2',
    lines: [{ spentOn: '2026-10-02', description: '書籍', amount: Money.yen(3_300) }],
    approvers: ['e2'],
  });
  assert.deepEqual(report.approve('e2', at), { ok: false, violation: 'self-approval' });
});

test('規程と承認者の人数が合わない申請・0 円の明細は作れない', () => {
  const lines = [{ spentOn: '2026-10-02', description: '機材', amount: Money.yen(120_000) }];
  assert.throws(() => ExpenseReport.submitted({ id: 'r3', applicantId: 'e1', lines, approvers: ['e2'] }));
  const zero = [{ spentOn: '2026-10-02', description: '0 円', amount: Money.yen(0) }];
  assert.throws(() => ExpenseReport.submitted({ id: 'r4', applicantId: 'e1', lines: zero, approvers: ['e2'] }));
});

test('金額は 0 以上の整数の円だけ', () => {
  assert.throws(() => Money.yen(100.5));
  assert.throws(() => Money.yen(-1));
});

test('スナップショットから戻した申請は、元と同じ状態を持つ', () => {
  const report = twoStepReport();
  report.approve('e2', at);
  const restored = ExpenseReport.restore(report.toSnapshot());
  assert.deepEqual(restored.toSnapshot(), report.toSnapshot());
});

次に、ユースケースの​テストです。​Port にはメモリ版を​渡し、​Presenter の​代わりに、​渡された​出力を​配列に​記録するだけの Output Port を使います。

test/approve-expense-report.test.ts

import assert from 'node:assert/strict';
import { test } from 'node:test';
import {
  FixedClock,
  InMemoryEmployeeDirectory,
  InMemoryExpenseReportRepository,
  noTransaction,
  RecordingPaymentRequests,
} from '../src/expense/adapters/persistence/in-memory.ts';
import type { ApproveExpenseReportOutput } from '../src/expense/use-cases/approve-expense-report/boundary.ts';
import { ApproveExpenseReport } from '../src/expense/use-cases/approve-expense-report/interactor.ts';
import { names, twoStepReport } from './fixtures.ts';

/** Presenter の代わりに、渡された出力を覚えておくだけの Output Port */
async function setup() {
  const reports = new InMemoryExpenseReportRepository();
  await reports.save(twoStepReport('r1'));
  const payments = new RecordingPaymentRequests();
  const outputs: ApproveExpenseReportOutput[] = [];
  const useCase = new ApproveExpenseReport(
    {
      reports,
      employees: new InMemoryEmployeeDirectory(names),
      payments,
      clock: new FixedClock('2026-10-08T05:00:00Z'),
      transaction: noTransaction,
    },
    { present: (output) => outputs.push(output) },
  );
  return { reports, payments, outputs, useCase };
}

test('1 段目の承認: 次の承認者の名前を返し、支払依頼はまだ出さない', async () => {
  const { useCase, outputs, payments } = await setup();
  await useCase.execute({ reportId: 'r1', approverId: 'e2' });
  assert.deepEqual(outputs, [
    { kind: 'approved', reportId: 'r1', totalYen: 45_800, approvedAt: new Date('2026-10-08T05:00:00Z'), nextApproverName: '高橋' },
  ]);
  assert.deepEqual(payments.requested, []);
});

test('最後の段の承認: 保存され、申請者あての支払依頼が 1 回だけ出る', async () => {
  const { useCase, outputs, payments, reports } = await setup();
  await useCase.execute({ reportId: 'r1', approverId: 'e2' });
  await useCase.execute({ reportId: 'r1', approverId: 'e3' });
  assert.equal(outputs[1]?.kind === 'approved' && outputs[1].nextApproverName, null);
  assert.equal((await reports.findById('r1'))?.status, 'approved');
  assert.deepEqual(payments.requested, [{ reportId: 'r1', payeeId: 'e1', amountYen: 45_800 }]);

  await useCase.execute({ reportId: 'r1', approverId: 'e3' });
  assert.deepEqual(outputs[2], { kind: 'refused', reportId: 'r1', reason: 'closed' });
  assert.equal(payments.requested.length, 1);
});

test('断った承認は保存しない', async () => {
  const { useCase, outputs, reports } = await setup();
  await useCase.execute({ reportId: 'r1', approverId: 'e3' });
  assert.deepEqual(outputs, [{ kind: 'refused', reportId: 'r1', reason: 'not-your-turn' }]);
  assert.equal((await reports.findById('r1'))?.currentStep()?.approverId, 'e2');
});

test('自分の申請・見つからない申請・名簿にない承認者', async () => {
  const { useCase, outputs } = await setup();
  await useCase.execute({ reportId: 'r1', approverId: 'e1' });
  await useCase.execute({ reportId: 'nope', approverId: 'e2' });
  await useCase.execute({ reportId: 'r1', approverId: 'x' });
  assert.deepEqual(outputs, [
    { kind: 'refused', reportId: 'r1', reason: 'own-report' },
    { kind: 'not-found', target: 'report' },
    { kind: 'not-found', target: 'approver' },
  ]);
});

残りの 4 つの​ファイルは​畳んで​おきます。​Presenter の​テスト、​Repository の契約テスト (メモリ版と SQLite 版に同じテストを​流す)、​Main から SQLite まで​通すテスト、​依存性の​ルールの​検査です。

Presenter の​テストを開く

test/presenter.test.ts

import assert from 'node:assert/strict';
import { test } from 'node:test';

// 手元の時間帯が日本でも「日本時間に直す処理」の抜けで落ちるように、UTC にしてから読み込む
process.env.TZ = 'UTC';
const { toViewModel } = await import('../src/expense/adapters/web/approve-presenter.ts');

test('金額は桁区切りの円、日時は日本時間で出す', () => {
  const vm = toViewModel({
    kind: 'approved',
    reportId: 'r1',
    totalYen: 1_234_567,
    approvedAt: new Date('2026-10-08T15:30:00Z'),
    nextApproverName: '高橋',
  });
  assert.equal(vm.total, '1,234,567円');
  assert.equal(vm.approvedAt, '2026/10/09 00:30');
  assert.equal(vm.message, '承認しました。次は 高橋 さんの承認です。');
});

test('断った理由ごとに、状態コードと文言が決まる', () => {
  const status = (reason: 'closed' | 'own-report' | 'not-your-turn') =>
    toViewModel({ kind: 'refused', reportId: 'r1', reason }).status;
  assert.deepEqual([status('closed'), status('own-report'), status('not-your-turn')], [409, 403, 403]);
  assert.equal(toViewModel({ kind: 'not-found', target: 'report' }).status, 404);
});
Repository の契約テストを開く

test/repository-contract.test.ts

import assert from 'node:assert/strict';
import { describe, test } from 'node:test';
import { DatabaseSync } from 'node:sqlite';
import { InMemoryExpenseReportRepository } from '../src/expense/adapters/persistence/in-memory.ts';
import { migrate, SqliteExpenseReportRepository } from '../src/expense/adapters/persistence/sqlite.ts';
import type { ExpenseReportRepository } from '../src/expense/use-cases/gateways.ts';
import { twoStepReport } from './fixtures.ts';

/** 同じ約束を、メモリ版と SQLite 版の両方で確かめる (偽物が本物とずれないように) */
const implementations: [string, () => ExpenseReportRepository][] = [
  ['メモリ', () => new InMemoryExpenseReportRepository()],
  ['SQLite', () => {
    const db = new DatabaseSync(':memory:');
    migrate(db);
    return new SqliteExpenseReportRepository(db);
  }],
];

for (const [name, create] of implementations) {
  describe(`ExpenseReportRepository の約束 (${name})`, () => {
    test('保存した申請を、同じ状態で読み出せる', async () => {
      const repo = create();
      const report = twoStepReport('r1');
      report.approve('e2', new Date('2026-10-08T05:00:00Z'));
      await repo.save(report);
      assert.deepEqual((await repo.findById('r1'))?.toSnapshot(), report.toSnapshot());
    });

    test('2 回保存すると、後の状態で上書きされる', async () => {
      const repo = create();
      const report = twoStepReport('r1');
      await repo.save(report);
      report.approve('e2', new Date('2026-10-08T05:00:00Z'));
      report.approve('e3', new Date('2026-10-08T06:00:00Z'));
      await repo.save(report);
      assert.equal((await repo.findById('r1'))?.status, 'approved');
    });

    test('無い ID は null', async () => {
      assert.equal(await create().findById('nope'), null);
    });
  });
}
通しの​テストを開く

test/app.test.ts

import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { fileURLToPath } from 'node:url';
import { DatabaseSync } from 'node:sqlite';
import { SqliteExpenseReportRepository } from '../src/expense/adapters/persistence/sqlite.ts';
import { createApp } from '../src/main/composition-root.ts';
import { names, twoStepReport } from './fixtures.ts';

async function seededApp() {
  const db = new DatabaseSync(':memory:');
  const app = createApp(db, { now: () => new Date('2026-10-08T05:00:00Z') });
  for (const [id, name] of Object.entries(names)) db.prepare('INSERT INTO employees VALUES (?, ?)').run(id, name);
  await new SqliteExpenseReportRepository(db).save(twoStepReport('r1'));
  const approve = (userId: string | null) => app.handle({ method: 'POST', path: '/expense-reports/r1/approve', userId });
  return { db, app, approve };
}

test('HTTP の形から SQLite まで通して、2 段の承認が終わる', async () => {
  const { db, approve } = await seededApp();
  const first = await approve('e2');
  assert.equal(first.status, 200);
  assert.equal(JSON.parse(first.body).message, '承認しました。次は 高橋 さんの承認です。');
  const second = await approve('e3');
  assert.equal(JSON.parse(second.body).total, '45,800円');
  const rows = db.prepare('SELECT report_id, amount_yen FROM payment_requests').all();
  assert.deepEqual(rows.map((row) => ({ ...row })), [
    { report_id: 'r1', amount_yen: 45_800 },
  ]);
});

test('ログインしていなければ 401、知らない URL は 404', async () => {
  const { app, approve } = await seededApp();
  assert.equal((await approve(null)).status, 401);
  assert.equal((await app.handle({ method: 'GET', path: '/nope', userId: 'e2' })).status, 404);
});

test('支払依頼の書き込みに失敗したら、承認の記録も取り消す', async () => {
  const { db, approve } = await seededApp();
  await approve('e2');
  db.exec('DROP TABLE payment_requests'); // 最後の段で依頼の書き込みが失敗するようにする
  await assert.rejects(approve('e3'));
  const step = db.prepare('SELECT approved_at FROM approval_steps WHERE report_id = ? AND step_no = 1').get('r1');
  assert.deepEqual({ ...step }, { approved_at: null });
});

test('seed を 2 回実行しても、最初から最後まで承認できる', async () => {
  const dir = mkdtempSync(join(tmpdir(), 'expense-'));
  const env = { ...process.env, DB_FILE: join(dir, 'expense.db') };
  const seed = fileURLToPath(new URL('../src/main/seed.ts', import.meta.url));
  for (let i = 0; i < 2; i++) {
    execFileSync(process.execPath, [seed], { env });
    const app = createApp(new DatabaseSync(env.DB_FILE));
    const approve = (userId: string) => app.handle({ method: 'POST', path: '/expense-reports/r-2026-001/approve', userId });
    assert.equal((await approve('e2')).status, 200);
    assert.equal((await approve('e3')).status, 200);
  }
  rmSync(dir, { recursive: true });
});

最後の​ファイルは、​依存性の​ルール​その​ものを​検査します。​各ファイルの import を​読み、​外側の​層を import していないか、​内側の 2 層が Node の​機能や​外部の​パッケージを import していないかを​調べます。

test/dependency-rule.test.ts

import assert from 'node:assert/strict';
import { readdirSync, readFileSync } from 'node:fs';
import { dirname, join, relative, resolve } from 'node:path';
import { test } from 'node:test';

// 内側から順に。ファイルは、自分と同じか内側の層だけを import してよい
const layers = ['expense/entities', 'expense/use-cases', 'expense/adapters', 'main'];
const src = resolve(import.meta.dirname, '../src');

const layerOf = (file: string) => layers.findIndex((layer) => relative(src, file).startsWith(layer + '/'));

function* sourceFiles(dir: string): Generator<string> {
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const path = join(dir, entry.name);
    if (entry.isDirectory()) yield* sourceFiles(path);
    else if (path.endsWith('.ts')) yield path;
  }
}

test('ソースコードの依存は内側へだけ向いている', () => {
  const violations: string[] = [];
  for (const file of sourceFiles(src)) {
    const from = layerOf(file);
    assert.notEqual(from, -1, `${relative(src, file)} がどの層にも入っていません`);
    for (const [, spec] of readFileSync(file, 'utf8').matchAll(/^import[^'"]*['"]([^'"]+)['"]/gm)) {
      const name = `${relative(src, file)} → ${spec}`;
      if (spec!.startsWith('.')) {
        const to = layerOf(resolve(dirname(file), spec!));
        if (to > from) violations.push(`${name} (外側の層を import)`);
      } else if (from <= 1) {
        // 内側の 2 層は、Node の機能も外部のパッケージも直接は使わない
        violations.push(`${name} (内側の層から外部を import)`);
      }
    }
  }
  assert.deepEqual(violations, []);
});

型チェックと​テストは​次のように​実行します。

npm install          # 型チェック用の typescript と @types/node を入れる
npm run typecheck
npm test
# ℹ tests 24
# ℹ pass 24
# ℹ fail 0

テストが​本当に​不具合を​見つけられるかを​確かめる​ため、​コードに​わざと​不具合を 1 つずつ​入れて、​テストが​落ちるかを​調べました (ミューテーションテストと​呼ばれる​確かめ方です)。

わざと​入れた​不具合 落ちた​テストの数
Interactor の save を消す 4
本人の​申請を​断る​行を消す 2
承認済みの​申請を​断る​行を消す 2
最後の​段でなくても​支払いを​依頼する 4
3 万円の​区切りを 1 円ずらす 1
SQLite 版で ROLLBACK を消す 1
承認の​段を​逆の​順に​読み出す 5
Presenter で​日本時間に​直す指定を消す 1
entities から use-cases を import する 1
use-cases から node:fs を import する 1
seed で​前回の​支払依頼を​消さない 1

最初に​試した​ときは、​日本時間の​指定を​消しても​テストが​通ってしまいました。​手元の​時間帯が​もともと​日本時間だったからです。​そこで Presenter の​テストは​時間帯を UTC に​してから​読み込むように​直しました (presenter.test.ts の先頭)。​テストを​書いたら、​一度わざと​壊して​落ちる​ことを​確かめる、と​いう​手順は​おすすめです。

10. 変更が​来たら、​どこが​変わるか

この構造の​価値は、​変更が​来た​ときに​見えます。

変更 変わる所 変わらない所
3 万円の​区切りを 5 万円にする expense-report.ts の requiredApprovals とその​テスト ユースケース・​画面・​データベース
承認の​結果を​コマンドラインでも出す コマンドライン用の Controller と Presenter を​足す。​Main Entities・​Use Cases
SQLite を PostgreSQL にする Port の​実装を 4 つ足す。​Main。​契約テストに 1 行足す Entities・​Use Cases・​Web
承認したら​申請者に​メールで​知らせる 通知の Port を​足し、​Interactor から呼ぶ。​実装は​外側。​Main Entities
代理の​承認 (部長が​不在の​とき代理が​承認する) を​入れる Entities の approve の条件。​代理の​関係を​調べる Port を足す Web の​形は​ほぼ​そのまま
支払依頼を​会計システムの API へ直接送る PaymentRequests の実装を​替える。​Main ほかすべて

最後の​行には​注意が​要ります。​API へ直接送ると、​データベースの​トランザクションで​「両方​残るか​両方残らないか」を​守れなくなります。​今の​実装のように、​まず​同じ​データベースの​表に​書き、​別の​処理が​そこから​会計システムへ​送る​形に​しておく方が​安全です。​Chris Richardson の microservices.io では、この​形が Transactional outbox という​パターンと​して​説明されています。​依存の​向きの​規則は、​こうした​設計の​判断を​代わりに​してはくれません。​判断した​結果を​置く​場所を​決めてくれるだけです。

11. 安定度と​抽象度を測る

Martin は C++ Report 誌の連載の 1 本​「Stability」​で、パッケージの​不安定さ I と抽象度 A を定義しています (定義と​出典は​理論編の 6 章)。

  • I = Ce ÷ (Ca + Ce)。Ca は​外から​中の​クラスに​依存している​クラスの​数、​Ce は​中から​外の​クラスに​依存している​クラスの​数。​0 が​最も安定
  • A = 抽象クラスの​数 ÷ クラスの総数
  • (0, 1) と (1, 0) を​結ぶ​線が Main Sequence (メイン系列)。​線からの​距離 D′ = |A + I − 1⁠|。​(0, 0) と (1, 1) の​付近は、​論文では​「zone of exclusion」​(避けるべき領域)

この記事の​コードを、​この​定義に​沿って​数えてみました。​数え方は​この​記事で​決めた​ものです。

  • 対象は src/ の 12 ファイルです (テストの​ファイルと、​12 章の​比較用の​版は​除きました)
  • Ca と Ce は、​1 つの​ファイルを​論文の​「クラス」に​当てはめ、​ほかの​まとまりの​ファイルを import している​ファイルの​数で​数えました
  • A は、ファイルではなく​宣言の​数で​数えました。export interface の宣言を抽象、export class の宣言を​具象とし、​A = interface の数 ÷ (interface と class の​数の​合計) です。​型の​別名と​関数は​数えていません。​たとえば use-cases は interface 7 つと class 1 つで、​A = 7 ÷ 8 = 0.88 です
  • main には interface も class も​無く、​A は 0 ÷ 0 に​なります。​表では​これを 0 と​みなしました

12 ファイルしかない​小さな​例なので、​数値は​目安です。

横軸が不安定さ I、縦軸が抽象度 A のグラフ。左上 (0, 1) から右下 (1, 0) への斜めの線がメイン系列。1 entities は I 0、A 0。2 use-cases は I 0.29、A 0.88。3 adapters/web は I 0.67、A 0。4 adapters/persistence は I 0.5、A 0。5 main は I 1、A 0 zone ofexclusionzone ofexclusionメイン系列00.5100.51I (不安定さ) →A (抽象度) →12345
不安定さ I と抽象度 A のグラフと、​この​記事の​コードの 5 つの​まとまり (番号は​下の​表)。​斜めの​線が​メイン系列、​色を​付けた 2 つの​角が​「Stability」​の論文で​いう zone of exclusion (避けるべき領域) です。
番号 まとまり Ca Ce I A D′
1 entities 5 0 0.00 0.00 1.00
2 use-cases 5 2 0.29 0.88 0.16
3 adapters/web 1 2 0.67 0.00 0.33
4 adapters/persistence 2 2 0.50 0.00 0.50
5 main 0 2 1.00 0.00 (0 とみなした) 0.00

use-cases は Port が​インターフェースなので​メイン系列の​近くに​あり、​main は​誰からも​依存されない​具体的な​部品と​して (1, 0) に​います。​目を​引くのは entities で、​全員から​依存され、​何にも​依存せず、​具体的な​クラスだけなので、​式の​上では (0, 0) の​真ん中 (D′ = 1) に来ます。

「Stability」​の論文は、​(0, 0) の​付近に​あっても、​文字列の​クラスのように​変わりにくい​ものなら​害は​ない、と​書いています。​Entities に​置くのは​「外の​何かが​変わっても​変わりにくい規則」​なので、​この​位置は​設計の​意図通りとも​言えます。​ただし、​承認権限規程のように​業務の​都合で​変わる​規則も Entities にはあります。​その​ときは、​内側の​変更が​外側へ​波及する​ことを​受け入れる (向きは​正しい)、​Entities の​公開する​面を​小さく​保つ、の 2 つで​影響を​抑える、とこの​記事では​考えます。​指標は​「どこを​見直すか」の​手がかりで、​点数を​上げる​こと自体を​目的に​する​ものではありません。

12. 層に​分けない​版と​比べる

この記事の​コードの​量を​数えてみました。​テストと​テスト用の​メモリ版、​試すための​データの​スクリプト、​HTTP サーバーの​起動、​表の​定義を​除くと、​Entities から Main までで 517 行 (空行と​コメントを​含む) です。​比べる​ために、​同じ​振る舞いを 1 つの HTTP の​処理の​中に​全部​書いた​版も​作りました。​こちらは 41 行です。​同じ​申請に​同じ順で 5 回承認を​試し、​断る・​承認する・​支払いを​依頼するの​結果が​同じに​なる​ことを​確かめました (次の​承認者の​名前と​承認日時は​返さない、​簡略な​版です)。

比べる​ための​版 (41 行) を開く

compare/all-in-one.ts

import type { DatabaseSync } from 'node:sqlite';

type Reply = { status: number; body: Record<string, string> };

/** 比べるための版: 同じ「承認する」を、HTTP の処理の中に全部書いたもの */
export function approveHandler(db: DatabaseSync, reportId: string, userId: string | null): Reply {
  if (!userId) return { status: 401, body: { message: 'ログインしてください。' } };
  db.exec('BEGIN IMMEDIATE');
  try {
    const reply = approveInTransaction(db, reportId, userId);
    db.exec(reply.status === 200 ? 'COMMIT' : 'ROLLBACK');
    return reply;
  } catch (error) {
    db.exec('ROLLBACK');
    throw error;
  }
}

function approveInTransaction(db: DatabaseSync, reportId: string, userId: string): Reply {
  const report = db.prepare('SELECT * FROM expense_reports WHERE id = ?').get(reportId) as
    | { applicant_id: string; status: string }
    | undefined;
  if (!report) return { status: 404, body: { message: '申請が見つかりません。' } };
  if (report.status !== 'submitted') return { status: 409, body: { message: 'この申請は、いま承認を受け付けていません。' } };
  if (report.applicant_id === userId) return { status: 403, body: { message: '自分の申請は承認できません。' } };
  const step = db
    .prepare('SELECT step_no, approver_id FROM approval_steps WHERE report_id = ? AND approved_at IS NULL ORDER BY step_no')
    .get(reportId) as { step_no: number; approver_id: string } | undefined;
  if (step?.approver_id !== userId) return { status: 403, body: { message: 'いまはあなたが承認する順番ではありません。' } };

  db.prepare('UPDATE approval_steps SET approved_at = ? WHERE report_id = ? AND step_no = ?')
    .run(new Date().toISOString(), reportId, step.step_no);
  const { total } = db.prepare('SELECT SUM(amount_yen) AS total FROM expense_lines WHERE report_id = ?').get(reportId) as { total: number };
  const { rest } = db.prepare('SELECT COUNT(*) AS rest FROM approval_steps WHERE report_id = ? AND approved_at IS NULL').get(reportId) as { rest: number };
  if (rest === 0) {
    db.prepare("UPDATE expense_reports SET status = 'approved' WHERE id = ?").run(reportId);
    db.prepare('INSERT INTO payment_requests VALUES (?, ?, ?)').run(reportId, report.applicant_id, total);
  }
  const message = rest === 0 ? '承認しました。経理に支払いを依頼しました。' : '承認しました。';
  return { status: 200, body: { message, total: `${total.toLocaleString('ja-JP')}円` } };
}

1 つの​ユースケースだけなら、​10 倍以上の​行数です。​ただし、​2 つ目の​ユースケース (差し戻しなど) を足すときは、​Entities・​Repository・​Main の多くを​そのまま​使えるので、​差は​縮まります。​逆に、​規則が​この​程度で​増えないと​分かっているなら、​41 行の​版の​方が​読みやすく、​直しやすいでしょう。​どちらが​良いかは、​規則と​変更の​量で​決まる、とこの​記事では​考えます。​層に​分ける​書き方への​批判は​理論編の 8 章に​まとめています。

13. テスト戦略

Martin は 2017 年の​ブログ​「Test Contra-variance」​で、本番の​コードの​構造に​合わせて​テストを​組むと、​振る舞いを​変えない​リファクタリングでも​テストが​大量に​壊れる (the Fragile Test Problem) と書き、​こう​勧めています。

Design the structure of your tests to be contra-variant with the structure of your production code.

(テストの​構造は、​本番の​コードの​構造と​反変に​なるように​設計せよ)

— 「Test Contra-variance」​(2017 年の​ブログ)

本番の​クラス 1 つに​テストの​クラス 1 つを​対応させると、​本番の​コードを​整理しただけで​テストが​壊れます。​テストは​振る舞い (Port の​外から​見える​こと) を​確かめ、​内部の​分け方には​結びつけない​方が​よい、とこの​記事では​読みます。​本には​第 28 章​『The Test Boundary』があります。

この記事の​テストは、​次のように​役割を​分けています。

種類 何を確かめるか 偽物 件数
Entities 業務の規則 使わない 7
ユースケース 保存・​支払依頼・​出力の​組み立て メモリ版の Port 4
Presenter 文言・​状態コード・​日本時間 使わない 2
契約 偽物と​本物が​同じ​約束を​守るか メモリ版と SQLite 版の両方 6
通し 組み立て・​トランザクション・​seed のやり直し 使わない (SQLite は​メモリ上か​ファイル) 4
依存性の​ルール import の向き なし 1

14. DDD などとの関係

ドメイン駆動設計 (DDD)

Martin Fowler の解説​「Domain​DrivenDesign」​によると、​ドメイン駆動設計は、​業務の​過程と​規則を​よく​理解した​ドメインモデルを​中心に​開発を​進める​考え方で、​名前は Eric Evans の 2003 年の​本から​来ています。​クリーンアーキテクチャが​「依存の​向き」を​決めるのに​対し、​DDD は​「内側に​何を​どう​書くか」を​詳しく​扱う、と​この​記事では​整理します。

Fowler の​解説の​言葉を​借りて、​この​記事の​コードを​読むと​次のようになります。

  • Money は値オブジェクト。​属性の​組み合わせだけで​意味が​決まり、​同じ値なら​同じ​ものとみなすオブジェクトです (Fowler​「ValueObject」​「EvansClassification」)
  • ExpenseReport は、明細や​承認の​段を​含めて 1 つの​単位と​して​扱う​集約。​Fowler は、​注文と​その​明細を 1 つの​単位と​して​扱う​例を​挙げています (Fowler​「DDD_Aggregate」)
  • 経費精算と​会計は​別々の​境界づけられた​コンテキスト (Bounded Context) で、PaymentRequests はその 2 つを​つなぐ​口。​大きな​モデルを​複数の​コンテキストに​分け、​その間の​関係をはっきりさせる​考え方です (Fowler​「BoundedContext」)

CQRS

CQRS (Command Query Responsibility Segregation) は、更新に​使う​モデルと​読み取りに​使う​モデルを​分ける​考え方です。​Fowler は 2011 年の​解説で、​Greg Young から聞いた​考え方だと​紹介しつつ、​こう​注意しています。

for most systems CQRS adds risky complexity.

(たいていの​システムでは、​CQRS は​危うい​複雑さを​足すことになる)

— Martin Fowler​「CQRS」​(2011)

マイクロサービス

Martin は 2014 年の​ブログ​「Clean Micro-service Architecture」​でこう​書いています。

Micro-services are a deployment option, not an architecture.

(マイクロサービスは​デプロイの​選択肢であって、​アーキテクチャではない)

部品が​別の​サーバーで​動いているのか、​同じ​プロセスの​中で​関数と​して​呼ばれているのかを、​部品の​コードが​知らずに​済むように​しておけば、​配置は​後から​選べる、と​いう​主張です。​同じ​記事は、​サーバーを​複数台に​分ける​前提で​大きな 3 層構成を​最初から​作り、​結局 1 台で​足りた​例を​挙げて、​配置を​知らないままに​しておく​ことを​破るのは​過剰設計への​近道だ、​とも​書いています。​本には​第 27 章​『Services: Great and Small』が​あります。

この記事の​コードでは、PaymentRequests の実装を​「同じ​データベースの​表に​書く」から​「会計システムの API を​呼ぶ」に​替えても、​ユースケースは​変わりません。​ただし 10 章で​書いた​とおり、​トランザクションの​範囲は​変わるので、​設計の​判断は​別に​要ります。

フロントエンド

関数型​プログラミング

Mark Seemann は 2016 年の​記事で​こう​書いています。

Functional architecture tends to fall into a pit of success that looks a lot like Ports and Adapters.

(関数型の​アーキテクチャは、​Ports and Adapters によく​似た​形に​自然と​落ち着きやすい)

— Mark Seemann​「Functional architecture is Ports and Adapters」​(2016)

副作用の​ない​関数を​中心に​置き、​入出力を​端に​寄せると、​同じ​形に​なる、と​いう​指摘です。​この​記事の requiredApprovals は副作用の​ない​関数で、​テストも​一番​簡単でした。

15. 既存の​システムへの​入れ方

すでに​動いている​システムを​一度に​作り直す必要は​ありません。​次の​順に、​少し​ずつ内側を​育てる​進め方を​おすすめします (この記事の​考えです)。

  1. 変更が​多くて、​間違えると​痛い​規則を 1 つ選ぶ。 経費精算なら​承認の​規則や​精算額の​計算です
  2. 今の振る舞いを​テストで​固定する。 既存の​コードを​そのまま​呼ぶ、​通しの​テストでかまいません。​直した​後に​振る舞いが​変わっていない​ことを​確かめる​ためです
  3. 規則を、​フレームワークを import しない​関数か​クラスに移す。 これが Entities の​始まりです。​既存の Controller やサービスの​クラスから、​それを​呼ぶように​変えます
  4. 手順を​ユースケースに​移し、​データベースなどは Port 越しにする。 Port の​実装は、​最初は​既存の ORM の​コードを​包むだけでかまいません
  5. 依存性の​ルールを​機械で​検査する。 この記事の dependency-rule.test.ts、dependency-cruiser、ArchUnit などです
  6. 次の変更が​来た​所から​広げる。 古い経路は、​新しい​経路に​置き換わった​所から​消していきます。​Martin Fowler が「Strangler Fig」と​呼ぶ、​古い​システムを​少し​ずつ​新しい​ものに​置き換えていく​進め方です
  7. 最初は​緩い​境界でよい。 インターフェースと​入出力の​データは​用意するが、​別の​パッケージには​分けない、と​いう​形から​始め、​分ける​理由が​出てから​分けます (本には​第 24 章​『Partial Boundaries』があります)

16. まとめと​チェックリスト

経費精算の​「申請を​承認する」を、​Entities・​ユースケース・​Interface Adapters・​Main に分けて​作り、​24 件の​テストで​確かめました。​規則は ExpenseReport の 1 か所に​あり、​データベースや HTTP を​替えても​規則の​コードは​変わらず、​依存の​向きは​テストで​検査されています。​その​代わり、​行数は​層に​分けない​版の 10 倍以上に​なりました。​どこまで​やるかは、​規則と​変更の​量を​見て​決めてください。

自分の​コードを​見直す​ときの​チェックリストです (この記事の​まとめです)。

  • 内側の​ファイルが、​外側の​ファイル・​フレームワーク・​データベースの​ライブラリを import していない。​それを​機械で​検査している
  • 最上位の​ディレクトリ名を​見れば、​何の​システムか​分かる
  • 業務の​規則が Entities (または​それに​当たる​場所) の 1 か所に​あり、​ユースケースや Controller に if 文で​散っていない
  • ユースケースは​手順を​書き、​規則の​判断は Entities に​任せている
  • Port は​内側が​定義し、​業務の​言葉で​名前を​付けている
  • 境界を​越えるのは​単純な​データで、​Entity や​データベースの​行を​そのまま​外に​渡していない
  • 表示用の​変換 (金額・​日時・​文言) が Presenter に​あり、​テストしている
  • 偽物の​実装 (メモリ版) は、​本物と​同じ​契約テストを​通っている
  • トランザクションの​範囲が、​業務の​「両方​残るか、​両方残らないか」と​合っている
  • 具体的な​部品を​組み立てる​場所 (Main) が 1 か所にある
  • Port は、​外の​世界に​触る​所か、​差し替える​理由が​ある​所にだけある
  • 小さな CRUD や​使い捨ての​コードには​使っていない (使うなら、​その​理由を​言える)
  • 図やフォルダの​形ではなく、​依存の​向きで​設計を​説明できる

考え方の​背景や​原典は、​理論編に​まとめています。

参考文献

URL は 2026 年 10 月 8 日に​開ける​ことを​確かめました。​原典の​一覧は​理論編の​参考文献にも​あります。

Robert C. Martin のブログ・​記事 (本文を​確かめて​引用したもの)

Robert C. Martin の本 (目次で​章の​題名を​確かめたもの)

  • 『Clean Architecture: A Craftsman’s Guide to Software Structure and Design』​(Pearson, 2017)。​出版社の目次

Node.js の​公式の​資料 (変更履歴で​版を​確かめたもの)

  • Modules: TypeScript (型を書いたまま .ts を実行する​機能が​既定で​有効に​なった​版: v23.6.0・​v22.18.0)
  • SQLite (--experimental-sqlite のフラグが​要らなくなった​版: v23.4.0・​v22.13.0)

関連する​考え方

道具