best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AEM as a Cloud Service — Best Practices

AEM as a Cloud Service — 最佳实践

Platform guidance for AEM as a Cloud Service: Java/OSGi (what to use, what to avoid, how to refactor legacy patterns) and HTL (component

.html

templates, Cloud SDK HTL lint).

This skill holds the pattern transformation modules (

references/*.md

). They ship with the aem-cloud-service
plugin; use this skill without the migration skill for greenfield or maintenance work that only needs these references. Use migration when you need BPA/CAM orchestration on top.

Quick pick: Open the Pattern Reference Modules table below → jump to the matching

references/<file>.md

→ read it fully before editing. For Java: Felix SCR, resolvers, or logging, use Java / OSGi baseline links first when those appear in the same change set.

AEM as a Cloud Service平台指南：Java/OSGi（适用方案、规避事项、遗留模式重构方法）以及HTL（组件

.html

模板、Cloud SDK HTL代码检查）。

本技能包含模式转换模块（

references/*.md

），随**

aem-cloud-service

插件一同发布；若仅需这些参考模块进行新项目开发或维护工作，可单独使用本技能，无需搭配迁移技能。如需BPA/CAM编排功能，则需使用迁移**技能。

快速指引： 打开下方的「模式参考模块」表格 → 跳转至对应的

references/<file>.md

文件 → 在编辑代码前完整阅读该模块内容。针对Java相关的Felix SCR、解析器或日志问题，当同一变更集中出现相关链接时，请优先查看Java / OSGi基线链接。

When to Use This Skill

适用场景

Use this skill when you need to:

Apply AEM as a Cloud Service constraints to Java/OSGi code (new or existing)
Refactor legacy Java patterns into supported APIs (same modules migration uses)
Follow consistent rules across schedulers, replication, JCR observation listeners (
```
eventListener
```
), OSGi event handlers (
```
eventHandler
```
), and DAM assets
Fix HTL (Sightly) issues from the AEM Cloud SDK build, especially
```
data-sly-test: redundant constant value comparison
```
Read step-by-step transformation and validation checklists for a specific pattern

For BPA/CAM orchestration (collections, CSV, MCP project selection), use the migration
skill (

skills/aem/cloud-service/skills/migration/

在以下场景中可使用本技能：

为Java/OSGi代码（新代码或现有代码）应用AEM as a Cloud Service约束
将遗留Java模式重构为受支持的API（与迁移技能使用相同模块）
在调度器、复制机制、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/

）。

Pattern Reference Modules

模式参考模块

Each supported pattern has a dedicated module under

references/

relative to this

SKILL.md

Pattern / topic	BPA Pattern ID	Module file	Status
Scheduler	`scheduler`	`references/scheduler.md`	Ready
Resource Change Listener	`resourceChangeListener`	`references/resource-change-listener.md`	Ready
Replication	`replication`	`references/replication.md`	Ready
Event listener (JCR observation)	`eventListener`	`references/event-migration.md`	Ready
Event handler (OSGi Event Admin)	`eventHandler`	`references/event-migration.md`	Ready
Asset Manager	`assetApi`	`references/asset-manager.md`	Ready
Felix SCR → OSGi DS	—	`references/scr-to-osgi-ds.md`	Ready
ResourceResolver + SLF4J	—	`references/resource-resolver-logging.md`	Ready
HTL: `data-sly-test` redundant constant	— (HTL lint)	`references/data-sly-test-redundant-constant.md`	Ready
(Prerequisites hub)	—	`references/aem-cloud-service-pattern-prerequisites.md`	—

Event listener vs event handler (not the same): eventListener
is JCR observation — the JCR API for repository change callbacks (

javax.jcr.observation.EventListener

onEvent

). eventHandler
is OSGi Event Admin — whiteboard-style OSGi events (

org.osgi.service.event.EventHandler

handleEvent

). Both migrate via references/event-migration.md
(Path A vs Path B). resourceChangeListener
is separate: Sling ResourceChangeListener
, module references/resource-change-listener.md
.

Before changing code for a pattern: read the module for that pattern in full. Modules include classification criteria, ordered transformation steps, and validation checklists.

每个受支持的模式在本

SKILL.md

相对路径下的

references/

目录中都有对应的专属模块。

模式/主题	BPA模式ID	模块文件	状态
Scheduler	`scheduler`	`references/scheduler.md`	已就绪
Resource Change Listener	`resourceChangeListener`	`references/resource-change-listener.md`	已就绪
Replication	`replication`	`references/replication.md`	已就绪
Event listener (JCR observation)	`eventListener`	`references/event-migration.md`	已就绪
Event handler (OSGi Event Admin)	`eventHandler`	`references/event-migration.md`	已就绪
Asset Manager	`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` redundant constant	— (HTL lint)	`references/data-sly-test-redundant-constant.md`	已就绪
(前置条件中心)	—	`references/aem-cloud-service-pattern-prerequisites.md`	—

Event listener与event handler的区别： 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 vs 路径B）。

resourceChangeListener

是独立模块：Sling ResourceChangeListener
，对应模块为

references/resource-change-listener.md

**。

在针对某一模式修改代码前： 完整阅读该模式对应的模块内容。模块包含分类标准、有序的转换步骤和验证检查清单。

Java / OSGi baseline (same skill; no separate installables)

Java / OSGi基线（同属本技能；无需单独安装）

SCR→DS and

ResourceResolver

/logging are reference modules under

references/

— not separate skills. Read them when relevant instead of re-embedding the same steps inside each pattern file.

Hub:

references/aem-cloud-service-pattern-prerequisites.md

Modules:

references/scr-to-osgi-ds.md

references/resource-resolver-logging.md

SCR→DS和

ResourceResolver

/日志相关内容是

references/

目录下的参考模块——并非独立技能。当涉及相关内容时，请阅读这些模块，而非在每个模式文件中重复嵌入相同步骤。

中心入口：

references/aem-cloud-service-pattern-prerequisites.md

模块：

references/scr-to-osgi-ds.md

、

references/resource-resolver-logging.md

Critical Rules (All Patterns)

核心规则（所有模式通用）

These rules apply to every pattern module. Violation means incorrect migration or unsafe Cloud Service code.

READ THE PATTERN MODULE FIRST — never transform code without reading the module
READ
```
scr-to-osgi-ds.md
```
and
```
resource-resolver-logging.md
```
when SCR,
```
ResourceResolver
```
, or logging are in scope (pattern modules link via the prerequisites hub; do not duplicate long guides inline)
DO preserve environment-specific guards (e.g.
```
isAuthor()
```
run mode checks)
DO NOT change business logic inside methods (Java) or logical show/hide intent (HTL) unless the module explicitly allows it
DO NOT rename classes unless the pattern module explicitly says to
DO NOT invent values — extract from existing code
DO NOT edit files outside the scope agreed with the user (e.g. only BPA targets or paths they named)
DO keep searches, discovery, and edits for the customer's AEM sources inside the IDE workspace root(s) currently open; DO NOT grep or walk directories outside that boundary to find Java unless the user explicitly points there

以下规则适用于所有模式模块。违反规则意味着迁移错误或云服务代码存在安全风险。

务必先阅读模式模块——绝不跳过阅读模块直接转换代码
当涉及SCR、
```
ResourceResolver
```
或日志内容时，务必阅读
```
scr-to-osgi-ds.md
```
和
```
resource-resolver-logging.md
```
（模式模块会通过前置条件中心链接至这些内容；请勿在模块内重复冗长指南）
务必保留环境特定的防护逻辑（例如
```
isAuthor()
```
运行模式检查）
请勿修改方法内的业务逻辑（Java）或逻辑显示/隐藏意图（HTL），除非模块明确允许
请勿重命名类，除非模式模块明确要求
请勿自行编造值——从现有代码中提取
请勿修改与用户约定范围外的文件（例如仅修改BPA目标或用户指定路径下的文件）
务必在当前打开的IDE工作区根目录内搜索、发现和编辑客户的AEM源代码；请勿在该边界外遍历目录查找Java文件，除非用户明确指定

Manual Pattern Hints (Classification)

手动模式识别提示（分类）

When no BPA list exists, scan imports and types to pick a module:

Look for	Pattern
`org.apache.sling.commons.scheduler.Scheduler` or `scheduler.schedule(` with `Runnable`	`scheduler`
`implements ResourceChangeListener`	`resourceChangeListener`
`com.day.cq.replication.Replicator` or `org.apache.sling.replication.*`	`replication`
JCR observation: `javax.jcr.observation.EventListener` , `onEvent(EventIterator)` , `javax.jcr.observation.*`	`eventListener`
OSGi Event Admin: `org.osgi.service.event.EventHandler` , substantive `handleEvent` (resolver/session/node work)	`eventHandler`
`com.day.cq.dam.api.AssetManager` create/remove asset APIs	`assetApi`
`org.apache.felix.scr.annotations`	read `references/scr-to-osgi-ds.md` (often combined with a BPA pattern)
`getAdministrativeResourceResolver` , `System.out` / `printStackTrace`	read `references/resource-resolver-logging.md`
HTL: build warning `data-sly-test: redundant constant value comparison` , or `.html` under `ui.apps` / `jcr_root` with bad `data-sly-test`	read `references/data-sly-test-redundant-constant.md`

If multiple patterns match, ask which to fix first.

当无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` ，或 `ui.apps` / `jcr_root` 下包含错误 `data-sly-test` 的 `.html` 文件	阅读 `references/data-sly-test-redundant-constant.md`

若多个模式匹配，请询问用户优先修复哪一个。

Relationship to Migration

与迁移技能的关系

The migration
skill defines one-pattern-per-session workflow, BPA/CAM/MCP flows, and user messaging. It delegates all detailed transformation steps to this skill's

references/

modules. It uses a {best-practices}
repo-root path alias to this folder (see its

SKILL.md

). Keep platform truth here; keep orchestration there.

migration
技能定义了「每会话处理一个模式」的工作流、BPA/CAM/MCP流程以及用户交互信息。它将所有详细的转换步骤委托给本技能的

references/

模块。它使用**

{best-practices}

**仓库根路径别名指向本文件夹（详见其

SKILL.md

）。平台相关的标准定义在此处，流程编排逻辑在迁移技能中。