ApexEloquent トップへ

ApexEloquent ガイド

ApexEloquent は、SOQL と DML を「型付きで組み立て可能なクエリビルダー」と「DI 可能なデータアクセス層」で扱う Apex Stem の中心 OSS です。Setup (事前準備・インストール)、プロダクションコードでの使い方を解説する 使い方ガイド、各クラスの API を網羅する API リファレンス、設計の動機を掘り下げる Deep Dives の 4 段構えで構成しています。

バージョンについて

現行は v3 系と v2 系です。 違いは実行モードだけで、v3 系は SOQL / DML の既定が ユーザーモード (項目・オブジェクト権限を尊重) になっています。 それ以外の機能は同じです。

本ガイドは共通の内容として書き、モードの差分だけ個別に示します。 使っているバージョンは次で確認できます。

git -C force-app/main/default/classes/ApexEloquent describe --tags

Setup

ApexEloquent を最初に組織へインストールするまでの導線を、環境セットアップから順に解説します。

Setup

事前準備

ApexEloquent を導入する前に押さえておきたい Salesforce CLI / 対象組織 / make コマンドのセットアップを 4 ステップで確認します。

Salesforce CLISetupmake
Setup

インストールガイド

コマンド1つで入る Unlocked Package (推奨) と、Git Submodule + make install の2つの導入経路を並べて解説します。それぞれの更新手順も扱います。

Unlocked PackageGit SubmoduleDeploy

使い方ガイド

プロダクションコードでの典型シナリオを Usecase / Handler 文脈で解説します。

使い方ガイド

Scribe でクエリを組み立てる

型付きメソッドチェーンで SOQL を組み立てるクエリビルダー Scribe の使い方。SELECT・WHERE・並び替え・集計・動的なクエリ組み立てまでを 1 本でまとめます。

ScribeSOQLQuery Builder
使い方ガイド

データ取得と DML、IEntry、Mock

IEloquent インターフェース経由でのデータ取得と DML、IEntry の扱い方、MockEloquent によるテストまで。Layered Constructor Pattern との統合や Spy / failOn による検証も解説。

IEloquentIEntryMockEloquentDMLTesting
使い方ガイド

親項目・子サブクエリ・多対多

親リレーション、子サブクエリ、Junction Object 経由の多対多を Scribe で組み立てる方法と、MockEntry の setParent / setChildren で親子をモックする方法。

RelationsJunctionMockEntry

API リファレンス

クラスごとに全 API をシグネチャ付きで網羅した詳細リファレンスです。

API リファレンス

Scribe

Scribe クエリビルダーの全 API を整理した詳細リファレンス。Static ファクトリ・SELECT・WHERE・並び替え・集計関数・GROUP BY / HAVING・検査メソッドを網羅。

ScribeQuery Builder
API リファレンス

IEloquent / Eloquent / MockEloquent

データアクセスのインターフェースと、その本番実装 Eloquent、テスト実装 MockEloquent の API リファレンス。共通契約、Spy プロパティ、failOn シリーズまで網羅。

IEloquentMockEloquentDML
API リファレンス

IEntry / Entry / MockEntry

レコードラッパーのインターフェースと、本番実装 Entry、テスト実装 MockEntry の API リファレンス。フィールド・リレーション操作、テスト用の拡張 API (set / template / setParent / setChildren / autoId / alias / asAggregateResult ほか) を網羅。

IEntryMockEntryTesting

Deep Dives

ApexEloquent の設計哲学、Apex 文脈での Repository パターンの落とし所、生 SOQL からの移行など、なぜこの形に落ち着いたかを掘り下げる読みものです。

Deep Dive

Query Delegation Pattern

ApexEloquent の設計哲学。Selector Pattern の長期運用課題を出発点に、クエリ構築と実行を分けることでどんな問題が解けるのか、Scribe / IEloquent / IEntry がそれをどう体現しているのかを解説します。

ArchitectureDesign PatternSelector
Deep Dive

Apex における Repository パターンの試行錯誤と内蔵化

Apex で Repository パターンを愚直に書くと何が起きるか、Salesforce 公式の Selector Pattern との関係、ApexEloquent が IEloquent として「内蔵 Repository」を提供する理由を、公式メリットと長期運用副作用の対比で解説します。

SelectorRepositoryBuilt-in Repository
Deep Dive

Apex の生 SOQL から、チェーンメソッドで組み立てる ORM へ

生 SOQL 中心の Apex 開発で支払っている代償 (可読性 / 動的条件 / 型安全性 / リレーション / テスト) を、Scribe + IEloquent でどう軽くするかを実例ベースで解説する移行入門です。

SOQLScribeMigration
Deep Dive

MockEntry: Apex のテストデータ作成を成立させる仕組み

書き込み不可項目 (数式 / ロールアップ / auto-number / リレーション名) と親子関係構築の困難という Apex のテスト 2 大課題を、MockEntry の override map / SELECT 漏れ検知 / setParent・setChildren / times プレースホルダ / 集計結果のモックでどう解決するかを網羅的に解説します。

MockEntryTest DataNon-writable Fields
Deep Dive

モックテストの偽陽性を検知する: SELECT 漏れの安全網

「テストでは通って本番で落ちる」タイプの偽陽性問題を、ApexEloquent が Scribe との連携で構造的に塞いでいる仕組みを、主オブジェクト / 親リレーション / 子サブクエリ / 集計エイリアスの 4 ケースで「バグ入り Usecase + テストが catch する」ペアの実コード例で実証します。

False PositiveSELECT 漏れTesting

次に読む