Installing Apex Stem
Apex Stem の各フレームワークは Unlocked Package(2GP、名前空間なし)と git submodule の2つの経路で導入できます。どちらも中身は同じソースです。プロジェクトごとに選べますし、org によって使い分けても問題ありません。
Which path should I take?
| Unlocked Package(推奨) | Git Submodule | |
|---|---|---|
| 向いている場面 | 新規プロジェクト、本番 org | submodule 運用中の既存プロジェクト、コントリビュータ |
| デプロイ時のフレームワークテスト | RunLocalTests から除外。validate がフレームワークのテストを実行しない(=落ちない) | ローカルテストとして毎回実行される |
| org のカバレッジ計算 | フレームワークのコードは計算から除外 | コードもテストも計算に含まれる |
| バージョンの可視性 | sf package installed list で正確なバージョンが見える | submodule の git タグを確認する |
| アップグレード | 次バージョンをインストールするだけ(上書き) | git submodule update --remote |
| ディレクトリ階層 | retrieve 直後はフラット。npx apex-librarian arrange で復元できる(後述) | submodule がそのまま保持する |
パッケージ経路を用意した理由は、実レコードを作るフレームワークテスト(たとえば ApexBlueprint の結合テスト)が、org 固有の入力規則や必須項目と衝突しうるためです。パッケージとして導入すれば、それらのテストはデプロイと validate では実行されません。リリースを止める失敗クラスが丸ごと消えます。
なお、sf apex run test -l RunLocalTests で手動実行したときは、名前空間を持たないアンロックパッケージのテストも対象に入ります (Salesforce CLI のヘルプでも、デプロイ側と手動実行側で RunLocalTests の定義が書き分けられています)。Apex Stem のパッケージは名前空間なしで発行しているので、手動実行ではフレームワークのテストも走ります。そこで落ちたテストのクラスが ManageableState = installedEditable なら、パッケージ由来なので無視して構いません。
Current versions
| Framework | Version | Install command |
|---|---|---|
| ApexEloquent | v4.0.1 | sf package install -p 04tgK000000axpZQAQ -o <your-org> -w 10 |
| ApexBlueprint | v2.2.2 | sf package install -p 04tgK000000b1gHQAQ -o <your-org> -w 10 |
| ApexTrace | v1.6.1 | sf package install -p 04tgK000000b1ZpQAI -o <your-org> -w 10 |
| ApexTools | v1.2.1 | sf package install -p 04tgK000000b1YDQAY -o <your-org> -w 10 |
各フレームワークは完全に独立しています。インストール順の制約も相互依存もありません。必要なものだけ入れてください。
ブラウザからインストールする場合は https://login.salesforce.com/packaging/installPackage.apexp?p0=<install ID> を開きます(Sandbox は test.salesforce.com に読み替え)。過去バージョンの install ID は各リポジトリの GitHub Releases に載っています。
ApexEloquent / ApexBlueprint / ApexTrace / ApexTools
Git submodule
cd /path/to/your/project
git submodule add https://github.com/krile136/ApexEloquent.git force-app/main/default/classes/ApexEloquent
git submodule add https://github.com/krile136/ApexBlueprint.git force-app/main/default/classes/ApexBlueprint
git submodule add https://github.com/krile136/ApexTrace.git force-app/main/default/classes/ApexTrace
git submodule add https://github.com/krile136/ApexTools.git force-app/main/default/classes/ApexTools
git submodule update --init --recursive
sf project deploy start -d force-app/main/default/classes/<Name> で通常のソースフォルダと同じようにデプロイできます。submodule を使うプロジェクトをクローンするときは git clone --recurse-submodules を忘れずに。
Switching from submodules
submodule のソースで導入済みの org にパッケージを入れる場合も、既存クラスを先に消す必要はありません。同名の unmanaged クラスがあると、インストール時にパッケージがその所有権を引き取ります (ManageableState が unmanaged から installedEditable に変わります)。
- 小さいものから 1 本ずつ入れる (ApexTools → ApexTrace → ApexBlueprint → ApexEloquent)。まとめて入れると、失敗したときに切り分けられません
- インストール時に org の全テストは走りません。本番 org でも 1 本あたり数十秒から数分で終わった実測があります
- 確認は
ManageableStateで行う。sf package installed listへの反映は遅れることがあります
sf data query -o <your-org> --use-tooling-api -r csv \
-q "SELECT ManageableState, COUNT(Id) c FROM ApexClass WHERE NamespacePrefix = null GROUP BY ManageableState"
⚠️ 引き取った後は、submodule をデプロイ対象に含めないでください。 含めると
installedEditableのクラスをunmanagedで上書きし、状態が巻き戻ります。リポジトリの submodule は、ソースの参照元とバージョンの記録として残しておけば十分です。
Restoring the directory layout
Salesforce の org には Apex クラスのフォルダという概念がありません。そのため、パッケージでインストールしたクラスを sf project retrieve で手元に取得すると、すべて classes/ 直下にフラットに落ちてきます。
ApexEloquent v4.0.0 / ApexBlueprint v2.2.0 / ApexTrace v1.6.0 / ApexTools v1.2.0 以降、全クラスが自分の置き場所を @directory doc コメントタグとして持っています。retrieve のあとに npm モジュール ApexLibrarian を 1 回実行するだけで、submodule 導入時と同一のディレクトリ階層に戻せます。
npx apex-librarian arrange
.cls-meta.xml も必ずペアで移動します。仕組みと他のコマンド (check / stamp) の説明もリンク先にまとめています。
Next steps
- はじめての方は Get Started with Apex Stem から
- 各フレームワークのガイド: ApexEloquent / ApexBlueprint / ApexTrace / ApexTools