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、resolvers 或日志记录，请先查看 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 工作区根目录内；切勿在该边界之外 grep 或遍历目录来查找 Java，除非用户明确指出这些位置

手动模式提示（分类）

没有 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

如果匹配多个模式，请询问用户希望先修复哪一个。

与迁移的关系

migration 技能定义了每个会话处理一个模式的工作流、BPA/CAM/MCP 流程和用户沟通方式。它会将所有详细转换步骤委托给本技能的 references/ 模块。它使用指向此文件夹的仓库根目录路径别名 {best-practices}（见其 SKILL.md）。平台事实应保留在此处；编排应保留在彼处。