Apex Stem思想で統一された Apex 開発スタック
Handler-Usecase Architecture と4 つの OSS ライブラリ。
5 年間運用され技術的負債で身動きが取れなくなった現場に、
リファクタリングと健全な機能追加を重ね続けた末に生まれました。
規約が薄いからこそ、AI コーディングアシスタントが迷わず従える。 AI 時代のために設計された開発スタックです。
Apex Stem を構成する 3 つの要素
設計
Handler-Usecase Architecture
道具
4 つの OSS ライブラリ
規律
層と 1 対 1 で対応するテスト戦略
The Stack
4 つの OSS ライブラリと、1 つのアーキテクチャ。
それぞれ単体でも、まとめてスタックとしても導入できます。
ApexEloquent
モックを前提に設計された SOQL/DML の ORM。Usecase 層の単体テストで使います。
⚡ MockEntry による SELECT 漏れ検知
ApexBlueprint
宣言的なテストデータファクトリ。 実 DML を流すHandler 層の結合テストで使います。
⚡ レイヤー化トポロジカルソートによる bulk DML
GitHub →ApexTrace
Usecase のライフサイクルログ。Trace.of() を起点に start / skip / finish / log。
⚡ TraceFlow によるテストの振る舞い検証
GitHub →ApexTools
TriggerHandler 基底クラスと、 DI 対応の HTTP リクエストラッパー。
⚡ after-update ハンドラ向けのフィールド変更検知ヘルパー
GitHub →さらに、LWC ↔ Apex 境界のための薄い Result DTO 規約 も。 まずは 1 つのライブラリから。どこからでも始められます。
Handler-Usecase Architecture
2 つの層、層ごとに 1 つのルール。あとは現場に委ねます。
Handler Layer
Integration tests · ApexBlueprintエントリーポイント (Trigger / Batch / REST / Flow / Schedulable)。 各エントリーポイント固有の作法を吸収し、Usecase に渡すだけ。ここにビジネスロジックは置きません。
Usecase Layer
Unit tests · ApexEloquent (mock DB)ビジネスロジック。public は invoke() のみ。 コンストラクタで全依存を受け取り、生焼けオブジェクトを作りません。
Define the stem only
幹となるアーキテクチャ (Handler + Usecase) だけを定義します。 そこから伸びる枝葉のクラス (Reader や Validator のような部品) をどう切り出すかは強制しません。
Tests map 1-to-1
Handler → 実 DML の結合テスト。 Usecase → モック DB の単体テスト。 どこでも同じ規約です。
AI-friendly by design
シンプルな規約だから、AI に読み込ませる開発ルールとして 無理なく機能します。コンテキストを圧迫しすぎず、 生成されるコードもブレません。
なぜ 2 層なのか、各層の責務、部品クラスの扱いまでをじっくり読み解きます
The Story
The Challenge
▸5 年運用された Salesforce 組織。トリガーがトリガーを呼ぶ負債、実質何も検証していないアサーション、呼ぶだけでガバナ制限に達する TestDataFactory。
▸fflib は少人数のチームには重すぎる。かといってベタ書きの SOQL は、複雑なデータ構造を必要とするテストに耐えられない。
▸AI コーディングアシスタントが実際に従える何かが欲しかった。CLAUDE.md に収まるくらい小さな規約を。
What emerged
▸少しずつ立て直しました。Usecase 1 つ、モック可能なクエリ 1 本ずつ。
▸最初は ApexEloquent。必要が見えてくるたびに ApexBlueprint、ApexTrace、ApexTools が続きました。
▸このスタックは今、AI とともに安定した品質のコードを継続的に生み出すための土台になっています。