best-practices

AEM as a Cloud Service — ベストプラクティス

AEM as a Cloud Service のプラットフォームに関するガイダンスです。Java/OSGi（何を使うか、何を避けるか、レガシーパターンをどのようにリファクタリングするか）と HTL（コンポーネントの .html テンプレート、Cloud SDK HTL lint）を扱います。

このスキルには、パターン変換モジュール（references/*.md）が含まれています。これらは aem-cloud-service プラグインに同梱されています。これらのリファレンスだけが必要な新規開発や保守作業では、migration スキルを使わずにこのスキルを使用してください。BPA/CAM のオーケストレーションが必要な場合は、migration を使用してください。

すぐに選ぶには： 以下の パターンリファレンスモジュールの表を開き、該当する references/<file>.md に移動して、編集前に全体を読んでください。Java では、同じ変更セットに該当するものがある場合、Felix SCR、リゾルバー、ロギングについては、まず Java / OSGi の基本ガイドのリンクを使用してください。

このスキルを使用する場面

次のような場合にこのスキルを使用してください。

• AEM as a Cloud Service の制約を Java/OSGi コード（新規または既存）に適用する
• レガシー Java パターンをサポート対象の API にリファクタリングする（migration が使用するものと同じモジュールです）
• スケジューラー、レプリケーション、JCR 観察リスナー（eventListener）、OSGi イベントハンドラー（eventHandler）、DAM アセット全体で一貫したルールに従う
• AEM Cloud SDK ビルドで検出される HTL（Sightly） の問題を修正する。特に data-sly-test: redundant constant value comparison
• 特定のパターンに関する段階的な変換手順と検証チェックリストを確認する

BPA/CAM のオーケストレーション（コレクション、CSV、MCP プロジェクトの選択）には、migration スキル（skills/aem/cloud-service/skills/migration/）を使用してください。

パターンリファレンスモジュール

サポート対象の各パターンには、SKILL.md からの相対パスで references/ 配下に専用モジュールがあります。

パターン / トピック	BPA パターン ID	モジュールファイル	ステータス
スケジューラー	scheduler	references/scheduler.md	対応済み
リソース変更リスナー	resourceChangeListener	references/resource-change-listener.md	対応済み
レプリケーション	replication	references/replication.md	対応済み
イベントリスナー（JCR 観察）	eventListener	references/event-migration.md	対応済み
イベントハンドラー（OSGi Event Admin）	eventHandler	references/event-migration.md	対応済み
アセットマネージャー	assetApi	references/asset-manager.md	対応済み
Felix SCR → OSGi DS	—	references/scr-to-osgi-ds.md	対応済み
ResourceResolver + SLF4J	—	references/resource-resolver-logging.md	対応済み
HTL: data-sly-test の冗長な定数比較	—（HTL lint）	references/data-sly-test-redundant-constant.md	対応済み
(前提条件ハブ)	—	references/aem-cloud-service-pattern-prerequisites.md	—

イベントリスナーとイベントハンドラーの違い（同じものではありません）： eventListener は JCR 観察です。リポジトリの変更コールバックに関する JCR API（javax.jcr.observation.EventListener、onEvent）を指します。eventHandler は OSGi Event Admin です。ホワイトボード形式の OSGi イベント（org.osgi.service.event.EventHandler、handleEvent）を指します。どちらも references/event-migration.md を使って移行します（パス A とパス B）。resourceChangeListener は別のもので、Sling の ResourceChangeListener を指し、モジュールは references/resource-change-listener.md です。

パターンのコードを変更する前に： 該当するパターンのモジュールを最初から最後まで読んでください。各モジュールには、分類基準、順序立てられた変換手順、検証チェックリストが含まれています。

Java / OSGi の基本ガイド（同じスキル内、個別インストールは不要）

SCR→DS と ResourceResolver/ロギングは、references/ 配下のリファレンスモジュールであり、個別のスキルではありません。関連する場合は、各パターンのファイルに同じ手順を再掲する代わりに、これらを読んでください。

• ハブ： references/aem-cloud-service-pattern-prerequisites.md
• モジュール： references/scr-to-osgi-ds.md、references/resource-resolver-logging.md

重要なルール（すべてのパターン）

これらのルールはすべてのパターンモジュールに適用されます。違反すると、移行が不正になったり、安全でない Cloud Service コードになったりします。

• まずパターンモジュールを読むこと — モジュールを読まずにコードを変換してはいけません
• SCR、ResourceResolver、またはロギングが対象となる場合は、scr-to-osgi-ds.md と resource-resolver-logging.md を読むこと（パターンモジュールからは前提条件ハブを参照します。長いガイドを本文に重複して記載しないでください）
• 環境固有のガード（例：isAuthor() 実行モードチェック）を維持すること
• モジュールで明示的に許可されていない限り、メソッド内のビジネスロジック（Java）や論理的な表示／非表示の意図（HTL）を変更してはいけません
• パターンモジュールで明示的に指定されていない限り、クラス名を変更してはいけません
• 値をでっち上げてはいけません — 既存のコードから抽出してください
• ユーザーと合意した範囲外のファイルを編集してはいけません（例：BPA の対象のみ、またはユーザーが指定したパスのみ）
• 顧客の AEM ソースに対する検索、調査、編集は、現在開いているIDE ワークスペースのルート内で行うこと。ユーザーから明示的な指示がない限り、Java ファイルを探すためにその境界の外を grep したり、ディレクトリをたどったりしてはいけません

手動でのパターン判定のヒント（分類）

BPA リストがない場合は、インポートと型を調べてモジュールを選択します。

確認するもの	パターン
org.apache.sling.commons.scheduler.Scheduler または Runnable を伴う scheduler.schedule(	scheduler
implements ResourceChangeListener	resourceChangeListener
com.day.cq.replication.Replicator または org.apache.sling.replication.*	replication
JCR オブザベーション： javax.jcr.observation.EventListener、onEvent(EventIterator)、javax.jcr.observation.*	eventListener
OSGi Event Admin： org.osgi.service.event.EventHandler、実質的な handleEvent（リゾルバー／セッション／ノード操作）	eventHandler
com.day.cq.dam.api.AssetManager のアセット作成／削除 API	assetApi
org.apache.felix.scr.annotations	references/scr-to-osgi-ds.md を読む（多くの場合、BPA パターンと併用）
getAdministrativeResourceResolver、System.out／printStackTrace	references/resource-resolver-logging.md を読む
HTL： ビルド警告 data-sly-test: redundant constant value comparison、または不適切な data-sly-test を含む ui.apps／jcr_root 配下の .html	references/data-sly-test-redundant-constant.md を読む

複数のパターンが該当する場合は、どれを先に修正するか確認してください。

移行との関係

migration スキルでは、セッションごとに1つのパターンというワークフロー、BPA／CAM／MCP のフロー、およびユーザーへのメッセージを定義します。詳細な変換手順は、このスキルの references/ モジュールに委譲します。このスキルでは、リポジトリルートの {best-practices} パスエイリアスを使用します（詳細はその SKILL.md を参照）。プラットフォームに関する正確な情報はここに、オーケストレーションはそちらに保持してください。