クリーンアーキテクチャの実践編:経費精算の承認を作ってテストする
クリーンアーキテクチャを、手を動かして確かめる記事です。経費精算の「申請を承認する」を題材に、業務の規則から、画面に返す形、データベース、テストまで、動くコード (TypeScript) を全部載せます。
この記事は 2 本組みの「実践編」です。
- 理論編:何のために分けるのか、どこから来た考えか、依存性のルール、境界の越え方、設計の原則、誤解と批判を、確かめられる原典を引きながら解説
- 実践編 (この記事):経費精算の実例、ディレクトリ構成、テスト戦略、DDD・CQRS・フロントエンドとの関係、既存のシステムへの入れ方、チェックリスト
どちらから読んでも分かるように書いています。理論編をまだ読んでいなくても、次の「3 行で振り返る」だけでコードは読めます。
クリーンアーキテクチャを 3 行で振り返る
source code dependencies can only point inwards.
(ソースコードの依存は、内側へだけ向けてよい)
— Robert C. Martin「The Clean Architecture」(2012 年のブログ)
- 内側に業務の規則 (Entities とユースケース)、外側に画面・データベース・フレームワークを置く
- ソースコードの依存 (import) は外から内へだけ向ける。内側は外側の名前を一切書かない
- 内側から外側を呼びたいとき (ユースケース → Presenter、ユースケース → データベース) は、内側にインターフェース (Port) を置き、外側がそれを実装する
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/
/** 円の金額。経費精算では 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/
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/
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/
// 「申請を承認する」の入口と出口。ここに出てくる型は、どれもただのデータ
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/
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/
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/
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/
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/
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/
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/
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/
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/
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/
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/
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/
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/
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/
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/
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 ファイルしかない小さな例なので、数値は目安です。
| 番号 | まとまり | 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/
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 の解説「DomainDrivenDesign」によると、ドメイン駆動設計は、業務の過程と規則をよく理解したドメインモデルを中心に開発を進める考え方で、名前は 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 つ選ぶ。 経費精算なら承認の規則や精算額の計算です
- 今の振る舞いをテストで固定する。 既存のコードをそのまま呼ぶ、通しのテストでかまいません。直した後に振る舞いが変わっていないことを確かめるためです
- 規則を、フレームワークを import しない関数かクラスに移す。 これが Entities の始まりです。既存の Controller やサービスのクラスから、それを呼ぶように変えます
- 手順をユースケースに移し、データベースなどは Port 越しにする。 Port の実装は、最初は既存の ORM のコードを包むだけでかまいません
- 依存性のルールを機械で検査する。 この記事の
dependency-rule.test.ts、dependency-cruiser、ArchUnit などです - 次の変更が来た所から広げる。 古い経路は、新しい経路に置き換わった所から消していきます。Martin Fowler が「Strangler Fig」と呼ぶ、古いシステムを少しずつ新しいものに置き換えていく進め方です
- 最初は緩い境界でよい。 インターフェースと入出力のデータは用意するが、別のパッケージには分けない、という形から始め、分ける理由が出てから分けます (本には第 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 のブログ・記事 (本文を確かめて引用したもの)
- The Clean Architecture (2012-08-13)
- Clean Micro-service Architecture (2014-10-01)
- Test Contra-variance (2017-10-03)
- Stability (C++ Report の連載「Engineering Notebook」の 1 本。Object Mentor の公開版を Internet Archive で閲覧)
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)
関連する考え方
- Martin Fowler, Domain Driven Design・Value Object・Evans Classification・DDD Aggregate・Bounded Context
- Martin Fowler, CQRS (2011-07-14)
- Martin Fowler, Optimistic Offline Lock (Patterns of Enterprise Application Architecture のカタログ)
- Martin Fowler, Strangler Fig
- Chris Richardson, Pattern: Transactional outbox (microservices.io)
- Simon Brown, Modular monolith and “package by component”
- Mark Seemann, Functional architecture is Ports and Adapters (2016-03-18)
道具
- ArchUnit (Java の構造のテスト)
- dependency-cruiser (JavaScript・TypeScript の依存の検査)